Skip to content

pidgeon 1.0.0: correctness fixes, Iggy removal, docs rewrite - #22

Merged
darioalessandro merged 4 commits into
mainfrom
audit/v1.0.0
Nov 7, 2026
Merged

darioalessandro merged 4 commits into
mainfrom
audit/v1.0.0

Conversation

@darioalessandro

@darioalessandro darioalessandro commented Nov 7, 2026 •

Copy link
Copy Markdown
Member

Three audits went through the whole crate: math and correctness, ease of use, and cruft. This PR is the result, and it bumps pidgeon to 1.0.0.

Code written against 0.3 still compiles

1.0 keeps the 0.3 API. Every public signature, field and enum variant is unchanged, except for the removed debugging feature (see below). To prove it, main's own core_tests.rs, std_tests.rs and drone_altitude_control.rs were compiled unmodified against this branch: all 14 tests compile and pass, and the example compiles.

Bugs fixed (each proven by a test that fails on main and passes here)

Bug Test
Conditional anti-windup froze the integral whenever the output was saturated, so an integral past the limit never unwound regression_tests::conditional_anti_windup_unwinds_integral_beyond_limit
On a frozen integral, the returned output didn't match the stored integral conditional_anti_windup_output_matches_stored_integral
Back-calculation with gain dt/Tt diverged once dt > 2*Tt; it now uses backward Euler dt/(Tt+dt) back_calculation_is_stable_when_dt_exceeds_tracking_time, back_calculation_matches_backward_euler
ControllerConfig::builder().build() always failed: the default limits were ±inf, which build() rejected default_builder_builds
DerivativeMode::OnError differentiated the error after the deadband on_error_derivative_ignores_deadband
An overflow returned Ok(NaN) and poisoned the state overflow_is_an_error_not_a_nan
set_output_limits(5, -5) stored bad limits, and the next compute() panicked inside f64::clamp std_regression_tests::set_output_limits_panics_at_once_and_keeps_old_limits, thread_safe_set_output_limits_rejects_bad_limits
One rejected NaN sample made average_error NaN forever rejected_sample_does_not_poison_statistics
Statistics were timed with the wall clock, not the sum of dt statistics_use_controller_time_not_wall_clock
max_overshoot was really the largest error, which for a step is just the step size overshoot_is_distance_past_setpoint_not_initial_error

Behaviour that changes (no code changes needed)

  • PidController::set_output_limits with invalid limits now panics right away with a clear message, instead of on the next compute(). ThreadSafePidController::set_output_limits returns Err, as its signature always said it could.
  • Statistics values are now correct: overshoot is the distance past the setpoint, times are controller time (the sum of dt), and statistics restart when the setpoint changes.
  • PidState::prev_error holds the raw error, so the deadband no longer leaks into the OnError derivative.

Breaking on purpose

  • The Iggy-based debugging feature is removed, along with debug.rs, the debug example, the pidgeoneer dashboard and run_pidgeon_demo.sh. Anyone with features = ["debugging"] gets a Cargo error. To watch a controller live, use the ratatui drone_altitude_control example, which reads the P/I/D terms from the new last_terms().
  • Edition 2024, so the minimum Rust version is now 1.85. A new CI job checks the library on 1.85 in both std and no_std mode. Running the tests and examples needs Rust 1.88, because ratatui's dependencies require it.

Kept

  • The wasm feature is unchanged, and CI now checks it on wasm32-unknown-unknown.

Additions

  • PidTerms and last_terms() on both controllers.
  • update_config and set_anti_windup_mode on PidController; set_anti_windup_mode, set_anti_windup, config() and state() on ThreadSafePidController.
  • ControllerConfig::to_builder(), plus extra derives.
  • A real pure_pid_compute benchmark.
  • A new temperature_control example.

Docs and cleanup

  • README and crate docs rewritten. False claims are removed (Bode plots, auto-tuning telemetry, drone features that didn't exist), and the benchmarks were re-measured.
  • Narration comments and dead code are cut.
  • CLAUDE.md matches the code.
  • CI now also runs the no_std, wasm32 and MSRV checks.

Verified locally

  • On Rust 1.91: cargo test (38 unit + 10 doc), fmt --check, clippy --all-targets -D warnings, the no_std check, wasm32 clippy with --features wasm, benches clippy, build --examples, cargo doc -D warnings, cargo publish --dry-run.
  • On Rust 1.85: cargo check of the library, std and no_std.

Not run: the drone TUI example is interactive, so it was built but not executed.

The CHANGELOG.md entry is left to release-plz.

🤖 Generated with Claude Code

darioalessandro and others added 4 commits November 6, 2026 22:26
- Fix 10 bugs in the core and the std wrappers, each proven by a
  regression test that fails on 0.3.x: conditional anti-windup lock-up,
  back-calculation divergence, default builder failing, unvalidated
  setters panicking in clamp, NaN-poisoned stats, wrong overshoot,
  wall-clock statistics, deadband leaking into the OnError derivative,
  overflow returning Ok(NaN).
- Add PidTerms and last_terms(); make the setters consistent and validated.
- Remove the Iggy-based `debugging` feature, the pidgeoneer dashboard and
  the demo script. The ratatui drone example is the visualization story.
- Keep the `wasm` feature and add a wasm32 check to CI.
- Rewrite the README and crate docs, add a temperature_control example,
  and cut dead code and narration comments.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Restore 0.3 signatures and shapes: PidError without non_exhaustive and
  with MutexPoisoned std-only, ControllerStatistics with its four f64
  fields, set_output_limits/set_settled_threshold returning (), and
  deadband taking abs(). Bug fixes that only change values stay.
- PidController::set_output_limits now panics immediately on invalid
  limits instead of on the next compute().
- Edition 2024, rust-version 1.85, with a CI job that checks the library
  on 1.85.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The library uses a matches! guard instead of a let-chain, so it still
builds on Rust 1.85. The examples need 1.88 for ratatui anyway, so they
take clippy's let-chain and is_multiple_of suggestions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@darioalessandro
darioalessandro merged commit 2059609 into main Nov 7, 2026
5 checks passed
@darioalessandro
darioalessandro deleted the audit/v1.0.0 branch November 7, 2026 07:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant