STINGR Gesture Specification I
Below is STINGR Gesture Specification I -- the original concept for STINGR Gestures, which was replaced by STINGR Gesture Specification II.
Gesture Specification
As mentioned above, a Gesture consists of a series of frames, each with a specific purpose. Each Gesture is transmitted on the CAN Bus, and allows all boards to determine if a Gesture is targeted towards them, and act appropriately. This section defines the specification of a Gesture, including a description of each of the frames.
More explicitly, a Gesture looks as so, with the leftmost frames being transmitted first, and the rightmost frames being transmitted last.
|
Type (Req/Resp) (1 bit) |
State Flags (7 bits) |
Source Identifier (8 bit) |
Destination Identifier (8 bit) |
Data (4-500 bytes) |
Checksum (8 byte) |
Type Frame
The Type frame, the first frame in a Gesture, is a 1 bit frame that determines whether a Gesture is a request from one board to another, or a response from one board from a prior request. This frame is a 0 for a request, and a 1 for a response.
State Flags Frame
The 7 bits following the Type bit are the State Flag bits. This 7-bit frame allows transmitting boards to provide specialty signals to the receiving board. A low bit indicates a flag that isn't down, while a high bit indicates a raised flag. The current flags are as follows, from LSB to MSB.
| High Priority | Low Priority | No Override | Reserved | Reserved | Reserved | Reserved |
The flags are defined as follows:
- High Priority: The board receiving the request should cease all operation immediately and respond to the request before continuing.
- Low Priority: The board receiving the request can wait to respond to the request until most convenient.
- No Override: The board receiving the request has no choice but to comply with the request sent -- it should not exert any effort attempting to question or combat the transmitting board. If this flag is low, a board receiving a request has the ability to ask the transmitting board for clarification or request a re-consideration. If this flag is high, the receiving board should execute the request regardless.
Flags are stacking, meaning multiple flags can be high. For example, a high high-priority flag and high no-override flag means a board not only must comply without question, but it should do so immediately prior to continuing any of its standard operations.
Source & Destination Identifiers
The Source & Destination Identifiers, the second and third frames in a Gesture, are 8 bit frames that indicate the source of the Gesture. Each board developed for the HONEY architecture is catalogued and given a unique identifier code. These unique identifiers allow boards to identify who a request or response from, and respond accordingly. Note that each unique board is given a unique identifier -- The Count, the first HONEY-compliant avionics board, has the identifier of 0, but a subsequent revision of avionics would acquire a new identifier code. This allows boards to be aware of the specific revisions that are flying in the stack -- allowing them to dynamically take advantage of the utilities of newer boards as they are added. The identifiers are encoded into the STINGR suite, and one can call a simple function to determine what board was the source or destination, without memorizing or encoding any of these identifiers in local board code.
There is also a unique, reserved designator, which is designator 256 (11111111). This designator is reserved for the broadcast functionality. Gestures with a destination identifier of 256 target all boards in the stack. That is, if a board wishes to notify all boards in the stack of some particular information, it can do so by designating a destination identifier of 256 -- all boards are configured, via STINGR, to process these gestures, even though the destination identifier isn't their own unique identifier. These are formally referred to as broadcast gestures.
The following are the current identifier codes, as of writing (June 21, 2017).
| The Count (Gen 4 Avionics) | 00000000 |
| Biscuit (Gen 2 BMS) | 00000001 |
| Macaw (Gen 1 Radio) | 00000010 |
Data Frame
The data frame carries the entirety of the request or response. This frame is variable in length, and can be as little as four bytes (at a minimum) or as much as 500 bytes (although this isn't a strict limit, but messages should seldom exceed 496 characters).
The data frame, in order to accommodate the large variety of possible data types that might arise in the HONEY architecture, is encoded strictly in ASCII characters as a char buffer. This allows boards to send messages as character strings -- STINGR is designed to understand and decode standardized messages, but this framework allows boards to send absolutely any data.
The payload portion of the data frame can be empty -- in this case, the data frame consists of four bytes. These are the start and end designators, which designate the start and end of the data payload. The start designator is '/1' while the end designator is '/0'
| Start Flag (2 bytes - '/1') | Payload (0-496 bytes) | End Flag (2 bytes - '/0') |
Checksum Frame
The Checksum Frame performs a checksum operation on the payload of the data frame, producing an 8-byte output. Receiving boards should perform an identical checksum operation on the data frame, and compare it to the received checksum value to verify data integrity. Identical checksums indicate proper transmission, while mismatched checksums indicate transmission error.
The current checksum calculation is as follows:
Each byte in the data payload (meaning, data excluding the start and end designators), takes its decimal ASCII value, which is multiplied by its position in the data frame. The sum of these products is the checksum value, which is 8 bytes.
Take the following data frame:
| / | 1 | H | E | L | L | O | / | 0 |
The checksum is performed on the data payload, meaning only HELLO. The calculation for each byte in the frame is as follows, following the guideline of taking the position of the character and multiplying that by its ASCII value:
| 72 * 1 (H) | 69 * 2 (E) | 76 * 3 (L) | 76 * 4 (L) | 79 * 5 (O) |
The sum of these products is 1,137, the checksum value.