The LoconetOverTcp protocol

Contents

• Protocol overview
• Version history
• Syntax of the protocol lines
• Messages from client to server
• Messages from server to client
• Sequence diagrams

Protocol overview

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 history

• Version 0: June 2002
  The first and so far only version. Included line types:
  • VERSION
  • RECEIVE
• Version 1: September 2002
  The first version that includes full duplex operation. Included line types:
  • VERSION
  • RECEIVE
  • SEND
  • SENT

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 (13_dec=0D_hex) or lf (10_dec=0A_hex). 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 (32_dec=20_hex) from the token. The syntax of the parameter is described below with the token.

Messages from client to server

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.
Example	SEND A0 2F 00 70

Messages from server to client

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.
Example	RECEIVE 83 7C

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.
Description	This message is always sent as response to a "SEND" message. Proper timeouts still have to be invented.
Example	SENT ERROR Did not receive echo from LocoBuffer

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:

• 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

No link means, the diagram is still under construction

Author of this page: Stefan Bormann.

Site hosted by: