compass: add MAG debug mode for raw magnetometer logging

[Raffi1202]

Problem

Fixes #10758. @and-sh asked for the raw magnetometer data to be saved to the blackbox so the compass can be calibrated with an external tool; @AlexC176 confirmed the need for out-of-application calibration. The magADC fields in the log are written after the magZero/magGain correction and after sensor and board alignment, so on a board with a stored calibration the original sample cannot be recovered from them.

Cause

src/main/sensors/compass.c:493 applies the magZero/magGain correction and compass.c:514-515 apply sensor and board alignment to mag.magADC; src/main/blackbox/blackbox.c:1772 logs that corrected value. mag.dev.magADCRaw is never published, and debugType_e has no compass entry (src/main/build/debug.h:85). Separately, src/main/drivers/compass/compass_mlx90393.c:108 ignores the busReadBuf result and returns true (line 114), so a failed bus read would yield zeros.

Change

Adds DEBUG_MAG at the end of debugType_e, to debugModeNames in cli.c and to debug_modes in settings.yaml, so existing debug numbers do not shift. compassUpdate() writes mag.dev.magADCRaw[X..Z] into debug[0..2] right after the driver read, before calibration and alignment, as DEBUG_ACC does with acc.dev.ADCRaw (acceleration.c:582). mlx90393Read() now returns false when busReadBuf fails, so the existing failure branch in compassUpdate() skips the sample instead of logging zeros (raised by the Qodo review on this PR). Enable with set debug_mode = MAG; the values appear in blackbox debug[0..2] and in the CLI debug command.

Test

Not run on hardware or SITL. Cause verified by reading compass.c:493/514 and blackbox.c:1772 on maintenance-10.x. Fork CI ran only the Settings.md consistency check, on f0dca86: https://github.com/Raffi1202/inav/actions/runs/34532494452 (success). No firmware build has run; the upstream "Build firmware" runs for both commits are waiting for approval (https://github.com/iNavFlight/inav/actions/runs/34619099396).

Flash / RAM

Not measured yet. The upstream firmware CI has not been released for this PR, so no size report exists.

Docs

docs/Blackbox.md lists MAG among the debug modes; docs/Settings.md regenerated from settings.yaml (checked by the docs workflow run above).

[qodo-code-review]

ⓘ Qodo reviews are paused because the subscription is no longer active. Ask your workspace admin to reactivate the subscription to resume reviews. Manage billing

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Add MAG debug mode for raw magnetometer logging

✨ Enhancement 📝 Documentation ⚙️ Configuration changes 🕐 10-20 Minutes

AI Description

• Exposes uncalibrated, unaligned magnetometer axes through the existing debug channels.
• Adds MAG to CLI and generated debug-mode settings without renumbering existing modes.
• Documents raw magnetometer capture for external hard- and soft-iron calibration.

Diagram

