API Documentation

Serial

The Serial API allows users to both configure and connect to a serial terminal device, as well as receive raw data.

In Linux, standard canonical and non-canonical modes are supported.

Synchronous IO operations (such as polling-timeouts or multiplexing) can be achieved through use of the standard select() system call mechanisms, which are performed on the ps_serial_device.handle file descriptor. Usage #include <polysync_serial.h>


// Typical use in Linux (omitting error handling):

// clear device memory
ps_serial_device device;
memset( &device, 0, sizeof(device) );

// init device
psync_serial_init( &device, "/dev/ttyUSB0" );

// open device
psync_serial_open( &device );

// configure non-canonical
// enable the receiver and set local mode
device.settings.c_cflag |= (CLOCAL | CREAD);
// set character size to data bits, set no parity, mask the character size bits
device.settings.c_cflag &= ~(CSIZE|PARENB);
// 8 data bits
device.settings.c_cflag |= CS8;
// 2 stop bits
device.settings.c_cflag |= CSTOPB;
// disable hardware flow control
device.settings.c_cflag &= ~CRTSCTS;
device.settings.c_lflag &= ~(ECHO|ECHONL|ICANON|ISIG|IEXTEN);
// disable software flow control
device.settings.c_iflag &= ~(IGNBRK|BRKINT|PARMRK|ISTRIP|INLCR|IGNCR|ICRNL|IXON);
// set raw output
device.settings.c_oflag &= ~OPOST;
// read minimum of 1 byte, inter-char timer set to 0.1 seconds
device.settings.c_cc[VMIN]     = 1;
device.settings.c_cc[VTIME]    = 1;

// set PolySync datarate
psync_serial_set_datarate_setting( &device.settings, DATARATE_4800 );

// apply the settings to the device
psync_serial_apply_settings( &device, &device.settings );

// set blocking IO mode
psync_serial_set_nonblock_option( &device, 0 );

// perform read/write operations
// ...

// close device
psync_serial_close( &device );

Constants

PSYNC_SERIAL_HANDLE_INVALID ( -1 )

This represents an invalid ps_serial_device.handle.

Please check the handle following initialization to ensure that it is valid.

Functions

psync_serial_apply_settings ( … )

This will apply IO settings to a serial device.

Parameters
in/out type name description
in ps_serial_device * const device A pointer to ps_serial_device that receives the configuration.
in const ps_serial_io_settings * const settings A pointer to ps_serial_io_settings that specifies the settings to apply.
Returns

Diagnostic trouble code reference

psync_serial_close ( … )

This will close a serial device.

The function performs a flush, and restores the original settings before closing.

Parameters
in/out type name description
in ps_serial_device * const device A pointer to ps_serial_device that receives the configuration.
Returns

Diagnostic trouble code reference

psync_serial_drain ( … )

This will drain a serial device’s send buffer.

The function will wait until all data (previously written to the serial device) has been sent. It returns when the send buffer has cleared.

Parameters
in/out type name description
in ps_serial_device * const device A pointer to ps_serial_device that receives the configuration.
Returns

Diagnostic trouble code reference

psync_serial_flush ( … )

This will flush a serial device’s IO.

The function will discard unsent data that is still in the send buffer. It can also flush (discard) received data that is still in the receive buffer.

Parameters
in/out type name description
in ps_serial_device * const device A pointer to ps_serial_device that receives the configuration.
Returns

Diagnostic trouble code reference

psync_serial_get_datarate_setting ( … )

This will get a serial IO setting’s datarate.

This gets the datarate value contained in a serial IO setting’s structure.

Parameters
in/out type name description
in const ps_serial_io_settings * const settings A pointer to ps_serial_io_settings that specifies the settings to read from.
out ps_datarate_kind* datarate A pointer to ps_datarate_kind that receives the datarate value. Set to value DATARATE_UNKNOWN if datarate is zero.
Returns

Diagnostic trouble code reference

psync_serial_get_modem_control_bits ( … )

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

In Linux, these are modem control bits (i.e. TIOCM_DTR, TIOCM_RTS, etc.).

Parameters
in/out type name description
in ps_serial_device * const device A pointer to the ps_serial_device that specifies the configuration.
out unsigned long * const bits A pointer to an unsigned long that receives the bits value.
Returns

Diagnostic trouble code reference

psync_serial_init ( … )

This will initialize a serial device.

Does the following:

  • Searches for device by name (i.e. ‘/dev/ttyUSB0’)
  • Checks if normal open/close operations are working
  • Checks if device is a tty
  • Sets ps_serial_device::original_settings
  • Sets ps_serial_device::name
Parameters
in/out type name description
in ps_serial_device * const device A pointer to ps_serial_device that receives the initialization.
in const char * const device_name A pointer to char that specifies the device name buffer.
Returns
  • DTC Code:
    • DTC_NONE - (Zero) if success
    • DTC_USAGE - If argument is invalid
    • DTC_CONFIG - If device has 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

Diagnostic trouble code reference

psync_serial_open ( … )

