Unit Serial

Return to Unit Reference

Description

---

Ultibo Serial interface unit

Serial devices represent a communication device that can be both read and written and has a set of common properties and capabilities. The underlying device may be an actual UART or it may be some other form of device such as a USB to Serial converter. As long as the device can implement the common capabilities then it can be accessed as a serial device without regard to the actual implementation.

Each serial device returns a set of properties that describe the capabilities of the device and includes a set of flags that indicate what features are supported.

Reads from and writes to serial devices are buffered so that varying data transfer rates can be accomodated and both reads and writes allow for non blocking so that a caller can avoid waiting for received data to be available or the device to be ready to transmit.

This unit also implements the serial logging device which can be configured via parameters in the GlobalConfig unit or from the command line.

Constants

---

[Expand]

Serial specific constants SERIAL_*

SERIAL_NAME_PREFIX = 'Serial';	Name prefix for Serial Devices
SERIAL_RECEIVE_DEPTH_DEFAULT = SIZE_2K;	Default receive buffer size in bytes
SERIAL_TRANSMIT_	Default transmit buffer size in bytes

[Expand]

Serial device type constants SERIAL_TYPE_*

SERIAL_TYPE_NONE = 0;
SERIAL_TYPE_UART = 1;
SERIAL_TYPE_USB = 2;

[Expand]

Serial device state constants SERIAL_STATE_*

SERIAL_STATE_CLOSED = 0;
SERIAL_STATE_CLOSING = 1;
SERIAL_STATE_OPENING = 2;
SERIAL_STATE_OPEN = 3;

[Expand]

Serial device flag constants SERIAL_FLAG_*

SERIAL_FLAG_NONE = $00000000;
SERIAL_FLAG_DATA_8BIT = $00000001;	Device supports 8 data bits
SERIAL_FLAG_DATA_7BIT = $00000002;	Device supports 7 data bits
SERIAL_FLAG_DATA_6BIT = $00000004;	Device supports 6 data bits
SERIAL_FLAG_DATA_5BIT = $00000008;	Device supports 5 data bits
SERIAL_FLAG_STOP_1BIT = $00000010;	Device supports 1 stop bit
SERIAL_FLAG_STOP_2BIT = $00000020;	Device supports 2 stop bits
SERIAL_FLAG_STOP_1BIT5 = $00000040;	Device supports 1.5 stop bits
SERIAL_FLAG_PARITY_ODD = $00000080;	Device supports odd parity
SERIAL_FLAG_PARITY_EVEN = $00000100;	Device supports even parity
SERIAL_FLAG_PARITY_MARK = $00000200;	Device supports mark parity
SERIAL_FLAG_PARITY_SPACE = $00000400;	Device supports space parity
SERIAL_FLAG_FLOW_RTS_CTS = $00000800;	Device supports RTS/CTS flow control
SERIAL_FLAG_FLOW_DSR_DTR = $00001000;	Device supports DSR/DTR flow control

[Expand]

Serial read flag constants SERIAL_READ_*

SERIAL_READ_NONE = $00000000;
SERIAL_READ_NON_BLOCK = $00000001;	Do not block when reading, if the buffer is empty return immediately
SERIAL_READ_PEEK_BUFFER = $00000002;	Return the number of bytes available in the receive buffer without reading them

[Expand]

Serial write flag constants SERIAL_WRITE_*

SERIAL_WRITE_NONE = $00000000;
SERIAL_WRITE_NON_BLOCK = $00000001;	Do not block when writing, if the buffer is full return immediately
SERIAL_WRITE_PEEK_BUFFER = $00000002;	Return the number of bytes free in the transmit buffer without writing anything

[Expand]

Serial status flag constants SERIAL_STATUS_*

SERIAL_STATUS_NONE = $00000000;
SERIAL_STATUS_RTS = $00000001;	RTS (Request to Send) is set (If applicable)
SERIAL_STATUS_CTS = $00000002;	CTS (Clear to Send) is set (If applicable)
SERIAL_STATUS_DSR = $00000004;	DSR (Data Set Ready) is set (If applicable)
SERIAL_STATUS_DTR = $00000008;	DTR (Data Terminal Ready) is set (If applicable)
SERIAL_STATUS_RX_FULL = $00000010;	Receive buffer is full
SERIAL_STATUS_RX_EMPTY = $00000020;	Receive buffer is empty
SERIAL_STATUS_TX_FULL = $00000040;	Transmit buffer is full
SERIAL_STATUS_TX_EMPTY = $00000080;	Transmit buffer is empty
SERIAL_STATUS_BUSY = $00000100;	Device is busy
SERIAL_STATUS_BREAK_ERROR = $00000200;	Break error reported
SERIAL_STATUS_PARITY_ERROR = $00000400;	Parity error reported
SERIAL_STATUS_FRAMING_ERROR = $00000800;	Framing error reported
SERIAL_STATUS_OVERRUN_ERROR = $00001000;	Overrun error reported
SERIAL_STATUS_DCD = $00002000;	DCD (Data Carrier Detect) is set (If applicable)
SERIAL_STATUS_RI = $00004000;	RI (Ring Indicator) is set (If applicable)

