Appendix II: BrainStem Communication Protocol

The BrainStem Communication Protocol is a very light weight transport independent binary packet protocol. The protocol simply imposes a max packet length restriction, and designates two bytes of the packet as “header” bytes which contain information used to address, and handle packets.

The BrainStem protocol is a command protocol. Commands are the foundational communication mechanism for BrainStem modules. Every BrainStem command has a similar structure shown in the following diagram.

Typical command structure.

Typical BrainStem Command Structure

Packet Structure

  • Header - The packet header consists of the module address and length byte.

  • Payload - The remainder of the packet is the payload, and consists of the command code followed by data bytes. The packet length cannot exceed aBRAINSTEM_MAXPACKETBYTES (28 bytes).

  • Address - The BrainStem module address that will receive the packet. This value is an even number that can range from the value 2 to 254. BrainStem module types have different default address values (Check your product Datasheet). The module address can be changed by the user, please see the command reference section on the System command for more information.

  • Length - The length of the packet Payload in Bytes.

  • Command - The command code for the BrainStem command. See the reference section on BrainStem commands for more information.

  • Byte 0 .. Byte N - The command data bytes, a command may impose structure on the data portion of the packet. This is documented in the command reference.

Byte Order

The BrainStem protocol does not specify byte order for the data portion of the packet, but UEI datatypes larger than byte are stored in bigEndian byte order.

Command Interaction

UEI’s impose a request response behavior on top of the BrainStem protocol, but the protocol does not itself define a need for a response. Delivery of data is best effort. Some Link transports (TCP/IP) make guarantees about data delivery, this is not part of the BrainStem protocol. Please see specific command documentation to determine whether to expect a response packet.

There are currently two cases when a BrainStem client may receive an error message unrelated to a request. The first case occures when a module address is given where no such module exists, in this case a cmdMSG packet will be received with a no I2C ack payload. The second case occures when a Reflex VM exits unexpectedly, a client may receive a cmdMSG packet with a vm exit payload. Please see the Command reference section for more information.