Light program blocks

Light program blocks encode the sequence of colors that the drone must display during a light show. The light program is stored as a sequence of instructions, similarly to a simplified programming language.

Instructions consist of a one-byte opcode followed by zero or more bytes encoding the arguments of the opcode (END, NOP and LOOP_END have no arguments). The number and total length of arguments can usually be determined from the opcode itself. For some opcodes, the last argument may be a varint.

The basic byte-level structure of a light program block is as follows:

Byte-level structure of a light program block
Figure 1. Byte-level structure of a light program block

Execution of the light program starts from the first opcode in the block. There are separate opcodes for setting the output color, fading the output color to a given target color during a time interval, delaying the execution of the next opcode for a given time interval and so on. Most light programs will only use these basic instructions. The mini-language of opcodes also includes basic looping constructs to provide tools for making light programs with repetitive sequences (e.g., flashes) smaller.

Colors are assumed to be encoded in linear RGB color space (not sRGB). The individual components are stored in one byte, with 0 meaning 0% and 255 meaning 100%.

Durations in the light program are encoded in frames, assuming 50 frames per second. In other words, one frame is equal to 20 milliseconds.

The following sections describe the supported opcodes and their arguments, while Opcodes and arguments summarizes the basic structure of the byte-level layout of each opcode.

Opcodes and arguments
Figure 2. Opcodes and arguments

Setting output color

Setting the output color is done by the SET_COLOR, SET_GRAY, SET_BLACK and SET_WHITE opcodes. These opcodes are identified by 0x04, 0x05, 0x06 and 0x07, respectively, and they set the color emitted by the light program to a given RGB color, followed by a timed wait until proceeding to the next opcode.

SET_COLOR has two arguments. The RGB color encoded as three bytes in R-G-B order, each component spanning the 0-255 range, followed by the wait duration in frames as a varint.

SET_GRAY has two arguments. The brightness is encoded as a single byte spanning the 0-255 range, followed by the wait duration in frames as a varint. This opcode is equivalent to SET_COLOR with identical RGB channel values but it is two bytes shorter.

SET_WHITE and SET_BLACK cater for the special case of SET_GRAY with full or zero brightness. They have only a single argument: the wait duration as a varint.

Fading output color

Fading the output color is done by the FADE_TO_COLOR, FADE_TO_GRAY, FADE_TO_BLACK and FADE_TO_WHITE opcodes. These opcodes are identified by 0x08, 0x09, 0x0a and 0x0b, respectively, and they are identical to the corresponding SET_COLOR commands, but the transition to the target color is a linear fade from the current color to the target color over the duration specified by the last argument.

When calculating the intermediate colors of a fade, each color component is truncated towards zero (not rounded) after the linear interpolation. For instance, halfway through a fade from 255 to 0, the value of the component is 127, not 128. A fade with a duration of zero sets the target color immediately.

Delaying execution

SLEEP opcode

The opcode is identified by 0x02 and has a single varint argument that encodes the number of frames to sleep for. Execution must proceed to the next opcode after the wait is over.

WAIT_UNTIL opcode

The opcode is identified by 0x03 and has a single varint argument that encodes a number of frames since the start of the light program. It instructs the execution engine to wait until the number of frames elapsed since the start of the light program reaches this value. No action must be performed when the number of frames elapsed is already larger than this value. Execution must proceed to the next opcode after the wait is over.

Control flow of execution

LOOP_BEGIN and LOOP_END opcodes

Loops are defined by the LOOP_BEGIN and LOOP_END opcodes, which must always come in pair and must enclose a sequence of opcodes that must be repeated a given number of times.

The number of iterations is given by the only argument of LOOP_BEGIN, which is a single-byte unsigned integer. An iteration count of zero means that the enclosed sequence of opcodes must be repeated indefinitely. When a LOOP_BEGIN instruction is encountered, a pair consisting of the iteration counter of the loop and the address of the next instruction is pushed down to a loop stack data structure, then the execution resumes with the next instruction.

LOOP_END has no arguments. When the instruction is executed, the topmost item of the loop stack is evaluated. If the topmost item has an iteration counter of zero (meaning an infinite loop), the execution jumps back unconditionally to the address stored in the topmost item of the loop stack. Otherwise, the iteration counter is decreased by one and compared to zero. If the counter reached zero, the topmost item of the loop stack is popped off and the execution continues with the instruction after the LOOP_END opcode. Otherwise the execution jumps back to the address stored in the topmost item of the loop stack.

Nested loops are allowed. The implementation of the light program player should choose a reasonable upper limit on the maximum nesting depth allowed. The reference implementation in libskybrush allows at most four nested loops.

The following rules apply to loops that are not well-formed:

  • A LOOP_END instruction without a matching LOOP_BEGIN (i.e. with an empty loop stack) is a no-op.

  • A LOOP_BEGIN instruction that would exceed the maximum nesting depth stops the execution of the light program; the current color is held indefinitely, as with END.

  • An infinite loop (with an iteration count of zero) whose iteration takes no time (i.e. no time passes between the start and the end of the iteration) stops the execution of the light program when the LOOP_END instruction of the iteration is reached; the current color is held indefinitely, as with END. Finite loops whose iterations take no time are allowed.

END opcode

The opcode is identified by 0x00 and has no arguments. Execution of the light program must terminate when this opcode is reached and the current color must be held indefinitely.

NOP opcode

The opcode is identified by 0x01 and has no arguments. No action must be performed when this opcode is reached and the execution must proceed to the next opcode.

Execution rules for malformed programs

  • Reaching the end of the light program block behaves as if an END opcode were found there; in other words, the trailing END opcode of a light program may be omitted.

  • Arguments of the last instruction that are truncated by the end of the block are read as zeros.

  • An unknown opcode stops the execution of the light program; the current color is held indefinitely, as with END.