Library / SDK
jnz/INSLIB avatar
jnz/INSLIB

INSLIB: a portable C Kalman-filter library for inertial navigation

Open Source Inertial Navigation Library

675 stars115 forksCAGPL-3.0

At a glance

What is it?
INSLIB fuses IMU data with GNSS, barometer, magnetometer and zero-velocity information in a dependency-free C11 library. It ships a requirements database, a post-processing GUI and a live UDP receiver, under AGPL-3.0.
Who is it for?
Adopt INSLIB if you are writing embedded or UAV navigation code in C11 and can accept AGPL-3.0, or if you need offline replay of recorded IMU/GNSS logs with a documented config.yaml. Do not adopt it if you need a permissively licensed core to link into closed firmware, or if you expect a versioned release to pin.
Can I use it commercially?
Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly C, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • jnz/INSLIB675 ★ · +141
Star history
Repository2026-09-212026-11-15
jnz/INSLIB534675

141 Stars in the last 55 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What INSLIB solves, and who it is written for

The README describes INSLIB as a portable C library for 3D navigation state estimation, built around a set of Kalman filters. The problem it addresses is concrete: an inertial measurement unit drifts, and a GNSS receiver is noisy and intermittent, so neither alone gives a usable position and attitude stream. INSLIB fuses them, plus barometer, magnetometer, local position references, absolute yaw references, scalar ground speed and zero-velocity or zero-rotation information. The README lists drones, autonomous vehicles, robotics platforms, aerospace, cars and embedded systems as typical uses.

The stated design constraints are what separate it from a desktop estimation framework. The core is C11 with no external dependencies, no heap allocation and no OS dependencies, so it can run on bare metal. Most arithmetic is 32-bit float, and the README says no 64-bit double precision floating point unit is required, with GNSS/GPS coordinates as the exception. The README also claims worst-case-execution-time friendliness: no unbounded loops and no recursion, which matters if the filter sits inside a real-time control loop. Those are claims from the project, not measurements I can reproduce here.

How the filter is put together: square-root covariance and delayed aiding

Two mechanisms are worth understanding before you commit code to this library. The first is the covariance representation. The README describes the core as using UDU/Bierman-Thornton Kalman filter routines for square-root filtering, with the stated effect that effective precision for the covariance is increased. Square-root forms avoid propagating a covariance matrix that can lose positive-definiteness through repeated subtraction in single precision, which is a real failure mode when the whole filter runs in 32-bit float. If you have debugged a diverging EKF on a microcontroller, this design choice is the reason to look at INSLIB at all.

The second is latency handling. GNSS receivers report with delay, and the README puts typical receiver latency at more than 100 to 200 milliseconds from processing, internal filtering and UART transmission. INSLIB implements measurement delay compensation and estimation rather than assuming the fix timestamp is the measurement time. The repository includes a way to measure that delay empirically: the README says the post-processing tools cross-correlate IMU plus barometric vertical velocity against GNSS-reported vertical velocity around a real climb or descent, producing a lag with a sharp correlation peak.

Aiding is configurable rather than fixed. A dataset directory holds one config.yaml that sets aiding mode, sensor noise, lever arms and which channels are enabled. The README points to two annotated starting points: doc/example_conf/config_basic.yaml for GNSS+IMU+baro+mag, and doc/example_conf/config_local_inertial.yaml for GNSS-free dead reckoning. It also notes a standalone AHRS_MODE_ARS mode, a 5-state filter with freely integrated yaw that runs from IMU data alone for platforms that only need roll and pitch.

Installing INSLIB and replaying a dataset

There is no package on a registry and no release archive in the README. The quickstart is a repository clone plus a shell script that builds a Python virtual environment and, as a side effect, runs make pylib to build the Python bindings. On POSIX or git-bash the activation script is env.sh. The commands below are copied from the README's post-processing quickstart.

bash
sh python/setup_venv.sh               # one-time (also runs `make pylib`)
. env.sh                              # activate the venv (POSIX/git-bash, any OS)
python3 python/inspostgui.py datasets/fog

