Table of Contents
rocNET Protocol
Diese Seite wurde lange nicht mit der originären EN-Seite abgeglichen
Deshalb wird für weitere Informationen darauf verwiesen:
Dies ist ein binäres Open-Source-Protokoll, entwickelt für die Kommunikation zwischen zwei oder mehreren Hardwareeinheiten in einem Peer-to-Peer-Netzwerk.
Software-Pakete werden in C bereitgestellt. Der C-Quelltext kann zum Teil auch als Basis für Embedded-Anwendungen dienen (PIC/Atmel).
In Entwicklung, Änderungen sind jederzeit möglich, Kommentare, Hinweise und Hilfe werden gerne entgegengenommen.
Warum 7-Bit Daten?
The design of a binary protocol with 8 bit data load will make it difficult to get the start byte of a packet unique. Mostly the defined start byte must be send twice or escaped when this code appears in the rest of the packet which results in undefined packet length.
If the overhead of a 8 bit data load is compared to the 7 bit slim size it is obvious for a small protocol with low data transport to choose the 7 bit. For protocols carrying much data the 7 bit data load is not a good choice.
Der Adressraum erstreckt sich von 1 bis 16383.
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
- 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:
At the moment there is no dialog for this, and only UDP is implemented with small packets.
Default settings:
- address: 224.0.0.1
- port: 4321
Packet Format
Small
Header | |||||||
group | address | action | data | ||||
group | addrH | addrL | code | length | n data bytes |
---|
Extended
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.
Receipient
Every unit in the network has its own ID. If left to zero all units must evaluate the packet.
Sender
The ID of the sender unit.
Address
Direct addressing of I/O and decoders.
Action
If the action needs an address it will be provided in the first two bytes of data part. (Extended format)
Data
The variable part of the packet which is action dependent.
For I/O and Loco actions the first 2 bytes are used to set the address.
The length may be set to zero if no further information is needed for the given action.
Validation
The protocol does not feature a checksum byte, but the packet is valid when the first byte has the 7th bit high and all following bytes low.
Network ID
bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
---|---|---|---|---|---|---|---|---|
function | 1 | extended=1 | command=0, event=1 | 5 bits ID (0-31) |
The network byte is the only one in the packet with bit 7 high to signal the start of a transmission.
Address High/Low
bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
---|---|---|---|---|---|---|---|---|
function | 0 | 7 bits high address (0-127) |
Calculating the Address
Address = addrL + addrH * 128
Group
bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
---|---|---|---|---|---|---|---|---|
function | 0/1 | small=0 | command=0, event=1 | 5 bit group code (0-31) |
In case of small package format bit 7 signals the start of a transmission.
The event bit is set incase of sensor reporting, throttle actions, SCD, ….
Action
bit | 7 | 6/5 | 4 | 3 | 2 | 1 | 0 | |
---|---|---|---|---|---|---|---|---|
function | 0 | type | 6 bit action code (0-63) |
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 | 0 | number of data bytes (0-127) |
Data
bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 |
---|---|---|---|---|---|---|---|---|
function | 0 | 7 data bits (0-127) |
Groups
Code | Description | Remark |
---|---|---|
1 | General | Command Station |
2 | Output | Switches, signals, … |
3 | Input | Sensors, buttons, … |
4 | Mobile decoders | Locomotives and functions |
5 | Stationary decoders | Multiport for inputs and outputs |
6 | Programming mobile | DCC CVs |
7 | Programming stationary | Including command stations |
8 | GP Data transfer | General purpose data transfer between modules |
9 | Clock | Fast clock |
General
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 |
Output
act | description | data 1 | data 2 | data 3 | data 4 | reply data 1 |
---|---|---|---|---|---|---|
1 | switch port | 0 = off, 1 = on | status | |||
2 | switch multi port¹ | port maskH | port maskL | valueH | valueL | status |
¹) Offset is address specified in the header.(small) Also use able for a coil pair.
Input
act | description | data 1 | data 2 | reply data 1 | reply data 2 | reply data 3 | reply data 4 |
---|---|---|---|---|---|---|---|
1 | port status | status | |||||
2 | multi port status¹ | port maskH | port maskL | port maskH | port maskL | valueH | valueL |
3 | report² | addrH | addrL | info1 | info2 |
¹) Offset is address specified in the header.(small)
²) A report is for extended inputs which for example provide the address of the passing train.
Mobile
Actions
request | reply | |||||||||
---|---|---|---|---|---|---|---|---|---|---|
code | description | data 1 | data 2 | data 3 | data 1 | data 2 | data 3 | data 4 | ||
1 | setup | protocol | number of functions | |||||||
2 | velocity | 0…127 | protocol, direction: 1=FWD 0=REV, lights | |||||||
3 | function | bit 0=F1, 1=F2, 2=F3, 3=F4, 4=F5, 5=F6 | bit 0=F7, 1=F8, 2=F9, 3=F10, 4=F11, 5=F12 | protocol | ||||||
4 | query | velocity | protocol, direction, lights | f1-6 | f7-12 | |||||
5 | dispatch put ¹ | ack | ||||||||
6 | dispatch get ² | ack | addrH | addrL | ||||||
7 | dispatch free ³ | ack | ||||||||
8 | link | addrH | addrL | ack | ||||||
9 | unlink | addrH | addrL | ack |
¹) Set mobile decoder ready for use with a throttle.
²) Get the dispatched mobile decoder address. (The address set in the header is ignored.)
³) Free the mobile decoder from the throttle.
DirF & Protocol Data:
bit | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 0 | |
---|---|---|---|---|---|---|---|---|---|
function | 0 | dir | lights | 0 | 4 bits protocol |
Protocol Type:
Code | Type | Description |
---|---|---|
0 | DCC 28 | NMRA DCC with 28 speed steps |
1 | DCC 128 | NMRA DCC with 128 speed steps |
2 | DCC 14 | NMRA DCC with 14 speed steps |
3 | MM 1 | Märklin/Motorola |
4 | MM 2 | Märklin/Motorola |
5 | MM 3 | Märklin/Motorola |
6 | MM 4 | Märklin/Motorola |
7 | MM 5 | Märklin/Motorola |
Extended Setup:
code | description | data 1 | data 2 | data 3 - 10 |
---|---|---|---|---|
1 | setup | protocol | number of functions | ASCII coded name |
If the length byte contains a length > 6 the loco name is following.
Acknowledge
Value | Description |
---|---|
0 | OK |
Stationary
Actions
code | description | data 1 | data 2 | data 3 | reply data 1 |
---|---|---|---|---|---|
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…127 where address is offset | protocol | status n |
4 | query single port | status | |||
5 | query port pair | status | |||
6 | query multi port | status n | |||
7 | report¹ | status n |
¹) 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 |