Table of Contents

RocNet Protocol

Content → Command Stations → RocNet


RocNet ⇒ Rocrail® Network

This is an binary Open Source protocol intended for communication between two or more, in a peer to peer network, hardware units.


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/recipient parameter in the header.
The unit who is processing all messages and sends a lot of them can be entitled to be the host 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 host.


Reserved IDs

ID Description Note
0 Broadcast All nodes will evaluate it.
1 Rocrail server. This is the recommended and default ID. A second server should use 65001+.
65535 Initial node ID; A new ID will be assigned by the Rocrail server.


Setup


More information about setting up the RocNet connection: Setup

UDP 8 bit

UDP is the default and the recommended communication method which is also used in combination with the RocNetNodes.
All other methods are restricted to "one-to-one" communication.

Default settings:


ASCII HEXA 16 bit

This can be used for serial communication using ASCII characters only.
A packet start is marked with an @ and the rest of it is HEXA1). (The value of 255 is represented in HEXA as "FF", 100 as "64" and so on…)
The used ASCII characters:

@ 0 1 2 3 4 5 6 7 8 9 A B C D E F

After detecting the start of a packet the first 16 character (8 bytes), the header, can be read.
The data length is in the last two characters of the header. In this case the length must be multiplied by two to read the data part.

Example:
A track power on command send from the server: 

@000000000101020101


Serial 7 bit

:!: The netid byte must have bit 7, 0x80, set hight to signal the start of the packet. All other byte may only use 7 bit, 0x7F, data load.

Default settings:

Example

  <digint iid="rn-1" lib="rocnet" sublib="serial" device="com1" bps="19200">
    <rocnet id="1" crc="true"/>
  </digint>


Packet Format

8 Byte Header
network receipient sender action data crc
netid idH idL idH idL group code length n data bytes optional for 7-bit



Packet Content

Network ID

To group units in a large system. Leave zero if there is only one active network.
Bit 7 must be set in case of 7 bit serial.
Alternatively it can be used as location ID for logically grouping nodes in an overview dialog.

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" is for broadcasting.

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
8 bits ID (0-255)
7 bits 1 ID (0-127)

ID zero is for all networks.

Node ID High/Low

bit 7 6 5 4 3 2 1 0
8 bits ID (0-255)
7 bits 0 ID (0-127)
Calculating the Address/ID
8 bit ID = idL + idH * 256
7 bit ID = idL + idH * 128


Group

bit 7 6 5 4 3 2 1 0
8 bit group code (0-255)
7 bit 0 group code (0-127)


Code

bit 7 6 5 4 3 2 1 0
function 0 2 bit type (0-3) 5 bit code (0-31)
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
8 bit number of data bytes (0-255)
7 bit 0 number of data bytes (0-127)


Data

bit 7 6 5 4 3 2 1 0
8 bits 8 data bits (0-255)
7 bits 0 7 data bits (0-127)


CRC

Optional for 7-bit serial connections:
The 1's complement of the byte wise Exclusive OR of all the bytes in the message.

Code example
unsigned char rnChecksum(const unsigned char *b, int len) {
  unsigned char chksum = 0xff;
  int i;
  for (i = 0; i < len; i++) {
    chksum ^= b[i];
  }
  return chksum;
}


Groups

Code Description Remark MQTT Topic
0 Host Rocrail rocnet/ht
1 Command Station Command Station rocnet/cs
2 Mobile decoders Locomotives and functions rocnet/lc
3 Stationary decoders Multiport for inputs and outputs rocnet/dc
4 Programming mobile DCC CVs rocnet/pm
5 Programming stationary Including command stations rocnet/ps
6 GP Data transfer General purpose data transfer between modules rocnet/gp
7 Clock Fast clock rocnet/ck
8 Sensor Position determination rocnet/sr
9 Output rocnet/ot
10 Input rocnet/in
11 Sound rocnet/sn
12 Display rocnet/dp


Host

Actions

act description data 1 data 2 data 3 data 4 data 5 data 6 data 7 reply data 1 reply data 2
1 Shutdown


Command Station

Actions

act description data 1 data 2 data 3 data 4 data 5 data 6 data 7 data 8 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
6 velocity addrH addrL 0…127 direction lights protocol speed steps
7 function addrH addrL F1-F8 F9-F16 F17-F24 protocol changed function + 0x80 lights F25-F32
8 POM addrH addrL cvH cvL value operation: 0=get, 1=set
9 Switch command type address
10 Output command type value address


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 4 data 5 data 6 data 7 data 1 data 2 data 3 data 4
0 NOP 0
1 setup protocol number of functions
2 velocity 0…127 direction lights mass steps
3 function F1-F8 F9-F16 F17-F24 changed function F25-F32
4 query code sub-code code sub-code response depends on code
5 fieldcmd base address V_raw dirf fg 0+1 fg 2+3 fg 4+5 fg 6+7


