Skip to main content

Crate skybrush

Crate skybrush 

Source
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:

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: a Screenplay and the ShowController are neither Send nor Sync, and stay on the thread that created them. The components read from a show file are Send and Sync. Trajectory players are Send but not Sync, since trajectory segments cache their polynomials in a OnceCell.
  • Units. Times, distances and angles are plain numbers (u32 milliseconds, f32 seconds, millimeters and degrees) with the unit in the name, as in the C library, rather than types such as Duration.
  • 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 FromIterator and Extend, which cannot report it; they have methods that return a Result instead.
  • 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 of RthPlanEntry, 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.