[Expand]

Serial logging constants SERIAL_LOG_*

SERIAL_LOG_LEVEL_DEBUG = LOG_LEVEL_DEBUG;	Serial debugging messages
SERIAL_LOG_LEVEL_INFO = LOG_LEVEL_INFO;	Serial informational messages, such as a device being attached or detached
SERIAL_LOG_LEVEL_ERROR = LOG_LEVEL_ERROR;	Serial error messages
SERIAL_LOG_LEVEL_NONE = LOG_LEVEL_NONE;	No Serial messages

Type definitions

---

To be documented

Public variables

---

To be documented

Function declarations

---

Initialization functions

[Expand]

procedure SerialInit;

Description: Initialize the Serial unit and Serial device table

Note	None documented

Serial functions

[Expand]

function SerialDeviceOpen(Serial:PSerialDevice; BaudRate,DataBits,StopBits,Parity,FlowControl,ReceiveDepth,TransmitDepth:LongWord):LongWord;

Description: To be documented

Note	None documented

[Expand]

function SerialDeviceClose(Serial:PSerialDevice):LongWord;

Description: To be documented

Note	None documented

[Expand]

function SerialDeviceRead(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;

Description: To be documented

Note	None documented

[Expand]

function SerialDeviceWrite(Serial:PSerialDevice; Buffer:Pointer; Size,Flags:LongWord; var Count:LongWord):LongWord;

Description: To be documented

Note	None documented

[Expand]

function SerialDeviceStatus(Serial:PSerialDevice):LongWord;

Description: To be documented

Note	None documented

[Expand]

function SerialDeviceProperties(Serial:PSerialDevice; Properties:PSerialProperties):LongWord;

Description: To be documented

Note	None documented

[Expand]

function SerialDeviceCreate:PSerialDevice;

Description: Create a new Serial entry

Return	Pointer to new Serial entry or nil if Serial could not be created

[Expand]

function SerialDeviceCreateEx(Size:LongWord):PSerialDevice;

Description: Create a new Serial entry

Size	Size in bytes to allocate for new Serial (Including the Serial entry)
Return	Pointer to new Serial entry or nil if Serial could not be created

[Expand]

function SerialDeviceDestroy(Serial:PSerialDevice):LongWord;

Description: Destroy an existing Serial entry

Note	None documented

[Expand]

function SerialDeviceRegister(Serial:PSerialDevice):LongWord;

Description: Register a new Serial in the Serial table

Note	None documented

[Expand]

function SerialDeviceDeregister(Serial:PSerialDevice):LongWord;

Description: Deregister a Serial from the Serial table

Note	None documented

[Expand]

function SerialDeviceFind(SerialId:LongWord):PSerialDevice;

Description: To be documented

Note	None documented

[Expand]

function SerialDeviceFindByName(const Name:String):PSerialDevice; inline;

Description: To be documented

Note	None documented

[Expand]

function SerialDeviceFindByDescription(const Description:String):PSerialDevice; inline;

Description: To be documented

Note	None documented

[Expand]

function SerialDeviceEnumerate(Callback:TSerialEnumerate; Data:Pointer):LongWord;

Description: To be documented

Note	None documented

[Expand]

function SerialDeviceNotification(Serial:PSerialDevice; Callback:TSerialNotification; Data:Pointer; Notification,Flags:LongWord):LongWord;

Description: To be documented

Note	None documented

Serial logging functions

[Expand]

function SerialLoggingStart(Logging:PLoggingDevice):LongWord;

Description: To be documented

Note	None documented

[Expand]

function SerialLoggingStop(Logging:PLoggingDevice):LongWord;

Description: To be documented

Note	None documented

[Expand]

function SerialLoggingOutput(Logging:PLoggingDevice; const Data:String):LongWord;

Description: To be documented

Note	None documented

RTL serial functions

[Expand]

function SysSerialAvailable:Boolean;

Description: Check if a Serial device is available

Note	None documented

[Expand]

function SysSerialOpen(BaudRate,DataBits,StopBits,Parity,FlowControl,ReceiveDepth,TransmitDepth:LongWord):LongWord;

Description: Open the default Serial device ready for sending and receiving

BaudRate	Baud rate for the connection (eg 9600, 57600, 115200 etc
DataBits	Size of the data (eg SERIAL_DATA_8BIT)
StopBits	Number of stop bits (eg SERIAL_STOP_1BIT)
Parity	Parity type for the data (eg SERIAL_PARITY_NONE)
FlowControl	Flow control for the connection (eg SERIAL_FLOW_NONE)
ReceiveDepth	Size of the receive buffer (0 = Default size)
TransmitDepth	Size of the transmit buffer (0 = Default size)

[Expand]

function SysSerialClose:LongWord;

Description: Close the default Serial device and terminate sending and receiving

Note	None documented

[Expand]

function SysSerialRead(Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;

Description: Read data from the default Serial device

Buffer	Pointer to a buffer to receive the data
Size	The size of the buffer
Count	The number of bytes read on return

[Expand]

function SysSerialWrite(Buffer:Pointer; Size:LongWord; var Count:LongWord):LongWord;

Description: Write data to the default Serial device

Buffer	Pointer to a buffer of data to transmit
Size	The size of the buffer
Count	The number of bytes written on return

Serial helper functions

[Expand]

function SerialGetCount:LongWord; inline;

Description: Get the current Serial count

Note	None documented

[Expand]

function SerialDeviceGetDefault:PSerialDevice; inline;

Description: Get the current default Serial device

Note	None documented

[Expand]

function SerialDeviceSetDefault(Serial:PSerialDevice):LongWord;

Description: Set the current default Serial device

Note	None documented

[Expand]

function SerialDeviceCheck(Serial:PSerialDevice):PSerialDevice;

Description: Check if the supplied Serial is in the Serial table

Note	None documented

[Expand]

function SerialBufferReadStart(Buffer:PSerialBuffer; var Available:LongWord):Pointer;

Description: Return a pointer to the next read from the buffer and the number of bytes that can be read

Note	Caller must hold the lock on the serial device which owns the buffer

[Expand]

function SerialBufferReadComplete(Buffer:PSerialBuffer; Removed:LongWord):Boolean;

Description: Update the buffer to reflect the number of bytes removed when reading

Note	Caller must hold the lock on the serial device which owns the buffer

[Expand]

function SerialBufferWriteStart(Buffer:PSerialBuffer; var Available:LongWord):Pointer;

Description: Return a pointer to the next write to the buffer and the number of bytes that can be written

Note	Caller must hold the lock on the serial device which owns the buffer

[Expand]

function SerialBufferWriteComplete(Buffer:PSerialBuffer; Added:LongWord):Boolean;

Description: Update the buffer to reflect the number of bytes added when writing

Note	Caller must hold the lock on the serial device which owns the buffer

[Expand]

procedure SerialLog(Level:LongWord; Serial:PSerialDevice; const AText:String);

Description: To be documented

Note	None documented

[Expand]

procedure SerialLogInfo(Serial:PSerialDevice; const AText:String); inline;

Description: To be documented

Note	None documented

[Expand]

procedure SerialLogError(Serial:PSerialDevice; const AText:String); inline;

Description: To be documented

Note	None documented

[Expand]

procedure SerialLogDebug(Serial:PSerialDevice; const AText:String); inline;

Description: To be documented

Note	None documented

[Expand]

function SerialParityToString(Parity:LongWord):String;

Description: To be documented

Note	None documented

[Expand]

function SerialFlowControlToString(Flow:LongWord):String;

Description: To be documented

Note	None documented

Serial logging helper functions

[Expand]

function SerialLoggingDeviceAdd(Serial:PSerialDevice):LongWord;

Description: To be documented

Note	None documented

[Expand]

function SerialLoggingDeviceRemove(Serial:PSerialDevice):LongWord;

Description: To be documented

Note	None documented

[Expand]

function SerialLoggingDeviceParameters(Serial:PSerialDevice; const Parameters:String; var BaudRate,Parity,DataBits,StopBits:LongWord):LongWord;

Description: Break down the serial parameters value into component parts of baud rate, parity, data bits and stop bits

Note	The parameters must be in the form 'BaudRate,Parity,DataBits,StopBits' (eg '115200,N,8,1')

[Expand]

function SerialLoggingFirstWord(var Value:String;const Delimiter:String):String;

Description: To be documented

Note	None documented

[Expand]

function SerialLoggingDeviceEnum(Serial:PSerialDevice; Data:Pointer):LongWord;

Description: To be documented

Note	None documented

[Expand]

function SerialLoggingDeviceNotify(Device:PDevice; Data:Pointer; Notification:LongWord):LongWord;

Description: To be documented

Note	None documented

Return to Unit Reference