Table of Contents
rocNET Protocol
Inhoud → Central Stations → rocNET
This is an binary Open Source protocol intended for communication between two or more, in a peer to peer network, hardware units.
Software stubs will be made available in C. The C source can, partly, also be used as base for embeded software. (PIC/Atmel)
Work in progress, can change any moment, open for any comment, advice and help.
Features
- Addressing range is from 1 to 65535.
- Address 0 is broadcast to all.
Masterless Network
The idea is to build a network of two or more units of operation.
There are different types of units:
- I/O, for switches, signals, sensors, …
- DCC/MM/SLX generators
- WLAN enabled stationary and mobile decoders
- computers
- …
All should have their own unique ID which is used as sender/receipient parameter in the header.
The unit who is processing all messages and sends a lot of them can be entitled to be the master of the network, but in fact it is only a player in the game. So in the case of Rocrail the computer running this software could be seen as the master.
Setup
RocNET has a dedicated node for setting up the communication:
Only UDP is supported.
Default settings:
- address: 224.0.0.1 (http://en.wikipedia.org/wiki/Multicast_address#IPv4_multicast_addresses)
- port: 4321
Packet Format
| Header | ||||||||
| network | receipient | sender | action | data | ||||
| netid | rcptH | rcptL | sndrH | sndrL | group | code | length | n data bytes |
|---|---|---|---|---|---|---|---|---|
Packet Content
Network ID
To group units in a large system. Leave zero if there is only one active network.
Receipient
Every unit in the network has its own ID.
If left to zero all units must evaluate the packet. This can be of use for queries to see which devices are available.
Sender
The ID of the sender unit. Rocrail Server default ID is 1.
A value of "0" means undefined.
Action
If the action needs an address it will be provided in the first two bytes of data part. (Extended format)
Length
Netto number of following data bytes.
Data
The variable part of the packet which is action dependent.
The length may be set to zero if no further information is needed for the given action.
Network ID
| bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
| function | 8 bits ID (0-255) | |||||||
Zero is for all networks.
Address/ID High/Low
| bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
| function | 8 bits ID (0-255) | |||||||
Calculating the Address/ID
ID = idL + idH * 256
Group
| bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
| function | 8 bit group code (0-255) | |||||||
Code
| bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | |
|---|---|---|---|---|---|---|---|---|---|
| function | 3 bit type (0-7) | 5 bit code (0-31) | |||||||
Type
- 0 request
- 1 event
- 2 reply
- 3 request; reply expected
If the type is an event or reply, no real I/O action should be taken on the specified address; mostly the I/O with this address signals a state change.
Length
| bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
| function | number of data bytes (0-255) | |||||||
Data
| bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|---|
| function | 8 data bits (0-255) | |||||||
Groups
| Code | Description | Remark |
|---|---|---|
| 1 | Command Station | Command Station |
| 2 | Mobile decoders | Locomotives and functions |
| 3 | Stationary decoders | Multiport for inputs and outputs |
| 4 | Programming mobile | DCC CVs |
| 5 | Programming stationary | Including command stations |
| 6 | GP Data transfer | General purpose data transfer between modules |
| 7 | Clock | Fast clock |
| 8 | Sensor | Position determination |
Command Station
Actions
| act | description | data 1 | reply data 1 | reply data 2 |
|---|---|---|---|---|
| 0 | NOP | 0 | ||
| 1 | query | status | ||
| 2 | track power | 0 = off, 1 = on | status | |
| 3 | halt | status | ||
| 4 | version | versionH | versionL | |
| 5 | PT on/off | on/off | on/off |
The address is optional and can be used to point at a single booster.
Status
| 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
|---|---|---|---|---|---|---|---|
| 0 | PT busy | idle | power |
Mobile
Actions
| request | reply | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| code | description | data 1 | data 2 | data 3 | data 1 | data 2 | data 3 | data 4 | ||
| 0 | NOP | 0 | ||||||||
| 1 | setup | protocol | number of functions | |||||||
| 2 | velocity³ | 0…255 | direction¹ | lights¹ | ||||||
| 3 | function | F-Group | F1-F8² | |||||||
| 4 | query | code | sub-code | code | sub-code | response depends on code | ||||
¹) Leave unchanged if bit 7 is not set in this byte.
²) Lights if F-Group = 0.
³) Alternatively the velocity can be send with only one byte in which bit 7 controls the direction and the velocity range ist 0…127.
Protocol Type
| Code | Type | Description |
|---|---|---|
| 0 | 256 | 256 step interpreted |
| 1 | DCC 28 | NMRA DCC with 28 speed steps |
| 2 | DCC 128 | NMRA DCC with 128 speed steps |
| 3 | DCC 14 | NMRA DCC with 14 speed steps |
Examples
Stop all locos send by the Rocrail server:
| netid | rcptH | rcptL | sndrH | sndrL | group | code | length | velocity | direction | lights |
|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 0 | 0 | 0 | 1 | 2 | 2 | 3 | 0 | 0 | 0 |
| all | all | all | srvr | srvr | mobile | velocity | ||||
Binary representation:
00 00 00 00 01 02 02 03 00 00 00
Direction and lights are left unchanged because bit 7 of both bytes are not set.
Set velocity by the Rocrail server:
- Loco address = 291
- Velocity = 48
- Direction = forwards
- Lights = off
| netid | rcptH | rcptL | sndrH | sndrL | group | code | length | velocity | direction | lights |
|---|---|---|---|---|---|---|---|---|---|---|
| 0 | 1 | 35 | 0 | 1 | 2 | 2 | 3 | 48 | 129 | 128 |
Binary representation:
00 01 23 00 01 02 02 03 30 81 80
Stationary
Actions
| code | description | data 1 | data 2 | data 3 | reply data 1 | reply data 2 | reply data 3 | reply data 4 |
|---|---|---|---|---|---|---|---|---|
| 0 | NOP | 0 | ||||||
| 1 | single port | 0,1 (off,on) | protocol | delay | status | |||
| 2 | port pair | 0,1 (close,throw) address is first port of pair | protocol | delay | status | |||
| 3 | multi port | port mask | 0…255 where address is offset | protocol | status n | |||
| 4 | query single port | addrH | addrL | status | ||||
| 5 | query port pair | addrH | addrL | status | ||||
| 6 | query multi port | addrH | addrL | status n | ||||
| 7 | report¹ | addrH | addrL | status1 | status2 |
¹) All connected stationary decoders should report status if receipient is set to zero.
Programming
For programming stationary decoders the address represents the module address.
Actions
| code | description | data 1 | data 2 | data 3 | data 4 | reply data 1 | reply data 2 | reply data 3 | reply data 4 |
|---|---|---|---|---|---|---|---|---|---|
| 1 | write | registerH | registerL | valueH | valueL | registerH | registerL | valueH | valueL |
| 2 | read | registerH | registerL | registerH | registerL | valueH | valueL | ||
| 3 | copy | destH | destL | data n | ack | ||||
Clock
Actions
| code | description | data 1 | data 2 | data 3 | data 4 | data 5 | data 6 | data 7 | data 8 |
|---|---|---|---|---|---|---|---|---|---|
| 1 | set | yearH | yearL | month | day | hour | minutes | seconds | div |
| 2 | sync | yearH | yearL | month | day | hour | minutes | seconds | div |
Sensor
Actions
| code | description | data 1 | data 2 | data 3 |
|---|---|---|---|---|
| 1 | report | addrH¹ | addrL¹ | status |
¹) Address of the reporting loco.
The sensor ID is set in the header; Sender.