A small summary of design goals:
- One TCP connection for one session with possibly several packet transmissions/transactions
- Human readable ASCII data exchange, a telnet client shell be sufficiant to debug a server
- Shell be designed to make it easy to write a wrapper that encapsulates a request to the master and its response into one procedure call on the client side
- Version 0: June 2002
- Version 1: September 2002
The first version that includes full duplex operation.
- Version 2: April 2015
Adding means to report errors from LocoNet as well as timestamping.
All transmitted data must be readable ASCII format. Binary data is coded in hex or decimal ASCII representations. The data stream in the TCP connection is split into lines. A line ends with either a cr (13dec=0Dhex) or lf (10dec=0Ahex). Receivers must accept any combination and have to discard empty lines, senders may send any combination. Each line starts with a token. A token is a sequence of uppercase ASCII characters. After the token may optionally follow a parameter which is separated by one space (32dec=20hex) from the token. The syntax of the parameter is described below with the token.
Parameter Hex dump of LocoNet message Description This message is a request to the server to send the LocoNet message passed as parameter to the net.
Added in version 2: The server can not rely on the fact that this message is correct with respect to opcode bit, length and checksum. This message can be corrupt on purpose if a client supports to issue corrupt messages. The server implementation (or interface hardware) has the freedom to support this or not. If not supported, the server shall reply with "SENT ERROR ...reason..."
Example SEND A0 2F 00 70
Parameter Arbitrary sequence of ASCII characters that identify the server and its version Description This messages may be sent from the server to any newly connected client to inform the (user of the) client about the server version. Example VERSION LbServer version 0.1a built May 30 2002
Parameter Hex dump of LocoNet message Description Every message that is received by the server from LocoNet is distributed to every client with this line.
Added in version 2: The server may only send messages that are correct with respect to opcode bits, length and checksum with this token. If the message is corrupt, it may be sent with the new "ERROR" token, see below!
Example RECEIVE 83 7C
Parameter two possibilities:
"_comment_" is an arbitrary sequence of character that explain the reason for the success (in case of "OK") or failure (in case of "ERROR") in English natural language. The comment is optional in case of OK
- OK _comment_
- ERROR _comment_
Description This message is always sent as response to a "SEND" message. Proper timeouts still have to be invented.
This token is sent after the RECEIVE token which is the echo of the sent message. This way, the client can expect the response to its question to come in right after the SENT token. Of course a sequence of OPC_BUSY message or BREAKs might have to be skipped.
Example SENT ERROR Did not receive echo from LocoBuffer
Parameter A decimal number that denotes the number of micro seconds since server program start.
It is the job of the client to compute an absolute time information from this based on the first TIMESTAMP token seen.
Description This token is optional. The server implementation may choose to send this or not. The TIMESTAMP token is sent before the token that is timestamped by this. It can be applied to RECEIVE, BREAK and ERROR tokens or any sub set of these. Example TIMESTAMP 47110815
RECEIVE 83 7C
Parameter A decimal number that denotes the length of the break in micro seconds or nothing at all.
This is optional! If the server or interface is able to measure the length of the break, it may deliver the measurement in this parameter. Otherwise BREAK does not have a parameter.
Description If the interface is capable of detecting breaks, it informs the clients with this token. A break is expected to be seen on occurance of a collision on the net. Example BREAK
Parameter An arbitrary text. For certain cases sub tokens are detailed below. Description Any error situation on the network that is detected by the server or the interface.
Parameter Hex dump of LocoNet message Description This message is correctly formatted with respect to opcode bit and length, but the checksum check failed. Example ERROR CHECKSUM 83 2A
Parameter English text explaining the error Description When the interface or server detects an error below the layer that deals with individual bytes, it informs with this sub token. Example ERROR LINE invalid stop bit detected
Parameter Hex dump of LocoNet message Description When the server detects an incomplete or inconsistent message, it informs the clients with this sub token. Possible errors can be (list is not exhaustive, not all errors can be detected by all interfaces):
The server may not declare a message faulty just because it is not mentioned in the known specifications. It is the job of the client to decide which message shall be processed.
- opcode bit not found on message start
- opcode bit found before end of message
- length error detected
- timing error (long intra message gap)
Example ERROR MESSAGE DE AD BE EF
To relate the sequence of messages and events on the net and on the TCP connection, I drew some sequence diagrams. I guess they are not strictly UML, but I am willing to learn :-)
No link means, the diagram is still under construction
- successful data exchange on server side
- successful data exchange on client side, using CAbstractLoconetApi
- send requests and timeouts on server side
- send requests and timeouts on client side, using CAbstractLoconetApi
- concurrent send requests from two clients
|Author of this page: Stefan Bormann.||Site hosted by:|