The first command is the one-time setup, the second activates the environment, and the third opens the GUI on the bundled datasets/fog directory. In the GUI you pick a dataset directory containing CSVs plus a config.yaml, adjust settings, and replay it. The command-line equivalent writes plots to a PDF and can emit a Google Earth file.

bash
python3 python/replay.py datasets/fog --plot --plot-out /tmp/plots.pdf

With --plot and --plot-out you get a PDF of the estimated states; the README shows --kml output.kml as the option for Google Earth tracks. Input data is plain CSV, one file per sensor, with a common t_us timestamp in microseconds as the first column. The IMU header in the README is `t_us, gyr_frd_x [rad/s], gyr_frd_y [rad/s], gyr_frd_z [rad/s], acc_frd_x [m/s^2], acc_frd_y [m/s^2], acc_frd_z [m/s^2]`, and the GNSS, magnetometer, barometer and speed files follow the same pattern. Example files are linked from the README for IMU, barometer, GNSS and magnetometer. If you want to measure receiver latency rather than assume it, the README gives this invocation for a u-blox X20P:

bash
python3 python/replay.py datasets/pedestrian/07_outdoor_only/ --estimate-gnss-delay

For live data the flow is different. insrcv listens for UDP packets in the format documented in tools/inslib_protocol.md, on port 29800 by default, and forwards output to PlotJuggler on UDP 9870 as JSON, with optional MAVLink on UDP 14550. The build and run commands from the README are:

bash
make insrcv
./build/insrcv --mavlink   # run and wait for UDP sensor input

Note the asymmetry: the Python path needs a virtual environment and bindings, while insrcv is a plain Makefile target producing build/insrcv. The Makefile builds and runs tests against the KFCore submodule, so a clone needs its submodules initialised before make test will do anything useful.

Where INSLIB is the wrong tool

The licence is the first hard boundary. The repository is AGPL-3.0. For a library whose stated audience includes cars, drones and embedded products, that is a significant constraint: AGPL-3.0 is a strong copyleft licence, and the interaction between it and a statically linked firmware image is exactly the kind of question you should put to your own counsel rather than to a review. If your product cannot ship source under those terms, INSLIB is the wrong starting point regardless of its technical merit.

The second boundary is release management. The repository has no published GitHub releases, so there is no versioned tarball to pin and no changelog to read. Integration means tracking the main branch or a commit hash, and the Makefile's dependence on the KFCore submodule means your build is pinned to a submodule revision as well as a parent revision. Teams that need a frozen artefact with a support window will find that awkward.

The third is scope. This is a state estimator, not a full navigation stack. The README does not document map matching, loop closure, SLAM, or any correction from prior maps, and it does not claim them. If your problem is indoor positioning without GNSS in a building you have already mapped, an estimator that fuses inertial and absolute references will not use that map. The README also does not document a rollback or migration path between config.yaml schema versions, so treat your configuration files as something you own and version yourself.

Finally, the documentation surface is split. The README covers quickstarts and data formats, but it states that the config.yaml keys are documented in doc/INSLIB_manual.pdf, section "Dataset configuration: config.yaml". That means the authoritative reference for the configuration is a PDF in the repository, not a generated HTML page. Whether that suits your team is a judgement call, but it is worth knowing before you plan onboarding around the README alone.

INSLIB against a GNSS-first stack such as a generic EKF or a mature INS suite

The natural alternative is not another C library but a GNSS-centric stack: a receiver's own PVT solution, or a general-purpose robot state estimation package that treats IMU as one input among many and assumes a Linux host with ROS-style message plumbing. The difference in approach is where the filter lives and what it assumes about the platform. A GNSS-first stack typically runs on the host, allocates freely, and can depend on a middleware layer. INSLIB inverts that: no heap, no OS dependencies, 32-bit float, and a stated goal of bounded execution time, so the filter can run on the flight controller itself.

