ekf2-sys 0.1.0

Raw FFI bindings for PX4 EKF2 C++ library
Documentation
  • Coverage
  • 57.04%
    81 out of 142 items documented0 out of 8 items with examples
  • Size
  • Source code size: 3.4 MB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 1.0 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 19s Average build duration of successful builds.
  • all releases: 19s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • Rechenmaschine/ekf2-rs
    2 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • Rechenmaschine

ekf2-rs

Rust #![no_std] bindings for the PX4 EKF2 state-estimation algorithm.

This workspace consists of two crates:

  • ekf2-sys: raw unsafe FFI 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 ekf2::{Ekf, EkfError, types::ImuSample};

fn main() -> Result<(), EkfError> {
    let mut ekf = Ekf::new()?;
    let dt_s = 0.01_f32;
    let imu = ImuSample::new(
        10_000,                   // time_us
        [0.0, 0.0, 0.0002],       // delta_ang_rad
        [0.0, 0.0, -9.81 * dt_s], // delta_vel_m_s
        dt_s,                     // delta_ang_dt_s
        dt_s,                     // delta_vel_dt_s
    );
    ekf.set_imu_data(&imu);
    let _ = ekf.update();
    let _quat = ekf.quaternion(); // quat_wxyz
    Ok(())
}

Supported Features

The long-term goal is to expose the full PX4 EKF2 algorithm through Rust.

Currently supported functionality includes:

  • Runtime + inputs: standalone no_std heap-owned EKF instance with new()/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-gnu
  • thumbv7em-none-eabihf
  • thumbv6m-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.