This will open a serial device.

This opens a serial device for read-write operations in blocking IO mode. It populates ps_serial_device::settings, and attempts to get exclusive access to the device.

Parameters
in/out type name description
in ps_serial_device * const device A pointer to ps_serial_device that receives the configuration.
Returns
  • DTC Code:

    • DTC_NONE - (Zero) if success
    • DTC_USAGE - If argument is invalid
    • DTC_CONFIG - If device has 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_INTR - If device open() system call was interrupted

Diagnostic trouble code reference

psync_serial_read ( … )

This will receive data from a serial device.

Parameters
in/out type name description
in ps_serial_device * const device A pointer to ps_serial_device that specifies the configuration.
out unsigned char * const buffer A pointer to an unsigned char buffer that receives the data read.
in const unsigned long buffer_len The maximum number of bytes to read.
out unsigned long * const bytes_read A pointer to an unsigned long that receives the bytes read value.
out ps_timestamp * const timestamp A pointer to ps_timestamp that receives the receive timestamp value.
Returns
  • DTC Code:
    • DTC_NONE - (Zero) if success
    • DTC_USAGE - If argument is invalid
    • DTC_CONFIG - If device has already been initialized but is now invalid, or device is not a valid tty device
    • DTC_INTR - If device open() system call was interrupted
    • DTC_UNAVAILABLE - If read would block in non-blocking mode, or a timeout was exceeded if one was set

Diagnostic trouble code reference

psync_serial_set_datarate_setting ( … )

This will set the datarate value contained in a ps_serial_io_settings structure.

Parameters
in/out type name description
in ps_serial_io_settings * const settings A pointer to ps_serial_io_settings that specifies the settings to configure.
in const ps_datarate_kind datarate The datarate value to set. Value DATARATE_UNKNOWN means zero.
Returns
  • DTC Code:
    • DTC_NONE - (Zero) if success
    • DTC_USAGE - If argument is invalid
    • DTC_CONFIG - If device has already been initialized but is now invalid, or device is not a valid tty device

Diagnostic trouble code reference

psync_serial_set_modem_control_bits ( … )

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

In Linux, these are modem control bits (i.e. TIOCM_DTR, TIOCM_RTS, etc.).

Parameters
in/out type name description
in ps_serial_device * const device A pointer to ps_serial_device that receives the configuration.
in const unsigned long bits Bits value to set.
Returns
  • DTC Code:
    • DTC_NONE - (Zero) if success
    • DTC_USAGE - If argument is invalid
    • DTC_CONFIG - If device has already been initialized but is now invalid, or device is not a valid tty device

Diagnostic trouble code reference

psync_serial_set_nonblock_option ( … )

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

In Linux, these are modem control bits (i.e. TIOCM_DTR, TIOCM_RTS, etc.).

Parameters
in/out type name description
in ps_serial_device * const device A pointer to ps_serial_device that receives the configuration.
in const unsigned int enabled If not zero, it enables the option. Otherwise, the option is disabled.
Returns
  • DTC Code:
    • DTC_NONE - (Zero) if success
    • DTC_USAGE - If argument is invalid
    • DTC_CONFIG - If device has already been initialized but is now invalid, or device is not a valid tty device

Diagnostic trouble code reference

psync_serial_set_nonblock_option ( … )

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

In Linux, these are modem control bits (i.e. TIOCM_DTR, TIOCM_RTS, etc.).

Parameters
in/out type name description
in ps_serial_device * const device A pointer to ps_serial_device that receives the configuration.
in const unsigned int enabled If not zero, it enables the option. Otherwise, the option is disabled.
Returns

Diagnostic trouble code reference

psync_serial_write ( … )

This will send the data to a serial device.

Parameters
in/out type name description
in ps_serial_device * const device A pointer to ps_serial_device that specifies the configuration.
in unsigned char * const buffer A pointer to an unsigned char buffer that specifies the data to be sent.
in const unsigned long buffer_len The number of bytes to write from the buffer.
out unsigned long * const bytes_sent A pointer to an unsigned long that receives the bytes sent value.
Returns
  • DTC Code:

    • DTC_NONE - (Zero) if success
    • DTC_USAGE - If 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 and in non-blocking mode, or a timeout was exceeded if one was set

Diagnostic trouble code reference

Typedefs

ps_serial_io_settings

A struct termios type that will store the serial connection IO settings.

ps_serial_device

A PolySync serial device will be used to create, configure, and manage a serial connection.

typedef struct
{
    //
    //
    int                         handle; // The device handle. In Linux this is the device file descriptor. Value [PSYNC_SERIAL_HANDLE_INVALID](/api-docs/c/serial/#constants) means an invalid device handle.
    //
    //
    ps_serial_io_settings       settings; // The device settings that are currently applied.
    //
    //
    ps_serial_io_settings       original_settings; // The original device settings.
    //
    //
    char                        name[PSYNC_DEFAULT_STRING_LEN]; // The device name. In Linux this is the full device path i.e. '/dev/ttyUSB0'.
} ps_serial_device;