AltOS

Revision History
Revision 0.1	22 November 2010
Initial content

Revision History
Revision 0.1	22 November 2010
Initial content

+ Version 1.1.1 is a bug-fix release. It fixes a couple of bugs in + AltosUI and one firmware bug that affects TeleMetrum version 1.0 + boards. Thanks to Bob Brown for help diagnosing the Google Earth + file export issue, and for suggesting the addition of the Ground + Distance value in the Descent tab. +

Version 1.1 is a minor release. It provides a few new features in AltosUI and the AltOS firmware and fixes bugs.

AltOS Companion Port

Protocol Definitions

Keith Packard

+AltOS Companion Port
AltOS Companion Port
Protocol Definitions
Keith Packard
Copyright © 2012 Keith Packard
This document is released under the terms of the Creative Commons ShareAlike 3.0 license. -
Revision History
Revision 0.1 13 January 2012
Initial content
Table of Contents
1. Companion Port
2. Companion SPI Protocol
3. SPI Message Formats
3.1. Command Message
3.2. SETUP reply message
3.3. FETCH reply message
4. History and Motivation
1. Companion Port
+
Revision History
Revision 0.1 13 January 2012
Initial content

Revision History
Revision 0.1	13 January 2012
Initial content

Revision History
Revision 0.1	13 January 2012
Initial content

Table of Contents

1. Companion Port

2. Companion SPI Protocol

3. SPI Message Formats

3.1. Command Message
3.2. SETUP reply message
3.3. FETCH reply message

4. History and Motivation

1. Companion Port

Many Altus Metrum products come with an eight pin Micro MaTch connector, called the Companion Port. This is often used to program devices using a programming cable. However, it can also @@ -25,7 +25,7 @@ provide a matching SPI slave implementation which supplies telemetry information for the radio downlink during flight

2. Companion SPI Protocol

The flight computer implements a SPI master communications channel over the companion port, and uses this to get information about a connected companion board and then to get @@ -42,11 +42,11 @@

Because of the limits of the AVR processors used in the first two companion boards, the SPI data rate is set to 187.5kbaud. -

3. SPI Message Formats

This section first defines the command message format sent from the flight computer to the companion board, and then the various reply message formats for each type of command message. -
3.1. Command Message
Table 1. Companion Command Message
Offset Data Type Name Description
0 uint8_t command Command identifier
1 uint8_t flight_state Current flight computer state
2 uint16_t tick Flight computer clock (100 ticks/second)
4 uint16_t serial Flight computer serial number
6 uint16_t flight Flight number
8

Table 2. Companion Command Identifiers
Value Name Description
1 SETUP Supply the flight computer with companion +
3.1. Command Message
Table 1. Companion Command Message
Offset Data Type Name Description
0 uint8_t command Command identifier
1 uint8_t flight_state Current flight computer state
2 uint16_t tick Flight computer clock (100 ticks/second)
4 uint16_t serial Flight computer serial number
6 uint16_t flight Flight number
8

Table 2. Companion Command Identifiers
Value Name Description
1 SETUP Supply the flight computer with companion information
2 FETCH Return telemetry information
3 NOTIFY Tell companion board when flight state changes

The flight computer will send a SETUP message shortly after @@ -74,7 +74,7 @@ use this to change data collection parameters, disabling data logging until the flight starts and terminating it when the flight ends. -
3.2. SETUP reply message
Table 3. SETUP reply contents
Offset Data Type Name Description
0 uint16_t board_id Board identifier
2 uint16_t board_id_inverse ~board_id—used to tell if a board is present
4 uint8_t update_period Minimum time (in 100Hz ticks) between FETCH commands
5 uint8_t channels Number of data channels to retrieve in FETCH command
6

+
3.2. SETUP reply message
Table 3. SETUP reply contents
Offset Data Type Name Description
0 uint16_t board_id Board identifier
2 uint16_t board_id_inverse ~board_id—used to tell if a board is present
4 uint8_t update_period Minimum time (in 100Hz ticks) between FETCH commands
5 uint8_t channels Number of data channels to retrieve in FETCH command
6

