Traintastic DIY protocol
The Traintastic DIY protocol is designed to make it possible to develop custom hardware, e.g. by using the Arduino platform and use it with Traintastic.
The Traintastic DIY protocol is currently supported via:
- Serial port: baudrate and flow control can be chosen, data format is fixed at 8N1 (8 data bits, no parity, one stop bit)
- Network connection (TCP): port number can be chosen.
It is currently limited to:
- Reading inputs
- Controlling outputs
- Throttles
Other features might be added in the future.
Message format
Each Traintastic DIY protocol message starts with an opcode byte, besides the message type it also contains the data payload length in the lowest nibble.
If the lowest nibble is 0xF the the second byte of the message determines the payload length.
The message always ends with a checksum byte, the checksum is the result of XOR-ing of all message bytes.
Examples:
The lowest nibble of the first byte is0 indicating a zero byte payload.
The checksum is identical to the opcode, there is no data to XOR with.
The lowest nibble of the first byte is 4 indicating a 4 byte payload.
The checksum is 0x24 XOR 0x11 XOR 0x22 XOR 0x33 XOR 0x44 = 0x60.
The lowest nibble of the first byte is F indicating that the second byte must be used as payload length, 32 byte.
The checksum is 0x2F XOR 0x20 XOR all payload bytes.
Messages
Messages are send by Traintastic to the DIY device, for most messages the DIY device sends a response message. Some messages are sent unsolicited by the DIY device to Traintastic if changes are detected by the DIY device.
| Command | |
|---|---|
| Heartbeat | Mandatory |
| Get information | Mandatory |
| Get features | Mandatory |
| Get input state | Mandatory if input feature flag is set |
| Set input state | Mandatory if input feature flag is set |
| Get output state | Mandatory if output feature flag is set |
| Set output state | Mandatory if output feature flag is set |
| Throttle set function | Mandatory if throttle feature flag is set |
| Throttle set speed/direction | Mandatory if throttle feature flag is set |
| Throttle subscribe/unsubscribe | Mandatory if throttle feature flag is set |
Heartbeat
The heartbeat message is sent by Traintastic to check if the DIY device is (still) present, the DIY device responds with a heartbeat message. The heartbeat rate can be configured in Traintastic, by default the heartbeat message is one second after the last message is received from the DIY device.
Request message
Response message
Get information
The get information message is the first message sent after connecting. The DIY device responds with an information message containing a description of the connected DIY device. This is pure informational and displayed in the message console.
Request message
Response message
Get features
The get features message is the second message sent by Traintastic after connecting. The DIY device responds with a features message containing flags which indicate what is supported by the DIY device.
Request message
Response message
<FF1>feature flags 1:- bit 0: input feature flag: set if the DIY device has inputs
- bit 1: output feature flag: set if the DIY device has outputs
- bit 2: throttle feature flag: set if the DIY device is a throttle
- bit 3...7: reserved, must be
0
<FF2>feature flags 2, reserved must be0x00<FF3>feature flags 3, reserved must be0x00<FF4>feature flags 4, reserved must be0x00
Get input state
Sent by Traintastic to retrieve the current input state. Address zero has a special meaning, it is used as broadcast address to retrieve the current state of all inputs.
Request message
<AH>high byte of 16bit input address<AL>low byte of 16bit input address
Response
If the address is non zero the DIY device responds with a set input state message containing the current state of the input address.
If the address is zero the DIY device responds with multiple set input state messages, one for each know input address or send a single set input state message with address zero and state invalid to inform Traintastic that the address zero request is not supported.
Set input state
Sent by the DIY device as response to the get input state message and must be sent by the DIY device whenever an input state changes.
Message
<AH>high byte of 16bit input address<AL>low byte of 16bit input address<S>input state:0x00if input state is unknown0x01if input state is low/false0x02if input state is high/true0x03if input is invalid (only as response to a get input state message)0x04...0xFFare reserved, do not use
Examples
Input 18 state changed to high/true Input 674 state changed to low/falseGet output state
Sent by Traintastic to retrieve the current output state. Address zero has a special meaning, it is used as broadcast address to retrieve the current state of all outputs.
Request message
<AH>high byte of 16bit output address<AL>low byte of 16bit output address
Response message
If the address is non zero the DIY device responds with a set output state message containing the current state of the output address.
If the address is zero the DIY device responds with multiple set inpoutputut state messages, one for each know output address or send a single set output state message with address zero and state invalid to inform Traintastic that the address zero request is not supported.
Set output state
Sent by Traintastic to change the state of an output, the DIY device responds with a get output state message containing the new output state, if for some reason the output state cannot be the current state must be send. Sent by the DIY device as response to the get output state message and must be sent by the DIY device whenever an output state changes.
Message
<AH>high byte of 16bit output address<AL>low byte of 16bit output address<S>output state:0x00if output state is unknown0x01if output state is low/false0x02if output state is high/true0x03if output is invalid (only as response to a get output state message)0x04...0xFFare reserved, do not use
Throttle set speed/direction
Set locomotive decoder speed and/or direction.
Once a Throttle set speed/direction message is sent, the throttle id will automatically be subscribed for speed, direction and function changes of the locomotive decoder specified by the decoder address. To stop receiving these changes a throttle unsubscribe message has to be send to Traintastic by the DIY device.
Message
<TH>high byte of 16bit throttle id<TL>low byte of 16bit throttle id<AH>:- bit 0...5: highest 6bit of 14bit decoder address
- bit 6 is reserved and must be
0 - bit 7 can be set to force a DCC long address
<AL>lowest 8bit of 14bit decoder address<SP>speed (step),0...<SM><SM>maximum speed (step), set to0for emergency stop<FL>flags:- bit 0: direction
1=forward,0=reverse - bit 1...5: reserved, must be
0 - bit 6: set to set direction
- bit 7: set to set speed
- bit 0: direction
Throttle id can be used to distinguish different throttles within the DIY device if it represents multiple throttles. If the DIY device is a single throttle use 0x00 0x00 as throttle id.
Internally Traintastic uses a value between 0 and 1 for the speed where 0 is stop and 1 is full speed. To determine a value between 0 and 1 Traintastic calculates <SP> / <SM>. Set <SP> and <SM> both to zero for an emergency stop.
Using the flags bit 6 and 7 it is possible to set speed and direction, just the speed, just the direction or nothing. Setting nothing still subscribes the throttle id for speed, direction and function changes.
Examples
Set speed to 50% (= 7 / 14) in forward direction for decoder with address 3. Emergency stop decoder with address 3, don't change direction.Throttle set function
Enable/disable locomotive decoder function.
Once a Throttle set function message is sent, the throttle id will automatically be subscribed for speed, direction and function changes of the locomotive decoder specified by the decoder address. To stop receiving these changes a throttle unsubscribe message has to be send to Traintastic by the DIY device.
Message
<TH>high byte of 16bit throttle id<TL>low byte of 16bit throttle id<AH>:- bit 0...5: highest 6bit of 14bit decoder address
- bit 6: reserved and must be
0 - bit 7: set to force a DCC long address
<AL>lowest 8bit of 14bit decoder address<FN>:- bit 0...6: function number
- bit 7: function value
Examples
Enable F0 for decoder with address 3. Disable F1 for decoder with long address 5.Throttle subscribe/unsubscribe
Subscribe/unsubscribe for change events. Traintastic will send a throttle set speed/direction message whenever speed or direction changes and a throttle set function message for every function that changes state.
Note
Subscribe is supported since v0.3, older version only support unsubscribe.
Message
<TH>high byte of 16bit throttle id<TL>low byte of 16bit throttle id<AH>:- bit 0...5: highest 6bit of 14bit decoder address
- bit 6: action:
0= Unsubscribe,1= Subscribe - bit 7: set to force a DCC long address
<AL>lowest 8bit of 14bit decoder address
When subscribing Traintastic will reply with a throttle set speed/direction and a throttle set function message for every function that is known for the address.
When unsubscribing Traintastic will reply with the same message to confirm the unsubscribe.