Table of Contents

rocNET Protocol

Inhalt → Software-Zentralen → rocNET



Diese Seite wurde lange nicht mit der originären EN-Seite abgeglichen

Deshalb wird für weitere Informationen darauf verwiesen:

rocnet-prot-en



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:

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:


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

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