Yaw control blocks

Yaw control blocks encode the yaw angle of the drone to follow during a light show using a sequence of baked first-order yaw setpoints to be followed with linear interpolation between them.

The yaw angle during flight is assumed to be continuous, i.e. the last yaw angle of each yaw setpoint is the same as the first yaw angle of the next setpoint. Furthermore, yaw angles shall not be restricted to the 0-360 degree range, instead, they should have a continuous representation in time (i.e., turning 2 full cycles clockwise should bring yaw angle from 0 to 720 degrees). Due to this requirement, yaw setpoints encode the relative yaw change (which we will refer to as a yaw delta in the future) and not the absolute yaw as the latter is not bounded.

The basic byte-level structure of a yaw control block is as follows:

Byte-level structure of a yaw control block
Figure 1. Byte-level structure of a yaw control block

Flags byte

The flags byte has the following structure:

Structure of the flags byte in a yaw control block
Figure 2. Structure of the flags byte in a yaw control block

where the Auto bit is 1 if the yaw of the drone should always follow the direction of motion (auto yaw mode). In this case the Yaw offset value contains a persistent yaw offset relative to the direction of motion, not the actual initial yaw.

If the Auto flag is set, yaw deltas must not be present in the yaw control block.

The Auto flag, and the meaning of the Yaw offset in auto yaw mode, are interpreted by the autopilot firmware of the drone. Libraries parsing the yaw control block simply expose the flag, the yaw offset and the yaw deltas; they do not need to implement auto yaw mode themselves.

Yaw offset

The yaw offset of the yaw control block is encoded as a 16-bit signed integer corresponding to either the initial yaw angle of the drone, or the yaw offset relative to the direction of motion, depending on the value of the Auto flag.

In both cases, the angle is encoded in 1/10th of a degree, modulo 3600. The modulo operation is an encoding rule: writers must produce a yaw offset in the range [0; 3600), while parsers use the stored value as-is.

Yaw deltas

Yaw deltas contain a relative duration and a relative yaw from the previous yaw setpoint. In the case of the first yaw setpoint, duration is relative to time zero and yaw is relative to Yaw offset. The yaw angle of the drone should reach the yaw determined by each entry by the end of the duration of the entry.

Structure of a yaw delta
Figure 3. Structure of a yaw delta

The duration of the yaw delta is encoded as an unsigned 16-bit integer, in milliseconds. This means that the longest setpoint allowed is about 65 seconds long. If you have longer setpoints, you need to slice them to smaller ones until you fit within the two-byte limit. A duration of zero is allowed and represents an instantaneous yaw change; when the yaw is evaluated at a time instant that falls within such a setpoint, the yaw is the midpoint of the change.

The relative yaw of the yaw delta is encoded as a signed 16-bit integer, in 1/10th of a degree. This means that the largest yaw change allowed within one setpoint is a bit more than 9 full circles. If you ever need larger yaw change than this, you need to slice the rotation into smaller deltas to fit within the two-byte limit.

For instance, a delta containing 0xd0 0x07 0xe8 0x03 means that the segment is 2000 milliseconds long (because 0x07d0 = 2000) and the relative yaw change is 100 degrees (because 0x03e8 = 1000).