Astrojays Rocketry – Documentation

Docs: Bit Manipulations

Mon, 01 Jan 0001 00:00:00 +0000

Version: 0.1.0
Date: 28 October 2019
Status: Draft
Type: Guide
ID: 3G

Overview

Data can be packed more compactly than even the smallest primitive type allow by manipulating the individual bytes of the numbers. For example, an 8 bit unsigned integer (uint8_t) can contain the number from 0-255, 8 boolean flags, 4 two bit numbers (0-3), a combination of 3-bit numbers (0-8) and two bit number, 2 4-bit numbers (0-15), or any combination of these. In general, the smallest on-wire primitive type in modern programming languages are at least 8 bits wide, even boolean type which can only hold two states. In a bandwidth constrained application like long-distance radio signaling, every bit matters, and thus Bit manipulation become a handy method to pack more data in much less space.

Basic Operations

To manipulate numerical data types at the bit level, we must resort to binary operators such as AND(&), OR(|), XOR(|), and NOT(~). These follow the following truth tables (A,B are inputs, Y is the output):

NOT

Y	A
0	1
1	0

AND

Y	A	B
0	0	0
0	0	1
0	1	0
1	1	1

Y	A	B
0	0	0
1	0	1
1	1	0
1	1	1

XOR

Y	A	B
0	0	0
1	0	1
1	1	0
0	1	1

These operations can be used formally to do boolean algebra. However, from a practical perspective, for data packing purposes, each of these operator have somewhat specific functions. An AND operator serves as a mask, allowing specific bits from a number to be “selected”. For instance:

IN        = 0b010100111
MASK      = 0b000010100 # "selecting" bits 5 and 3
IN & MASK = 0b000000100

And the OR operator can be used to “set” bits

IN           = 0b00100000
SETBITS      = 0b00100001
IN | SETBITS = 0b00100001

To unset bits, a combination and & and ~ can be used.

Additionally, there are the left shift(<<) and right shift(<<) operators, which “move” the number over a set number of bits and fill the rest of zeroes. For example:

0b00011 << 3 = 0b00011000
0b1010011 >> 4 = 0b101

Recipes

Bit Flag Setting

IN |= PATTERN << n

Where IN is an input variable, PATTERN is the pattern that need to get set, and n is the number of bits into the input where the pattern should get set. For instance:

IN = 0b000110011
        ~^

and we want to set the two underlined bits to 111, we’d do

IN |= 0b11 << 6

It is important to note that his can only set bits, if a bit is already one it cannot be converted to a zero.

Bit Flag Clearing

To clear bits, we follow the following recipe

IN &= ~(PATTERN << n)

For example:

IN = 0b0001010011
          ~~^

and we want to clear the three underlined bits (set them back to zero), we’d use

IN &= ~(0b111 << 4)

Reading bits

OUT = IN & MASK

For example, to read the 3 most significant bits from 0b0101100, we’d use

OUT = IN & 0b1110000
# or
OUT = IN & 0b111 << 4
# OUT = 0b0100000

However the issue here is that the extracted bits will still be in their original columns, and thus will be as large as the originals. To remedy this, we can right shift by the number of bits to make the LSB of the masked output to be in the 2^0 place.

OUT = (IN & MASK) >> n

OUT = (IN & 0b1110000) >> n
# out = 0b010

Thus, the easiest way to set a number of bits that might contains ones to a custom patters is to first clear those bits, then set using the OR operator.

Toggling

Finally, toggling is pretty similar to the other two, except we use the Xor operator instead of OR or AND:

IN ^= (PATTERN << n)

For example:

IN = 0b00110011
       ~~^

To toggle the three underlined bytes, we’d use:

IN ^= (0b111 << 5)
# IN = 0b11010011

Docs: General

Mon, 01 Jan 0001 00:00:00 +0000

Version: 0.1.0
Date: 19 October 2019
Status: Draft
Type: System Specification

Overview

