Old Bowler Communications System

From Neuron Robotics Wiki

Jump to: navigation, search

Contents

This information is very out of date, click here for modern documentation Bowler_Communications_System


Overview

The Bowler protocol is designed to allow for decentralized sensors and actuators to be utilized in a uniform and reliable manner.

The name comes from the logo, which was designed by Eric Sutman. It is a name for a protocol that has not yet been copyrighted

Bowler Network Protocol

Network Overview

A Bowler network is based on a asymmetric star topology in which two classes of devices exist: a Host and a Guest. In the network, Hosts utilize services provided by connected Guests to interact with the Guest's peripherals devices. A Host will communicate requests and Guests will communicate request status and data. An example setup may be a laptop running an application (Host) connected to a servo module (Guest) via a USB cable.

Hosts may have multiple Guests, Guests may have multiple Hosts and Hosts may even share Guests with other Hosts.


Messages and Synchronous/Asynchronous

Communications between devices are done via messages. A host may send a message to a node at any point during operation. Nodes, however, must issue a request to the host to send a message and may only do so once the host has granted the guest clearance. A host may receive communications from the node without having send prior request. This may occur in a situation when a node has a critical message (i.e. a motor overheats, a battery was disconnected, etc...) or if a node changes state. In the above example, the application may send a message down the USB connection to the server controller requesting a servo move to a certain position. The servo controller would receive this message, process it (i.e. move the servo to the requested position) and then send a return message informing the application the status of the task (i.e. Successful).

Timeouts

Between any two directly connected devices (i.e. DyCom and DyIO) the node is allotted 5ms to respond to a host message.

Guests Communications from a guests may process incoming messages in any order that they choose, so reply message are not guaranteed to be ordered. To ensure unambiguous communications, a host generates a 7 bit Synchronous/Asynchronous ID. The Synchronous/Asynchronous ID is used to allow a host to tag outgoing requests and to be able to map incoming replies to the original request. A guest will always use the Synchronous/Asynchronous ID provided by the host for any replies to the request and, additionally, the host may reuse Synchronous/Asynchronous IDs whenever it deems appropriate. In the event that there are multiple replies from the guest, each reply will use the same Synchronous/Asynchronous ID as the request that initiated the Synchronous/Asynchronous. The Synchronous/Asynchronous ID of 0 is reserved only for use synchronous messages. Using earlier example, if the application iprotocollssued a request that a servo temporary move to a position then, after an amount of time, move back to the original position, the host would send the request with a Synchronous/Asynchronous ID that it randomly generated. The module would receive the request, process it and may send a reply with the status once the servo has moved and then it may reply again once the servo had reached the original position. All three messages would have the same Synchronous/Asynchronous ID. If there was a sudden failure unrelated to the Synchronous/Asynchronous's scope, as determined by the servo module (i.e. a malformed request was received), the servo module would send an error message with a Synchronous/Asynchronous ID of 1.

Addressing

All Hosts and Guests within a Bowler network will be required to have a unique IEEE EUI-48 (MAC) address. Manufacturers will be responsible for providing unique addresses to devices. The addresses will be used to identify and route communications to devices.

00:00:00:00:00:00 is used to designate a broadcast address. All devices that receive a message addressed to the broadcast address will respond to message as though the message was intended for that device.

Message Packet

Messages are represented though a network as data packets. A packet consists of a head which provides routing information and processing information and a data payload which contains any additional information for the message.

Overview

Size Name Description
1b Protocol Revision The revision of the Bowler protocol to use
6b MAC Address The MAC address of the recipient device
1b Method The method of action that the communication will have
1bit Response Flag Flags if the message is a response
7bit Synchronous/Asynchronous ID A semi-unique number to identify the message for the short term
8bit Data Length The length of data to come including the RPC
1b CRC The checksum to determine the validity of the packet
4b RPC The remote procedure call identifier
0b - 251b Data The rest of the data


Revision

In order to provide the protocol room to expand and evolve over time, at the top of each packet will be a revision number. This will designate how the packet is structured and what constraints exist. Future revisions will always be downwards compatible.

Address

Messages sent from a Host contain either the MAC address of the end recipient Guest or the Broadcast address. Messages from a Host that contain the Broadcast address are intended for any directly connect Guests. A Routers receiving a message with the Broadcast address from a Host will be required to forward the message to all connected Guests.

Method

Each message contains a Method identifier to designate the context in which the message should be processed. The context designates the purpose and expected result of the message.

Method Codes
Value Name Description Expected Guest Response Expected Host Response
0x00 STATUS The message contains device status information. None None
0x10 GET The message has information for a device to use in a query. POST \ STATUS None
0x20 POST The message has information for a device to use in an action. POST \ STATUS None
0x30 CRITICAL The message has critical information that should not be interrupted. This contains configuration information STATUS None

Reply Flag

Communications originating from a Guest to a Host have the Reply Flag set in order to designate if the message should be directed towards the host or towards the Guest.

Synchronous/Asynchronous ID

Synchronous/Asynchronous IDs are by the module to signify what method generated the async packet. For synchronous packets, the ID is 0.

Data Length

The Data Length field is the size (in bytes) of the following payload. If there is no data payload, then 0 is given.

CRC Checksum

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

Bowler RPC

In the bowler protocol a "RPC" 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). This is similar in structure to a function call in any programming language. The function will take parameters and return data. This is where the name Remote Procedure Call comes from. They are considered to be unique for the entire protocol and the creation of a new RPC should consult the existing RPC's first. Invalid characters for use as an rpc include:

"."
";"
"*"

These 4 bytes are arranged in the packet with the first element of the string going first, then the second and so on.

All the RPC's in the bowler system must fall inside a namespace. Each namespace contains a group of RPC's that the device implements. These RPC's must be either implemented in the BCS wiki, or must be documented on a web page URL that is passed to the application from the device at runtime. All bowler devices MUST implement all of "bcs.core". For details on how the namespaces work and a list of namespaces see:

Bowler_Communications_System_Namespaces

note

When the 4 bytes are read as an int in a little endian system, the byte order appears reversed. Be careful about your byte order when checking the RPC in a single compare.

Physical Specification

Cable pinout facing connector

1 RTS-Output
2 RX-Input
3 GND
4 NOTCH 5v
5 GND
6 TX-Output
7 CTS-Input(Interuptible)


Troubleshooting

Pinging a Device

If you are unsure about communications with a device, try sending a ping packet to it and reading the results. You can use a serial terminal like RealTerm to do this

03 00 00 00 00 00 00 10 00 04 50 5F 70 6E 67
Personal tools