GCS light control setup blocks

GCS light control setup blocks contain the setup instructions that a ground control station (GCS) needs in order to control the lights of the drone interactively during a light show. The block describes which pixel of a virtual screen or LED matrix the drone represents, the size of the LED matrix in which the drone is being used, and which color palette the ground control station may use when controlling the lights of the drone with commands that use indices into a palette instead of raw RGB values.

The body of a GCS light control setup block is a sequence of tag-length-value (TLV) entries. Each entry consists of a one-byte tag, followed by the length of the value of the entry in two bytes (unsigned, little-endian), then the value itself. Entries follow each other without any padding or alignment.

Byte-level structure of the body of a GCS light control setup block
Figure 1. Byte-level structure of the body of a GCS light control setup block

The following tags are currently defined:

Coordinates entry (tag = `0x00`)
Figure 2. Coordinates entry (tag = 0x00)

The coordinates entry holds the X-Y coordinate pair of the pixel represented by the drone. Its value is four bytes long, consisting of two signed 16-bit little-endian integers. Valid coordinates are in the range [0; 4096); parsers should reject blocks where either coordinate is outside this range (including negative values).

Color palette entry (tag = `0x01`)
Figure 3. Color palette entry (tag = 0x01)

The color palette entry holds the color palette that the ground control station may use when controlling the lights of the drone interactively. Its value is a sequence of RGB colors, each encoded in three bytes (red, green and blue components, in this order), so the length of the value must be a multiple of three.

Matrix size entry (tag = `0x02`)
Figure 4. Matrix size entry (tag = 0x02)

The matrix size entry holds the size of the LED matrix in which the drone is being used. Its value is four bytes long, consisting of two signed 16-bit little-endian integers: the width and the height of the matrix. Valid values are in the range [0; 4096); parsers should reject blocks where either value is outside this range (including negative values).

Defaults and parsing rules

Tags are optional: when the block does not contain a coordinates entry, the pixel represented by the drone is implicitly assumed to be (0, 0). Similarly, when the block does not contain a matrix size entry, the size of the LED matrix is implicitly assumed to be (0, 0), and when the block does not contain a color palette entry, the color palette of the setup is implicitly assumed to be empty.

Parsers must skip entries with tags that they do not understand; this allows the block to be extended with new tags in the future without breaking older parsers. When the same tag appears multiple times in the same block, the last occurrence wins.