ekf2-rs
Rust #![no_std] bindings for the PX4 EKF2 state-estimation algorithm.
This workspace consists of two crates:
ekf2-sys: rawunsafeFFI bindings to vendored PX4 EKF2 C++ekf2: safe Rust wrapper API
Note that ekf2 requires an allocator. Any allocator implementing the
allocator_api2::alloc::Allocator
trait may be used. By default, Ekf::new() uses Rust's global allocator.
Minimal usage
use ;
Supported Features
The long-term goal is to expose the full PX4 EKF2 algorithm through Rust.
Currently supported functionality includes:
- Runtime + inputs: standalone
no_stdheap-owned EKF instance withnew()/with_config()/new_in()/with_config_in()/update(), IMU always-on, and feature-gated sensor feeds (GNSS, mag, baro, airspeed, range, flow, EV, aux-vel). - Outputs + diagnostics: attitude/position/velocity, biases/variances, innovation and aid-source diagnostics, validity/solution/fault/control status.
- Config + control: typed
params()/params_mut()access and runtime reset/control helpers (global origin, heading/wind, bias, WMM updates).
Feature Flags
ekf2-sys maps C++ compilation features to Rust features. Enabling a feature compiles the corresponding C++ code and
exposes related API in Rust.
| Rust feature | Default | PX4 compilation term |
|---|---|---|
gnss |
yes | CONFIG_EKF2_GNSS |
magnetometer |
yes | CONFIG_EKF2_MAGNETOMETER |
barometer |
yes | CONFIG_EKF2_BAROMETER |
gnss-yaw |
no | CONFIG_EKF2_GNSS_YAW |
baro-compensation |
no | CONFIG_EKF2_BARO_COMPENSATION |
airspeed |
no | CONFIG_EKF2_AIRSPEED |
range-finder |
no | CONFIG_EKF2_RANGE_FINDER |
optical-flow |
no | CONFIG_EKF2_OPTICAL_FLOW |
external-vision |
no | CONFIG_EKF2_EXTERNAL_VISION |
aux-vel |
no | CONFIG_EKF2_AUXVEL |
drag-fusion |
no | CONFIG_EKF2_DRAG_FUSION |
wind |
no | CONFIG_EKF2_WIND |
terrain |
no | CONFIG_EKF2_TERRAIN |
gravity-fusion |
no | CONFIG_EKF2_GRAVITY_FUSION |
sideslip |
no | CONFIG_EKF2_SIDESLIP |
logging |
no | - |
c-stubs |
no | - |
Note: range-finder and optical-flow implicitly enable CONFIG_EKF2_TERRAIN in ekf2-sys/build.rs.
drag-fusion and sideslip implicitly enable wind; airspeed implicitly enables
drag-fusion, sideslip, and wind because PX4 uses those implementation components
when compiling airspeed fusion.
The logging feature enables PX4 diagnostic messages through the target's
printf/fprintf symbols. The c-stubs feature provides no-op C runtime
symbols for bare-metal targets that do not provide them.
Verified targets
The crate is verified in CI to compile for the following targets:
x86_64-unknown-linux-gnuthumbv7em-none-eabihfthumbv6m-none-eabi
Further targets should also work, but are untested.
Memory Management
The EKF2 C++ code has been modified to route all EKF-owned dynamic allocations
through allocator callbacks provided by Rust. Ekf::new() uses the global
allocator, and Ekf::new_in() accepts any
allocator_api2::alloc::Allocator.
License
This repository is licensed under the BSD 3-Clause license.
See LICENSE.
It also depends on vendored third-party code (PX4 and components inside the
PX4 source tree). See THIRD_PARTY_NOTICES.md for
license attributions and paths.