Propulsion Avionics shall be avionics systems that control and instrument the BJ-01 rocket engine during test runs (CFTs and hot fires) and full flights. This system is safety critical, and any changes shall be integration tested with propulsion components before flying.

Goals

Minimize risk to anyone involved in propulsion system operations
Ensure reliable ignition and operation of the BJ-01 rocket engine
Collect propulsion system metrics for analysis

Requirements

Accept and log instrumentation data
Initiate and monitor ignition process for the rocket engine
Monitor instrumentation and alert operator(s) in case of malfunction and/or automatically act to minimize safety risk.
Respond automatically to failures to minimize safety risk

Out of scope

Rocket operations after engine burn has completed (this is the domain of recovery avionics)
Rocket operations before oxidizer fueling (this is the domain of the ground support hardware)

Components:

Data Acquisition Plane (DAP): Tasked with receiving and logging data from engine instrumentation
Command & Control Plane (C2P): Tasked with receiving operator commands and sending the appropriate control signals to the engine (oxidizer valve and fueling solenoids). Also tasked with automatically responding to real-time data received from the DAQ.
Data Transmission and Visualization plane (DTP): Tasked with transmitting data to the operator console. Must also visualize telemetry data easing identification of error conditions.

Data Acquisition Plane

The data acquisition plane shall read and track the state of the following engine components:

Thermocouples (TCs)
Pressure transducers (PTs)
Load cells (LCs)
Solenoids
Motorized valve

and log the output to a csv log at a sample rate of __ seconds. The log shall consist of one line per sample and E_[sensor] for any data collection errors. The log for each run shall be called log_[time] where [time] is the Unix timestamp. The DAQ shall also provide the DTP and C2P with updated data in every sample interval.

Command and Control Plane

See the specification for a detailed treatment of this component.

Docs: Specification Guidelines

Mon, 01 Jan 0001 00:00:00 +0000

Version: 0.0.1
Date: 29 September 2019
Status: Draft
Type: Meta-Specification
ID: 0M

Description

All specifications must have the following components:

Title
Header
Description or Overview section
Requirements section

and may also contain a “Components” and “Implementation” section as deemed necessary. Specifications must be written in markdown or asciidoc syntax, to ensure that the plaintext is equally readable.

Title and Header

The title should be a concise description of what the specification covers. All titles for specifications must be unique to prevent confusion.

The header serves as the “metadata” for the specification and should only contain the following fields:

Version: Following semver specifications
Date: Indicating the date that the specification was last updated
Status: Indicating where the specification lies along the specification lifecycle
Type: Describing what type of document it is. Must be one of the following values:
1. “Specification”: Engineering specifications for systems, formats, and components
2. “Meta-Specification”: Specifications about specifications are specification lifecycle and usage.
ID: A unique number assigned to each spec when it reaches draft status that serves as an official alias.

When creating the header, each line should have two space characters ( ) to force a new line between each item.

Example title and header

# B System Specifications
Version: 0.1.1  
Date: 20 September 2019  
Status: Draft  
Type: Meta-Specification

Overview/Description

This section shall contain a short description of the thing covered by the specification, as well as a brief overview specification conditions.

Requirements

This section shall list each requirement of an implementation that is in spec Each item listed here must be verified before the system is declared complete. Definitions written here shall follow meta-spec 1M “Keywords for use in specifications”

Docs: Specification Keywords

Mon, 01 Jan 0001 00:00:00 +0000

Version 1.0.0
Date: 29 September 2019
Status: Current
Type: Meta Specification
ID: 1M based on rfc2119

The following keywords shall carry special meaning when used within a specification:

SHALL: This word, and the words “REQUIRED” and “MUST”, mean that the definition is an absolute requirement of the specification. Implementations that fail to comply with one of these directives are always out of spec
SHALL NOT: This phrase and the phrase “MUST NOT” mean an absolute prohibition of the specification.
SHOULD: This word, or the word “RECOMMENDED”, mean that the definition is a strong recommendation of the specification that should be followed in the absence of a valid reason to diverge. Team members should seek advice from the subsystem lead before disregarding these directives. Divergences with documented justifications are within spec.
SHOULD NOT: This phrase means a strong discouragement of the specification.
MAY: This word means that the definition is completely optional recommendation of the specification and may be disregarded at will. Divergences are always within spec.
MAY NOT: This words means that the directive is a completely optional prohibition of the specification.

