//DokuWiki formated text//
====== rocNet Protocol ======
[[:english|{{  :rocrail-logo-35.png}}]]
[[:english|Content]] -> [[:english#interfaces|Interfaces]] ->  **[[rocnet:rocnet-lib-en|rocNet]]** 
  * **Protocol** | [[rocnet-gateway-en|Gateway]]

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 also be used as base for embeded software. (PIC/Atmel)\\
 \\
**Work in progress, and open for any comment, advice and help.**\\
 \\
===== Why 7 bit data load =====
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.
 \\

===== 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.\\

 \\

===== Packet Format v0.2 =====
|  Header  ||||||||
|  network  |  receipient  ||  sender  ||  action  ||  data  ||
^ netid ^ rcptH ^ rcptL ^ sndrH ^ sndrL ^ group ^ code ^ length |  n data bytes |\\

=== 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.\\
=== Action ===
If the action needs an address it will be provided in the first two bytes of data part.\\
=== 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  |  7 bits ID |||||||\\
The network byte is the only one in the packet with bit 7 high to signal the start of a transmission.\\
 \\

=== Group ===
|  bit ^  7 ^ 6 ^ 5 ^ 4 ^ 3 ^ 2 ^ 1 ^ 0 ^
^  function | 0 | group code  |||||||\\
 \\

=== Address High/Low ===
|  bit ^  7 ^ 6 ^ 5 ^ 4 ^ 3 ^ 2 ^ 1 ^ 0 ^
^  function |  0  |  7 bits high address |||||||\\
== Calculating the Address ==
<code>Address = addrL + addrH * 128</code>\\
 \\

=== Action ===
|       bit ^  7 ^  6/5  ^^ 4 ^ 3 ^ 2 ^ 1 ^ 0 ^
^  function |  0 | type | action code  ||||||\\
==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 |||||||\\
 \\

=== Data ===
|  bit ^  7 ^ 6 ^ 5 ^ 4 ^ 3 ^ 2 ^ 1 ^ 0 ^
^  function |  0  |  7 data bits  |||||||\\
 \\

 \\

===== Groups =====
^ Code ^ Description ^
|  1 | General |
|  2 | Mobile decoders |
|  3 | Stationary decoders output |
|  4 | Stationary decoders input |
|  5 | Programming mobile decoders |
|  6 | Programming stationary decoders |
|  7 | Programming command stations |

==== 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 | terminate PT | | status |  |
|   5 | version | | versionH | versionL |
|   6 | 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 4 ^ data 5 ^ data 6 | data 1 | data 2 | data 3 | data 4 | data 5 | data 6 |
|   1 | setup | addrH | addrL | speed steps | protocol: 0=DCC, 1=MM, 2=SLX | protocol version | number of functions | | | | | | | 
|   2 | velocity | addrH | addrL | 0...127 | direction: 1=FWD 0=REV | | | | | | | | | 
|   3 | fg1 | addrH | addrL | 0...31 where bit 0=F1, 1=F2, 2=F3, 3=F4, 4=F0 | | | | | | | | | |
|   4 | fg2 | addrH | addrL | 0...15 where bit 0=F5, 1=F6, 2=F7, 3=F8 | | | | | | | | | |
|   5 | fg3 | addrH | addrL | 0...15 where bit 0=F9, 1=F10, 2=F11, 3=F12 | | | | | | | | | |
|   6 | fg4 | addrH | addrL | 0...15 where bit 0=F13, 1=F14, 2=F15, 3=F16 | | | | | | | | | |
|   7 | query |addrH | addrL |  | | | | velocity | direction | fg1 | fg2 | fg3 | fg4 |
|   8 | dispatch put ¹ |addrH | addrL |  | | | | ack | | | | | |
|   9 | dispatch get ² |addrH | addrL |  | | | | ack | addrH | addrL | | | |
|  10 | dispatch free ³ |addrH | addrL |  | | | | ack | | | | | |\\
|  11 | link | addrH | addrL | addrH | addrL | | | ack | | | | | |
|  12 | unlink | addrH | addrL | 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.\\
 \\ 
Extended Setup: 
^ code ^ description ^ data 1 ^ data 2 ^ data 3 ^ data 4 ^ data 5 ^ data 6 ^ data 7 - 14 ^
|   1 | setup | addrH | addrL | speed steps | protocol: 0=DCC, 1=MM, 2=SLX | protocol version | 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 ^ data 4 ^ data 5 | reply data 1 ^
|   1 | single port | addrH | addrL | 0,1 (off,on) | protocol | delay | status |
|   2 | port pair | addrH | addrL | 0,1 (green,red) | protocol | delay | status |
|   3 | multi port | addrH | addrL | 0...127 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¹ | | | | | | status n |\\
|   8 | query² | | | | | | data n |\\
¹) All connected stationary decoders should report status if receipient is set to zero.\\
²) The receipient specified in the header must process the request.\\
 \\

==== 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       |   |   |   |\\

