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 ====== | ||
+ | [[: | ||
+ | [[: | ||
+ | < | ||
+ | * [[: | ||
+ | * [[: | ||
+ | * [[: | ||
+ | \\ | ||
+ | **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: | ||
+ | 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/ | ||
+ | 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: __**[[: | ||
+ | \\ | ||
+ | |||
+ | ====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 " | ||
+ | |||
+ | __Default settings: | ||
+ | * address: 224.0.0.1 (http:// | ||
+ | * 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 " | ||
+ | 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: | ||
+ | * device: com1 | ||
+ | ===Example=== | ||
+ | <code xml> | ||
+ | <digint iid=" | ||
+ | <rocnet id=" | ||
+ | </ | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ===== Packet Format ===== | ||
+ | | 8 Byte Header | ||
+ | | network | ||
+ | ^ 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 " | ||
+ | === 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 == | ||
+ | < | ||
+ | < | ||
+ | |||
+ | |||
+ | === 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; | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ===== Groups ===== | ||
+ | ^ Code ^ Description ^ Remark ^ MQTT Topic ^ | ||
+ | | 0 | Host | Rocrail | '' | ||
+ | | 1 | Command Station | ||
+ | | 2 | Mobile decoders | ||
+ | | 3 | Stationary decoders | ||
+ | | 4 | Programming mobile | ||
+ | | 5 | Programming stationary | Including command stations | '' | ||
+ | | 6 | GP Data transfer | ||
+ | | 7 | Clock | Fast clock | '' | ||
+ | | 8 | Sensor | ||
+ | | 9 | Output | ||
+ | | 10 | Input | ||
+ | | 11 | Sound | ||
+ | | 12 | Display | ||
+ | |||
+ | \\ | ||
+ | |||
+ | ==== 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 | ||
+ | | 7 | function | addrH | addrL | F1-F8 | F9-F16 | ||
+ | | 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 | | ||
+ | \\ | ||
+ | |||
+ | ==== Mobile ==== | ||
+ | === Actions === | ||
+ | ^ request ^^^^^^^^| | ||
+ | ^ 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 | | ||
+ | | 1 | setup | protocol | number of functions | | | | | | | | | | ||
+ | | 2 | velocity | 0...127 | direction | lights | ||
+ | | 3 | function | F1-F8 | F9-F16 | ||
+ | | 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 | [[: | ||
+ | | 4 | MM 2 | [[: | ||
+ | | 5 | MM 3 | [[: | ||
+ | | 6 | MM 4 | [[: | ||
+ | | 7 | MM 5 | [[: | ||
+ | \\ | ||
+ | ===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:== | ||
+ | * 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: | ||
+ | < | ||
+ | 00 01 23 00 01 02 02 03 30 41 40 | ||
+ | </ | ||
+ | ASCII HEXA representation: | ||
+ | < | ||
+ | @0001230001020203304140 | ||
+ | </ | ||
+ | \\ | ||
+ | |||
+ | ==== Stationary ==== | ||
+ | === Actions === | ||
+ | | |||||| | ||
+ | ^ 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/ | ||
+ | | 2 | port pair | 0,1 (close, | ||
+ | | 3 | multi port | port mask | 0...255 where address is offset | protocol/ | ||
+ | | 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 | ||
+ | | 4 | read port config | ||
+ | | 5 | write port config | ||
+ | | 6 | set RocNet ID | idH | idL | subipH | subipL | | | | ||
+ | | 7 | read options | ||
+ | | 8 | write options | ||
+ | | 9 | read macro | number | ||
+ | | 10 | write macro | number | ||
+ | | 11 | update | ||
+ | | 12 | read port event | from port | to port | | | | port# | idH | idL | port | | ||
+ | | 13 | write port event | port# | idH | idL | port | | | | | ||
+ | | 14 | delete port config | ||
+ | \\ | ||
+ | ==Channels== | ||
+ | ^ code ^ description ^ d1 ^ d2 ^ d3 ^ d4 ^ d5 ^ d6 ^ d7 ^ d8 | d1 | d2 | d3 | d4 | d5 | d6 | d7 | d8 ^ | ||
+ | | 15 | read channel config | ||
+ | | 16 | write channel config | ||
+ | | 17 | delete channel config | ||
+ | | 18 | set channel | channel# | valueH | valueL | | | | | | | ||
+ | |||
+ | \\ | ||
+ | The read, write and delete port/ | ||
+ | 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-prot-en.txt · Last modified: 2019/02/10 08:58 by 127.0.0.1