700
edits
Changes
Jump to navigation
Jump to search
Line 13:
Line 13: − + Line 42:
Line 42: + + Line 58:
Line 60: − + − + − + − + − + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
no edit summary
|Source Identifier (8 bit)
|Source Identifier (8 bit)
|Destination Identifier (8 bit)
|Destination Identifier (8 bit)
|Data (2-500 byte)
|Data (4-500 byte)
|Checksum (8 bit)
|Checksum (8 bit)
|}
|}
=== Source & Destination Identifiers ===
=== 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.
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 following are the current identifier codes, as of writing (June 21, 2017).
=== Data Frame ===
=== 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 two bytes (at a minimum) or as much as 500 bytes (although this isn't a strict limit, but messages should seldom exceed 500 characters).
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 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 data frame can be empty -- in this case, it consists of two bytes. These are the start and end bytes, which designate the start and end of the data payload. The start byte has a value of 256, and the end byte has a value of 255. The data frame spec can be seen here:
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'
{| class="wikitable"
{| class="wikitable"
|Start Flag (1 byte - 11111111)
|Start Flag (2 bytes - '/1')
|Payload (0-498 bytes)
|Payload (0-496 bytes)
|End Flag (1 byte - 11111110)
|End Flag (2 bytes - '/0')
|}
|}
=== Checksum Frame ===
=== Checksum Frame ===
The Checksum Frame performs a checksum operation on the payload of the data frame, producing an 8-bit 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 Checksum Frame performs a checksum operation on the payload of the data frame, producing an 8-bit 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.
== Operation ==
STINGR has a specific control flow that must be strictly followed to ensure proper operation. Luckily, most of this is handled within the STINGR internal code. It is described here in full detail, however, for posterity, debugging purposes, and for context in the following section, which enumerates specific methods and their purposes/parameters.
=== Initialization ===
Each board using STINGR must initialize the suite in order to properly utilize it. This initialization routine allows proper communication between boards in the stack, as well as gives vital information to each board about the actual structure of the stack, which isn't formally known unless hardcoded (a poor choice).
When a board initializes STINGR, it must provide its unique identifier. Once STINGR obtains the unique identifier of a board, it will send a broadcast gesture on the CAN Bus -- this signal has a destination identifier of 256 -- that is, it is sent to all boards in the flight stack. This is the first gesture sent out by a board, and its definition is as follows:
{| class="wikitable"
|Type -- 1 (Response)
|State Flags -- 0 (no flags)
|Source Identifier (8 bit)
|Destination Identifier -- 256 (broadcast)
|Data -- '/1/0' (empty payload)
|Checksum (8 bit)
|}
This particular gesture definition is reserved, and is known as the ''beacon gesture''. It is defined by a strict Type of 1, 0 State Flags, a unique source identifier, a broadcast destination identifier, an empty payload, and a checksum.
The beacon gesture indicates to all boards in the flight stack the presence and identity of a given board. Since all identifiers are enumerated within the STINGR source code, a beacon gesture allows any board to identify what boards are in the stack. Hence, if, for example, Macaw were to send a beacon gesture, with its identifier of 00000010, all boards would receive this gesture, correlate the identifier to that of Macaw, and consequently be aware of the presence of Macaw in the flight stack.
Once a board in the flight stack has sent its beacon gesture, it is now ''live'', and other boards are allowed to send it messages using STINGR. By means of each board in the flight stack sending out a beacon gesture, all boards will be aware of the full definition of the flight stack.
=== Standard Mode ===
Once STINGR passes initialization, it enters ''Standard Mode''. In Standard Mode, a board is able to send and receive gestures via the CAN Bus through STINGR. A board may send a message as frequently or infrequently as desired in Standard Mode. The other defining characteristic of Standard Mode is that, in Standard Mode, STINGR will transmit the beacon gesture every 60 seconds. This is known as the heartbeat gesture, and allows boards in the stack to continue to acknowledge the presence of a board, as well as register a boards presence if they hadn't already registered it.
=== Silent Mode ===
Silent Mode can be triggered by the ''Silence Gesture'', a gesture reserved for the avionics board. Silent Mode can be triggered for a specific board in the flight stack, or for the entirety of the flight stack.
To put a board into Silent Mode, the avionics transmits a reserved gesture that has a payload of '/0'. The Avionics can request a specific board to enter silent mode by specifying a destination identifier, or it can request all boards to enter silent mode by using the broadcast identifier.
Silence Gesture:
{| class="wikitable"
|Type -- 0 (Request)
|State Flags -- 0 (no flags)
|Source Identifier (avionics identifier)
|Destination Identifier
|Data -- '/1/0/0' (payload is '/0')
|Checksum (8 bit)
|}
There is, additionally, a gesture to reverse this, and put a board back into Standard Mode -- this is the ''Unsilence Gesture'', which is identical to the Silence Gesture, except the payload is '/1', as shown below.
Unsilence Gesture:
{| class="wikitable"
|Type -- 0 (Request)
|State Flags -- 0 (no flags)
|Source Identifier (avionics identifier)
|Destination Identifier
|Data -- '/1/1/0' (payload is '/0')
|Checksum (8 bit)
|}
== Core Functions ==
== Core Functions ==
The STINGR library features a large array of core functions that allow boards to send, receive, and interpret gestures. There is, however, a control flow that must be followed when initializing STINGR on a given board. The following sections explain the initialization routine, as well as provide a subset of the functions that are available to be used via STINGR.
=== Initialization Routine ===