cpp-sensor-fusion

Embedded-friendly C++17 Sensor Fusion library with threaded fake sensors (GPS, IMU, Temperature) and a simple 2D complementary filter. Includes a realtime demo app and minimal test.

What this project does

• Produces fake sensor streams on separate threads at different rates
• Moves data through lock-protected queues to a fusion engine
• Fuses GPS (absolute position) with IMU (integrated acceleration) using a complementary filter in 2D
• Tracks temperature for future drift compensation

Why this design

• Threads + queues model real-time producer/consumer pipelines
• Clear separation of concerns: sensors, queues, fusion
• Public headers (.hpp) for API/types; sources (.cpp) for implementation

Features

• Fake sensors: GPS (5 Hz), IMU (100 Hz), Temp (1 Hz)
• ThreadSafeQueue<T> with optional capacity
• FusionEngine with configurable complementary filter gain alpha
• Example: realtime_demo (Ctrl+C to stop)
• CMake build; minimal smoke test (no GoogleTest)

Build

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON -DBUILD_EXAMPLES=ON
cmake --build build -j

Run

• Demo:

./build/realtime_demo

• Tests:

ctest --test-dir build -V

Library overview

• include/sensor_fusion/common/types.hpp: basic types (Vec2, GpsSample, ImuSample, TempSample, FusedState2D)
• include/sensor_fusion/common/thread_safe_queue.hpp: thread-safe queue template
• include/sensor_fusion/sensors/i_sensor.hpp: generic sensor interface
• include/sensor_fusion/sensors/fake_*.hpp: fake GPS/IMU/Temp sensors
• include/sensor_fusion/fusion/fusion_engine.hpp: 2D complementary filter engine
• src/**: implementations
• examples/realtime_demo.cpp: demo wiring sensors -> fusion engine

How fusion works (2D complementary filter)

• Integrate IMU acceleration to update velocity and position continuously
• When GPS arrives, correct the position with gain alpha:
  • pos = (1-alpha)*pos + alpha*gps_pos
• Temperature is tracked and exposed in state for future use

Configuration

• sf::FusionEngine::Config: { alpha, queue_capacity }
• Sensor constructors: rates and noise (where applicable)

API quickstart

sf::FusionEngine engine({.alpha = 0.08, .queue_capacity = 4096});
engine.start();

sf::FakeGpsSensor gps(5.0, 1.2);
sf::FakeImuSensor imu(100.0, 0.15);
sf::FakeTempSensor temp(1.0);

gps.start([&](const sf::GpsSample &s){ engine.submitGps(s); });
imu.start([&](const sf::ImuSample &s){ engine.submitImu(s); });
temp.start([&](const sf::TempSample &s){ engine.submitTemp(s); });

// ... run ... then shutdown
gps.stop(); imu.stop(); temp.stop(); engine.stop();

Roadmap (optional)

• Thread-safe state getter / publisher interface
• CSV logging for analysis
• 3D state and orientation (AHRS) support

License

MIT. See LICENSE.

CI

GitHub Actions workflow builds and runs tests on Linux and macOS.