Scenario Gallery

Every animation on this site plays a trace recorded by a scenario under tools/trace/scenarios/, from the block’s own C++. Together the scenarios are the blocks’ scenario suite (BB-I2 of the building block standard). This page lists all of them.

Each scenario links to two kinds of page:

Shown on goes to the players that explain the scenario, with panels chosen for that purpose;
the scenario’s name goes to its own page, which plots every channel that changes and lists the rest.

How the scenarios are run

On every pull request, CI runs every scenario with gcc and clang and compares each trace with the committed one (what CI checks). A trace that differs, or a scenario that fails, fails the pull request.
On every deploy, and nightly, the docs workflow runs the suite again on main with both compilers, compares the traces with the committed ones, and publishes the site from the gcc run. A failing scenario is published, so that it shows here, and the workflow then fails.

Status

Status	Meaning
✓ pass	Every check passes
✗ fails, as designed	A check fails that the trace marks `"expect": "fail"`: the scenario shows the edge of the block’s envelope, and the page that plays it explains why. Every other check passes
✗ fail	A check fails
! passes, but is meant to fail	A check marked `"expect": "fail"` passes: the scenario no longer shows what its page says it does
– no checks	The scenario illustrates without a pass criterion; its page’s prose states what to look for
✗ compiler: …	That compiler’s run of the scenario did not run, wrote an invalid trace, or differs from the committed trace

Fail, passes, but is meant to fail, and a compiler’s failure count as failing.

29 scenarios, none failing. Their checks: 23 pass, 1 fail as designed, 0 fail, 5 have none.

Run on 2026-11-12 11:29 UTC at commit 2183adc, with clang (clang 18.1 optimized) and gcc (gcc 13.3 optimized). Each run is compared with the committed traces; the pages play the gcc run, or the committed trace where that run wrote none or an invalid one. Workflow run.

Quadrotor model

Scenario	Shown on	Checks	Status
`battery_sag`	How much headroom does a draining battery leave? Quadrotor Model Deployment	—	– no checks
`dt_convergence`	How fast does the error shrink as the step size halves? Quadrotor V&V Plan	BB-V2 `position_order_min` 3.97 ≥ 3.7	✓ pass
`ground_contact`	What does the model do at take-off and touch-down? Quadrotor V&V Plan	BB-T4 `grounded_steps_moved` 0 ≤ 0	✓ pass
`invariant_violation`	Where does an invalid state come from? Quadrotor Model	—	– no checks
`mirror`	Does the reflected flight mirror the original? Quadrotor V&V Plan	BB-V4 `mirror_relative_error_max` 1.18e-15 ≤ 1.14e-13	✓ pass
`motor_lag`	How quickly does a rotor follow its command? How the Quadrotor Model Works	BB-V1 `rotor_speed_error_vs_closed_form_max` 3.32e-6 ≤ 1.00e-4 rad/s	✓ pass
`punch_out`	What happens to a roll command at full throttle? Quadrotor Model Deployment	—	– no checks
`roll_pulse`	What does a roll torque pulse do to an uncontrolled quadrotor? How the Quadrotor Model WorksWhat does a roll torque pulse do to an uncontrolled quadrotor? Trace Player	BB-V3 `attitude_norm_error_max` 4.44e-16 ≤ 1.78e-15	✓ pass
`rotor_torques`	Which way does each rotor push and twist the body? How the Quadrotor Model Works	—	– no checks
`tumble`	Why does a spin about the middle axis flip over? How the Quadrotor Model Works	BB-V3 `energy_and_momentum_relative_drift_max` 2.18e-11 ≤ 1.00e-6	✓ pass

PID controller

Scenario	Shown on	Checks	Status
`derivative_filter`	How much should the derivative be filtered? How the PID Controller Works	—	– no checks
`external_saturation`	What happens when a downstream cut is not reported? PID Deployment	BB-V1 `reported_integral_vs_park_value` 2.44e-4 ≤ 0.001	✓ pass
`integral_limit`	How large a disturbance can the integral cancel? PID Deployment	BB-V1 `height_error_vs_closed_form_offset` 4.04e-9 ≤ 0.001 m	✓ pass
`terms`	What does a proportional controller alone do to a height? How the PID Controller WorksWhat does damping add, and what does it leave? How the PID Controller WorksHow does the integral remove the offset? How the PID Controller WorksDoes the PD loop settle at the closed-form offset? PID V&V Plan	BB-V1 `pd_height_error_vs_closed_form_offset` 1.22e-14 ≤ 0.001 m BB-T1 `pid_steady_state_error` 2.22e-4 ≤ 0.001 m	✓ pass
`timing_fault`	What does the controller do when its scheduler misbehaves? PID Controller	BB-T1 `output_and_integral_change_on_faulted_ticks` 0 ≤ 0	✓ pass
`windup`	Why does a saturated integral make the loop slow to recover? How the PID Controller WorksDoes the loop recover at once when the setpoint comes back within reach? PID V&V Plan	BB-T1 `recovery_time_to_within_0.02` 0.088 ≤ 0.2 s	✓ pass