The SETUP reply contains enough information to uniquely identify the companion board to the end user as well as for the flight computer to know how many data values to expect in @@ -85,12 +85,12 @@ bit-wise inverse of board_id. Current companion boards use USB product ID as the board_id, but the flight computer does not interpret this data and so it can be any value. -
3.3. FETCH reply message
Table 4. FETCH reply contents
Offset Data Type Name Description
0 uint16_t data0 0th data item
2 uint16_t data1 1st data item
...

+
3.3. FETCH reply message
Table 4. FETCH reply contents
Offset Data Type Name Description
0 uint16_t data0 0th data item
2 uint16_t data1 1st data item
...

The FETCH reply contains arbitrary data to be reported over the flight computer telemetry link. The number of 16-bit data items must match the 'channels' value provided in the SETUP reply message. -
4. History and Motivation
+
4. History and Motivation
To allow cross-programming, the original TeleMetrum and TeleDongle designs needed to include some kind of connector. With that in place, adding the ability to connect diff --git a/AltOS/doc/companion.pdf b/AltOS/doc/companion.pdf index 37616b6647af09a8501efc4c06c0cfd70f8f5e98..d10306b1d9e705aa8c67f475124732b1fb65227a 100644 GIT binary patch delta 163 zcmdlqhjG&!#tG%@W`-t42Bu~k>)vy7nS~gdSQ!~unVM}b=dol&;!obin~TKVY{<9B zKHkvG+|}63z{1VZ#m&{t(bCk>*woC?)WpKn)zrY%$i+^)vy78HX5}TA5f{85(RZ=dol&;!obin~TKVY{<9B zKHl8P%*D*u)zs0_*wn((z}eN=+{Dqq(!$u-%*n#U$kk54hM
+ Version 1.1.1 is a bug-fix release. It fixes a couple of bugs in + AltosUI and one firmware bug that affects TeleMetrum version 1.0 + boards. Thanks to Bob Brown for help diagnosing the Google Earth + file export issue, and for suggesting the addition of the Ground + Distance value in the Descent tab. +
+ AltOS Firmware Changes +
+ TeleMetrum v1.0 boards use the AT45DB081D flash memory part to + store flight data, which is different from later TeleMetrum + boards. The AltOS v1.1 driver for this chip couldn't erase + memory, leaving it impossible to delete flight data or update + configuration values. This bug doesn't affect newer TeleMetrum + boards, and it doesn't affect the safety of rockets flying + version 1.1 firmware. +
+
+ AltosUI Changes +
+ Creating a Google Earth file (KML) from on-board flight data + (EEPROM) would generate an empty file. The code responsible + for reading the EEPROM file wasn't ever setting the GPS valid + bits, and so the KML export code thought there was no GPS data + in the file. +
+ The “Landed” tab was displaying all values in metric units, + even when AltosUI was configured to display imperial + units. Somehow I just missed this tab when doing the units stuff. +
+ The “Descent” tab displays the range to the rocket, which is a + combination of the over-the-ground distance to the rockets + current latitude/longitude and the height of the rocket. As + such, it's useful for knowing how far away the rocket is, but + difficult to use when estimating where the rocket might + eventually land. A new “Ground Distance” field has been added + which displays the distance to a spot right underneath the + rocket. +
+ Sensor data wasn't being displayed for TeleMini flight + computers in Monitor Idle mode, including things like battery + voltage. The code that picked which kinds of data to fetch + from the flight computer was missing a check for TeleMini when + deciding whether to fetch the analog sensor data. +
+
diff --git a/AltOS/doc/telemetry.html b/AltOS/doc/telemetry.html index e1cdb01..6cabe0b 100644 --- a/AltOS/doc/telemetry.html +++ b/AltOS/doc/telemetry.html @@ -1,10 +1,10 @@ -AltOS Telemetry
AltOS Telemetry
Packet Definitions
Keith Packard
Copyright © 2011 Keith Packard
+AltOS Telemetry
AltOS Telemetry
Packet Definitions
Keith Packard
Copyright © 2011 Keith Packard
This document is released under the terms of the Creative Commons ShareAlike 3.0 license. -
Revision History
Revision 0.1 01 July 2011
Initial content
Table of Contents
1. Packet Format Design
2. Packet Formats
2.1. Packet Header
2.2. Sensor Data
2.3. Configuration Data
2.4. GPS Location
2.5. GPS Satellite Data
3. Data Transmission
3.1. Modulation Scheme
3.2. Error Correction
4. TeleDongle packet format
5. History and Motivation
1. Packet Format Design
+
Revision History
Revision 0.1 01 July 2011
Initial content
Table of Contents
1. Packet Format Design
2. Packet Formats
2.1. Packet Header
2.2. Sensor Data
2.3. Configuration Data
2.4. GPS Location
2.5. GPS Satellite Data
3. Data Transmission
3.1. Modulation Scheme
3.2. Error Correction
4. TeleDongle packet format
5. History and Motivation
1. Packet Format Design
AltOS telemetry data is split into multiple different packets, all the same size, but each includs an identifier so that the ground station can distinguish among different types. A single @@ -22,14 +22,14 @@ All packet types start with a five byte header which encodes the device serial number, device clock value and the packet type. The remaining 27 bytes encode type-specific data. -
2. Packet Formats
+
2. Packet Formats
This section first defines the packet header common to all packets and then the per-packet data layout. -
2.1. Packet Header
Table 1. Telemetry Packet Header
Offset Data Type Name Description
0 uint16_t serial Device serial Number
2 uint16_t tick Device time in 100ths of a second
4 uint8_t type Packet type
5