Docs: Specification Template

Mon, 01 Jan 0001 00:00:00 +0000

Version: 0.1.0
Date: 29 September 2019
Status: Provisional Document
Type: Meta Specification
ID: 2M

Template

Copy and paste the following into a markdown file, edit out the placeholders, and remove unneeded portions.

# Specifications for [system]
Version: [version]  
Date: [Date]  
Status: [status]  
Type: System Specification  
ID: [ID]  

## Overview
[Required Section]
This *word* is italicized. This **word** is bold.

## Goals
[Optional Section]

## Requirements
[Required Section]
1. This
2. is
3. an
4. ordered
5. list.

## Out of scope
[Optional Section]
- This
- is
- an
- unordered
- list.

## Componenets
[Optional Section]
```
this is a prmformatted code block
syntax highlighting will be automatically applied.
```

## Implementation
[Optional section]

## See also
[Optional section]

Docs: Control Plane

Mon, 01 Jan 0001 00:00:00 +0000

Version: 0.5.1
Date: 28 October 2019
Status: Draft
Type: Component Specification

Overview

The command and control (C2) plane is responsible for communicating with onboard systems such as the engine, and ensure they remain responsive and under operator control at all times. Control signals shall be transmitted over 915Mhz LoRa radio

I2C Protocol

I2C shall be used as the inter-board communication method of choice between the custom controllers in this system. The I2C protocol should follow the following

Device IDs

Address	Device
10	Engine Controller
11	Ground Valve Controller
48	ADC (for PTs)

To get the current EC state, request a single byte over I2C.

EC State packet

Bit 7	Bit 6	Bit 5	Bit 4	Bit 3	Bit 2	Bit 1	Bit 0
null	null	null	Req MV-G1 State	eMatch	MV-R1	MV-R1 moving	MV-S1

The EC will accept the following single byte write to set modifiable state

EC Command Packeta

Bit 7	Bit 6	Bit 5	Bit 4	Bit 3	Bit 2	Bit 1	Bit 0
null	null	null	null	null	Vent	Vent	E Shutdown

Vent is a two bit number to contain all of its states, with MSB at Bit 2 and LSB at bit 1.

Since the PI serves as the bus master, it should check the Requested MV-G1 State and compare it to the last one sent to the Ground valve controller. If it is different it should construct a single byte command packet with value 1 and sent it to the Ground valve Controller.

Radio protocol

The Ground Station, Relay Box and Ignition computer shall all implement the C2 over 915Mhz LoRa radio. Each packet sent over the LoRa network shall follow the following format:

Packet Byte	Description
0	Sender/Receiver ID byte
1	Packet Type
2…n	Packet Payload

Bytes 0-1 are considered the “header” of the packet and primarily serve as metadata that allow receivers to choose how to handle packets with minimal overhead.

The sender/receiver ID shall be an 8 bit integer (uint8_t) with the high 4 bits representing the sender ID and the low 4 bits representing the receiver ID. That is:

0b11110000 will be split into
Sender ID = 0b1111 = 15
Receiver ID = 0b0000 = 0

These IDs must follow the table below:

C2 Plane Component	ID
Ground Station	0
Ignition (Engine) Computer	1
Relay Box Controller	2
Broadcast	15

NOTE: ID #15 is reserved for broadcast messages sent to all radio devices on the same network and thus the maximum devices that can be connected to the same network as of this spec is 15.

Thus, if the Ground Station were to send a packet to the Ignition Computer, it would send 0b00000001 in the 1 byte of its radio packet. This also means that the sender of a packet can be determined by parsing byte 1 of the packet.

