Sensor: Investigate use of magnetometer readings for sensor fusion

[NArmistead]

Version: 2.7.0

Describe the feature you'd like
Magnetometer readings are useful because they give the direction of earth's magnetic field relative to the FC. Since gravity can't be used for compensation during flight, the magnetometer can give us a base to use so we aren't just integrating gyro and accumulating drift.

According to @ETSells, we don't get a simple vector from the mag xyz. The assignee should investigate how to transform our readings into usable data that can be fed to sensor fusion filters.

The magnetometer on the Rev 2 board is the Bosch BMM150.
https://www.bosch-sensortec.com/media/boschsensortec/downloads/datasheets/bst-bmm150-ds001.pdf

Describe alternatives you've considered
N/A

Additional context
Pending state estimation changes are on the integration/state-estims-telemetry branch.

Points of Contact
We don't really have any SMEs on the magnetometer, so whoever does this will become the first.
Driver maintainer - @ETSells
State estimations SME - @NArmistead

[bjornhbengtsson]

Proposed Path Forward Rev0

The active magnetometer path is already:

start_imu_read_IT() → imu_it_handler() → get_imu_it() → sensor_conv_mag() → IMU_CONVERTED.mag_x/y/z

The interrupt sequence reads raw BMM150 X, Y, Z, and RHALL values, sign-extends the packed measurements, and passes them through the Bosch-derived compensation equations to produce magnetic-field values in µT.

Before feeding these values into the attitude filter, I propose the following steps:

1. Validate the compensated output

   • Log raw X/Y/Z, RHALL, compensated X/Y/Z, magnitude, and timestamps.
   • Rotate the assembled flight computer through multiple orientations and verify that the measurements change smoothly and that field magnitude remains reasonably consistent.
   • Check for overflow, invalid values, stale samples, and interference from servos, high-current wiring, radios, and other avionics (as far as possible).

2. Determine the coordinate-frame mapping

   • Verify the BMM150 sensor-axis orientation on the PCB.
   • Verify whether the current attitude quaternion represents a body-to-world or world-to-body rotation.
   • Remap the compensated magnetometer vector into the flight-computer body frame so it follows the same axis convention as the gyroscope and accelerometer.

