API Documentation

Serial

The PolySync Serial API is a wrapper class around a serial port.

The user should be able to select the serial port by name via the constructor.

auto serialPort = new Serial( "/dev/ttyUSB0" );

This particular API provides an interface to terminal device IO. In Linux, standard canonical and non-canonical modes are supported.

Usage #include <PolySyncSerial.hpp>

Enumerations

The Serial Module Enumerations.

Value Description
SerialDataBits { dataBits5, dataBits6, dataBits7, dataBits8 }
SerialStopBits { stopBits1, stopBits2 }
SerialParity { parityNone, parityEven, parityOdd }
SerialHardwareFlowControl { hardwareFlowControlNone, hardwareFlowControlRtscts }
SerialSoftwareFlowControl { softwareFlowControlNone, softwareFlowControlXonXoff }

Serial

The Serial class specifically presents a series of functions that allow the user to access and communicate with devices via a serial port.

The serial port in this instance can be any of the various serial communication protocols, with the assumption that there is an existing adapter to convert from USB to RS232, RS422, RS485 or any other compatible hardware.

The usage is presented here for the user to select the name of the serial port to use and then configure to the appropriate baud rate.

Serial::Serial ( … )

The Serial class constructor will do the following:

  • Search for device by name (i.e. ‘/dev/ttyUSB0’)
  • Check if normal open/close operations are working
  • Check if device is a tty
  • Set ps_serial_device.original_settings
  • Set ps_serial_device.name
Parameters
in/out type name description
in const std::string & deviceName A string reference that specifies the device name buffer.
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - If an argument is invalid
    • DTC_CONFIG - If device had already been initialized, but is now invalid or device is not a valid tty device
    • DTC_NOINPUT - If device name does not exist on the host
    • DTC_NOPERM - If device is not readable
    • DTC_INTR - If device open () system call was interrupted

Serial::~Serial ( )

The Serial class destructor.

Serial::open ( )

This will open a serial device for read-write operations in blocking IO mode, populate the ps_serial_device.settings, and attempt to get exclusive access to a device.

Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - If an argument is invalid
    • DTC_CONFIG - If failed to close or open device
    • DTC_NOINPUT - If device name does not exist on the host
    • DTC_INTR - If device open () system call was interrupted

Serial::close ()

This will perform a flush Serial::flush(), and restore the original settings, before closing the serial device.

Exceptions
  • Throws polysync::DTCException on failure:

Serial::read ( … )

This will read up to 256 bytes of data from a serial device.

It is a blocking call, unless the user has enabled the non-block option (Serial::setNonblockOption) to allow the function to immediately return.

Parameters
in/out type name description
out std::vector< uchar > & buffer A std::vector for storing the data.
out ps_timestamp & timestamp A pointer to ps_timestamp that receives the timestamp value.
Returns
  • ulong - The number of bytes read from the serial device
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - If an argument is invalid
    • DTC_CONFIG - If device or settings structure is invalid
    • DTC_INTR - If device read() system call was interrupted
    • DTC_UNAVAILABLE - If read would block in non-blocking mode, or a timeout was exceeded if one was set

Serial::write ( … )

This will allow the user to specify a block of data (stored in a vector) to send over the serial port.

This is nominally a blocking call, unless the user has enabled the non-block option (Serial::setNonblockOption) to allow the function to return immediately.

Parameters
in/out type name description
in std::vector< uchar > & buffer A std::vector reference containing the data to be sent.
Returns
  • ulong - The number of bytes written to the serial device
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - If an argument is invalid
    • DTC_CONFIG - If device or settings structure is invalid
    • DTC_INTR - If device write() system call was interrupted
    • DTC_UNAVAILABLE - If write would block in non-blocking mode, or a timeout was exceeded if one was set

Serial::flush ( )

This will flush (discard) unsent data still in the send buffer, and/or received data already in the receive buffer.

