Bowler Packets
From Neuron Robotics Wiki
Contents |
Introduction
Communication on a Bowler Link consists of the exchange of Bowler Packets between a Bowler Host and a Bowler Device. Packets may be sent by either the host or device during a Bowler Transaction
Packet Structure
The following table defines the structure of a Bowler Packet
| Size | Name | Description |
|---|---|---|
| 1b | Protocol Revision | The revision of the Bowler protocol to use |
| 6b | Target Device ID | The IEEE OUI-48 MAC address of the recipient device |
| 1b | Packet Type | Metadata pertaining to how the packet will affect device state. (POST,GET,STATUS,CRITICAL) |
| 1bit | Direction Flag | Indicates the packet as a request or a response. |
| 7bit | Namespace Collision Resolution | Used to resolve namespace collisions. |
| 8bit | Data Length | The length of data to come including the RPC |
| 1b | Header Checksum | The checksum to determine the validity of the packet |
| 4b | RPC | The Bowler RPC call identifier |
| 0b - 251b | Data | The rest of the data |
Protocoll Revision
This field contains a version number that allows a bowler device to determine if it will understand the incoming message.
Device Address
The bowler address is a globally unique address across all bowler devices. Now two devices should have the same 6 byte address. This field contains the address of the Device that is being communicated with.
One address out of all the possible addresses is treated differently. This address is the Link Local Address. It consists of all zeros (00:00:00:00:00:00) and any bowler device will respond to it.
Packet Type
The Packet type field contains information on how the RPC will affect the state of the device. They are used so that filtering and queing mechanisims can work with packets without having to have full knowlage of all the possible RPCs. There are 4 possible Method Types.
GET (0x10)
The packet is a query, It will not affect the state of the device. For example, Requesting the value of a pin.
A Device responding to a GET method would mark it's response as a POST because it affects the state of the host by providing it with new data.
[2011/01/21 21:57:55:993] Debug : TX>> Raw Packet: 03 74 f7 26 00 00 00 10 00 05 a9 67 63 68 76 0b Revision: 3 Device ID: 74:F7:26:00:00:00 Packet Type: GET Direction: (0) Syncronous Reserved: 0 Data Size: 5 Checksum: 169 RPC: gchv Data: 67 63 68 76 0b [2011/01/21 21:57:56:136] Debug : RX<< Raw Packet: 03 74 f7 26 00 00 00 20 80 07 3b 67 63 68 76 0b 00 9c Revision: 3 Device ID: 74:F7:26:00:00:00 Packet Type: POST Direction: (1) Syncronous Reserved: 0 Data Size: 7 Checksum: 59 RPC: gchv Data: 67 63 68 76 0b 00 9c
POST (0x20)
The Packet Contains information intended for the device that will cause the device to change its state. For example, setting a digital output to a specific value.
A Device Responding to a POST Should mark its response packet as a STATUS packet.
STATUS (0x00)
The packet contains a Response or Status Update on a previously issued request. For Example, A POST request does not return data but affects the state of a device, A response containing ether a confirmation of success or an error would have its method set to STATUS. This method type is exclusively used for responses from the device intended for the host.
[2011/01/21 21:52:33:33] Debug : TX>> Raw Packet: 03 74 f7 26 00 00 00 20 00 06 ba 73 63 68 76 17 01 Revision: 3 MAC address: 74:F7:26:00:00:00 Method: POST Direction: (0) Syncronous Session ID: 0 Data Size: 6 Checksum: 186 RPC: schv Data: 73 63 68 76 17 01 [2011/01/21 21:52:33:57] Debug : RX<< Raw Packet: 03 74 f7 26 00 00 00 00 80 06 1a 5f 72 64 79 02 02 Revision: 3 MAC address: 74:F7:26:00:00:00 Method: STATUS Direction: (1) Syncronous Session ID: 0 Data Size: 6 Checksum: 26 RPC: _rdy Data: 5f 72 64 79 02 02
CRITICAL (0x30)
A Critical high priority message that should not be interrupted or delayed if at all possible.
A Device Responding to a CRITICAL Should mark its response packet as a STATUS packet.
ASYNCHRONOUS (0x40)
An Asynchronous packet packet is sent from device to host without a request from the host. These packets are processed by the stack and passed to the user to be dealt with as they come in. An Asynchronous packet can arrive in between a synchronous packet and its response.
Direction Flag
Packets travel along a bidirectional link between a Host and a Device. The Direction flag specifies the direction the packet is traveling. a value of 0 indicates a packet is traveling from Host to Device. Likewise, A value of 1 indicates Device to host.
Collision Resolution Number
In the event that a bowler device implements two name-spaces with identical RPCs, The device will return an error packet if this field is left zero. To resolve this collision, the host must supply the index of the desired namespace. This index is the same as the index used in bcs.core._NMS
Data Length
The Length in bytes of the data in the payload field including the RPC.
Header Checksum
The Header Checks is a checksum that is generated from all of the previous bytes of the packet. It is used to ensure data integrity. The method of generating/validating the checksum is to add all the bytes in the header, then take the low 8 bits of the integer that represents the sum.
RPC
This contains the Bowler RPC and is a 4 byte code (usually ascii, but not necessarily) that is used to identify the command that the packet represents. The device will read this RPC and determine how to read the data coming with it (parameters) and how to format the packet it returns (returns).
Payload
The packet payload. Depends on the RPC. Can be empty.