+
2.1. Packet Header
Table 1. Telemetry Packet Header
Offset Data Type Name Description
0 uint16_t serial Device serial Number
2 uint16_t tick Device time in 100ths of a second
4 uint8_t type Packet type
5

Each packet starts with these five bytes which serve to identify which device has transmitted the packet, when it was transmitted and what the rest of the packet contains. -
2.2. Sensor Data
Type Description
0x01 TeleMetrum Sensor Data
0x02 TeleMini Sensor Data
0x03 TeleNano Sensor Data
+
2.2. Sensor Data
Type Description
0x01 TeleMetrum Sensor Data
0x02 TeleMini Sensor Data
0x03 TeleNano Sensor Data
TeleMetrum, TeleMini and TeleNano share this same packet format for sensor data. Each uses a distinct packet type so that the receiver knows which data values are valid and which @@ -38,63 +38,63 @@ Sensor Data packets are transmitted once per second on the ground, 10 times per second during ascent and once per second during descent and landing -
Table 2. Sensor Packet Contents
Offset Data Type Name Description
5 uint8_t state Flight state
6 int16_t accel accelerometer (TM only)
8 int16_t pres pressure sensor
10 int16_t temp temperature sensor
12 int16_t v_batt battery voltage
14 int16_t sense_d drogue continuity sense (TM/Tm)
16 int16_t sense_m main continuity sense (TM/Tm)
18 int16_t acceleration m/s² * 16
20 int16_t speed m/s * 16
22 int16_t height m
24 int16_t ground_pres Average barometer reading on ground
26 int16_t ground_accel TM
28 int16_t accel_plus_g TM
30 int16_t accel_minus_g TM
32

2.3. Configuration Data
Type Description
0x04 Configuration Data
+
Table 2. Sensor Packet Contents
Offset Data Type Name Description
5 uint8_t state Flight state
6 int16_t accel accelerometer (TM only)
8 int16_t pres pressure sensor
10 int16_t temp temperature sensor
12 int16_t v_batt battery voltage
14 int16_t sense_d drogue continuity sense (TM/Tm)
16 int16_t sense_m main continuity sense (TM/Tm)
18 int16_t acceleration m/s² * 16
20 int16_t speed m/s * 16
22 int16_t height m
24 int16_t ground_pres Average barometer reading on ground
26 int16_t ground_accel TM
28 int16_t accel_plus_g TM
30 int16_t accel_minus_g TM
32

