Expand description
Parsing and playback of Skybrush drone show files.
This crate is a Rust rewrite of the C library libskybrush, with feature parity to version 6.0.4 of the C library where possible. It is meant to be used from firmware, therefore it does not depend on the standard library; it requires a global allocator only.
§Overview
A show file (.skyb) is a list of blocks, read with
BinaryFile. Each block holds a component
of the show for one drone:
- its trajectory,
- its light program,
- its yaw control,
- its events, such as pyro triggers,
- the collective return-to-home plan,
- the setup of light control from the ground station, and the metadata of the show.
Each component has a player that evaluates it at a time instant. A screenplay places scenes of these components on the show clock, each with a time axis that may slow down, stop or speed up the time of the scene, and the show controller tells what the drone should do at a time instant of the screenplay.
Components read from a show file in memory borrow their bytes from it where they are not modified, so loading a show copies little. Playback does not allocate, and malformed input is reported as an error rather than a panic.
§Example
use skybrush::control::ShowController;
use skybrush::formats::binary::BinaryFile;
use skybrush::screenplay::Screenplay;
// `bytes` holds the contents of a show file
let file = BinaryFile::new(&bytes)?;
let screenplay = Screenplay::from_binary_file(&file)?;
let mut controller = ShowController::new(screenplay);
// What the drone should do 2.5 s into the show
controller.update_time_msec(2500);
let output = controller.current_output();
let position = output.position().ok_or("the show has no trajectory")?;
assert!(position.z > 0.0 && position.z < 5000.0);
// Fire the events that are due by then
while let Some(event) = controller.next_event() {
println!("{event:?}");
}Positions are in millimeters, times in milliseconds or seconds as the names of the functions tell, and angles in degrees.
§Design notes
A few choices follow from the firmware that the crate is written for, and differ from what is usual in Rust crates:
- Threads. A flight controller module runs on a single thread, so
scenes share their components through
Rc: aScreenplayand theShowControllerare neitherSendnorSync, and stay on the thread that created them. The components read from a show file areSendandSync. Trajectory players areSendbut notSync, since trajectory segments cache their polynomials in aOnceCell. - Units. Times, distances and angles are plain numbers (
u32milliseconds,f32seconds, millimeters and degrees) with the unit in the name, as in the C library, rather than types such asDuration. - Allocation. Memory is allocated when a show is loaded, and a failed
allocation is reported as an error instead of aborting. Therefore the
collections do not implement
FromIteratorandExtend, which cannot report it; they have methods that return aResultinstead. - Missing values are
None, except where infinity is the mathematical answer (e.g. the travel time at zero speed, or an acceleration without a limit) and in the fields ofRthPlanEntry, which follow the file format.
Modules§
- basic_
types - Basic data types used throughout the library.
- colors
- RGB and RGBW colors.
- control
- The show controller: what the drone should do at a time instant of a screenplay, and which events it should fire.
- events
- Events placed on the timeline of a show, such as pyro triggers and light control events, and the player that fires them as the time moves forward.
- formats
- The file formats of Skybrush.
- gcs_
light_ control - The setup of interactive light control from the ground station: the pixel that the drone represents in an LED matrix, the size of the matrix, and the palette of colors that the ground station may use.
- lights
- Light programs and the light player.
- metadata
- The metadata of a show: its unique ID and the index of the drone within the show.
- motion
- Motion helpers: travel times and velocities of simple motions, and cubic Bézier curves with given velocities at their ends.
- palette
- Color palettes: lists of colors that are referred to by their indices.
- poly
- Polynomials of degree at most 7, and 4D polynomials along the X, Y, Z and yaw coordinates.
- rth_
plan - Collective return-to-home (RTH) plans: what each drone should do if the show is interrupted at a given time instant.
- screenplay
- Screenplays: the scenes of a show, placed on the show clock, and the return-to-home plan of the show.
- time_
axis - Time axes: mappings from the wall clock to the warped time of a scene, where the time may run faster or slower than real time, or stop.
- trajectory
- Trajectories of drones.
- yaw_
control - Yaw control: the yaw of the drone during a show, given as a yaw offset and a list of relative yaw changes with durations.