3. Perform board-level calibration

   • Determine hard-iron offsets caused by permanent magnetic fields.
     (Hard-iron bias is a constant offset in a magnetometer's magnetic field readings. It is caused by nearby permanent magnets, ferrous metals, or electrical components on the same device. This bias permanently distorts compass headings. You fix it by measuring the offset and subtracting it from your sensor data)
   • Determine a soft-iron correction matrix for axis scaling and distortion.
     (Soft-iron calibration is a process used to correct compass or magnetometer errors caused by nearby metals like iron, steel, or nickel. These materials distort the Earth's magnetic field, turning a perfect spherical sensor reading into a distorted oval. The calibration recalculates the data into a sphere, ensuring accurate navigation.)
   • Apply these corrections after Bosch factory compensation and before sensor fusion.
   • These calibrations will likely only be testable with the rest of the PCB for now, yet can be modeled for integration with servos, wiring, powered subsystems, and commonly used metals.

4. Establish a magnetic reference

   • Average valid magnetometer samples while the vehicle is stationary before launch.
   • Normalize the averaged body-frame magnetic vector.
   • Rotate it into the world frame using the initial attitude quaternion and retain it as the expected Earth-field direction.

5. Add gated magnetometer correction

   • Use the current attitude quaternion to predict the magnetic-field direction in the body frame.
   • Compare the predicted direction with the measured direction using a cross product.
   • Use the resulting error as a small proportional correction to the gyro rates before quaternion integration.
   • Skip correction when the magnetic measurement fails magnitude, freshness, interference, or innovation checks.

6. Test incrementally

   • First compare gyro-only attitude against gyro-plus-magnetometer attitude using recorded bench data.
   • Begin with proportional correction only and no integral gyro-bias term.
     (proportional term: corrects the current attitude error.
     integral term: estimates persistent gyro bias over time)
   • Add the correction behind a feature flag and tune it on hardware before considering use during dynamic flight.

A Mahony-style correction appears to be the simplest first implementation because the current state estimator already propagates a quaternion from gyro measurements. The immediate next task should be validating the compensated vector and confirming the sensor-to-body axis mapping before modifying sensor_body_state().

[ETSells]

Proposed Path Forward

The active magnetometer path is already:

start_imu_read_IT() → imu_it_handler() → get_imu_it() → sensor_conv_mag() → IMU_CONVERTED.mag_x/y/z

The interrupt sequence reads raw BMM150 X, Y, Z, and RHALL values, sign-extends the packed measurements, and passes them through the Bosch-derived compensation equations to produce magnetic-field values in µT.

Before feeding these values into the attitude filter, I propose the following steps:

1. Validate the compensated output

   • Log raw X/Y/Z, RHALL, compensated X/Y/Z, magnitude, and timestamps.
   • Rotate the assembled flight computer through multiple orientations and verify that the measurements change smoothly and that field magnitude remains reasonably consistent.
   • Check for overflow, invalid values, stale samples, and interference from servos, high-current wiring, radios, and other avionics (as far as possible).

2. Determine the coordinate-frame mapping

   • Verify the BMM150 sensor-axis orientation on the PCB.
   • Verify whether the current attitude quaternion represents a body-to-world or world-to-body rotation.
   • Remap the compensated magnetometer vector into the flight-computer body frame so it follows the same axis convention as the gyroscope and accelerometer.

3. Perform board-level calibration

   • Determine hard-iron offsets caused by permanent magnetic fields.
     (Hard-iron bias is a constant offset in a magnetometer's magnetic field readings. It is caused by nearby permanent magnets, ferrous metals, or electrical components on the same device. This bias permanently distorts compass headings. You fix it by measuring the offset and subtracting it from your sensor data)
   • Determine a soft-iron correction matrix for axis scaling and distortion.
     (Soft-iron calibration is a process used to correct compass or magnetometer errors caused by nearby metals like iron, steel, or nickel. These materials distort the Earth's magnetic field, turning a perfect spherical sensor reading into a distorted oval. The calibration recalculates the data into a sphere, ensuring accurate navigation.)
   • Apply these corrections after Bosch factory compensation and before sensor fusion.
   • These calibrations will likely only be testable with the rest of the PCB for now, yet can be modeled for integration with servos, wiring, powered subsystems, and commonly used metals.

4. Establish a magnetic reference

   • Average valid magnetometer samples while the vehicle is stationary before launch.
   • Normalize the averaged body-frame magnetic vector.
   • Rotate it into the world frame using the initial attitude quaternion and retain it as the expected Earth-field direction.

5. Add gated magnetometer correction

   • Use the current attitude quaternion to predict the magnetic-field direction in the body frame.
   • Compare the predicted direction with the measured direction using a cross product.
   • Use the resulting error as a small proportional correction to the gyro rates before quaternion integration.
   • Skip correction when the magnetic measurement fails magnitude, freshness, interference, or innovation checks.

6. Test incrementally

   • First compare gyro-only attitude against gyro-plus-magnetometer attitude using recorded bench data.
   • Begin with proportional correction only and no integral gyro-bias term.
     (proportional term: corrects the current attitude error.
     integral term: estimates persistent gyro bias over time)
   • Add the correction behind a feature flag and tune it on hardware before considering use during dynamic flight.

A Mahony-style correction appears to be the simplest first implementation because the current state estimator already propagates a quaternion from gyro measurements. The immediate next task should be validating the compensated vector and confirming the sensor-to-body axis mapping before modifying sensor_body_state().

@bjornhbengtsson

Good idea on all of this EXCEPT lets consider skipping the raw logging step. We did that for years before implementing the conversions, and im reasonably confident we get decent values straight out of the device.

For calibration, I expect this will need to be done on a device-by-device basis? If so, lets look for a one-time-programmable memory region on the H750 where we can store these values. If one doesn't exist, we should consider running the calibration routine once every time flash is fully wiped, and then log those as part of our preset structure with other sensors' per-run offsets.

[bjornhbengtsson]

Thanks, @ETSells.

We’ll skip the full raw-data logging investigation and focus the initial validation on the compensated X/Y/Z vector, field magnitude, interference, and sensor-to-body axis mapping. We can keep the raw values available as a debugging fallback if the compensated output behaves unexpectedly.

I agree that the board-level calibration will likely need to be device-specific. We’ll investigate whether the STM32H750 provides an appropriate one-time-programmable or otherwise protected nonvolatile region for storing the hard-iron and soft-iron calibration coefficients. If not, we’ll look at integrating those values into the existing preset structure and running calibration only when the persistent flash configuration has been fully erased.

[bjornhbengtsson]

Proposed Path Forward Rev1

The active magnetometer path is already:

start_imu_read_IT() → imu_it_handler() → get_imu_it() → sensor_conv_mag() → IMU_CONVERTED.mag_x/y/z

The interrupt sequence reads raw BMM150 X, Y, Z, and RHALL values, sign-extends the packed measurements, and passes them through the Bosch-derived compensation equations to produce magnetic-field values in µT.

Before feeding these values into the attitude filter, I propose the following steps:

1. Validate the compensated output

   • Focus the initial validation on the compensated X/Y/Z values, magnetic-field magnitude, timestamps, and sample freshness rather than repeating the previous raw-data logging investigation.
   • Rotate the assembled flight computer through multiple orientations and verify that the measurements change smoothly and that the field magnitude remains reasonably consistent.
   • Consider collaborating with the mechanical team to create a simplified nonmagnetic multi-axis positioning fixture for repeatable calibration and axis-mapping tests. Examples: (https://www.ideal-aerosmith.com/rate-and-positioning-tables/, https://www.ideal-aerosmith.com/product-category/non-magnetic-rate-and-positioning-tables/)
   • Check for overflow, invalid values, stale samples, and interference from servos, high-current wiring, radios, and other avionics, as far as practical.
   • Keep raw X/Y/Z and RHALL values available as a debugging fallback if the compensated output behaves unexpectedly.

2. Determine the coordinate-frame mapping

   • Verify the BMM150 sensor-axis orientation on the PCB.
   • Verify whether the current attitude quaternion represents a body-to-world or world-to-body rotation.
   • Remap the compensated magnetometer vector into the flight-computer body frame so that it follows the same axis convention as the gyroscope and accelerometer.

3. Perform device-specific board-level calibration

   • Determine the hard-iron bias vector caused by permanent magnetic fields from the individual assembled flight computer.
     (Hard-iron bias is a constant offset in a magnetometer's magnetic field readings. It is caused by nearby permanent magnets, ferrous metals, or electrical components on the same device. This bias permanently distorts compass headings. You fix it by measuring the offset and subtracting it from your sensor data)
   • Determine a soft-iron correction matrix for axis scaling, misalignment, and magnetic-field distortion.
     (Soft-iron calibration is a process used to correct compass or magnetometer errors caused by nearby metals like iron, steel, or nickel. These materials distort the Earth's magnetic field, turning a perfect spherical sensor reading into a distorted oval. The calibration recalculates the data into a sphere, ensuring accurate navigation.)
   • Apply these corrections after the Bosch factory compensation and before sensor fusion.
   • Treat the calibration coefficients as specific to the assembled flight computer and, where significant external magnetic distortion exists, to its installed rocket configuration.
   • Perform calibration with the flight computer assembled in a configuration representative of normal use, including fully assembled PCB, nearby wiring, servos, powered subsystems, and commonly used mounting hardware where practical.
   • Validate the resulting calibration by rotating the assembled flight computer through many attitudes relative to Earth’s magnetic field and confirming that the corrected measurements form an approximately spherical distribution with reasonably consistent field magnitude.

4. Store calibration coefficients persistently

   • Investigate whether the STM32H750 or the existing flight-computer hardware provides an appropriate protected or dedicated nonvolatile storage region for the hard-iron bias vector and soft-iron correction matrix.
   • Consider one-time-programmable storage only if the calibration coefficients are not expected to require later updates.
   • Otherwise, integrate the coefficients into the existing preset or persistent configuration structure alongside other sensor calibration values.
   • Run the calibration routine during initial board setup and again when explicitly requested, when the stored calibration is missing or invalid, or after the persistent configuration has been erased.
   • Include a validity marker, calibration-format version, and checksum so the firmware can detect missing, incompatible, or corrupted calibration data.

5. Establish a magnetic reference

   • Average valid, calibrated magnetometer samples while the vehicle is stationary before launch.
   • Normalize the averaged body-frame magnetic vector.
   • Rotate it into the world frame using the initial attitude quaternion and retain it as the expected local Earth-field direction.

6. Add gated magnetometer correction

   • Use the current attitude quaternion to predict the magnetic-field direction in the body frame.
   • Compare the predicted direction with the measured direction using a cross product.
   • Use the resulting error as a small proportional correction to the gyro rates before quaternion integration.
   • Skip the correction when the magnetic measurement fails magnitude, freshness, interference, or innovation checks.
   • Avoid allowing a temporarily disturbed magnetic field to produce a large or discontinuous attitude correction.

7. Test incrementally

   • First compare gyro-only attitude against gyro-plus-magnetometer attitude using recorded bench data.
   • Begin with proportional correction only and no integral gyro-bias term.
   • Add the correction behind a feature flag and tune it on hardware before considering use during dynamic flight.
   • Verify that disabling or rejecting magnetometer correction causes the estimator to fall back cleanly to the existing gyro-based quaternion propagation.

A Mahony-style correction appears to be the simplest first implementation because the current state estimator already propagates a quaternion from gyro measurements.

The immediate next task should be validating the compensated magnetic-field vector and confirming the sensor-to-body axis mapping. After that, the device-specific calibration procedure and persistent storage method should be established before modifying sensor_body_state().

[ETSells]

1: I don't hate the idea of a jig like that, but we don't have a "mechanical team". we're probably looking for an HPR group or the hardware team.

3/4. we probably want an automated routine to do this for new units or old units that get their offsets wiped. let's consider having a database in SDEC that re-applies the offsets based on the connected device's UID and triggers the calibration routine if the UID doesn't exist yet OR an override is passed to the command. Huge scope for both of these ^^ so maybe a next-release task or future improvement.

5: yep, easy to fold this into our existing calib routines

6: yes, def necessary esp for tests in magnetically noisy environments like the shop. we should also consider using GPS course for fusion when we start to integrate that.

[bjornhbengtsson]

1: By mechanical team, I was speaking generally, but I meant Lucas. He and I have worked on a PCB mount this summer already, so I asked him. We'll see what he says. It would be a great tool to have for both Mag and IMU calibration. So anyone willing to take it on would be great.

3/4: Understood. Do Rev2 and Rev3 use the same magnetometer and the same sensor-axis orientation on the PCB? That may affect whether the same calibration workflow and data format can be shared across both revisions.

5: Nice.

6: Sounds good.

For the immediate scope, We'll continue with validating the compensated vector and confirming the sensor-to-body axis mapping.

[ETSells]

Lucas as in Lucas Bradley?

Maybe, but not necessarily. That wasn't a design parameter. We'll have the converted sensor data use the same axes for consistency but I have no idea about the raw data. The mag is a BMM150 for rev 2 and a BMM350 for rev 3, which is not a direct port and will require new driver work.

[bjornhbengtsson]

Yes Lucas Bradley.

Understood.

[bjornhbengtsson]

Update: Lucas and I met today. He's 3-D printing a gyroscope and making a clamping mechanism for the flight computer rev2 within the gyroscope should be a cool tool that we can continue to develop for testing sensors and the overall ADCS.