2.3. Configuration Data
Type Description
0x04 Configuration Data
This provides a description of the software installed on the flight computer as well as any user-specified configuration data.
Configuration data packets are transmitted once per second during all phases of the flight -
Table 3. Sensor Packet Contents
Offset Data Type Name Description
5 uint8_t type Device type
6 uint16_t flight Flight number
8 uint8_t config_major Config major version
9 uint8_t config_minor Config minor version
10 uint16_t apogee_delay Apogee deploy delay in seconds
12 uint16_t main_deploy Main deploy alt in meters
14 uint16_t flight_log_max Maximum flight log size (kB)
16 char callsign[8] Radio operator identifier
24 char version[8] Software version identifier
32

2.4. GPS Location
Type Description
0x05 GPS Location
+
Table 3. Sensor Packet Contents
Offset Data Type Name Description
5 uint8_t type Device type
6 uint16_t flight Flight number
8 uint8_t config_major Config major version
9 uint8_t config_minor Config minor version
10 uint16_t apogee_delay Apogee deploy delay in seconds
12 uint16_t main_deploy Main deploy alt in meters
14 uint16_t flight_log_max Maximum flight log size (kB)
16 char callsign[8] Radio operator identifier
24 char version[8] Software version identifier
32

2.4. GPS Location
Type Description
0x05 GPS Location
This packet provides all of the information available from the Venus SkyTraq GPS receiver—position, time, speed and precision estimates.
GPS Location packets are transmitted once per second during all phases of the flight -
Table 4. GPS Location Packet Contents
Offset Data Type Name Description
5 uint8_t flags See GPS Flags table below
6 int16_t altitude m
8 int32_t latitude degrees * 10⁷
12 int32_t longitude degrees * 10⁷
16 uint8_t year
17 uint8_t month
18 uint8_t day
19 uint8_t hour
20 uint8_t minute
21 uint8_t second
22 uint8_t pdop * 5
23 uint8_t hdop * 5
24 uint8_t vdop * 5
25 uint8_t mode See GPS Mode table below
26 uint16_t ground_speed cm/s
28 int16_t climb_rate cm/s
30 uint8_t course / 2
31 uint8_t unused[1]
32

+
Table 4. GPS Location Packet Contents
Offset Data Type Name Description
5 uint8_t flags See GPS Flags table below
6 int16_t altitude m
8 int32_t latitude degrees * 10⁷
12 int32_t longitude degrees * 10⁷
16 uint8_t year
17 uint8_t month
18 uint8_t day
19 uint8_t hour
20 uint8_t minute
21 uint8_t second
22 uint8_t pdop * 5
23 uint8_t hdop * 5
24 uint8_t vdop * 5
25 uint8_t mode See GPS Mode table below
26 uint16_t ground_speed cm/s
28 int16_t climb_rate cm/s
30 uint8_t course / 2
31 uint8_t unused[1]
32

Packed into a one byte field are status flags and the count of satellites used to compute the position fix. Note that this number may be lower than the number of satellites being tracked; the receiver will not use information from satellites with weak signals or which are close enough to the horizon to have significantly degraded position accuracy. -
Table 5. GPS Flags
Bits Name Description
0-3 nsats Number of satellites in solution
4 valid GPS solution is valid
5 running GPS receiver is operational
6 date_valid Reported date is valid
7 course_valid ground speed, course and climb rates are valid

+
Table 5. GPS Flags
Bits Name Description
0-3 nsats Number of satellites in solution
4 valid GPS solution is valid
5 running GPS receiver is operational
6 date_valid Reported date is valid
7 course_valid ground speed, course and climb rates are valid

Here are all of the valid GPS operational modes. Altus Metrum products will only ever report 'N' (not valid), 'A' (Autonomous) modes or 'E' (Estimated). The remaining modes are either testing modes or require additional data. -
Table 6. GPS Mode
Mode Name Decsription
N Not Valid All data are invalid
A Autonomous mode Data are derived from satellite data
D Differential Mode +
Table 6. GPS Mode
Mode Name Decsription
N Not Valid All data are invalid
A Autonomous mode Data are derived from satellite data
D Differential Mode Data are augmented with differential data from a known ground station. The SkyTraq unit in TeleMetrum does not support this mode
E Estimated Data are estimated using dead reckoning from the last known data -
M Manual Data were entered manually
S Simulated GPS receiver testing mode