Packet types must be one of the following:

Packet Type	Code
NOOP (does nothing)	0
GS State Command	1
Heartbeat Request	2
ACK	100
NACK	101

Synchronization and Acknowledgemen

The C2 plane uses an acked radio protocol. This means that every command sent from the Grand Station to the rocket must be acknowledged by a corresponding packet from the rocket to be considered successfully transmitted. However, since only the newest state of the ground station needs to be carried out by the rocket, only the latest command packet will need to be acked.

repeat forever:
    if button state changed from last transmitted state:
        record state of GS
        assign sequence code to state so ack can be track
        replace current state pending ack
        send state to rocket
    otherwise:
       if state transmission is pending ack
             check for ack with matching sequence number from rocket, if received, mark state as acked
             if no response, and time is over ack timeout:
                 resend only if there are retries left, otherwise light up transmission error led

Heartbeat Request Packet Format:

Packet Byte	Content
0-1	HEADER
2	Sequence Code

ACK Packet Format:

Packet Byte	Content
0-1	HEADER
2	Sequence Code

The sequence code is a pseudo-unique code that matches request packets with their corresponding ACK packets. Sequence codes should be incremented after every ack’d packet transmission and should roll over at 256 (uint8_t will do this automatically). All ack’d packets transmitted from the same node should use and increment the same sequence node counter to ensure that all packets transmitted in a short time window from the node have different sequence codes. Packets that require acknowledgement should include a sequence code so the resulting ack can be tracked back to the originating request.

Valve Control

Valve Control Packet

Packet Byte	Content
0-1	HEADER
2	Sequence Code
3	Ball Valve State
4	Vent State
5	Fuel Valve State

The ignition computer receives valve control commands from the operator. Corresponding control signals are then sent to the propulsion system. Radio commands for each valve shall be represented by an integer value, should be of the int8_t type. As there are 3 valves, a radio command shall be an array containing 3 integers of the following order:

Open/Close of fuel-combustion ball valve
Open/Close of fueling solenoid valve
Open/Close of venting solenoid valve

The commands values used by each of the command is outlined in the following tables. Note, the values here are only used at software level, whilst the actual signals sent to hardware components need to be defined based on the particular needs.

Ball valve control

value	Description
0	Standby signal that does not lead to any change in current valve action.
1	Reversed movement of the valve.
2	Forward movement of the valve.
255	signal for Ignition Sequence, including opening the valve for a preset amount of time, before closing.

Venting solenoid valve control

value	Description
0	Standby Signal, with no change in current valve action
1	Closing of the venting valve
2	Opening of the venting valve

Fuel solenoid valve control

value	Description
0	Standby Signal, with no change in current valve action
1	Closing of the Fuel valve
2	Opening of the Fuel valve

One example of a command would be {1,-1,0}, denoting the unlikely command of forward action of ball valve, no change in action of venting valve, and the closing of fuel valve. For future expansion of the commands, it is recommended that any simple command should obtain a value ascending from 1, whilst complex sequence command should obtain a value descending from 127. For the valves used, Simple and sequence commands are defined as:

Simple command is a command that is accomplished by #one# #continuous# and #unidirectional# action of the valve.
Sequence commands is a command that is accomplished by #multiple# #discontinuous(e.g. with intervals)# and/or #multidirectional# action of the valve.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

DartPlot Utility Specifications

Version: 0.1.0
Date: 14 September 2019
Status: Current
Type: Software Specification
ID: 4S

Description

dartplot is a utility that takes a complete csv flight log as the input. It will output plots for each of the sensors of interest in the form of png images.

Requirements

The following quantities will be plotted against time (t):

6 thermocouples (Header name TC#)
3 loadcells against time (Header name LC#)
4 pressure transducers (Header name PT#)

The utility will output to folder called plots by default, in the directory the script was run in.

The following will also be plotted:

1 red horizontal line at critical pressure and critical temperature
boolean sensor monitor

Future Considerations

Continuous monitor?
Find a way to process data faster?