Message protocol

SerialPort uses a command and response protocol. Commands are issued by the application interface. Every command receives a response from the server. Commands that trigger immediate actions, such as opening a connection, setting its operating conditions or querying its state, are carried out when they are received and the result of the command is returned in the response. Commands that may take some time to complete generate an immediate response showing whether the command was accepted while the associated activity, such as sending a block of data to the remote host, continues asynchronously until it completes. The server supports queries that allow the progress of asynchronous activities to be monitored.

In the interest of maximising throughput there are no wait states in the server apart from the per-character transmission delay, a configurable pause to allow a slow remote host to deal with each character before it is sent the next one. SerialPort implements functions that calculate and apply a waiting time to allow for data to be transferred to the remote host and for it to transmit a block of data in reply. This is implemented entirely within the interface code, so the application that has requested the transfers is the only process that is suspended during the waiting time.

Message format

Each message has a common format:

C,nnnn,value

where:

is the command code:

C	close port
D	set transmission delay per character
G	get input
I	echo mode
L	request_portlist
O	open port
P	output text
Q	query buffer state
R	reset linespec, tx delay, record separator
S	set port params
T	set record separator

nnnn

is the length of the following value, max 1500 bytes.

value

is dependent on the command mnemonic.

Command	Value in the command	Value in the response
C [1]	force	n/a
D	delay (in mSec)	n/a
G	max bytes to be retrieved	character string
L	n/a	port name string (CSV format)
O	portname	baud,dbits,par,sbits
P	character string	n/a
Q [2]	n/a	input,output,buffsize
R [3]	linespec\|delay\|separator	n/a
S	baud,dbits,par,sbits	n/a
T [4]	active\|marker\|external	n/a

Notes:

[1]:	The force value is a string. If the first character starts with T, t or 1 the port will be forced closed regardless of whether there is still data in the server's buffers. Any other value or a zero value length will cause a normal close if the buffers are empty but will leave the port open and return an error if there is still data in the buffers.
[2]:	The command returns three comma-separated numbers. These are the number of bytes in the input buffer, the number of bytes in the output buffer and the buffer size. Both buffers are the same size.
[3]:	These parameters are three fixed length single byte values. They are concatenated to form a three byte command parameter. All are boolean and may be T/F, t/f or 1/0. Each controls whether a set of control variables are reset ot not. linespec resets the baudrate, databits, parity and stop bits to the default values for the line. delay resets the per-character transmission delay to zero. separator sets the field separator to inactive, clears the separator character and marks the separator as internal.
[4]:	These parameters are three fixed length single byte values. They are concatenated to form a three byte command parameter. active and external are boolean and may be T/F, t/f or 1/0. marker can be any ASCII character code. setting active enables the use of the marker value as a field separator marker is the field separator character setting external causes marker to be appended to each P value string and to be removed from the end of the G value. If external is unset the field marker, if any, must be included in the P value string and, though it delimits the G value, it is returned as the last character in the value.

Command/response relationships

Every command generates a response. The command code in the response is set according to the following rules:

If the response may contain data its command code is the same as the triggering command.
If the response can never contain data the command code is A.
If the command caused an error, the command code is E and the value is the error message.

Output is sent to the port with a P command. The response is returned immediately. The data has been buffered for transmission but nothing has been transmitted to the remote host when the response is sent. If external separators are enabled the P command causes a separator to be appended to the output byte list.

Input is retrieved with the G command. All immediately available characters up the the requested maximum are returned. If no data is available a G response with a zero length value is returned. If separators are enabled the current separator character will terminate the retrieval if it is encountered within the available characters. If the terminator is external it is not returned as part of the retrieved bytes list, but if it is internal then the terminator is the last character in value.