User Tools
rocnet:rocnet-prot7-en
Differences
This shows you the differences between two versions of the page.
| — |
rocnet:rocnet-prot7-en [2018/11/12 08:56] (current) |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| + | ====== rocNET Serial Protocol ====== | ||
| + | [[:english#command_stations|{{ :interface.png}}]][[:english|{{ :rocrail-logo-35.png}}]] | ||
| + | [[:english|Content]] -> [[:english#command_stations|Command Stations]] -> **[[rocnet:rocnet-lib-en|rocNET]]** | ||
| + | * [[rocnet-prot-en|8 bit UDP]] | **7 bit Serial** | ||
| + | * [[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, partly, also be used as base for embeded software. (PIC/Atmel)\\ | ||
| + | \\ | ||
| + | **Work in progress, can change any moment, 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.\\ | ||
| + | \\ | ||
| + | The addressing range is from 1 to 16383.\\ | ||
| + | \\ | ||
| + | |||
| + | |||
| + | ===== 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.\\ | ||
| + | |||
| + | |||
| + | \\ | ||
| + | ===== Setup ===== | ||
| + | RocNET has a dedicated node for setting up the communication: | ||
| + | * http://www.rocrail.net/doc/rocrail-wrappers/wrapper-en.html#rocnet | ||
| + | A serial sublib for 7 bit small packets is planned.\\ | ||
| + | \\ | ||
| + | __Default settings:__\\ | ||
| + | * Baudrate: 19200 | ||
| + | * Line: 8,N,1 | ||
| + | * Flow: RTS/CTS | ||
| + | \\ | ||
| + | |||
| + | ===== 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 == | ||
| + | <code>Address = addrL + addrH * 128</code>\\ | ||
| + | |||
| + | |||
| + | === 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== | ||
| + | * 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 (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 | [[: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]] | | ||
| + | \\ | ||
| + | |||
| + | \\ | ||
| + | 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 | | ||
rocnet/rocnet-prot7-en.txt · Last modified: 2018/11/12 08:56 (external edit)
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
