Skip to content

SentiNAV External Library

SentiNAV can be integrated into any C++ software application (which includes ROS and ROS2 frameworks) by linking a precompiled sentinav.a external library and including the SentiNAV header files in your application's include/ folder. SentiNAV External Library requires Eigen3 (sudo apt install libeigen3-dev) installed and included in your C++ software enviroment. Pre-compiled versions for x64, aarch64/arm64, and arm32, together with SentiNAV header files, are included in your SentiSystems SharePoint folder sentinav/binaries and sentinav/include/.

Navigation filter instances can be user created on-demand, and it will be the end-user's responsibility to provide the sensor data to the navigation filter instance. This means the sensor data can be pre-processed and filtered in any way the end-user see fit, before the navigation filter is updated. This could e.g be place recognition from a camera, optical flow from a stereo camera rig, or local position measurement from a customary positioning sensor.

The benefit of using SentiNAV in external library mode is complete control of the navigation filter, deciding which sensor data to utilize, and when and how to perform filter updates.

Several different navigation filters can also be created and run in parallell, serving different purposes. One could for instance have one main filter used during normal operation, and one fall-back filter which uses a different set of sensor data input. In case of primary filter failure, the secondary filter can provide it's navigation state in-place of missing navigation data.

Example Initialization

Once SentiNAV is included in your application (see SentiNAV Installation for details), creating a filter can be achieved in the following manner:

#include <sentinav/ins_ecef.hpp>

#include <Eigen/Dense>
#include <Eigen/Geometry>

int main(int argc, char **argv) 
{
    SentiNAV::BiasStatesConfig bias_config{SentiNAV::singleBias};
    SentiNAV::Tuning tuning;
    double imu_rate{100};

    // Specify reference frame
    // GPS coords of 0,0,0 in case of GNSS-denied navigation
    Eigen::Vector3d origin_llh{61.2479, 4.72787, 73.55};
    Eigen::Vector3d imu_lever_arm{0,0,0};
    bool extract_geoid_params = false;
    auto m_ins_ecef = std::make_unique<SentiNAV::InsEcef>(
        bias_config, tuning, imu_lever_arm, extract_geoid_params);

    auto [sec, ns] = SentiNAV::getTimestamp();
    ret = m_ins_ecef->initialize(sec, ns, imu_rate, init_states, origin_llh);
    if (ret != SentiNAV::SENTINAV_OK) {
        std::cout << "INS Failed to initialize ECEF INS";
    }
    return 0;
}

Measurement Input

Measurements from different sensors can be filtered through SentiNAV by using the initialized filter object and available measurement input function calls. One example of such a function call is newPosMeasLLH which is a GNSS position measurement given in the Latitude-Longitude-Height coordinate system. Example code is shown below.

    // Given a GNSSPosLLH Protobuf Msg, gnss_llh_pos, from SentiBoard:
    auto confidence = SentiNAV::UPDATE_INS(m_ins_ecef, newPosMeasLLH, 
                                gnss_llh_pos.header.utc_s(), 
                                gnss_llh_pos.header.utc_ns(), 
                                gnss_llh_pos.llh, gnss_llh_pos.h_acc, 
                                gnss_lever_arm);
    std::cout << "Likelyhood of measurement " 
              << "given internal states: " << confidence << std::endl;

Tip

Each measurement update will return a confidence parameter, which is a measure on how well the measurement itself fits the internal state of the SentiNAV filter. The filter can be configured to disregard unlikely measurement above a user specified (dynamic) threshold.

Available measurement input functions:

  • newPosMeasLLH: New GPS position measurement in LLH coordinate system.
  • newPosMeasECEF : New GPS position in ECEF coordinate frame.
  • newGnssVelMeas: New GNSS velocity measurement.
  • newLocalPosMeas: Position measurement in local reference frame (e.g from place recognition or similar).
  • newHeightMeas : New height measurement in utilized coordinate frame.
  • newAccMeas : New acceleration measurement.
  • newArsCalibMeas : New attitude calibration measurement.
  • newHeadMeas : New heading measurement.
  • newVectorMeas : New relative vector measurement (relative vector between two known points on vehicle)

Filter Updates (State Propogation)

Available filter update functions to propagate filter's internal states

  • updateIns : Propagate filter with IMU data (absolute specific force and absolute angular rate)
  • updateInsDelta: Propagate filter with IMU data using incremental values for force and angular rate
  • updateDopStatus : Update GPS accuracy state
  • updateGnssRfiStatus : Update GPS quality weighting parameter (0 = GNSS-denied)