altos: Add EasyMega v2.0 to default build
[fw/altos] / doc / telemetry.txt
1 = AltOS Telemetry
2 :doctype: article
3 :toc:
4 :numbered:
5
6 == Packet Format Design
7
8         AltOS telemetry data is split into multiple different packets,
9         all the same size, but each includs an identifier so that the
10         ground station can distinguish among different types. A single
11         flight board will transmit multiple packet types, each type on
12         a different schedule. The ground software need look for only a
13         single packet size, and then decode the information within the
14         packet and merge data from multiple packets to construct the
15         full flight computer state.
16
17         Each AltOS packet is 32 bytes long. This size was chosen based
18         on the known telemetry data requirements. The power of two
19         size allows them to be stored easily in flash memory without
20         having them split across blocks or leaving gaps at the end.
21
22         All packet types start with a five byte header which encodes
23         the device serial number, device clock value and the packet
24         type. The remaining 27 bytes encode type-specific data.
25
26 == Packet Formats
27
28       This section first defines the packet header common to all packets
29       and then the per-packet data layout.
30
31         === Packet Header
32
33                 .Telemetry Packet Header
34                 [options="border",cols="2,3,3,9"]
35                 |====
36                 |Offset |Data Type      |Name   |Description
37                 |0      |uint16_t       |serial |Device serial Number
38                 |2      |uint16_t       |tick   |Device time in 100ths of a second
39                 |4      |uint8_t        |type   |Packet type
40                 |5
41                 |====
42
43                 Each packet starts with these five bytes which serve to identify
44                 which device has transmitted the packet, when it was transmitted
45                 and what the rest of the packet contains.
46
47         === TeleMetrum v1.x, TeleMini v1.0 and TeleNano Sensor Data
48
49                 .Sensor Packet Type
50                 [options="border",cols="1,3"]
51                 |====
52                 |Type   |Description
53                 |0x01   |TeleMetrum v1.x Sensor Data
54                 |0x02   |TeleMini v1.0 Sensor Data
55                 |0x03   |TeleNano Sensor Data
56                 |====
57
58                 TeleMetrum v1.x, TeleMini v1.0 and TeleNano share this same
59                 packet format for sensor data. Each uses a distinct
60                 packet type so that the receiver knows which data
61                 values are valid and which are undefined.
62
63                 Sensor Data packets are transmitted once per second on
64                 the ground, 10 times per second during ascent and once
65                 per second during descent and landing
66
67                 .Sensor Packet Contents
68                 [options="border",cols="2,3,3,9"]
69                 |====
70                 |Offset |Data Type      |Name           |Description
71                 |5      |uint8_t        |state          |Flight state
72                 |6      |int16_t        |accel          |accelerometer (TM only)
73                 |8      |int16_t        |pres           |pressure sensor
74                 |10     |int16_t        |temp           |temperature sensor
75                 |12     |int16_t        |v_batt         |battery voltage
76                 |14     |int16_t        |sense_d        |drogue continuity sense (TM/Tm)
77                 |16     |int16_t        |sense_m        |main continuity sense (TM/Tm)
78                 |18     |int16_t        |acceleration   |m/s² * 16
79                 |20     |int16_t        |speed          |m/s * 16
80                 |22     |int16_t        |height         |m
81                 |24     |int16_t        |ground_pres    |Average barometer reading on ground
82                 |26     |int16_t        |ground_accel   |TM
83                 |28     |int16_t        |accel_plus_g   |TM
84                 |30     |int16_t        |accel_minus_g  |TM
85                 |32
86                 |====
87
88         === TeleMega Sensor Data
89
90                 .TeleMega Packet Type
91                 [options="border",cols="1,3"]
92                 |====
93                 |Type   |Description
94                 |0x08   |TeleMega IMU Sensor Data
95                 |0x09   |TeleMega Kalman and Voltage Data
96                 |====
97
98                 TeleMega has a lot of sensors, and so it splits the sensor
99                 data into two packets. The raw IMU data are sent more often;
100                 the voltage values don't change very fast, and the Kalman
101                 values can be reconstructed from the IMU data.
102
103                 IMU Sensor Data packets are transmitted once per second on the
104                 ground, 10 times per second during ascent and once per second
105                 during descent and landing
106
107                 Kalman and Voltage Data packets are transmitted once per second on the
108                 ground, 5 times per second during ascent and once per second
109                 during descent and landing
110
111                 The high-g accelerometer is reported separately from the data
112                 for the 9-axis IMU (accel/gyro/mag). The 9-axis IMU is mounted
113                 so that the X axis is "across" the board (along the short
114                 axis0, the Y axis is "along" the board (along the long axis,
115                 with the high-g accelerometer) and the Z axis is "through" the
116                 board (perpendicular to the board). Rotation measurements are
117                 around the respective axis, so Y rotation measures the spin
118                 rate of the rocket while X and Z rotation measure the tilt
119                 rate.
120
121                 The overall tilt angle of the rocket is computed by first
122                 measuring the orientation of the rocket on the pad using the 3
123                 axis accelerometer, and then integrating the overall tilt rate
124                 from the 3 axis gyroscope to compute the total orientation
125                 change of the airframe since liftoff.
126
127                 .TeleMega IMU Sensor Packet Contents
128                 [options="border",cols="2,3,3,9"]
129                 |====
130                 |Offset |Data Type      |Name           |Description
131                 |5      |uint8_t        |orient         |Angle from vertical in degrees
132                 |6      |int16_t        |accel          |High G accelerometer
133                 |8      |int32_t        |pres           |pressure (Pa * 10)
134                 |12     |int16_t        |temp           |temperature (°C * 100)
135                 |14     |int16_t        |accel_x        |X axis acceleration (across)
136                 |16     |int16_t        |accel_y        |Y axis acceleration (along)
137                 |18     |int16_t        |accel_z        |Z axis acceleration (through)
138                 |20     |int16_t        |gyro_x         |X axis rotation (across)
139                 |22     |int16_t        |gyro_y         |Y axis rotation (along)
140                 |24     |int16_t        |gyro_z         |Z axis rotation (through)
141                 |26     |int16_t        |mag_x          |X field strength (across)
142                 |28     |int16_t        |mag_y          |Y field strength (along)
143                 |30     |int16_t        |mag_z          |Z field strength (through)
144                 |32
145                 |====
146
147                 .TeleMega Kalman and Voltage Data Packet Contents
148                 [options="border",cols="2,3,3,9"]
149                 |====
150                 |Offset |Data Type      |Name           |Description
151                 |5      |uint8_t        |state          |Flight state
152                 |6      |int16_t        |v_batt         |battery voltage
153                 |8      |int16_t        |v_pyro         |pyro battery voltage
154                 |10     |int8_t[6]      |sense          |pyro continuity sense
155                 |16     |int32_t        |ground_pres    |Average barometer reading on ground
156                 |20     |int16_t        |ground_accel   |Average accelerometer reading on ground
157                 |22     |int16_t        |accel_plus_g   |Accel calibration at +1g
158                 |24     |int16_t        |accel_minus_g  |Accel calibration at -1g
159                 |26     |int16_t        |acceleration   |m/s² * 16
160                 |28     |int16_t        |speed          |m/s * 16
161                 |30     |int16_t        |height         |m
162                 |32
163                 |====
164
165         === TeleMetrum v2 Sensor Data
166
167                 .TeleMetrum v2 Packet Type
168                 [options="border",cols="1,3"]
169                 |====
170                 |Type   |Description
171                 |0x0A   |TeleMetrum v2 Sensor Data
172                 |0x0B   |TeleMetrum v2 Calibration Data
173                 |====
174
175                 TeleMetrum v2 has higher resolution barometric data than
176                 TeleMetrum v1, and so the constant calibration data is
177                 split out into a separate packet.
178
179                 TeleMetrum v2 Sensor Data packets are transmitted once per second on the
180                 ground, 10 times per second during ascent and once per second
181                 during descent and landing
182
183                 TeleMetrum v2 Calibration Data packets are always transmitted once per second.
184
185                 .TeleMetrum v2 Sensor Packet Contents
186                 [options="border",cols="2,3,3,9"]
187                 |====
188                 |Offset |Data Type      |Name           |Description
189                 |5      |uint8_t        |state          |Flight state
190                 |6      |int16_t        |accel          |accelerometer
191                 |8      |int32_t        |pres           |pressure sensor (Pa * 10)
192                 |12     |int16_t        |temp           |temperature sensor (°C * 100)
193                 |14     |int16_t        |acceleration   |m/s² * 16
194                 |16     |int16_t        |speed          |m/s * 16
195                 |18     |int16_t        |height         |m
196                 |20     |int16_t        |v_batt         |battery voltage
197                 |22     |int16_t        |sense_d        |drogue continuity sense
198                 |24     |int16_t        |sense_m        |main continuity sense
199                 |26     |pad[6]         |pad bytes      |
200                 |32
201                 |====
202
203                 .TeleMetrum v2 Calibration Data Packet Contents
204                 [options="border",cols="2,3,3,9"]
205                 |====
206                 |Offset |Data Type      |Name           |Description
207                 |5      |pad[3]         |pad bytes      |
208                 |8      |int32_t        |ground_pres    |Average barometer reading on ground
209                 |12     |int16_t        |ground_accel   |Average accelerometer reading on ground
210                 |14     |int16_t        |accel_plus_g   |Accel calibration at +1g
211                 |16     |int16_t        |accel_minus_g  |Accel calibration at -1g
212                 |18     |pad[14]        |pad bytes      |
213                 |32
214                 |====
215
216         === TeleMini v3.0 Sensor Data
217         
218                 .Sensor Packet Type
219                 [options="border",cols="1,3"]
220                 |====
221                 |Type   |Description
222                 |0x11   |TeleMini v3.0 Sensor Data
223                 |====
224
225                 TeleMini v3.0 uses this
226                 packet format for sensor data.
227
228                 Sensor Data packets are transmitted once per second on
229                 the ground, 10 times per second during ascent and once
230                 per second during descent and landing
231
232                 .Sensor Packet Contents
233                 [options="border",cols="2,3,3,9"]
234                 |====
235                 |Offset |Data Type      |Name           |Description
236                 |5      |uint8_t        |state          |Flight state
237                 |6      |int16_t        |v_batt         |battery voltage
238                 |8      |int16_t        |sense_a        |apogee continuity sense
239                 |10     |int16_t        |sense_m        |main continuity sense
240                 |12     |int32_t        |pres           |pressure sensor (Pa * 10)
241                 |16     |int16_t        |temp           |temperature sensor (°C * 100)
242                 |18     |int16_t        |acceleration   |m/s² * 16
243                 |20     |int16_t        |speed          |m/s * 16
244                 |22     |int16_t        |height         |m
245                 |24     |int16_t        |ground_pres    |Average barometer reading on ground
246                 |28     |pad[4]         |pad bytes      |
247                 |32
248                 |====
249
250
251         === Configuration Data
252
253                 .Configuration Packet Type
254                 [options="border",cols="1,3"]
255                 |====
256                 |Type   |Description
257                 |0x04   |Configuration Data
258                 |====
259
260                 This provides a description of the software installed on the
261                 flight computer as well as any user-specified configuration data.
262
263                 Configuration data packets are transmitted once per second
264                 during all phases of the flight
265
266                 .Configuration Packet Contents
267                 [options="border",cols="2,3,3,9"]
268                 |====
269                 |Offset |Data Type      |Name           |Description
270                 |5      |uint8_t        |type           |Device type
271                 |6      |uint16_t       |flight         |Flight number
272                 |8      |uint8_t        |config_major   |Config major version
273                 |9      |uint8_t        |config_minor   |Config minor version
274                 |10     |uint16_t       |apogee_delay   |Apogee deploy delay in seconds
275                 |12     |uint16_t       |main_deploy    |Main deploy alt in meters
276                 |14     |uint16_t       |flight_log_max |Maximum flight log size (kB)
277                 |16     |char           |callsign[8]    |Radio operator identifier
278                 |24     |char           |version[8]     |Software version identifier
279                 |32
280                 |====
281
282         === GPS Location
283
284                 .GPS Packet Type
285                 [options="border",cols="1,3"]
286                 |====
287                 |Type   |Description
288                 |0x05   |GPS Location
289                 |====
290
291                 This packet provides all of the information available from the
292                 GPS receiver—position, time, speed and precision
293                 estimates.
294
295                 GPS Location packets are transmitted once per second during
296                 all phases of the flight
297
298                 .GPS Location Packet Contents
299                 [options="border",cols="2,3,3,9"]
300                 |====
301                 |Offset |Data Type      |Name           |Description
302                 |5      |uint8_t        |flags          |See GPS Flags table below
303                 |6      |int16_t        |altitude       |m
304                 |8      |int32_t        |latitude       |degrees * 107
305                 |12     |int32_t        |longitude      |degrees * 107
306                 |16     |uint8_t        |year           |
307                 |17     |uint8_t        |month          |
308                 |18     |uint8_t        |day            |
309                 |19     |uint8_t        |hour           |
310                 |20     |uint8_t        |minute         |
311                 |21     |uint8_t        |second         |
312                 |22     |uint8_t        |pdop           |* 5
313                 |23     |uint8_t        |hdop           |* 5
314                 |24     |uint8_t        |vdop           |* 5
315                 |25     |uint8_t        |mode           |See GPS Mode table below
316                 |26     |uint16_t       |ground_speed   |cm/s
317                 |28     |int16_t        |climb_rate     |cm/s
318                 |30     |uint8_t        |course         |/ 2
319                 |31     |uint8_t        |unused[1]      |
320                 |32
321                 |====
322
323                 Packed into a one byte field are status flags and the
324                 count of satellites used to compute the position
325                 fix. Note that this number may be lower than the
326                 number of satellites being tracked; the receiver will
327                 not use information from satellites with weak signals
328                 or which are close enough to the horizon to have
329                 significantly degraded position accuracy.
330
331                 .GPS Flags
332                 [options="border",cols="1,2,7"]
333                 |====
334                 |Bits   |Name           |Description
335                 |0-3    |nsats          |Number of satellites in solution
336                 |4      |valid          |GPS solution is valid
337                 |5      |running        |GPS receiver is operational
338                 |6      |date_valid     |Reported date is valid
339                 |7      |course_valid   |ground speed, course and climb rates are valid
340                 |====
341
342                 Here are all of the valid GPS operational modes. Altus
343                 Metrum products will only ever report 'N' (not valid),
344                 'A' (Autonomous) modes or 'E' (Estimated). The
345                 remaining modes are either testing modes or require
346                 additional data.
347
348                 .GPS Mode
349                 [options="border",cols="1,3,7"]
350                 |====
351                 |Mode           |Name                   |Description
352                 |N              |Not Valid              |All data are invalid
353                 |A              |Autonomous mode        |
354                   Data are derived from satellite data
355
356                 |D              |Differential Mode      |
357                   Data are augmented with differential data from a
358                   known ground station. The SkyTraq unit in TeleMetrum
359                   does not support this mode
360
361                 |E              |Estimated              |
362                   Data are estimated using dead reckoning from the
363                   last known data
364
365                 |M              |Manual                 |
366                   Data were entered manually
367
368                 |S              |Simulated              |
369                   GPS receiver testing mode
370
371                 |====
372
373         === GPS Satellite Data
374
375                 .GPS Satellite Data Packet Type
376                 [options="border",cols="1,3"]
377                 |====
378                 |Type           |Description
379                 |0x06           |GPS Satellite Data
380                 |====
381
382                 This packet provides space vehicle identifiers and
383                 signal quality information in the form of a C/N1
384                 number for up to 12 satellites. The order of the svids
385                 is not specified.
386
387                 GPS Satellite data are transmitted once per second
388                 during all phases of the flight.
389
390                 .GPS Satellite Data Contents
391                 [options="border",cols="2,3,3,9"]
392                 |====
393                 |Offset |Data Type      |Name           |Description
394                 |5      |uint8_t        |channels       |Number of reported satellite information
395                 |6      |sat_info_t     |sats[12]       |See Per-Satellite data table below
396                 |30     |uint8_t        |unused[2]      |
397                 |32
398                 |====
399
400                 .GPS Per-Satellite data (sat_info_t)
401                 [options="border",cols="2,3,3,9"]
402                 |====
403                 |Offset |Data Type      |Name           |Description
404                 |0      |uint8_t        |svid           |Space Vehicle Identifier
405                 |1      |uint8_t        |c_n_1          |C/N1 signal quality indicator
406                 |2
407                 |====
408
409         === Companion Data
410
411                 .Companion Data Packet Type
412                 [options="border",cols="1,3"]
413                 |====
414                 |Type   |Description
415                 |0x07   |Companion Data
416                 |====
417
418                 When a companion board is attached to TeleMega or
419                 TeleMetrum, it can provide telemetry data to be
420                 included in the downlink. The companion board can
421                 provide up to 12 16-bit data values.
422
423                 The companion board itself specifies the transmission
424                 rate. On the ground and during descent, that rate is
425                 limited to one packet per second. During ascent, that
426                 rate is limited to 10 packets per second.
427
428                 .Companion Data Contents
429                 [options="border",cols="2,3,3,9"]
430                 |====
431                 |Offset |Data Type      |Name           |Description
432                 |5      |uint8_t        |board_id       |Type of companion board attached
433                 |6      |uint8_t        |update_period  |How often telemetry is sent, in 1/100ths of a second
434                 |7      |uint8_t        |channels       |Number of data channels supplied
435                 |8      |uint16_t[12]   |companion_data |Up to 12 channels of 16-bit companion data
436                 |32
437                 |====
438
439 == Data Transmission
440
441         Altus Metrum devices use Texas Instruments sub-GHz digital
442         radio products. Ground stations use parts with HW FEC while
443         some flight computers perform FEC in software. TeleGPS is
444         transmit-only.
445
446         .Altus Metrum Radio Parts
447         [options="border",cols="1,4,4"]
448         |====
449         |Part Number    |Description    |Used in
450
451         |CC1111
452         |10mW transceiver with integrated SoC
453         |TeleDongle v0.2, TeleBT v1.0, TeleMetrum v1.x, TeleMini
454
455         |CC1120
456         |35mW transceiver with SW FEC
457         |TeleMetrum v2, TeleMega
458
459         |CC1200
460         |35mW transceiver with HW FEC
461         |TeleDongle v3.0, TeleBT v3.0
462
463         |CC115L
464         |14mW transmitter with SW FEC
465         |TeleGPS
466
467         |====
468
469         === Modulation Scheme
470
471                 Texas Instruments provides a tool for computing
472                 modulation parameters given a desired modulation
473                 format and basic bit rate.
474
475                 While we might like to use something with better
476                 low-signal performance like BPSK, the radios we use
477                 don't support that, but do support Gaussian frequency
478                 shift keying (GFSK). Regular frequency shift keying
479                 (FSK) encodes the signal by switching the carrier
480                 between two frequencies. The Gaussian version is
481                 essentially the same, but the shift between
482                 frequencies gently follows a gaussian curve, rather
483                 than switching immediately. This tames the bandwidth
484                 of the signal without affecting the ability to
485                 transmit data.
486
487                 For AltOS, there are three available bit rates,
488                 38.4kBaud, 9.6kBaud and 2.4kBaud resulting in the
489                 following signal parmeters:
490
491                 .Modulation Scheme
492                 [options="border",cols="1,1,1"]
493                 |====
494                 |Rate           |Deviation      |Receiver Bandwidth
495                 |38.4kBaud      |20.5kHz        |100kHz
496                 |9.6kBaud       |5.125kHz       |25kHz
497                 |2.4kBaud       |1.5kHz         |5kHz
498                 |====
499
500         === Error Correction
501
502                 The cc1111 and cc1200 provide forward error correction
503                 in hardware; on the cc1120 and cc115l that's done in
504                 software. AltOS uses this to improve reception of weak
505                 signals. As it's a rate 1/2 encoding, each bit of data
506                 takes two bits when transmitted, so the effective data
507                 rate is half of the raw transmitted bit rate.
508
509                 .Error Correction
510                 [options="border",cols="1,1,1"]
511                 |====
512                 |Parameter      |Value  |Description
513
514                 |Error Correction
515                 |Convolutional coding
516                 |1/2 rate, constraint length m=4
517
518                 |Interleaving
519                 |4 x 4
520                 |Reduce effect of noise burst
521
522                 |Data Whitening
523                 |XOR with 9-bit PNR
524                 |Rotate right with bit 8 = bit 0 xor bit 5, initial value 111111111
525
526                 |====
527
528 == TeleDongle serial packet format
529
530         TeleDongle does not do any interpretation of the packet data,
531         instead it is configured to receive packets of a specified
532         length (32 bytes in this case). For each received packet,
533         TeleDongle produces a single line of text. This line starts with
534         the string "TELEM " and is followed by a list of hexadecimal
535         encoded bytes.
536
537         ....
538         TELEM 224f01080b05765e00701f1a1bbeb8d7b60b070605140c000600000000000000003fa988
539         ....
540
541         The hexadecimal encoded string of bytes contains a length byte,
542         the packet data, two bytes added by the cc1111 radio receiver
543         hardware and finally a checksum so that the host software can
544         validate that the line was transmitted without any errors.
545
546         .TeleDongle serial Packet Format
547
548         [options="border",cols="2,1,1,5"]
549         |====
550         |Offset |Name   |Example        |Description
551
552         |0
553         |length
554         |22
555         |Total length of data bytes in the line. Note that
556          this includes the added RSSI and status bytes
557
558         |1 ·· length-3
559         |packet
560         |4f ·· 00
561         |Bytes of actual packet data
562
563         |length-2
564         |rssi
565         |3f
566         |Received signal strength. dBm = rssi / 2 - 74
567
568         |length-1
569         |lqi
570         |a9
571         |Link Quality Indicator and CRC status. Bit 7
572          is set when the CRC is correct
573
574         |length
575         |checksum
576         |88
577         |(0x5a + sum(bytes 1 ·· length-1)) % 256
578
579         |====
580
581 == History and Motivation
582
583       The original AltoOS telemetry mechanism encoded everything
584       available piece of information on the TeleMetrum hardware into a
585       single unified packet. Initially, the packets contained very
586       little data—some raw sensor readings along with the current GPS
587       coordinates when a GPS receiver was connected. Over time, the
588       amount of data grew to include sensor calibration data, GPS
589       satellite information and a host of internal state information
590       designed to help diagnose flight failures in case of a loss of
591       the on-board flight data.
592
593       Because every packet contained all of the data, packets were
594       huge—95 bytes long. Much of the information was also specific to
595       the TeleMetrum hardware. With the introduction of the TeleMini
596       flight computer, most of the data contained in the telemetry
597       packets was unavailable. Initially, a shorter, but still
598       comprehensive packet was implemented. This required that the
599       ground station be pre-configured as to which kind of packet to
600       expect.
601
602       The development of several companion boards also made the
603       shortcomings evident—each companion board would want to include
604       telemetry data in the radio link; with the original design, the
605       packet would have to hold the new data as well, requiring
606       additional TeleMetrum and ground station changes.