Protocol Type

Code Type Description
0 256 256 step interpreted (8 bit only)
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
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


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

ASCII HEXA representation: 

@0000000001020203000000

Direction and lights are left unchanged because bit 6 of both bytes are not set.


Set velocity by the Rocrail server:
netid rcptH rcptL sndrH sndrL group code length velocity direction lights
0 1 35 0 1 2 2 3 48 65 64

Binary representation: 

00 01 23 00 01 02 02 03 30 41 40

ASCII HEXA representation: 

@0001230001020203304140


Stationary

Actions

Reply
code description data 1 data 2 data 3 data 4 data 1 data 2 data 3 data 4 data 5 data 6 data 7
0 NOP 0
1 single port 0,1 (off,on) protocol/type delay port status
2 port pair 0,1 (close,throw) protocol/type delay port status
3 multi port port mask 0…255 where address is offset protocol/type port status n
4 query single port port addrH addrL status
5 query port pair port addrH addrL status
6 query multi port port addrH addrL status n
7 report¹ addrH addrL status1 status2
8 identify class manuID versionH versionL nr I/O subipH subipL
9 shutdown 1=nodes should shutdown too rc
10 acknowledge action code optional portnr
11 show²
12 startofday
13 errorreport error class reason addrH addrL

¹) All connected stationary decoders should report status if recipient is set to zero.
²) The push button on the node will trigger the RocNetNode dialog to popup with the node selected. A show request from the host will flash the LED on the node.

Programming

For programming stationary decoders the address represents the module address.

Actions

code description data 1 data 2 data 3 data 4 data 5 reply data 1 reply data 2 reply data 3 reply data 4 reply data 5 reply data 6 reply data 7 reply data 8 reply data 9 reply data 10 reply data 11 reply data 12 reply data 13
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
4 read port config from port to port port# value type delay
5 write port config port# value type delay
6 set RocNet ID idH idL subipH subipL
7 read options iotype flags cstype csdevice I2C scan 0x20 H I2C scan 0x20 L I2C scan 0x30 H I2C scan 0x30 I2C scan 0x40 H I2C scan 0x40 L adc threshold I2C scan 0x50 H I2C scan 0x50 L
8 write options iotype:
0=GPIO, 1=I2c-0, 2=I2C-1 		flags:
bit0=ack 		cstype:
0=none, 1=dcc232, 2=sprog 		csdevice:
0=/dev/ttyUSB0, 1=/dev/ttyUSB1
9 read macro number number port delay type value
10 write macro number port delay type value
11 update revH revL
12 read port event from port to port port# idH idL port
13 write port event port# idH idL port
14 delete port config port#


Channels
code description d1 d2 d3 d4 d5 d6 d7 d8 d1 d2 d3 d4 d5 d6 d7 d8
15 read channel config from channel to channel channel# offposH offposL onposH onposL offsteps onsteps options
16 write channel config channel# offposH offposL onposH onposL offsteps onsteps options
17 delete channel config channel#
18 set channel channel# valueH valueL


The read, write and delete port/channel may contain up to 8 port configurations.
The read and write macro may contain up to 8 commands.

Output

Type

Type Value
switch 0
light 1
servo 2
sound 3
motor 4
analog 5
macro 6
backlight 7

Actions

code description data 1 data 2 data 3 data 4 data 5 data 6 data 7 data 8
0 off type value address
1 on type value address
1 (macro) on 6 0 aspect macro offset


Input

The Input Group is not used and not defined; Use the Sensor group.

Actions

code description data 1 data 2 data 3 data 4 data 5 data 6 data 7 data 8


Clock

Actions

code description data 1 data 2 data 3 data 4 data 5 data 6 data 7 data 8 data 9
1 set yearH yearL month day hour minutes temperature divider brightness
2 sync yearH yearL month day hour minutes temperature divider brightness


Sound

Actions

code description data 1-n
1 play sound file name
2 setpath sound path
3 setplayer sound player program name


Display

Actions

code description data 1 data 2 data 3-n
1 text addr displaynr text for show on the display


Sensor

Actions

code description data 1 data 2 data 3 data 4 data n
1 report addrH¹ addrL¹ status port identifier (RFID)

¹) Address of the reporting loco.
The sensor ID is set in the header; Sender.
A sensor secure ack is done with the stationary acknowledge message:


Files

1)
One byte is represented by two ASCII characters.