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, 4-byte, or N-byte data sizes and the UEI’s allow a common mechanism for either reading or writing these entity values. UEI Values of 2-byte and 4-byte are stored in big endian format. Some entities are limited to strictly reading (getting) or writing (setting), based on the underlying entity properties. For instance, an 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.

There is one other mode of operation which is called streaming. When streaming has been enabled, the device will automatically send new values to the requestor by asynchronously generating and sending a VAL payload.

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.

  • Port - The class used for USB Port manipulation, enabling/disabling data or power.

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 (This is part of BrainStem 2.0 command structure).

  • Operation - the operation of the UEI which is GET in the case where the possible operations are VAL (0), GET (1), SET (2), or ACK (3)

  • Option - The specific option code within the class of UEI’s

  • Reply - Identifies the requestor so the response returns to that requestor where the possible options include Host (1), I2C (2), or Reflex (3).

  • Index - The array index of the class. This allows for multiple groups of classes like ports, servos, motion channels, etc.

  • Subindex (optional) - The subindex of a specific index of the class. This allows for there to be sub-components of a class like setting/getting the configuration for a channel of an equalizer class.

  • 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 over I2C 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.

GET UEI 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, 4-byte, or N-byte value, depending on the entities native size. There are then four 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. Third, subindex is not transmitted back to the requestor in the VAL. Finally, the data (1-N 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 (This is part of BrainStem 2.0 command structure).

  • Operation - The operation of the UIE which is VAL in this case where the possible operations are VAL (0), GET (1), SET (2), or ACK (3).

  • Option - The specific option code within the class of UEI’s

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

  • Stream - Identifies if this is a streaming payload or not. If the payload is a normal GET/VAL, this value is zero. If the payload is streamed asynchronously bit (6) of this byte will be set.

  • Index - The array index of the class. This allows for multiple groups of classes like ports, servos, motion channels, etc.

  • Data - 1, 2, 4, or N 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.

  • Continue - Identifies if there are subsequent payloads after this one that should be used in conjunction or if this is the last payload for the value.

  • Sequence - Used to identify the payload index for a multi-payload response.

  • 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, 4, and N 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 Error Packet

Packed Byte VAL UEI Error Structure

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 is included (This is part of BrainStem 2.0 command structure).

  • Operation - The operation of the UEI which is SET in this case where the possible operations are VAL (0), GET (1), SET (2), or ACK (3).

  • Option - The specific option code within the class of UEI’s

  • Reply - Identifies the requestor so the acknowledgement returns to that requestor where the possible options include none (no acknowledgement), Host (1), I2C (2), or Reflex (3).

  • Index - The array index of the class. This allows for multiple groups of classes like ports, servos, motion channels, etc.

  • Subindex (optional) - The subindex of a specific index of the class. This allows for there to be sub-components of a class like setting/getting the configuration for a channel of an equalizer class.

  • Data - empty, 1, 2, 4, or N bytes for the entity value or trigger being written.

  • Continue - Identifies if there are subsequent payloads after this one that should be used in conjunction or if this is the last payload for the value.

  • Sequence - Used to identify the payload number for a multi-payload response. If the value is greater than what can fit in 1 payload, the continue bit will be set and there will be multiple payloads each with an incrementing sequence number until the last payload in which the continue bit will be set low.

  • 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 over I2C where the response will be sent. If the reply specifies the host, no additional replyID information is needed so it will not be present.

SET UEI Packet

Packed Byte SET UEI Structure 1, 2, 4, and N 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 (This is part of BrainStem 2.0 command structure).

  • Operation - The operation of the UIE which is ACK in this case where the possible operations are VAL (0), GET (1), SET (2), or ACK (3).

  • Option - The specific option code within the class of UEI’s

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

  • Index - The array index of the class. This allows for multiple groups of classes like ports, servos, motion channels, etc.

  • 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

The Streaming VAL UEI Transaction

There is also a way to configure the device to asynchronously create UEI update payloads that will stream to the requestor upon change of the value. This is very useful for capturing all the voltage measurements on a USB port or being notified of a status change so polling isn’t required. The appropriate command, index, option combo is configured via the Link Class using the Stream Command.

UEI VAL Streaming

  • Command - The command that groups the class of UEI’s in which the entity is included (This is part of BrainStem 2.0 command structure).

  • Operation - The operation of the UIE which is VAL in this case where the possible operations are VAL (0), GET (1), SET (2), or ACK (3).

  • Option - The specific option code within the class of UEI’s

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

  • Stream - Identifies if this is a streaming payload or not. If the payload is a normal GET/VAL, this value is zero. If the payload is streamed asynchronously bit (6) of this byte will be set.

  • Index - The array index of the class. This allows for multiple groups of classes like ports, servos, motion channels, etc.

  • Stream Type - Identifies the type of value that will be coming back, 1, 2, 4, or N byte value, with/without Subindex.

  • Subindex (optional) - The subindex of a specific index of the class. This allows for there to be sub-components of a class like setting/getting the configuration for a channel of an equalizer class.

  • Seconds - The 4 byte value of seconds of uptime for the device.

  • uSeconds - The 4 byte value of microseconds of uptime for the device. (To be used in conjunction with seconds of uptime above)

  • Data - 1, 2, 4, or N 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.

  • Continue - Identifies if there are subsequent payloads after this one that should be used in conjunction or if this is the last payload for the value.

  • Sequence - Used to identify the payload index for a multi-payload response.

  • 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 Stream Packet

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