The LoconetOverTcp protocol

 SourceForge   Overview   Protocols   

Note: this is a draft version for review. Changes with respect to the version 1 are marked with red text color.

Contents

Protocol overview

A small summary of design goals:
Token Sender of
message		 Version number
0 1 2
VERSION Server yes yes yes
RECEIVE Server yes yes yes
SEND Client no yes yes
SENT Server no yes yes
TIMESTAMP Server no no yes
BREAK Server no no yes
ERROR CHECKSUM Server no no yes
ERROR LINE Server no no yes
ERROR MESSAGE Server no no yes

Version history

Syntax of the protocol lines

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.

Messages from client to server

SEND <byte sequence>

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

Messages from server to client

VERSION <info>

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

RECEIVE <byte sequence>

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

SENT OK|ERROR <info>

Parameter two possibilities:
  • OK _comment_
  • ERROR _comment_
"_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
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

TIMESTAMP <microseconds>

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

BREAK <microseconds>

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

ERROR <info>

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.

ERROR CHECKSUM <byte sequence>

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

ERROR LINE <info>

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

ERROR MESSAGE <byte sequence>

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):
  • opcode bit not found on message start
  • opcode bit found before end of message
  • length error detected
  • timing error (long intra message gap)
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.
Example ERROR MESSAGE DE AD BE EF

Sequence diagrams

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 :-)
Available diagrams:
 SourceForge   Overview   Protocols   
Author of this page: Stefan Bormann. Valid HTML 4.01 Transitional Site hosted by: SourceForge Logo