graph TD
  A["Mag Sensor"] --> B["Raw XYZ"] --> C{"MAG enabled?"} -->|Yes| D["Debug array"] --> E["Blackbox log"]
  D --> F["CLI debug"]
  B --> G["Calibration"] --> H["Alignment"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Add dedicated blackbox fields

• ➕ Provides explicit magnetometer field names and semantics.
• ➕ Avoids requiring users to reserve the shared debug mode.
• ➖ Changes the blackbox schema and associated tooling.
• ➖ Adds logging and flash overhead outside an opt-in diagnostic workflow.
• ➖ Requires broader compatibility and migration review.

Recommendation: Keep the PR's existing debug-channel approach. It matches the established raw accelerometer pattern, preserves the blackbox format and existing debug-mode numbering, and imposes no cost unless MAG debugging is selected. Dedicated fields would only be preferable if raw magnetometer capture became a permanent, broadly consumed logging requirement.

Files changed (6) +7 / -2

Enhancement (3) +4 / -1

debug.hDefine the MAG debug mode identifier +1/-0

Define the MAG debug mode identifier

• Appends DEBUG_MAG immediately before DEBUG_COUNT, preserving every existing debug mode's numeric value.

src/main/build/debug.h

cli.cExpose MAG in CLI debug mode names +2/-1

Expose MAG in CLI debug mode names

• Adds MAG to the debug mode name array so users can select and inspect the mode through the CLI.

src/main/fc/cli.c

compass.cPublish raw magnetometer axes to debug channels +1/-0

Publish raw magnetometer axes to debug channels

• Writes magADCRaw X, Y, and Z into debug channels 0–2 immediately after a successful sensor read. Capture occurs before zero/gain calibration and sensor or board alignment.

src/main/sensors/compass.c

Documentation (2) +2 / -0

Blackbox.mdDocument MAG blackbox debug logging +1/-0

Document MAG blackbox debug logging

• Adds MAG to the available blackbox debug modes and explains that it records raw, uncalibrated magnetometer samples for external calibration.

docs/Blackbox.md

Settings.mdList MAG as a supported debug mode +1/-0

List MAG as a supported debug mode

• Adds MAG to the generated debug_mode setting value reference.

docs/Settings.md

Other (1) +1 / -1

settings.yamlRegister MAG in the debug mode settings table +1/-1

Register MAG in the debug mode settings table

• Extends the debug_modes settings lookup with MAG, enabling generated configuration handling for the new mode.

src/main/fc/settings.yaml

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Bus faults skew external compass fits ✓ Resolved 🐞 Bug ☼ Reliability

Description

compassUpdate records magADCRaw whenever the compass driver returns true, but mlx90393Read
ignores the bus-read result, parses its zero-initialized buffer, and unconditionally reports
success. When an MLX90393 transaction fails, three artificial zero coordinates reach both the debug
channel and blackbox log as valid samples, contaminating any external ellipsoid fit that consumes
them.

Code

src/main/sensors/compass.c[426]

+        DEBUG_SET(DEBUG_MAG, axis, mag.dev.magADCRaw[axis]);

Evidence

The new logging line publishes every sample accepted by compassUpdate. The MLX90393 implementation
reads into a zero-initialized buffer without checking whether the transaction succeeded and always
returns true, while blackbox copies the resulting debug values directly into its records.

src/main/sensors/compass.c[417-426]
src/main/drivers/compass/compass_mlx90393.c[103-114]
src/main/blackbox/blackbox.c[1821-1823]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new raw magnetometer logger trusts each driver's success result, but `mlx90393Read` reports success after a failed bus transaction and supplies three zero values. Those values are consequently recorded as real measurements and can skew external calibration.
## Fix Focus Areas
- src/main/drivers/compass/compass_mlx90393.c[103-114]
- src/main/sensors/compass.c[417-426]
## Recommended Fix
Check the return value from `busReadBuf` in `mlx90393Read` and return false without replacing `magADCRaw` when the transaction fails. This allows the existing failure branch in `compassUpdate` to skip publishing the invalid sample.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can type 'qodo, fix this' on a finding and the fix lands right on your PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[github-actions]

RAM / Flash usage vs. base commit 76ee415 — commit 99f7a68

Target	Flash Δ	RAM Δ
MATEKF405	+8 B (+0.00%)	±0 B (±0.00%)
MATEKF722	-8 B (-0.00%)	±0 B (±0.00%)
MATEKF765	+24 B (+0.00%)	±0 B (±0.00%)
MATEKH743	+24 B (+0.00%)	±0 B (±0.00%)

See RAM/flash optimization guide for techniques to reduce usage.

[github-actions]

Test firmware build ready — commit 99f7a68

Download firmware for PR #11924

249 targets built. Find your board's .hex file by name on that page (e.g. MATEKF405SE.hex). Files are individually downloadable — no GitHub login required.

Development build for testing only. Use Full Chip Erase when flashing.

[sensei-hacker]

FYI, in case useful: PR #11708 just added MSP2_INAV_MAG_UNALIGNED, an MSP command that reports the compass reading with zero/gain calibration applied but no alignment rotation. It's not the same thing you're adding here (yours is truly raw, pre-calibration, for external calibration tools via blackbox; that one is post-calibration, pre-alignment, for the Configurator's alignment wizard) — but if anyone building external tooling would rather poll over MSP than parse blackbox logs, the plumbing for a similarly-shaped fully-raw MSP message would be a small addition alongside it.

[Raffi1202]

Merged maintenance-10.x in (3623e4b) and put the table fix on top (8c50a4a), so this is mergeable again. The conflicts were the three lists ESC and MAG both append to - debugType_e, debugModeNames, debug_modes - with ESC keeping its upstream position and MAG following it.

8c50a4a is a separate bug and can be split out if you prefer: #11708 added DEBUG_MAG_CALIB to debugType_e (build/debug.h:83) and to debugModeNames (fc/cli.c) but not to the debug_modes table in settings.yaml. set debug_mode = <name> stores the table index, so from index 27 up every name selected the wrong mode - ESC selected DEBUG_TERRAIN_NAV, and DEBUG_ESC had no name at all. This branch's MAG would have landed on DEBUG_ESC for the same reason. All three lists now hold 33 entries, MAG_CALIB at 27, ESC at 31, MAG at 32.

On the MSP point, no overlap: this logs mag.dev.magADCRaw (compass.c:470), the device reading before the magZero/magGain correction. MSP2_INAV_MAG_UNALIGNED returns mag.magADCUnaligned (fc_msp.c:1718), which msp_protocol_v2_inav.h:161 documents as "zero/gain calibration applied but no alignment rotation".

The firmware builds here will stay red until #11968 lands - maintenance-10.x itself has not compiled since #11798.