No Image

Protocol

Architecture

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.

Bowler Host

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

Bowler Device

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

Bowler Link

Introduction

A 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.

Implementations

A 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 Serial

The 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

Synchronous serial

TCP/IP

Packets 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]

UDP/IP

missing wiki info

Bluetooth

missing wiki info

Communication

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.

Bowler Transactions

Introduction

Communication 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 Transactions

A 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 00 
Note, 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 Transactions

An 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..).

Bowler Packets

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 /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 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| 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.

Synchronous

A synchronous communication is a transaction initiated by the host and responded to by the device.

Asynchronous

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.

Formatting

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.

Bowler RPC

Bowler Namespaces