Event list blocks
Event list blocks store arbitrary events (actions) to be performed by the drone at specific points in the show timeline. This block is currently used to store the timestamps of pyro trigger events and light control events, but new event types may be added in the future as needed.
The basic byte-level structure of an event list block is as follows:
Events in an event list block must be sorted by timestamp in ascending order. Libraries implementing support for this block may safely assume that the number of events in the block is small (especially compared to trajectories and light programs) and therefore it is feasible to store the entire event list in memory.
Parsers must reject event list blocks where the events are not sorted by timestamp; events with equal timestamps are allowed. If the length of the block payload is not a multiple of the size of a single event (10 bytes), the trailing bytes are ignored.
Structure of a single event
Each event in the event list has an absolute timestamp (encoded in unsigned milliseconds since show start), an event type, a subtype and a payload. The type determines the kind of the event; the possible subtypes are dependent on the event type itself, while the interpretation of the payload may depend on the event type and the subtype as well.
The basic byte-level structure of a single event is as follows:
Supported event types
Currently we have the following event types:
-
0x00: No event -
0x01: Pyro trigger event -
0x02: Light control event
In the future we might have additional event types with unique subtypes and payloads.
Parsers must not reject events with unknown types or unknown subtypes; such events are passed through as opaque events, with their timestamp, type, subtype and payload preserved.
Pyro trigger events
The subtype of a pyro trigger event is the index of the pyro channel to be triggered. A payload of 0x00000000 turns the pyro channel on (i.e. triggers it), while a payload of 0xFFFFFFFF turns the pyro channel off. Other payload values are reserved.
Timestamps of pyro events stored in the .skyb format must already have payload-specific prefire times compensated, but should not take into account pyro-module specific triggering times/delays. The former must be compensated when converting e.g. from .skyc to .skyb, the latter will be compensated in the drone firmware on the fly by libskybrush, depending on the pyro module used.
|
Light control events
Light control events are used to control the lights of the drone from a ground control station (GCS) in an interactive fashion, i.e. while the show is being executed, typically as part of a swarm show in which the GCS sends commands to individual drones in the fleet. The interpretation of the payload depends on the subtype of the event:
-
0x00: Sets the input source of a light output. The first byte of the payload is the index of the light output to affect, the second byte is the light source to apply for the given light output. Sources are defined by the application; in light shows, source0is a fixed color (defined by the remaining two bytes of the payload in RGB565 notation), source1is the current light program from the show file, and source2is interactive GCS control mode. -
0x01: Sets the X coordinate of the pixel represented by the drone in interactive GCS control mode. The payload is a little-endian 32-bit unsigned integer whose 12 least significant bits carry the coordinate. -
0x02: Sets the Y coordinate of the pixel represented by the drone in interactive GCS control mode. The payload is a little-endian 32-bit unsigned integer whose 12 least significant bits carry the coordinate.
| The remaining bits of the payload of pixel coordinate events should be set to zeros, but this is not enforced by parsers, as these bits may be assigned a meaning in later versions of the format. |
| The payloads of light control events are interpreted by the firmware of the drone. Libraries parsing the event list block may treat them as opaque data. |
The pixel that the drone represents in interactive GCS control mode is assumed to be (0, 0) until it is set by an event; for reference, the GCS light control setup block may also be used to declare the X-Y coordinate pair of the pixel represented by the drone up front.