2.5. GPS Satellite Data
Type Description
0x06 GPS Satellite Data
+
M Manual Data were entered manually
S Simulated GPS receiver testing mode

2.5. GPS Satellite Data
Type Description
0x06 GPS Satellite Data
This packet provides space vehicle identifiers and signal quality information in the form of a C/N1 number for up to 12 satellites. The order of the svids is not specified.
GPS Satellite data are transmitted once per second during all phases of the flight. -
Table 7. GPS Satellite Data Contents
Offset Data Type Name Description
5 uint8_t channels Number of reported satellite information
6 sat_info_t sats[12] See Per-Satellite data table below
30 uint8_t unused[2]
32

Table 8. GPS Per-Satellite data (sat_info_t)
Offset Data Type Name Description
0 uint8_t svid Space Vehicle Identifier
1 uint8_t c_n_1 C/N1 signal quality indicator
2

3. Data Transmission
+
Table 7. GPS Satellite Data Contents
Offset Data Type Name Description
5 uint8_t channels Number of reported satellite information
6 sat_info_t sats[12] See Per-Satellite data table below
30 uint8_t unused[2]
32

Table 8. GPS Per-Satellite data (sat_info_t)
Offset Data Type Name Description
0 uint8_t svid Space Vehicle Identifier
1 uint8_t c_n_1 C/N1 signal quality indicator
2

3. Data Transmission
Altus Metrum devices use the Texas Instruments CC1111 microcontroller which includes an integrated sub-GHz digital transceiver. This transceiver is used to both transmit and receive the telemetry packets. This section discusses what modulation scheme is used and how this device is configured. -
3.1. Modulation Scheme
+
3.1. Modulation Scheme
Texas Instruments provides a tool for computing modulation parameters given a desired modulation format and basic bit rate. For AltOS, the basic bit rate was specified as 38 kBaud, resulting in the following signal parmeters: -
Table 9.
Parameter Value Description
Modulation GFSK Gaussian Frequency Shift Keying
Deviation 20.507812 kHz Frequency modulation
Data rate 38.360596 kBaud Raw bit rate
RX Filter Bandwidth 93.75 kHz Receiver Band pass filter bandwidth
IF Frequency 140.62 kHz Receiver intermediate frequency

3.2. Error Correction
+
Table 9.
Parameter Value Description
Modulation GFSK Gaussian Frequency Shift Keying
Deviation 20.507812 kHz Frequency modulation
Data rate 38.360596 kBaud Raw bit rate
RX Filter Bandwidth 93.75 kHz Receiver Band pass filter bandwidth
IF Frequency 140.62 kHz Receiver intermediate frequency

3.2. Error Correction
The cc1111 provides forward error correction in hardware, which AltOS uses to improve reception of weak signals. The overall effect of this is to halve the available bandwidth for data from 38 kBaud to 19 kBaud. -
Table 10.
Parameter Value Description
Error Correction Convolutional coding FEC 1/2 code, constraint length m=4
Interleaving 4 x 4 Reduce effect of noise burst
Data Whitening XOR with 9-bit PNR Rotate right with bit 8 = bit 0 xor bit 5, initial - value 111111111

4. TeleDongle packet format
+
Table 10.
Parameter Value Description
Error Correction Convolutional coding FEC 1/2 code, constraint length m=4
Interleaving 4 x 4 Reduce effect of noise burst
Data Whitening XOR with 9-bit PNR Rotate right with bit 8 = bit 0 xor bit 5, initial + value 111111111

4. TeleDongle packet format
TeleDongle does not do any interpretation of the packet data, instead it is configured to receive packets of a specified length (32 bytes in this case). For each received packet, @@ -106,9 +106,9 @@ the packet data, two bytes added by the cc1111 radio receiver hardware and finally a checksum so that the host software can validate that the line was transmitted without any errors. -
Table 11.
Offset Name Example Description
0 length 22 Total length of data bytes in the line. Note that +
Table 11.
Offset Name Example Description
0 length 22 Total length of data bytes in the line. Note that this includes the added RSSI and status bytes
1 ·· length-3 packet 4f ·· 00 Bytes of actual packet data
length-2 rssi 3f Received signal strength. dBm = rssi / 2 - 74
length-1 lqi a9 Link Quality Indicator and CRC status. Bit 7 - is set when the CRC is correct
length checksum 88 (0x5a + sum(bytes 1 ·· length-1)) % 256

