Innovative Model Railroad Control System

User Tools

Site Tools

Trace:
rocnet:rocnet-prot-en

Differences

This shows you the differences between two versions of the page.


—rocnet:rocnet-prot-en [2019/02/10 08:58] (current) – created - external edit 127.0.0.1
Line 1: Line 1:
 +====== RocNet Protocol ======
 +[[:english#command_stations|{{  :interface.png}}]][[:english|{{  :rocrail-logo-35.png}}]][[:rocnet:rocnetnode-en|{{ :rocnet:rocnet-hw.png}}]]
 +[[:english|Content]] -> [[:english#command_stations|Command Stations]] ->  **[[rocnet:rocnet-prot-en|RocNet]]** 
 +<html><!--  * **8 bit UDP** | [[rocnet-prot7-en|7 bIt Serial]]--></html>
 +  * [[:rocnet:rocnetnode-en|RocNetNode]]
 +    * [[:rocnet:rocnetnode-hwsetup-en|RocNetNode Setup]] | [[:rocnet:rocnetnode-setup-en|RocNetNode Configuration]] | [[:rocnet:rocnetnode-img-en|Installer package]]
 +    * [[:gca1-pi01-en|GCA-Pi01]] | [[:rocnet:pi01can-en|Pi01CAN]] | [[:gca_pi02-en|GCA-Pi02]] | [[:gca-pi03-en|GCA-PI03]] | [[:gca-pi04-en|GCA-PI04]] | [[:gca-pi05-en|GCA-Pi05]] | [[:gca-pi06-en|GCA-Pi06]] | [[:GCA-PI07-en|GCA-PI07]] | [[:rocnet:rocdisplay-en|RocDisplay]]
 + \\
 +**RocNet => Rocrail(r) 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 =====
 +{{ rocnet:rocnet-wlan.png?250}}
 +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 generators
 +  * WLAN enabled stationary and mobile decoders
 +  * computers
 +  * ...
 +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 =====
 +{{:rocnet:rocnet-en.png}}{{:rocnet:rocnet-nodelist-en.png}}\\
 +More information about setting up the RocNet connection: __**[[:rocnet:rocnetnode-hwsetup-en#software_setup|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:__\\
 +  * address: 224.0.0.1 (http://en.wikipedia.org/wiki/Multicast_address#IPv4_multicast_addresses)
 +  * port: 4321 -> Make sure that no other service is running on the same port!
 + \\
 +
 +====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 HEXA((One byte is represented by two ASCII characters.)). (The value of 255 is represented in HEXA as "FF", 100 as "64" and so on...)\\
 +The used ASCII characters:\\
 +<code>
 +@ 0 1 2 3 4 5 6 7 8 9 A B C D E F
 +</code>
 +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:
 +<code>
 +@000000000101020101
 +</code>
 +
 + \\
 +
 +====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:__\\
 +  * device: com1
 +===Example===
 +<code xml>
 +  <digint iid="rn-1" lib="rocnet" sublib="serial" device="com1" bps="19200">
 +    <rocnet id="1" crc="true"/>
 +  </digint>
 +</code>
 +
 + \\
 +
 +===== 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 ==
 +<code>8 bit ID = idL + idH * 256</code>
 +<code>7 bit ID = idL + idH * 128</code>\\
 +
 +
 +=== 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==
 +  * 0 request
 +  * 1 event
 +  * 2 reply
 +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==
 +<code c>
 +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;
 +}
 +</code>
 +
 + \\
 +
 +===== 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    | [[:ddx-en#motorola_protocol_specifics|Märklin/Motorola]] | 
 +|    4 | MM 2    | [[:ddx-en#motorola_protocol_specifics|Märklin/Motorola]] |
 +|    5 | MM 3    | [[:ddx-en#motorola_protocol_specifics|Märklin/Motorola]] |
 +|    6 | MM 4    | [[:ddx-en#motorola_protocol_specifics|Märklin/Motorola]] |
 +|    7 | MM 5    | [[:ddx-en#motorola_protocol_specifics|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:
 +<code>
 +00 00 00 00 01 02 02 03 00 00 00
 +</code>
 +ASCII HEXA representation:
 +<code>
 +@0000000001020203000000
 +</code>
 +
 +Direction and lights are left unchanged because bit 6 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 |       65 |    64 |
 +Binary representation:
 +<code>
 +00 01 23 00 01 02 02 03 30 41 40
 +</code>
 +ASCII HEXA representation:
 +<code>
 +@0001230001020203304140
 +</code>
 + \\
 +
 +==== 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:
 +  * Code = 1
 +  * Port = port
 +\\
 +
 +=====Files=====
 +  * {{:rocnet:rocnet-const.h.zip}} Header file for C.
rocnet/rocnet-prot-en.txt · Last modified: 2019/02/10 08:58 by 127.0.0.1