# Wiki

Clone wiki# libeknav / Home

## Welcome

Welcome to libeknav, a C++ library for navigational kalman filtering.

### Filter Design

This filter provides a loosely-coupled GPS-INS sensor fusion algorithm. The filter takes high-rate gyroscope and accelerometer measurments and combines them with low-rate GPS position and velocity measurements to obtain a complete attitude, position, and velocity fix. Optionally, the filter may process vector observations from a magnetometer and/or thermopile, which improves the robustness of the filter.

The filter is strictly kinematic. It may safely be used by fixed or rotorwing aircraft, boats, cars, or anything else with the requisite sensors. Its performance rather strongly depends on supplying the filter with frequent, unfiltered GPS velocity updates, at 3Hz or better. In Monte Carlo testing, minimum sensor rates, when augmented with a magnetometer, are:

- 100 Hz state prediction, with accelerometer and gyroscope measurements
- 3 Hz GPS velocity, 10 Hz preferred. GPS VTG sentences are supported, but a full 3D doppler-derived velocity fix is strongly preferred. It is more important to have unfiltered readings than fast readings. A lower GPS measurement rate will reduce the robustness of the filter's initialization while the vehicle is actively spinning.
- 1Hz GPS position
- 25 Hz magnetometer readings, 50 Hz preferred.

Both the North-East-Down (NED) and Earth-Centered, Earth-Fixed (ECEF) reference frames are supported.

### State Variables

The filter estimates the quaternion-valued vehicle attitude, the bias of the three gyroscopes, the position of the vehicle, and its velocity. Even though there are 13 scalars in the state vector, it tracks the orientation covariance in the tangent space of the quaternion, using the euler angle-axis form. Therefore, the covariance matrix is only 12x12.

### Library Design and Prerequisites

The library is ISO C++98, with a few C++11 uses thrown in where it was appropriate. The library makes extensive use of the Eigen C++ library (version 3.x) for all of its linear algebra. Some features of C++ were purposefully avoided to help ensure that the implementation would be sufficiently efficient for realtime use on commodity microcontrollers. The restricted features are exceptions, RTTI, and heap memory allocation. Boost will also be required to build the library.

The user-facing entry points to the library are all in class basic_ins_qkf, defined in ins_qkf.hpp. You will find basic doxycomments for each of the functions defined in this header. An example program that uses the class is also provided in test_ins_qkf.cpp.

The library's build system is woefully primitive at this time, and takes the form of hand-written Makefile. The targets "all" and "clean" are valid. You may also load the project in the Eclipse CDT using the provided project files, but this is not a requirement to build the library.

### Performance

See the Benchmarks page for some performance statistics on both PC hardware and an ARM7TDMI.

### Recommended Reading

- "A Survey of Nonlinear Attitude Estimation Methods", by Crassidis, Markley, and Cheng.
- "Kalman Filtering for Spacecraft Attitude Estimation", by Lefferts, Markley, and Shuster.
- "Attitude Error Representations for Kalman Filtering", by Markley.
- "Kalman Filtering of Spacecraft Attitude and the QUEST Model", by Shuster.
- "Exploiting Quaternions to Support Expressive Interactive Character Motion", PhD thesis by Michael Patrick Johnson. Only read sections 3, 4, and 6. Section 7 is pure garbage. To understand why, read it anyway and then see:
- "Averaging Quaternions" by F. Landis Markley

Updated