5. History and Motivation
+ is set when the CRC is correct
length checksum 88 (0x5a + sum(bytes 1 ·· length-1)) % 256

5. History and Motivation
The original AltoOS telemetry mechanism encoded everything available piece of information on the TeleMetrum hardware into a single unified packet. Initially, the packets contained very diff --git a/AltOS/doc/telemetry.pdf b/AltOS/doc/telemetry.pdf index 938dc825b08db024044d0cad75feda06008cbd0e..1556094cfec2f993e61c5374bd89b9477023f1d9 100644 GIT binary patch delta 163 zcmbO?g=yXtrU~WjW`-t42Bsz(>)vy7nS~gdSQ!~unVM`a=dol&;!obin~TKVY{=JF z9q(vp>||tSW@+r^V&P_K;$m!MX=Lu`>|$zaVdUoKW?`pbLr_U9mz^C~aY)vy78HX5}TA5f{8CYyC=dol&;!obin~TKVY{=JF z9dGVz;OgpT;^JmzWNB$>;b!4tVrgmYXl~|WYUyZdWM-#eLr_U9mz^C~aY

Offset	Data Type	Name	Description
0	uint8_t	command	Command identifier
1	uint8_t	flight_state	Current flight computer state
2	uint16_t	tick	Flight computer clock (100 ticks/second)
4	uint16_t	serial	Flight computer serial number
6	uint16_t	flight	Flight number
8

AltOS

Altos Metrum Operating System

Keith Packard

AltOS

Altos Metrum Operating System

Keith Packard

Chapter 1. Overview

Chapter 1. Overview

Chapter 2. Programming the 8051 with SDCC

Chapter 2. Programming the 8051 with SDCC

1. 8051 memory spaces

1. 8051 memory spaces

1.1. __data

1.1. __data

1.2. __idata

1.2. __idata

1.3. __xdata

1.3. __xdata

1.4. __pdata

1.4. __pdata

1.5. __code

1.5. __code

1.6. __bit

1.6. __bit

1.7. __sfr, __sfr16, __sfr32, __sbit

1.7. __sfr, __sfr16, __sfr32, __sbit

2. Function calls on the 8051

2. Function calls on the 8051

2.1. __reentrant functions

2.1. __reentrant functions

2.2. Non __reentrant functions

2.2. Non __reentrant functions

2.3. __interrupt functions

2.3. __interrupt functions

2.4. __critical functions and statements

2.4. __critical functions and statements

Chapter 3. Task functions

Chapter 3. Task functions

1. ao_add_task

1. ao_add_task

2. ao_exit

2. ao_exit

3. ao_sleep

3. ao_sleep

4. ao_wakeup

4. ao_wakeup

5. ao_alarm

5. ao_alarm

6. ao_start_scheduler

6. ao_start_scheduler

7. ao_clock_init

7. ao_clock_init

Chapter 4. Timer Functions

Chapter 4. Timer Functions

1. ao_time

1. ao_time

2. ao_delay

2. ao_delay

3. ao_timer_set_adc_interval

3. ao_timer_set_adc_interval

4. ao_timer_init

4. ao_timer_init

Chapter 5. AltOS Mutexes

Chapter 5. AltOS Mutexes

1. ao_mutex_get

1. ao_mutex_get

2. ao_mutex_put

2. ao_mutex_put

Chapter 6. CC1111 DMA engine

Chapter 6. CC1111 DMA engine

1. ao_dma_alloc

1. ao_dma_alloc

2. ao_dma_set_transfer

2. ao_dma_set_transfer

3. ao_dma_start

3. ao_dma_start

4. ao_dma_trigger

4. ao_dma_trigger

5. ao_dma_abort

5. ao_dma_abort

1.7. sfr, sfr16, sfr32, sbit

1.7. sfr, sfr16, sfr32, sbit