That inversion has costs. You give up the ecosystem of message types, visualisation tools and prebuilt integrations that a host-side framework provides, and you take on the CSV and config.yaml data model instead. You also take on the requirement to supply well-formed sensor CSVs or speak the inslib_protocol.md UDP format. The compensating benefit, according to the README, is that the same code runs on bare metal and on a desktop, which is what makes the replay tools useful: you can post-process recorded flights with the same filter that runs live.

There is also a testing argument in the repository. The README claims more than 90 percent test coverage including MC/DC, and links the code logic to a machine-checked requirements database under requirements/ that `make reqs` checks. The README frames this as aerospace-style traceability, mentioning DO-178 DAL-A and ISO 26262 ASIL-D developments as contexts where such coverage matters. Coverage numbers and traceability do not by themselves make an estimator correct, but for a safety-adjacent component they change the review conversation from "what does this code do" to "which requirement does this line satisfy".

Maintenance, upgrade cost and licence implications

The repository is not archived, and the last push was on 2026-09-09, which is recent. That is the only maintenance signal available here. The repository has no published GitHub releases, so there is no published upgrade path, no semantic versioning to reason about, and no deprecation notices to read. Practically, an upgrade means diffing the main branch, re-reading the manual PDF for config.yaml key changes, and re-running the dataset replay gates to confirm your recorded logs still produce the same estimates. The Makefile gives you the gate: `make test` runs the unit and integration binaries plus the replay gates, `make datasets` runs the real-world dataset replays on their own, and `make test-asan` rebuilds and runs the tests under ASan/UBSan on POSIX. Running those three after a pull is the cheapest way to detect that an upgrade changed behaviour.

On licence: AGPL-3.0 is a copyleft licence with a network-interaction clause. If you modify INSLIB and let users interact with it over a network, the licence's terms reach that deployment in a way that the plain GPL's do not. The repository also contains a KFCore submodule and a magneticmodel directory, and submodules can carry their own licence terms, so check them separately rather than assuming the top-level LICENSE covers everything. This is not legal advice; the point is that the licence choice here is a design constraint you should resolve before writing integration code, not after.

Editorial conclusion

Adopt INSLIB if you are writing embedded or UAV navigation code in C11 and can accept AGPL-3.0, or if you need offline replay of recorded IMU/GNSS logs with a documented config.yaml. Do not adopt it if you need a permissively licensed core to link into closed firmware, or if you expect a versioned release to pin. Before committing, verify the licence obligations against your distribution model, check that your sensor set maps onto the aiding modes the manual documents, and confirm the KFCore submodule initialises, since the Makefile builds against it.

Frequently asked questions

What is the difference between GNSS and INS?

GNSS is an external absolute reference and INSLIB treats it as one aiding measurement among several, subject to receiver latency that the README puts at more than 100 to 200 milliseconds. The inertial side integrates IMU data at high rate and drifts, so INSLIB's Kalman filters fuse the two rather than relying on either alone.

Is INS more accurate than GPS?

The README does not make an accuracy comparison between the two. What it does describe is a fusion design: the filter combines IMU data with GNSS/GPS, barometer, magnetometer, local position, absolute yaw, ground speed and zero-velocity information, and it implements delay compensation because GNSS measurements arrive late.

What is INS used for?

The README lists drones and UAVs, autonomous vehicles, robotics platforms, aerospace, cars, embedded systems requiring precise tracking, and post-processing of recorded flights or driving data. The bundled datasets and replay tools cover the post-processing case directly.

What is INS vs IMU?

An IMU is the sensor set that supplies gyroscope and accelerometer measurements, which INSLIB reads as CSV files with a common t_us timestamp and gyr_frd and acc_frd columns. INS is the resulting navigation solution, which in INSLIB comes from Kalman filters that fuse those IMU measurements with aiding sources such as GNSS, barometer and magnetometer.

Official sources

  1. Issues
  2. jnz/INSLIB on GitHub
  3. License: AGPL-3.0
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/jnz-inslib.svg)](https://hysenlabs.com/projects/jnz-inslib)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/jnz-inslib.svg)](https://hysenlabs.com/projects/jnz-inslib)

Was this useful?