Appendix I: BrainStem Universal Entity Interface (UEI)

Most of the BrainStem 2.0 functionality is represented by abstract entities. These entities are things like battery voltage, the module address, or an analog voltage. These entities are accessed in a common command interface called a UEI. These UEIs allow various clients to access module entities both locally and over the BrainStem’s network. Clients include the Host, and Reflex code running on the module or on another module in the network.

How UEI’s Work

UEI’s allow the setting and getting of entity information. This information can be in empty, byte, 2-byte, or 4-byte data sizes and the UEI’s allow a common mechanism for either reading or writing these entity values. Some entities are limited to strictly reading (getting) or writing (setting), based on the underlying entity properties. For instance, and A2D input on a BrainStem module can be queried (read) but not written. An empty write is used to trigger an entity on the module, much like a void parameter to a routine in C.

The mechanism for both reads and writes is performed with an exchange of two UEI’s. Reads use a GET/VAL pair where the entity value is requested (GET) and a value is sent back as the reply (VAL). Writes use a SET/ACK pair where the write employs a SET UEI and then an optional ACK response can be sent to learn the status of the SET operation.

UEI Classes

Each UEI is part of a group or class of UEI’s that share a common subsystem within the BrainStem 2.0 architecture. These classes directly correspond to underlying command structures within the protocols on the link and BrainStem network. The classes also logically group common functionality for various entities.

Example UEI Classes

  • System - These are system global values like the module’s serial number, I2C rate, etc. Not all modules will have all possible system UEI’s available, based upon functionality.
  • Servo - This class collects all the common functionality around a servo input/output for modules supporting servos. These may include things like enable, reverse, and position UEI’s along with others.
  • Analog - Both A2D and DAC channels are grouped in this class of UEI’s as they often share functionality or are conceptually similar.

The GET/VAL UEI Transaction

The UEI GET/VAL transaction is a back-and-forth between the requestor (client) and the BrainStem 2.0 module (server) where the entity being read is located. There are several client types including the host, another module, a virtual machine running on the network’s modules, or a third-party device on the BrainStem network. The requestor first identifies the full entity and specifies a GET operation. The requestor also is responsible for identifying where the response (VAL operation) should be sent. Both of these operations are asynchronous commands.

Breaking this down further, lets first consider the GET UEI from the client requestor. This specifies 5 or 6 specific pieces of information:

UEI GET Request

  • Command - The command that groups the class of UEI’s in which the entity is included.
  • Option - The specific entity within the class of UEI’s
  • Index - The array index of the class. This allows for multiple groups of classes like servos, motion channels, etc.
  • Operation - the operation of the UEI which is GET in the case where the possible operations are GET, VAL, SET, and ACK
  • Reply - Identifies the reuestor so the response returns to that requestor where the possible options include I2C, Host, Reflex Machine, etc.
  • ReplyID (optional) - For reply values that require more information, this information is include such as the Reflex Machine thread identifier or the remote module’s address where the response will be sent. If the reply specifies the host, no additional replyID information is needed so it will not be present.

The above information is packed into a sequence of bytes for transmission to the module from the requestor. These packed bytes overlay the normal BrainStem 2.0 command structure so they are essentially a generalized set of commands for accessing entities.

Typical UEI header for GET packet.

Packed Byte GET UEI Structure

Once this UEI command payload is received by the module where the entity resides, the bytes are converted to the UEI information which is then validated. Provided all the information checks out and the entity can be read, a response is constructed and returned to the requestor as specified in the GET UEI information. The value may be a single byte, 2-byte, or 4-byte value, depending on the entities native size. There are then three possible return packet structures, one for each size.

The information returned in the VAL response is identical to the GET with the following exceptions. First, the responder address identifies the entity where the entity lives which is not necessarily that of the requestor. Second, the operation is VAL. Finally, the data (1-4 bytes) follows the index and there is no replyID.

UEI VAL Reply

  • Command - The command that groups the class of UEI’s in which the entity is included.
  • Option - The specific entity within the class of UEI’s.
  • Index - The array index of the class. This allows for multiple groups of classes like servos, motion channels, etc.
  • Operation - The operation of the UIE which is VAL in this case where the possible operations are GET, VAL, SET, and ACK.
  • State - Identifies the response state. If no errors occurred, this value is zero. If an error occurred the high bit (7) of this byte will be set.
  • Data - 1, 2, or 4 bytes for the entity value that was read. If an error occurred, the error bit is set in the state and the data is always a 1-byte error value describing the error.
  • Responder Address - The responding entity’s module address so the requestor can potentially match the initial request with this response. For replies to the host, this responder address is implicit in the inbound packet protocol so the responder address is not sent in host responses.
VAL UEI Packet

Packed Byte VAL UEI Structure 1,2, and 4 Byte Values

UEI VAL Error Handling

In some cases, the UEI GET request may be incorrect, refer to a non-existent entity, or have some type of mode error like reading from a write-only entity. If the request cannot be fulfilled for some such reason, a response is still sent but the response simply contains an error state and error code.

VAL UEI Packet

Packed Byte VAL UEI Structure 1,2, and 4 Byte Values

The SET/ACK UEI Transaction

Much like GET/VAL transactions which are request/response, the SET/ACK is a request/acknowledge pair of commands. The SET sends a payload of data to write to the entity and the ACK offers acknowledgment and possibly an error code. The ACK is optional so a requestor can “set and forget” if the acknowledgement is not desired. Typically the ACK is used to synchronize behavior on the requesting side to ensure that the value has been written before proceeding. When this synchronizing is not needed, the ACK needn’t be requested.

UEI SET Request

  • Command - The command that groups the class of UEI’s in which the entity being written is included.
  • Option - The specific entity within the class of UEI’s.
  • Index - The array index of the class. This allows for multiple groups of classes like servos, motion channels, etc.
  • Operation - The operation of the UIE which is SET in this case where the possible operations are GET, VAL, SET, and ACK.
  • Reply - Identifies the requestor so the acknowledgement returns to that requestor where the possible options include none (no acknowledgement), I2C, Host, Reflex Machine, etc.
  • Data - empty, 1, 2, or 4 bytes for the entity value or trigger being written.
  • ReplyID (optional) - For acknowledgements that require more information, this information is included such as the Reflex Machine thread identifier or the remote module’s address where the acknowledgement response will be sent. When acting as a requestor, the host does not have any additional replyID information.
VAL UEI Packet

Packed Byte SET UEI Structure 1,2, and 4 Byte Values

Once a SET is performed, the module responds to the reply location if one was specified. The response is an ACK operation which indicates success or an error. Again, if a reply of “none” was specified, there is no ACK sent anywhere.

UEI ACK Reply

  • Command - The command that groups the class of UEI’s in which the entity is included.
  • Option - The specific entity within the class of UEI’s.
  • Index - The array index of the class. This allows for multiple groups of classes like servos, motion channels, etc.
  • Operation - The operation of the UIE which is ACK in this case where the possible operations are GET, VAL, SET, and ACK.
  • Responder Address - The module address from where the ACK is being sent. This helps the requestor verify the completion status of the SET command. When replies are sent to the host, the responder address is implicit in the link protocol so it is not included host acknowledgements.
ACK UEI Packet

Packed Byte ACK UEI Structure

UEI ACK Error Handling

In the event of an error such as invalid entity index, configuration, etc., the error bit is set in the ACK state and an error code is added to the ACK further describing the error to the SET requestor.

ACK UEI Error Packet

Packed Byte ACK UEI Error Structure