1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
//! 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`](formats::binary::BinaryFile). Each block holds a component
//! of the show for one drone:
//!
//! - its [trajectory](trajectory::Trajectory),
//! - its [light program](lights::LightProgram),
//! - its [yaw control](yaw_control::YawControl),
//! - its [events](events::EventList), such as pyro triggers,
//! - the collective [return-to-home plan](rth_plan::RthPlan),
//! - the [setup of light control](gcs_light_control::GcsLightControlSetup)
//! from the ground station, and the [metadata](metadata::ShowMetadata) of
//! the show.
//!
//! Each component has a player that evaluates it at a time instant. A
//! [screenplay](screenplay::Screenplay) places scenes of these components on
//! the show clock, each with a [time axis](time_axis::TimeAxis) that may slow
//! down, stop or speed up the time of the scene, and the
//! [show controller](control::ShowController) 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;
//! # use skybrush::basic_types::Vector3WithYaw;
//! # use skybrush::trajectory::TrajectoryBuilder;
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! # // A show file with a single trajectory block: a climb to 5 m in 5 s
//! # let mut builder = TrajectoryBuilder::new(1)?;
//! # builder.set_start_position(Vector3WithYaw::default())?;
//! # let top = Vector3WithYaw { z: 5000.0, ..Vector3WithYaw::default() };
//! # builder.move_to_in_time(top, 5000, 2000.0)?;
//! # let body = builder.build()?.bytes().to_vec();
//! # let mut bytes = b"skyb\x01\x01".to_vec();
//! # bytes.extend_from_slice(&u16::try_from(body.len())?.to_le_bytes());
//! # bytes.extend_from_slice(&body);
//! // `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:?}");
//! }
//! # Ok(())
//! # }
//! ```
//!
//! 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`](alloc::rc::Rc): a
//! [`Screenplay`](screenplay::Screenplay) and the
//! [`ShowController`](control::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`](core::cell::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`](core::time::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`](rth_plan::RthPlanEntry), which follow the file format.
//!
//! [Skybrush]: https://skybrush.io
//! [libskybrush]: https://github.com/skybrush-io/libskybrush
extern crate alloc;