Calibrate magnetometer using UKF

Online calibration of the magnetometer sensor using an UKF approach. It is required to redirect the magnetometer measurements to this module before using them in your estimation filters. In order to do that, define the mag id for your filter (for example AHRS_MLKF_MAG_ID for the mlkf ahrs filter) to MAG_CALIB_UKF_ID.

For more information see TRICAL project page (https://www.github.com/sfwa/TRICAL).

Example for airframe file

Add to your firmware section: This example contains all possible configuration options, not all of them are mandatory!

 <module name="mag_calib_ukf">
   <define name="[AHRS/INS]_XXX_MAG_ID" value="MAG_CALIB_UKF_ID" />
 </module>

Module configuration options

Define Options

name: [AHRS/INS]_XXX_MAG_ID value: MAG_CALIB_UKF_ID
Description: Select correct input mag for your estimation filter (AHRS or INS), replace XXX by your filter name as defined in sw/airborne/subssytems/abi_sender_ids.h

Airframe file section

section name: MAG_CALIB_UKF prefix: MAG_CALIB_UKF_
- name NORM value: 1.0f
  Description: Measurement norm of magnetometer
- name NOISE_RMS value: 2e-1f
  Description: Noise RMS of magnetometer
- name ABI_BIND_ID value: ABI_BROADCAST
  Description: Bind to a specific source for input data, broadcast ID by default
- name INITIAL_STATE value: 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0
  Description: Initial state to be used by filter. There is an option to send the state from settings, after which the state will be send through the PAYLOAD_FLOAT message.
- name HOTSTART value: TRUE
  Description: Read calibration on initialization and Write calibration periodically to file (only for Linux-based boards)
- name HOTSTART_SAVE_FILE value: /data/ftp/internal_000/mag_ukf_calib.txt
  Description: Hotstart save file (only for Linux-based boards)
- name VERBOSE value: FALSE
  Description: Enable terminal verbose mode (only for Linux-based boards)

Module functions

Init Functions

These initialization functions are called once on startup.

mag_calib_ukf_init()

Periodic Functions

These functions are called periodically at the specified frequency from the module periodic loop.

mag_calib_hotstart_write()
- Frequency in Hz: 0.25
- Autorun: LOCK
  Periodic function automatically starts after init and can't be stopped.

Files

Header Files

The following headers are automatically included in modules.h

mag_calib_ukf.h

Source Files

modules/calibration/mag_calib_ukf.c
/sw/ext/TRICAL/src/TRICAL.c
/sw/ext/TRICAL/src/filter.c

Raw mag_calib_ukf.xml file:

<!DOCTYPE module SYSTEM "module.dtd">
<module name="mag_calib_ukf" dir="calibration">
  <doc>
    <description>
      Calibrate magnetometer using UKF
      Online calibration of the magnetometer sensor using an UKF approach.
      It is required to redirect the magnetometer measurements to this module before using them in your estimation filters. In order to do that, define the mag id for your filter (for example AHRS_MLKF_MAG_ID for the mlkf ahrs filter) to MAG_CALIB_UKF_ID.
      
      For more information see TRICAL project page (https://www.github.com/sfwa/TRICAL).
    </description>
    <define name="[AHRS/INS]_XXX_MAG_ID" value="MAG_CALIB_UKF_ID" description="Select correct input mag for your estimation filter (AHRS or INS), replace XXX by your filter name as defined in sw/airborne/subssytems/abi_sender_ids.h"/>
    <section name="MAG_CALIB_UKF" prefix="MAG_CALIB_UKF_">
      <define name="NORM" value="1.0f" description="Measurement norm of magnetometer"/>
      <define name="NOISE_RMS" value="2e-1f" description="Noise RMS of magnetometer"/>
      <define name="ABI_BIND_ID" value="ABI_BROADCAST" description="Bind to a specific source for input data, broadcast ID by default"/>
      <define name="INITIAL_STATE" value="0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0" type="float[]" description="Initial state to be used by filter. There is an option to send the state from settings, after which the state will be send through the PAYLOAD_FLOAT message."/>
      <define name="HOTSTART" value="TRUE" description="Read calibration on initialization and Write calibration periodically to file (only for Linux-based boards)"/>
      <define name="HOTSTART_SAVE_FILE" value="/data/ftp/internal_000/mag_ukf_calib.txt" description="Hotstart save file (only for Linux-based boards)"/>
      <define name="VERBOSE" value="FALSE" description="Enable terminal verbose mode (only for Linux-based boards)"/>
  </section>
  </doc>
  <settings>
    <dl_settings>
      <dl_settings NAME="mag calib">
        <dl_setting var="mag_calib_ukf_send_state" min="0" step="1" max="1" shortname="Send UKF state" values="FALSE|TRUE" type="bool" />
        <dl_setting var="mag_calib_ukf_reset_state" min="0" step="1" max="1" shortname="Reset UKF state" values="FALSE|TRUE" type="bool" />
      </dl_settings>
    </dl_settings>
  </settings>
  <header>
    <file name="mag_calib_ukf.h"/>
  </header>
  <init fun="mag_calib_ukf_init()"/>
  <periodic fun="mag_calib_hotstart_write()" freq="0.25"/>
  <makefile>
    <file name="mag_calib_ukf.c"/>
    <include name="$(PAPARAZZI_SRC)/sw/ext/TRICAL/include"/>
    <include name="$(PAPARAZZI_SRC)/sw/ext/TRICAL/src"/>
    <file name="TRICAL.c" dir="$(PAPARAZZI_SRC)/sw/ext/TRICAL/src"/>
    <file name="filter.c" dir="$(PAPARAZZI_SRC)/sw/ext/TRICAL/src"/>
    <define name="NDEBUG"/> <!-- disable assert -->
    <flag name="CFLAGS" value="Wno-unknown-pragmas -Wno-shadow"/> <!-- silence warnings due to TRICAL pragmas -->
  </makefile>
</module>