Exceptions
  • Throws polysync::DTCException on failure:

Serial::drain ( )

This will wait until all data previously written to the serial device has been sent.

The function will return when the send buffer has cleared. It is a synchronous call.

Exceptions
  • Throws polysync::DTCException on failure:

Serial::setNonblockOption ( … )

This will set a serial device’s non-blocking option.

Parameters
in/out type name description
in uint enabled non-zero = enable, 0 = disabled.
Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - If there is an invalid argument

Serial::getDataRate ( )

This will return the datarate value contained in a serial IO settings structure.

Returns
Exceptions
  • Throws polysync::DTCException on failure:

Serial::setDataRate ( … )

The function will set the datarate value contained in a serial IO settings structure.

Parameters
in/out type name description
in ps_datarate_kind datarate The datarate value to set. Value DATARATE_UNKNOWN means zero.
Exceptions
  • Throws polysync::DTCException on failure:

Serial::getModemControlBits ( )

This will get a serial device’s modem control bits.

In Linux, the following are examples of modem control bits:

  • TIOCM_DTR
  • TIOCM_RTS
  • etc.
Returns
  • ulong - The value of the modem control bits
Exceptions
  • Throws polysync::DTCException on failure:

Serial::setModemControlBits ( … )

This will set a serial device’s modem control bits.

In Linux, the following are examples of modem control bits:

  • TIOCM_DTR
  • TIOCM_RTS
  • etc.
Parameters
in/out type name description
in ulong bits The bits value to set.
Exceptions
  • Throws polysync::DTCException on failure:

Serial::getDataBits ( )

This will return the number of data bits the serial port is using.

Returns
  • SerialDataBits dataBits - The number of data bits the serial port is currently using

Serial::setDataBits ( … )

The function will set the number of data bits that the serial port will use.

Parameters
in/out type name description
in SerialDataBits dataBits The number of data bits to set.
Exceptions
  • Throws polysync::DTCException on failure:

Serial::getStopBits ( )

This will return the number of stop bits the serial port is using.

Returns
  • SerialStopBits stopBits - The number of stop bits the serial port is currently using

Serial::setStopBits ( … )

The function will set the number of stop bits that the serial port will use.

Parameters
in/out type name description
in SerialStopBits stopBits The number of stop bits to set.
Exceptions
  • Throws polysync::DTCException on failure:

Serial::getParity ( )

This will return the parity that the serial port is using.

Returns
  • SerialParity parity - The parity the serial port is currently using

Serial::setParity ( … )

The function will set the parity that the serial port will use.

Parameters
in/out type name description
in SerialParity parity The parity to set.
Exceptions
  • Throws polysync::DTCException on failure:

Serial::getHardwareFlowControl ( )

This will return the hardware flow control that the serial port is using.

Returns
  • SerialHardwareFlowControl - The hardware flow control the serial port is currently using

Serial::setHardwareFlowControl ( … )

The function will set the hardware flow control that the serial port will use.

Parameters
in/out type name description
in SerialHardwareFlowControl flowControl The hardware flow control to set.
Exceptions
  • Throws polysync::DTCException on failure:

Serial::getSoftwareFlowControl ( )

This will return the software flow control that the serial port is using.

Returns
  • SerialSoftwareFlowControl - The software flow control the serial port is currently using

Serial::setSoftwareFlowControl ( … )

The function will set the software flow control that the serial port will use.

Parameters
in/out type name description
in SerialSoftwareFlowControl flowControl The software flow control to set.
Exceptions
  • Throws polysync::DTCException on failure:

Serial::applySettings ( )

This will perform a necessary step if you want, or need, to change the configuration of the serial device.

It should follow any set of changes to the configuration of the serial port to push those changes to the physical device.

Exceptions
  • Throws polysync::DTCException on failure:
    • DTC_USAGE - If an item in the settings is invalid
    • DTC_CONFIG - If device or settings structure is invalid