Log file format

The Hub and Hub Plus record .onflight files to a microSD card. Filenames use dataX.onflight, with X increasing from 0 to avoid overwriting existing files. The optional .acrowrx format is separate and is not described here.

The Hub processes data at 50 Hz. Firmware 6 and later support recording rates of 5, 10, 25, or 50 Hz. The Hub holds samples in a buffer before writing them to the card. Switching off power can lose the last buffered samples or leave an incomplete packet at the end of the file.

Reading a log file

A log contains measurement packets and records describing the device and recording. This chapter defines three packet types:

Search for the packet types above, read the ones your application needs, and ignore other file content. A measurement packet need not start at the beginning of the file.

1. Scan for a defined two-byte header: BF for a data packet, MD for aircraft/pilot metadata, or AD for Hub Plus analog metadata.
2. Read its packet version. Binary data v0 has a fixed 143-byte payload and no length byte. Data v1–v3 and the documented metadata packets have a one-byte payload_length immediately after the version.
3. Read the complete payload and the following two checksum bytes. The length excludes the header, version, length byte, and checksum.
4. Validate the Fletcher-16 checksum over the header, version, length byte when present, and all payload bytes.
5. Decode recognized fields only after validation. Advance past the complete packet. Ignore other file content.
6. If the size or checksum is wrong, resume searching one byte after the suspected header. The same two bytes can occur in unrelated data. Ignore any incomplete packet at the end of the file.

What payload length counts

For data versions 1–3 and the MD and AD metadata packets, payload_length counts every byte immediately after the length byte through the last byte before the checksum. It excludes the two-byte header, version byte, length byte itself, and two checksum bytes. The field tables below include these framing fields for completeness; they are not part of the payload count.

Offsets are zero-based from the start of the packet, with N = payload_length:

The complete packet is N + 6 bytes. For example, a version 3 data packet has N = 198: its payload occupies packet bytes 4–201, and its checksum occupies bytes 202–203.

For BF data packets, the payload begins with the status bytes. For MD, it begins with serial_num; for AD, it begins with analog_channel_enabled. Data version 0 has no length byte: its fixed 143-byte payload occupies bytes 3–145, followed by the checksum at bytes 146–147.

Compatibility with extended packets

Use payload_length to find the checksum and the start of the next packet. A later format may add fields at the end of an existing payload. Your application can continue reading the fields it knows if their positions and meanings are unchanged.

Read the entire payload and check its checksum, including any added bytes. Interpret only fields that are fully present and whose layout you know. If you do not support the layout, skip the complete packet and continue searching.

Always check the version as well as the length. For example, version 1 moves fields compared with version 0, so a version 0 decoder cannot read it simply by ignoring extra bytes.

Encoding and packet sizes

Fields appear in table order, with no padding between them. Multibyte values are little-endian: the least significant byte comes first. Floating-point values use IEEE 754.

Multiply the stored integer by the listed scale to obtain the measurement. For example, a stored value of 1234 with scale 1 / 100 means 12.34 in the listed unit. Where the description gives an offset instead, apply that rule: subtract 10,000 from biased altitude fields, or add 1970 to the year field.

Fletcher-16 checksum

Compute the checksum over every packet byte preceding the checksum, including the header. Store the result as a little-endian U2, with sum0 first and sum1 second.

uint16_t Checksum(uint8_t * data, size_t len) {
  uint16_t sum0 = 0;
  uint16_t sum1 = 0;
  for (size_t i = 0; i < len; i++) {
    sum0 = (sum0 + data[i]) % 255;
    sum1 = (sum1 + sum0) % 255;
  }
  return sum1 << 8 | sum0;
}

Packet and checksum example

This example is an AD packet for four analog channels. Its payload says all four channels are enabled, assigns Elevator, Aileron, Rudder, and Throttle, and selects three-point calibration for the first three channels and two-point calibration for the fourth.

Pass bytes 0–12 to the checksum function above: start with the A in the header and stop after the final calibration type. Compare the result with the two checksum bytes. The nine-byte payload is bytes 4–12, while the complete packet is 15 bytes.

Packed fields

gnss_fix_num_sv uses the lower three bits for fix type and the upper five bits for satellites used:

fix = gnss_fix_num_sv & 0x07;
num_sv = gnss_fix_num_sv >> 3;

Fix values are 0 = no fix, 2 = 2D, 3 = 3D, and 4 = differential fix.

In version 2, each analog status byte holds two sets of four channel flags. Bits 0–3 contain the first set, and bits 4–7 contain the second. For channel n, test 1 << n in the first set and 1 << (n + 4) in the second. The field table identifies what each set means.

Version 0

The original data packet has five status bytes and no payload-length field. Read 143 payload bytes after the version byte, then the two checksum bytes.

The defined payload is 143 bytes; the complete packet is 148 bytes.

Version 0 data fields

Version 0 status flags

Byte 0 is the first byte of status. A flag is set when the byte AND the listed mask is nonzero. Use this version’s table and ignore unlisted bits; UDP status bits have a different layout.

Version 1

Introduced with firmware 3, this layout adds a payload-length byte, a sixth status byte, calibrated airspeed, and wind estimates.

The defined payload is 152 bytes; the complete packet is 158 bytes.

Version 1 data fields

Version 1 status flags

Byte 0 is the first byte of status. A flag is set when the byte AND the listed mask is nonzero. Use this version’s table and ignore unlisted bits; UDP status bits have a different layout.

Version 2

Introduced with firmware 6, this layout adds heart rate and four analog channels. Firmware 6 and later also write metadata packets.

