The Bowler communication system is designed to be a distributed processing system for micro-controllers and OS based computers. A Device's features are accessed usingBowler Remote Procedure Call (RPCs). These RPCs are then grouped together into Bowler Namespaces which serve as an interface to a specific sets of functionality(For example, IO manipulation and PID control) Each device is addressable using a IEEE standard MAC address that is unique to that device.
The protocol allows for the host to query a device for implemented name-spaces to allow for zero-configuration.
The network topology is an asymmetric star, with one host (Client) to N devices (Server). The connection between these elements is called a link.
A Bowler Host lies at the beginning of a Bowler Link. It is the initiator of Synchronous Bowler Transactions and the recipient of asynchronous Bowler Packets
A bowler device is an entity that lies at the end of a Bowler Link that and is involved in Bowler Transactions. It Implements a set of Bowler_RPCs divided into Bowler Namespaces. These RPCs allow a Bowler Host to manipulate and query the Device's state. State manipulations include such operations as Toggling an IO pin, or reading an ADC value.
A Bowler Device also sends Asynchronous Bowler Packets to the Bowler Host on the other end of the Bowler Link
IntroductionA bowler link is bidirectional communications channel between a Bowler Host and a Bowler Device It is this link that Bowler Packets Traverse. IT is the medium in which Bowler Transactions occur.
ImplementationsA bowler link can be implemented with any communications medium capable of transmitting data bidirectionally from one device to another. Neuron Robotics has implemented the following links.
Asynchronous SerialThe DyIO uses 115200 baud Asynchronous serial 8n1 and send the packets down the link one byte at a time starting from the first byte of the packet
TCP/IPPackets sent over a TCP socket, In this implementation the socket server would be on the device and the socket client would be the master. An easy way to get a bowler device onto a network would be to use an existing ether-net to serial bridge like the [http://www.lantronix.com/device-networking/embedded-device-servers/xport.html XPort]
missing wiki info
missing wiki info
Communicating with the Bowler Communication System consists of sending packets from host to device to establish a link, then packets can be sent in either direction.
IntroductionCommunication between a Bowler Host and a Bowler Device consists of Bowler Transactions made up of Bowler Packets There are two types of transactions, Synchronous transactions and asynchronous transactions.
Synchronous TransactionsA Synchronous transaction is a transaction between a master and a device initiated by the master with the transmission of a Bowler Packet containing an RPC. The device, in turn, must reply with a packet containing the result of the RPC within 50ms. For Example, When the NRSDK requests the user assigned name of a device it sends a GET Request with the RPC "INFO". The host then has 50ms to respond with a POST response containing the name of the device.
[2011/01/21 21:42:45:414] Debug : TX>> Raw Packet: 03 00 00 00 00 00 00 10 00 04 17 69 6e 66 6f Revision: 3 MAC address: 00:00:00:00:00:00 Method: GET Direction: (0) Syncronous Session ID: 0 Data Size: 4 Checksum: 23 RPC: info Data: 69 6e 66 6f [2011/01/21 21:42:45:427] Debug : RX<< Raw Packet: 03 74 f7 26 00 00 00 20 80 15 49 69 6e 66 6f 44 79 49 4f 20 4d 6f 64 75 6c 65 20 20 20 20 20 00 Revision: 3 MAC address: 74:F7:26:00:00:00 Method: POST Direction: (1) Syncronous Session ID: 0 Data Size: 21 Checksum: 73 RPC: info Data: 69 6e 66 6f 44 79 49 4f 20 4d 6f 64 75 6c 65 20 20 20 20 20 00Note, the name returned is the default name of " DyIO Module " (44 79 49 4f 20 4d 6f 64 75 6c 65 20 20 20 20 20 00)
Asynchronous TransactionsAn Asynchronous transaction is a transaction the device initiates by transmitting a packet with an Asynchronous Transaction Type. The host does not respond. Asynchronous Transactions are typically initiated when the internal state of the device has changed (IE, battery connected) or when the device has been configured by a previous Synchronous Transaction to push new data to the host(Voltage on an ADC input has changed, ADC sample, etc..).
IntroductionCommunication 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 StructureThe following table defines the structure of a Bowler Packet
|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 /td>||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 RevisionThis field contains a version number that allows a bowler device to determine if it will understand the incoming message.
Device AddressThe 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 TypeThe 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 FlagPackets 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 NumberIn 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| bcs.core._NMS]]
Data LengthThe Length in bytes of the data in the payload field including the RPC.
Header ChecksumThe 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.
RPCThis 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).
PayloadThe packet payload. Depends on the RPC. Can be empty.
A synchronous communication is a transaction initiated by the host and responded to by the device.
Once a link is established, the device can send packets to the host without the host initiating the transaction. These are Asynchronous Transactions consisting of one Upstream Bowler Packet and are used to inform the host of device state updates.
The structure of the bowler packets makes use of "Remote Procedure Calls" or RPC's. An RPC is defined within a namespace, or collection of RPC's. The RPC is a code that will define how the raw data in the data section of the packet is formatted. This formatting needs to be known by both host and device. The Host will use the list of namespaces, that the device reposts back as implementing, to determine compatibility. This allows the application to check the device for the functionality it needs.