Mixer

Scenario	Shown on	Checks	Status
`clip_vs_priority`	At full throttle, what does plain per-rotor clipping cost? How the Mixer WorksDoes the tilt settle when every rotor is saturated? Mixer V&V Plan	BB-I2 `tilt_error_after_0.2s` 0.02456 ≤ 0.05236 rad	✓ pass
`priority`	How much roll can RP-1 get, and at what collective? Mixer DeploymentAs the roll demand grows past what the rotors can give, what goes first? How the Mixer WorksIs the achieved torque always the demand, scaled? Mixer V&V Plan	BB-T1 `achieved_torque_vs_scaled_demand` 4.44e-16 ≤ 1.00e-12 N·m	✓ pass
`throttle_sweep`	Across the whole throttle range, when does the mixer change the demand? How the Mixer WorksDoes any rotor jump where the mixer starts or stops cutting? Mixer V&V PlanWhich channel does the report flag as the throttle sweeps? Mixer	BB-T1 `rotor_thrust_step_per_collective_step` 0.5 ≤ 1	✓ pass

Cascaded controller

Scenario	Shown on	Checks	Status
`climb`	When the thrust runs out on a climb, does the controller wind up? How the Cascade WorksAfter 2 s against the thrust limit, does the climb overshoot? Cascade V&V Plan	BB-I2 `overshoot_above_unsaturated` -0.03701 ≤ 0.05	✓ pass
`roll_step`	How do the loop gains shape a roll step? How the Cascade Works	BB-I2 `roll_overshoot` 0 ≤ 0.1	✓ pass
`schedule`	How often does each loop update its output? How the Cascade WorksDoes each loop update only on its own ticks? Cascade V&V Plan	BB-T1 `updates_off_schedule` 0 ≤ 0	✓ pass
`tilt_yaw`	Does a large turn slow the tilt down? How the Cascade WorksDoes a 90° turn slow the tilt down? Cascade V&V PlanDoes a 90° turn change how the vehicle tilts? Cascaded Controller	BB-I2 `tilt_settle_delay_from_yaw` 0.002 ≤ 0.004 s	✓ pass
`waypoint`	What does the cascade fly from a setpoint with feed-forward? Cascade DeploymentHow closely does the cascade follow a moving setpoint? How the Cascade Works	BB-I2 `worst_criterion_fraction` 0.1981 ≤ 1	✓ pass

Scenario	Shown on	Checks	Status
`delay`	How long do the gyro filters delay a change in roll rate? How the Gyro Filters WorkDoes the gyro chain leave the rate loop 45° of phase margin? Gyro Filters V&V Plan	BB-C2 `rate_loop_phase_margin_deg` 53.04 ≥ 45 deg	✓ pass
`low_rate`	What can the notches do at a 1 kHz gyro rate? Gyro Filters Deployment	BB-I2 `vibration_residual_db` -1.079 ≤ -30 dB BB-C2 `motion_gain_error` 3.40e-4 ≤ 0.02	✗ fails, as designed
`notch`	What does one notch do to a tone that sweeps through it? How the Gyro Filters WorkIs the notch as wide as its closed form says? Gyro Filters V&V Plan	BB-V1 `width_error_hz` 0.472 ≤ 3.75 Hz	✓ pass
`sweep`	Do the notches keep up with a throttle sweep? How the Gyro Filters WorkDo the tracked notches leave less than −30 dB of the vibration? Gyro Filters V&V Plan	BB-I2 `vibration_residual_db` -70.68 ≤ -30 dB BB-C2 `motion_gain_error` 2.55e-4 ≤ 0.02	✓ pass

player

Scenario	Shown on	Checks	Status
`scene_square`	What does a trace's scene show around the vehicle? Trace Player	BB-I2 `worst_criterion_fraction` 0.1981 ≤ 1	✓ pass