PX4
[WIP] Magnetometer Calibration algorithm documentation
Motivation
As noted in https://github.com/PX4/PX4-Autopilot/issues/19459, the calibration algorithm in PX4 is sophisticated & amazing, but it isn't well documented and reading the code to understand it is quite challenging (due to it's complexity), this adds a documentation for what Magnetometer calibration actually does.
This came up while discussing whether PX4 includes online soft iron calibration feature, which was hard to figure out by reading the codebase! And only 10+ minutes later, I realized offline soft iron calibration is implemented in this PR: https://github.com/PX4/PX4-Autopilot/pull/15235
Relevant Twitter thread: https://twitter.com/YohanHadji/status/1566075481576931330 Relevant Discord message: https://discord.com/channels/1022170275984457759/1032412576727978084/1084491061935738930
Relevant doc (perhaps): https://www.infineon.com/dgdl/Infineon-AN2272_PSoC_1_Sensing_Magnetic_Compass_with_Tilt_Compensation-ApplicationNotes-v04_00-EN.pdf?fileId=8ac78c8c7cdc391c017d0731b0d05573
TODOs
- [ ] Include diagram about soft iron calibration (how off-diagonal scaling comes into play)
- [ ] Include hard iron calibration diagram (how diagonal scaling affects)
- [ ] Include flowchart of how the calibration data gets applied (with units)
Btw @bresch it seems like this paper implements online 'soft iron' calibration. Any reason why this wasn't implemented, but only the 'hard iron' calibration was adapted in https://github.com/PX4/PX4-Autopilot/pull/18327?
I've moved to draft. MOve it back when you are ready for review.
This is a good topic but as with any content, have a little think about who it is for, and what they will use it for. Then you ask yourself, did this doc help those people - a bit like test driven programming.
If it is developers then they probably would benefit from links to the code which implement the interesting bits. You should also provide cross links from the calibration pages because otherwise this will probably not be very discoverable.
Arguably the people who are most interested in this will already know, but I like to define what is meant by each term - so what is hard/soft iron. How does the calibration differ. What are the impacts of getting it wrong. Etc.
This pull request has been mentioned on Discussion Forum for PX4, Pixhawk, QGroundControl, MAVSDK, MAVLink. There might be relevant details there:
https://discuss.px4.io/t/some-notes-on-everything-that-was-a-pain-in-using-px4/33573/1
