Overview
Skybrush binary show files start with a short file header that is meant to be used for identifying the file format and the version being used, followed by one or more content blocks. Each content block has a type marker, followed by the length of the block, then the block itself, meaning that parsers can easily skip blocks that they do not need or can not parse.
Basic data types
In Skybrush binary show files, the following basic data types are used:
-
Integers are encoded in a fixed number of bytes in little endian format (least significant byte at the smallest address). Integers may be signed or unsigned. The specification of each integer field in the file format description should always specify the length and signedness of the integer field unless it is clear from the context (e.g., durations cannot be negative so they do not need to be signed).
-
In some cases, the file format uses variable-length integers (varints). Bytes in a varint uses the seven least significant bits to encode the value in little endian ordering, and the MSB is set to 1 if the next byte also belongs to the varint and 0 otherwise. So, the integer 513 is encoded as
10000001 00000100where the seven LSBs encode the integer itself in little endian format and the MSB of the first byte is set to 1 to indicate that there will be a second byte. -
Strings are encoded as UTF-8 and are prefixed with their length unless the length is clear from the context (like in comment blocks where the entire payload is a string).
-
Bit fields are filled from right to left unless specified otherwise.
-
Reserved bits in bit fields must be set to zeros by writers in order to allow us to use these bits in later versions of the format without breaking files created with earlier versions. Parsers must ignore reserved bits and must not reject files where they are set; this allows later versions of the format to use these bits for additional, optional features while files using them can still be processed by older parsers that do not support those features.
File structure
The following diagram shows the typical structure of a binary show file:
Signature, version and features
Each show file starts with a 4-byte signature consisting of 0x73 0x6b 0x79 0x62, the ASCII encoding of the string skyb.
The next byte is the version number of the file format.
Versioning started at version 1, and the highest supported version number is version 2.
The next byte in files with a version number 2 or larger is a feature bit field where each bit declares which additional parts are present in the header (MSB on left, LSB on right):
Currently we only use bit 0 to indicate whether a CRC32 checksum is present in the file.
The remaining parts of the header are present only if the corresponding bit is set in the feature bit field.
CRC32 checksum
The CRC32 checksum spans four bytes (stored as an unsigned 32-bit little-endian integer), and it is calculated over the entire file, except the four bytes at zero-based offsets 6 to 9 (inclusive) where the CRC32 checksum itself is stored. When calculating the expected CRC32 checksum of a file, the bytes at offsets 6 to 9 must be assumed to be zeros. The particular CRC32 variant used by the Skybrush binary file format is identical to the one used in ArduPilot; we will refer to this as AP-CRC32.
AP-CRC32 has the following properties:
-
Generator polynomial:
0x104C11DB7(reversed order, shifting to the right) -
Reflected input and output (bits are processed starting from the least significant bit of each byte)
-
Initial shift register value: 0
-
No final XOR (the content of the shift register is used as-is as the checksum)
You can find a reference implementation in C in the libskybrush library in src/crc32.c.
Content blocks
The remainder of the file after the header is a concatenation of one or more content blocks.
Each content block starts with a one-byte type marker, followed by the length of the payload of the block in two bytes (unsigned, little-endian), then the payload itself.
A skyb file may contain more than one block of the same type in the same file.
The order of blocks is not fixed.
Version 2 of the file format defines the following block types:
-
Trajectory blocks (type =
0x01) -
Light program blocks (type =
0x02) -
Comment blocks (type =
0x03) -
Return-to-home plan blocks (type =
0x04) -
Yaw control blocks (type =
0x05) -
Event list blocks (type =
0x06) -
GCS light control setup blocks (type =
0x07) -
Metadata blocks (type =
0x08)
The following sections describe each of the supported block types.
Parsing rules for content blocks
-
Parsers must skip blocks with types that they do not understand. The length field of the block header allows parsers to skip such blocks without knowing their structure.
-
When a file contains multiple blocks of the same type, parsers use the first one and ignore the rest.
-
Block type
0x00is reserved and must not be used by writers. Parsers treat a block type of0x00as the end of the list of content blocks; any data after it (including further blocks) is ignored. -
A file is invalid if it ends before the end of a block as declared by the length field of the block header, or if it ends in the middle of a block header.