TCP Communication

WORK IN PROGRESS - MIGHT BY SUBJECT TO CHANGE

Both the controller and the client GUI send their data as JSON Objects.
In JSON every Object is an unordered set of key/value pairs. The values of these pairs can be a JSON Object, a JSON Array or a primitive value (integer, string, boolean or null).
For more information or a complete grammar see http://www.json.org/.

Messages sent by Controller

Every message must provide the keys msgType and data.
Valid values for msgType are log, error or status.

Log messages

For log messages the data segment consists of a JSON Array, containing zero or more strings.

Error messages

For error messages the data segment consists of one single string, describing the error.

Status messages

In status messages the data segment is a JSON Object which must contain the following key/value pairs.

debug - true if the controller is set to verbose debug output, false otherwise
cleanup - true after cleanup mode has been engaged, false before that point
pause - true while the controller is paused, false otherwise
trainCount - an integer with the number of active trains on the railway
trains - a JSON Array with the data of all trains, each entry is a JSON Object with these values
- trainNum - the individual controller number of the train
- spdSlow - the integer PWM value of this train while driving slow
- spdCaution - the integer PWM value of this train while driving caution
- spdNormal - the integer PWM value of this train while driving normally
- currentIndex -an integer describing the current position in the schedule
- schedule - a JSON Array of integer values, representing the station tracks in the normal encoding (Hoermann API) NEED TO CHANGE THIS TO ENABLE KH-REVERSE TRACKS
locks - a JSON Array containing the current value of the track permissions, ordered by the default encoding (Hoermann API)

Sample status

{"msgType":"status",
	"data":{
		"debug":false,
		"cleanup":false,
		"pause":false,
		"trainCount":8,
		"trains":[
			{"trainNum":0, "spdSlow":40, "spdCaution":60, "spdNormal":100, "currentIndex":2, "schedule":[8, 10, 25, 29, 41, 43]},
			{"trainNum":1, "spdSlow":50, "spdCaution":70, "spdNormal":100, "currentIndex":0, "schedule":[8]},
			... ],
		"locks":[-1, -1, -1, 5, -1, -1, 2, 10, -1, -1, ..., -1]}}

Messages received by controller

Every message must contain the key command.
Depending on the command, additional keys might be required.

Valid commands

SHUTDOWN - Causing the controller to end the program and close all sockets
LOGOUT - Closing the connection, leaving the controller running
STATUS - Poll for the current status, should trigger a status reply message
CLEANUP - Start the cleanup procedure, sending the trains back to their home tacks
DEBUG - enable or disable verbose output, must supply additional payload
- state - boolean value, true if verbose output should be activated
PAUSE - suspend or resume the controller, must supply additional payload
- state - boolean value, true if controller should be suspended
LIGHT - activate or deactivate the lights on the railway, must supply additional payload
- state - boolean value, true if lights should be lit
WAIT - Force a train to wait in the next station, must supply additional payload
- train - integer train identification
START - Force a waiting train to immediately abort the waiting timer, must supply additional payload
- train - integer train identification
SCHEDULE - Set the new schedule for a train, needs additional payload
- train - integer train identification
- currentIndex - current integer position in the schedule array
- tracks - a JSON Array of integer values, representing the station tracks in the normal encoding (Hoermann API) NEED TO CHANGE THIS TO ENABLE KH-REVERSE TRACKS
SPEED - Change the speed settings of a train, needs additional payload
- train - integer train identification
- speeds - JSON Array with three integer values spdSlow, spdCaution, spdNormal
TIME - Change the waiting times for a train
- train - integer train identification
- times - DEFINE A FORMAT FOR THIS

Page tree