700
edits
Changes
Jump to navigation
Jump to search
Line 1:
Line 1: − + Line 6:
Line 6: − + Line 14:
Line 14: − + − As mentioned above, a Gesture consists of a series of CAN Packets -- these packets specify the source and destination of a gesture, some auxiliary data, and the primary data payload. STINGR manages CAN Packets, which are obfuscated from the end-user. − + + + Line 39:
Line 40: − + Line 46:
Line 47: − + − + + + − + Line 92:
Line 95: + + − + − + Line 107:
Line 112: + + − + − + Line 128:
Line 135: − + − − === 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''. − + − + − + − + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + − === Data Frame ===+ − − + − + − 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"+ − |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. − + − 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:+ − + − + − + − + − + − + − + − + − + − + − + − 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:+ − {| class="wikitable"+ − + − + − + − + − + + + + − − The sum of these products is 1,137, the checksum value. − + Line 201:
Line 254: − + − Type -- 1 (Response)+ − State Flags -- 0 (no flags)+ − + − Source Identifier (8 bit)+ − + − Destination Identifier -- 256 (broadcast)+ + + + + + + − Data -- '/1/0' (empty payload)+ − | style="background-color: #C25959;"| − Checksum (8 byte) − + − + − + + + Line 230:
Line 289: − + − Type -- 0 (Request)+ + + + + + + − State Flags -- 0 (no flags)+ − | style="background-color: #FFA6CE;"| − Source Identifier (avionics identifier) − | style="background-color: #EDFF7A;"| − Destination Identifier − + − | style="background-color: #C25959;"| − Checksum (8 byte) − + + − Type -- 0 (Request)+ + + + + − State Flags -- 0 (no flags)+ − + − Source Identifier (avionics identifier)+ − + − + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + − + − | style="background-color: #C25959;"| − Checksum (8 byte) Line 468:
Line 568: + +
no edit summary
{{tech-sidebar
{{HONEY-sidebar
| header = STINGR
| header = STINGR
| img link = File:stingr.png
| img link = File:stingr.png
| version = Generation I
| version = Generation I
| name = STINGR
| name = STINGR
| missions = SSI-52 onward
| acronym = Stack Transmission & Inter-Nodal Gesture Repository
}}
}}
== Gesture Specification ==
== Gesture Specification ==
The following is STINGR Gesture Specification II, which replaces the theoretical, but never implemented, [[STINGR Gesture Specification I]].<br/>
The following is STINGR Gesture Specification II, which replaces the theoretical, but never implemented, [[STINGR Gesture Specification I]].The STINGR Gesture Specification II was designed by Kirill Safin, Kai Marshland, Theo Diamandis, Ella Hofmann-Coyle, and Davy Ragland.
More explicitly, a Gesture looks is comprised of an initialization CAN Packet, followed by up to 256 additional CAN Packets, each comprised of a 1 byte header and 7 byte data payload, for a total possible data length of 256 * 7 = 1,792 bytes. The initialization CAN Packet consists of the standard header, 2 bytes of additional information, and 5 bytes of data payload. Subsequent CAN Packets consist of the 1 byte header and up to 7 bytes of data. The general structure of this format is as such:
As mentioned above, a Gesture consists of a series of CAN Packets -- these packets specify the source and destination of a gesture, some auxiliary data, and the primary data payload. STINGR manages CAN Packets, which are hidden from the end-user, and managed entirely by STINGR.
More explicitly, a Gesture looks is comprised of an initialization CAN Packet, followed by up to 256 additional CAN Packets, each comprised of a 1 byte header and 7 byte data payload, for a total possible data length of 255 * 7 = 1,792 + 4 bytes (255 packets, plus 4 bytes of data in the initialization packet). The initialization CAN Packet consists of the standard header, 3 bytes of additional information, and 4 bytes of data payload. Subsequent CAN Packets consist of the 1 byte header and up to 7 bytes of data. The general structure of this format is as such:
{| class="wikitable"
{| class="wikitable"
|}
|}
The following is the initialization CAN Packet -- the first packet sent to begin a gesture transmission. It consists of a standard header followed by a two-byte auxiliary information frame.
The following is the initialization CAN Packet -- the first packet sent to begin a gesture transmission. It consists of a standard header followed by a two-byte auxiliary information frame, and a 1 byte gesture-type specification frame.
{| class="wikitable"
{| class="wikitable"
| style="background-color: #8AFFDF;"|
| style="background-color: #8AFFDF;"|
Destination Identifier (4 bits)
Destination Identifier (4 bits)
| style="background-color: #FFA6CE;"|
| style="background-color: #8AFFDF;"|
Flags (4 bits)
Flags (4 bits)
| style="background-color: #EDFF7A;"|
| style="background-color: #8AFFDF;"|
Message Length (in # Packets) (8 bits)
Message Length (in # Packets) (8 bits)
| style="background-color: #FFA6CE;"|
Gesture Type (8 bits)
| style="background-color: #AD6DF9;"|
| style="background-color: #AD6DF9;"|
Data (5 bytes)
Data (4 bytes)
|}
|}
| style="background-color: #EDFF7A;"|
| style="background-color: #EDFF7A;"|
Message Length (in # Packets) (8 bits)
Message Length (in # Packets) (8 bits)
| style="background-color: #C25959;"|
Gesture Type (8 bits)
| style="background-color: #AD6DF9;"|
| style="background-color: #AD6DF9;"|
Data (5 bytes)
Data (4 bytes)
|}
|}
The '''Header''' is defined in the previous section. For the initialization packet, most fields in the Header remain standard -- source is the 4-bit identifier of the sending board, the parity bit is even parity, the message ID is the message ID of the current gesture. The only thing that explicitly changes in the header for the initialization packet is the '''IsInit''' bit, which is HIGH for the initialization packet.
The '''Header''' is defined in the previous section. For the initialization packet, most fields in the Header remain standard -- source is the 4-bit identifier of the sending board, the parity bit is even parity, the message ID is the message ID of the current gesture. The only thing that explicitly changes in the header for the initialization packet is the '''IsInit''' bit, which is HIGH for the initialization packet.
Following the header, the initialization packet provides two bytes of information as part of the data frame. This data is organized as such:
Following the header, the initialization packet provides three bytes of information as part of the data frame. This data is organized as such:
{| class="wikitable"
{| class="wikitable"
| style="background-color: #FFA6CE;"|
| style="background-color: #FFA6CE;"|
Length (8 bits)
Length (8 bits)
| style="background-color: #C25959;"|
Gesture Type (8 bits)
| style="background-color: #EDFF7A;"|
| style="background-color: #EDFF7A;"|
Data (8 bytes)
Data (4 bytes)
|}
|}
The reader should recognize that it is the first three frames -- Destination, Flags, and Length -- that are considered the initialization data, and that the subsequent 5 bytes of data are the beginning of the gesture data.
The reader should recognize that it is the first four frames -- Destination, Flags, Length, and Gesture Type -- that are considered the initialization data, and that the subsequent 4 bytes of data are the beginning of the gesture data.
The '''Destination''' field is a 4-bit field that uniquely identifies the destination board. This is akin to the source identifier, in that you would specify the same identifier. For example, if the BMS transmitted a gesture, and it's identifier was 2, it would specify a source identifier of 2. Likewise, if the avionics were to send a message ''to'' the BMS, it would specify a ''destination identifier'' of 2. It should be noted that the identifier of "15" is reserved as the Broadcast Identifier. A destination of 15 specifies that the entire flight-stack is the recipient of a gesture, rather than any specific board.
The '''Destination''' field is a 4-bit field that uniquely identifies the destination board. This is akin to the source identifier, in that you would specify the same identifier. For example, if the BMS transmitted a gesture, and it's identifier was 2, it would specify a source identifier of 2. Likewise, if the avionics were to send a message ''to'' the BMS, it would specify a ''destination identifier'' of 2. It should be noted that the identifier of "15" is reserved as the Broadcast Identifier. A destination of 15 specifies that the entire flight-stack is the recipient of a gesture, rather than any specific board.
The '''Request ACK''' Flag, if HIGH, indicates that a receiving board should respond to the transmitting board with an ACK to indicate that it has successfully received and acknowledged a gesture.
The '''Request ACK''' Flag, if HIGH, indicates that a receiving board should respond to the transmitting board with an ACK to indicate that it has successfully received and acknowledged a gesture.
The '''Length''' field is an 8-bit field that defines the number of subsequent CAN Packets, all of which define the current transmitting gesture. This field is used by STINGR to carefully monitor all incoming CAN traffic and reassemble gestures.
The '''Length''' field is an 8-bit field that defines the number of subsequent CAN Packets, all of which define the current transmitting gesture. This field is used by STINGR to carefully monitor all incoming CAN traffic and reassemble gestures.
The following are the current identifier codes, as of writing (June 21, 2017).
The '''Gesture Type''' field is an 8-bit field that defines the type of gesture being transmitted. This field allows STINGR to optimize performance by performing up to 256 standardized gesture in one CAN Packet instead of using multiple packets. The following table shows the current list of Gesture Types.
{| class="wikitable"
{| class="wikitable"
|-
|-
|The Count (Gen 4 Avionics)
|Custom
|00000000
|00000000
|-
|-
|Biscuit (Gen 2 BMS)
|Beacon
|00000001
|00000001
|-
|-
|Macaw (Gen 1 Radio)
|Silence
|00000010
|00000010
|-
|Unsilence
|00000011
|-
|Request Re-Transmit
|00000100
|-
|ACK
|00000101
|-
|Disable
|00000110
|-
|Enable
|00000111
|-
|Get Altitude
|00001000
|-
|Get Pressure Altitude
|00001001
|-
|Get GPS Altitude
|00001010
|-
|Get Pressure
|00001011
|-
|Get Latitude
|00001100
|-
|Get Longitude
|00001101
|-
|Get Internal Temp
|00001110
|-
|Get External Temp
|00001111
|-
|Get Stability Index
|00010000
|-
|Get Flight State
|00010001
|-
|Get Ascent Rate
|00010010
|-
|Get Voltage
|00010011
|-
|Get Current
|00010100
|-
|Get Capacity
|00010101
|}
|}
The blanket "0" type is for non-standardized gestures, which constitute a large part of board-to-board gestures. The rest of the Gesture Types specify standardized data requests or responses.
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.
=== Source & Destination Identifiers ===
The Source & Destination Identifiers merit some specific discussion. Boards each have an 8-bit unique Identifier that fully defines that board, and cannot be shared between boards. This allows for a possible 256 HONEY-compliant boards to be used within the STINGR suite. This 8-bit identifier is known as the '''Absolute Board Identifier (ABI)'''.
When a flight stack is constructed and assembled, it ends up being comprised of a series of boards each with one of these unique, enumerated identifiers. It should be noted that a flight stack '''cannot exceed''' 15 boards total (3U). Upon boot-up, the Avionics receives a variety of messages from STINGR identifying all boards in the flight stack, and re-labels the identifiers to the '''Flight Stack Identifiers''' (FSI) format, whereby all 8-bit identifiers are re-categorized and re-assigned into 4-bit stack-relative addresses.
As of August 10th, 2017, HONEY boards now also have an associated Board Serial Number (BSN). This number starts at 0 for the first of a given board to be made, and increases by one for each additional version of the same board made. The BSN was introduced to allow multiple versions of the same board to exist in the same flight stack -- IE, having two Cobra's in a stack would not permit a unique identifier for each, as their ABI is the same. By adding a BSN, the ABI and BSN are enough to uniquely identify each board in the stack.
The current checksum calculation is as follows:
'''Boards designed & fabricated prior to August 10, 2017, do not have a BSN. This includes The Count, Biscuit, and Macaw. For The Count and Biscuit, this is OK -- as there cannot be more than one BMS or Avionics in a flight stack. Macaw has no BSN, and only one Macaw can be flown in a flight stack.'''
More details about the re-assignment process can be found in the operations section of STINGR, below on this page.
The following are the current ABI's, as of August 10, 2017).
{| class="wikitable"
{| class="wikitable"
|/
|-
|1
|The Count (Gen 4 Avionics)
|H
|00000000
|E
|-
|L
|Biscuit (Gen 2 BMS)
|L
|00000001
|O
|-
|/
|Macaw (Gen 1 Radio)
|0
|00000010
|}
|-
|Cobra (Gen 1 Expander)
|00000011
|-
|72 * 1 (H)
|Viper (Gen 1 Breakout)
|69 * 2 (E)
|00000100
|76 * 3 (L)
|-
|76 * 4 (L)
|QueenBee (Gen 1 TestBench)
|79 * 5 (O)
|00000101
|-
|ProtoBee (Gen 1 Payload Board)
|00000110
|}
|}
== Operation ==
== Operation ==
The following operations are defined by STINGR Gesture Specification I -- for legacy operations defined by [[STINGR Gesture Specification I]], visit its page.
The following operations are defined by STINGR Gesture Specification II -- for legacy operations defined by [[STINGR Gesture Specification I]], visit its page.
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.
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.
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).
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:
When a board initializes STINGR, it must provide its ABI (Absolute Board 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 15 -- 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"
{| class="wikitable"
| style="background-color: #4CC9FF;"|
| style="background-color: #4CC9FF;"|
Header (Source = 15, IsInit = 1, Parity, Message ID = 0)
| style="background-color: #8AFFDF;"|
| style="background-color: #8AFFDF;"|
Destination (15 -- Broadcast)
| style="background-color: #FFA6CE;"|
| style="background-color: #8AFFDF;"|
Flags - (0000)
| style="background-color: #EDFF7A;"|
| style="background-color: #8AFFDF;"|
Length - (00000000)
| style="background-color: #8AFFDF;"|
Gesture Type - (00000001)
| style="background-color: #AD6DF9;"|
Data -- Absolute Board Identifier (1 byte)
| style="background-color: #AD6DF9;"|
Data -- Board Serial Number (1 byte)
| style="background-color: #AD6DF9;"|
| style="background-color: #AD6DF9;"|
0 Padded (3 bytes)
|}
|}
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.
This particular gesture definition is reserved, and is known as the ''beacon gesture''. It is defined by Source & Destination Identifiers of 15 (broadcast), 0 Flags, 0 Length, a Gesture Type of 1, and a data frame consisting only a 1 byte ABI and a 1 byte Serial Number, zero padded.
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.
The beacon gesture is transmitted to the entirety of the stack, and uniquely identifies a given board as being present in the flight stack. In the initialization phase, each board transmits the beacon gesture every 2 seconds. The Avionics waits 5 seconds to receive all beacon gestures, then re-assigns the received ABI's into FSI's. The FSI's are then provided to STINGR, which provides the FSI's to all other boards in the stack. Once the FSI's have been re-assigned and re-distributed, the initialization phase is over.
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.
Once the FSI's have been distributed, all boards in the flight stack are now "live" and are able to send and receive messages via STINGR. Until the FSI's are distributed, a board is not live, and STINGR will not allow any messages to be transmitted or received by the given board.
The initialization routine is limited to 5 seconds -- the time that the avionics waits to receive all beacon gestures.
=== Standard Mode ===
=== Standard 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.
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.
To put a board into Silent Mode, the avionics transmits a reserved gesture that has a gesture type of 2. 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:
Silence Gesture:
{| class="wikitable"
{| class="wikitable"
| style="background-color: #4CC9FF;"|
| style="background-color: #4CC9FF;"|
Header
| style="background-color: #8AFFDF;"|
Destination
| style="background-color: #8AFFDF;"|
Flags
| style="background-color: #8AFFDF;"|
Length - (00000000)
| style="background-color: #8AFFDF;"|
| style="background-color: #8AFFDF;"|
Gesture Type - (00000010)
| style="background-color: #AD6DF9;"|
| style="background-color: #AD6DF9;"|
Data -- '/1/0/0' (payload is '/0')
Data -- Empty
|}
|}
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.
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 Gesture Type is 3, as shown below.
Unsilence Gesture:
Unsilence Gesture:
{| class="wikitable"
{| class="wikitable"
| style="background-color: #4CC9FF;"|
| style="background-color: #4CC9FF;"|
Header
| style="background-color: #8AFFDF;"|
Destination
| style="background-color: #8AFFDF;"|
Flags
| style="background-color: #8AFFDF;"|
| style="background-color: #8AFFDF;"|
Length - (00000000)
| style="background-color: #FFA6CE;"|
| style="background-color: #8AFFDF;"|
Gesture Type - (00000011)
| style="background-color: #EDFF7A;"|
| style="background-color: #AD6DF9;"|
Destination Identifier
Data -- Empty
|}
=== Disabled Mode ===
Disabled Mode forces a board to disable all of its standard operations, except STINGR. That is, the board pauses all of its standard operations and only leaves STINGR operating, and listening -- allowing it to be re-enabled at a later time.
Disabled Mode can be triggered by the ''Disable Gesture'', a gesture reserved for the avionics board. Disable 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 Disabled Mode, the avionics transmits a reserved gesture that has a gesture type of 6. The Avionics can request a specific board to enter disabled mode by specifying a destination identifier, or it can request all boards to enter disabled mode by using the broadcast identifier.
Disable Gesture:
{| class="wikitable"
| style="background-color: #4CC9FF;"|
Header
| style="background-color: #8AFFDF;"|
Destination
| style="background-color: #8AFFDF;"|
Flags
| style="background-color: #8AFFDF;"|
Length - (00000000)
| style="background-color: #8AFFDF;"|
Gesture Type - (00000110)
| style="background-color: #AD6DF9;"|
Data -- Empty
|}
There is, additionally, a gesture to reverse this, and put a board back into Standard Mode -- this is the ''Enable Gesture'', which is identical to the Disable Gesture, except the Gesture Type is 7, as shown below.
Enable Gesture:
{| class="wikitable"
| style="background-color: #4CC9FF;"|
Header
| style="background-color: #8AFFDF;"|
Destination
| style="background-color: #8AFFDF;"|
Flags
| style="background-color: #8AFFDF;"|
Length - (00000000)
| style="background-color: #8AFFDF;"|
Gesture Type - (00000111)
| style="background-color: #AD6DF9;"|
| style="background-color: #AD6DF9;"|
Data -- '/1/1/0' (payload is '/1')
Data -- Empty
|}
|}
</code><br />
</code><br />
Sends a speciality gesture to all boards to resume all operations.
Sends a speciality gesture to all boards to resume all operations.
[[Category: High Altitude Balloons]][[Category: HABEES]][[Category: HONEY]]