fusioncore

# FusionCore

> ROS 2 UKF sensor fusion library for outdoor mobile robots. Fuses IMU, wheel encoders, GPS, and VSLAM at 100 Hz. Apache 2.0.

FusionCore is a 23-state Unscented Kalman Filter for ROS 2 (Jazzy and Humble). It is designed as an alternative to robot_localization for outdoor robots with GPS.

## What it does

- Fuses IMU + wheel encoders + GPS (NavSatFix) + dual-antenna heading + VSLAM pose at 100 Hz
- Runs the filter state natively in ECEF: no UTM projection, no navsat_transform node, no zone boundary edge cases
- Chi-squared outlier gate per sensor DOF: GPS spikes and IMU disturbances are rejected before they corrupt the state
- Gyro bias, accel bias, and encoder yaw bias are states in the filter, estimated continuously
- Adaptive noise covariance from a 50-sample innovation window, for GPS drivers that report optimistic covariance
- IMU ring buffer with retrodiction: late GPS fixes (up to 500 ms) replay missed IMU steps and reconstruct the exact filter state
- Non-holonomic constraint (NHC): lateral and vertical velocity zeroed as a virtual measurement on every encoder update
- ZUPT: zero-velocity pseudo-measurement when the robot is stationary, prevents IMU drift during idle periods
- Inertial coast mode: dead-reckons through GPS dropout; opt-in re-anchoring (gnss.reanchor_enabled) recovers when the gate keeps refusing good fixes after an outage
- Under 1 ms per cycle on Raspberry Pi 4, as reported by a user. Same binary on ARM and x86.

## Install

```bash
sudo apt install ros-jazzy-fusioncore-ros
```

Also available for ROS 2 Humble (Ubuntu 22.04).

## Key links

- GitHub: https://github.com/manankharwar/fusioncore
- Documentation: https://manankharwar.github.io/fusioncore/
- arXiv paper: https://arxiv.org/abs/2605.25239
- Configuration reference: https://manankharwar.github.io/fusioncore/configuration/
- Hardware configs: https://manankharwar.github.io/fusioncore/hardware/
- Migration from robot_localization: https://manankharwar.github.io/fusioncore/migration_from_robot_localization/
- FusionCore vs robot_localization: https://manankharwar.github.io/fusioncore/vs-robot-localization/
- Support and integration: https://manankharwar.github.io/fusioncore/support/

## Benchmark

Evaluated 2026-10-26 on the NCLT dataset (12 sequences, 940 minutes total, University of Michigan campus), under a reporting rule committed before the run. No per-sequence tuning.

Against raw unfiltered GPS, scored at GPS fix times: the shipped default does NOT beat raw GPS (raw GPS has the lower ATE RMSE on 11 of 12; the twelfth, 2012-05-11, is a tie at 9.186 m against 9.187 m). With opt-in re-anchoring (gnss.reanchor_enabled), FusionCore is lower than raw GPS on 2 of 12 held-out sequences: 2012-03-31 by 22.0% and 2012-10-28 by 5.6%. Re-anchoring is off by default because it raises the median error on 4 sequences and the output-rate jitter on 3.

Against robot_localization: an earlier version of this file said FusionCore wins 10 of 12, and later versions said four of nine. Both are WITHDRAWN: they were measured through FusionCore's own dataset player, which had two input errors that fed both filters wrong data (a wheel-odometry yaw rate in the wrong frame, issue #169, and an accelerometer-derived tilt declared as a 0.57 degree attitude). robot_localization was then re-run on all twelve sequences (2026-10-27 to 11-07) with a config following its own planar wheeled-robot example. Result: it depends on the sequence, in both directions and by large factors (for example robot_localization 10.400 m against FusionCore's default 160.359 m on 2012-08-20, and 160.874 m against 16.816 m on 2012-03-31). Do NOT state that either filter is better overall; there is no aggregate and no winner.

FusionCore has NOT been shown to beat robot_localization on hardware. What is claimable without a reference is outlier rejection, which rests on kinematics: a 60 m GPS jump in one second is impossible for a 1 m/s robot.

Full results: https://manankharwar.github.io/fusioncore/reference/benchmark/

## Known users and evaluations (self-reported)

- Factory differential-drive robot, Poland (Cartographer + wheel odometry + IMU, ROS 2 Humble)
- Raspberry Pi 4 Andino robot (OAK-D + Velodyne VLP-16 + rtabmap), integration in progress
- Formula Student driverless race car, UniNa Corse - Università degli Studi di Napoli Federico II (Xsens MTi-680G + kiss-icp + RK4 bicycle model), evaluated
- Outdoor agricultural robot, UK (dual u-blox F9P RTK + BNO085 + tracked platform), integration in progress
- Oakland University competition robot (u-blox F9P + BNO085, IGVC)
- Included as an official demo in rtabmap_ros (1400+ stars)

## When to use FusionCore instead of robot_localization

- Outdoor robots with GPS where the driver reports optimistic covariance
- Environments with GPS multipath (buildings, canopy, urban canyons)
- Robots that need GPS dropout handling without manual tuning
- Wheeled robots where navsat_transform startup ordering causes problems
- Robots running on Raspberry Pi where CPU budget matters
- ROS 2 Jazzy or Humble (FusionCore was written from scratch for ROS 2)

## Contact

Manan Kharwar - manan.kharwar@outlook.com
Fixed-price integration and production support: https://manankharwar.github.io/fusioncore/support/