The defined payload is 184 bytes; the complete packet is 190 bytes.

Version 2 data fields

Version 2 status flags

Byte 0 is the first byte of status. A flag is set when the byte AND the listed mask is nonzero. Use this version’s table and ignore unlisted bits; UDP status bits have a different layout.

Version 3 (Hub Plus)

Hub Plus uses data version 3, with a 198-byte payload and a 204-byte complete packet. It retains the version 2 measurement offsets and scales, replaces the external analog-channel measurements with onboard analog inputs, and appends 14 bytes of clock information before the checksum.

The first six payload bytes are stored as status[2] followed by ext_status[4]. Together they occupy the same bytes as status[6] in version 2. UTC fields come from the Hub Plus clock. The renamed cabin-pressure and external-sensor fields retain their version 2 encodings.

Version 3 data fields

Offsets below are from the start of the complete packet, including the two-byte BF header. All arrays are in channel order, 0–3.

Version 3 status flags

Bytes 0–1 are status[0–1]; bytes 2–5 are ext_status[0–3]. A flag is set when the byte AND the listed mask is nonzero. Ignore unlisted bits; UDP status bits have a different layout.

GPS and UTC time initialization

These two initialization features are currently available only on Hub Plus. They indicate separate conditions: GPS time initialization checks for the locked signal from the GPS, while UTC time initialization checks that leap seconds have been set. The leap-second offset is needed to convert GPS time to UTC.

Check byte 5 (ext_status[3]) in each packet before using its absolute time fields. Use gps_time_us when the GPS initialization flag (0x20) is set. Use the UTC calendar fields and utc_us when the UTC initialization flag (0x40) is set. GPS initialization alone does not establish that UTC is initialized; check the UTC flag separately.

While the corresponding flag is clear, do not interpret those fields as an initialized absolute timestamp. Use sys_time_ms and sys_time_us for elapsed time since boot; they do not require GPS or UTC initialization.

Version 3 analog validity

Hub Plus retains the older analog status fields so the following measurements stay at the same byte offsets. It writes fixed values into those fields: 0xFF for connection and health, and zero for battery status and temperature. They are not measurements of onboard-channel status. All four onboard analog channels are included in the output. The AD packet supplies the channel assignments and calibration types; it does not report whether calibration is complete.

Reconstructing time

Hub versions 0–2 record UTC calendar fields directly from the GNSS receiver, with whole-second resolution in the .onflight format. Hub Plus synchronizes its clock to the receiver’s one-pulse-per-second (PPS) signal. Between pulses, it advances time using its internal clock, with a scale correction derived from the PPS intervals. This provides UTC and GPS time of week for samples recorded faster than once per second, both with microsecond resolution. UTC is derived from GPS time using the receiver-provided leap-second offset. Resolution is not a specification of absolute timing accuracy.

The final three payload fields provide the extra timing information:

System time: elapsed time since boot

sys_time_ms contains whole milliseconds. sys_time_us contains the remaining 0–999 microseconds. Convert both to seconds and add them:

Elapsed seconds = (sys_time_ms ÷ 1,000) + (sys_time_us ÷ 1,000,000)

For example, sys_time_ms = 1234 and sys_time_us = 567 represent 1.234567 seconds since boot.

UTC: calendar date and time

Use utc_year, utc_month, utc_day, utc_hour, utc_min, and utc_sec for the calendar date and whole-second time. Add 1970 to utc_year to obtain the calendar year.

utc_us supplies the fractional part of the second, from 0–999,999 microseconds:

UTC seconds within the minute = utc_sec + (utc_us ÷ 1,000,000)

For example, utc_sec = 12 and utc_us = 345678 represent 12.345678 seconds within the recorded minute. The configured UTC offset affects microSD file timestamps only; it does not change these UTC fields.

GPS time: week number and time within the week

gps_time_us is a total count from the GPS epoch. To split it into a GPS week number and time of week:

1. Divide the count by 604,800,000,000, the number of microseconds in one week. The whole-number quotient is the GPS week number.
2. Take the remainder from that division. Divide it by 1,000,000 to obtain seconds within the GPS week.

For example, gps_time_us = 1391040123456789 gives GPS week 2300 and time of week 123.456789 seconds.

Perform the week division and remainder using 64-bit unsigned integers or another exact integer type. Convert the remainder to floating point only when expressing it in seconds; converting the full count first can lose microsecond precision.

GPS time uses a different epoch from Unix time and does not include UTC leap seconds. Use the recorded UTC fields when you need a UTC calendar timestamp.

Metadata packet

Firmware 6 and later include MD metadata packets in the log. Scan for the packet header rather than relying on a fixed file offset. It contains the serial number and null-terminated aircraft/pilot character arrays. Earlier firmware does not write this frame.

Analog metadata packet

Hub Plus writes an AD version 0 packet near the beginning of the file. It describes the four onboard analog channels whose measurements appear in version 3 data packets. Search for the AD header and check its checksum; its position in the file is not fixed.

The payload is 9 bytes, and the complete packet is 15 bytes. Offsets are from the start of the AD header.

Control assignments

Calibration types

These values describe normalized control positions, not angles in degrees. The calibration coefficients and completion flags are not carried in AD. The calibrated values themselves are recorded in ain_val in each BF packet.

Match each entry in AD to the same channel number in ain_volt and ain_val. For example, entry 0 in each array describes channel 0. Keep the channel number in your application even if two channels have the same control assignment.

If AD is missing or its checksum is wrong, the control assignments and calibration types are unknown. Leave unknown type codes unidentified. The fixed analog status values in BF do not provide this information.