feat(demag): demag compensation — measure demag time, cut power on demag-past-ZC (PR #2 rebased)

[AlexKlimaj]

⚠️ Status: bench-validated — ship comp-OFF, do NOT enable demag compensation

Bench validation is complete (ARK 4IN1 F051 + Flight Stand 50). Full report:
hwci/DEMAG_BENCH_FINDINGS.md.

• Inertness (comp OFF): PASS. A no-prop A/B against ark-release HEAD shows
  the compiled-in-but-off demag port adds no zero-cross jitter (2.31 % → 2.35 %
  mean, flat max) and no CPU regression.
• Demag compensation (comp ON): NET-HARMFUL — do not enable. With a prop +
  6S, the demag_step_stress snap-steps ran clean with comp off but
  desynced hard with DEMAG_COMP=2: at 100 % throttle the motor collapsed from
  ~30 000 RPM to a mean of ~8 500 (595 bemf-timeout samples vs 0 off). Root
  cause: the F051 demag-edge ISR branch is an ungated/unconfirmed parallel edge
  path, the arm has no stability check (arms through fast accel), and the
  allOff + duty-cut + re-entrant interruptRoutine() response sustains the
  desync.

Demag comp is off by default (eeprom 184/185 default 0xff), so this branch
is safe to merge as the comp-OFF path — adaptive stall timeout + perf v5
telemetry + the review fixes below, all bench-clean. The compensation itself
needs the rework in the report (stability-gate the arm, gate/confirm the demag
edge, soften the response) before it is enabled; DEMAG_COMP=<n> stays a
bench-only experiment until then.

---

Summary

Rebase of the demag-compensation half of draft PR #2 onto ark-release. The original branch predates #14/#19/#21, which rewrote the F051 comparator ISR path it patches (inlined comparator read, RAM-resident hot path, glitch-tolerant confirm loop), so this is a hand re-application as a reviewable commit series rather than a textual rebase. The active demag half (freewheel through the FET channel instead of the body diode) is split out into stacked PR #25 so its hazard profile can be reviewed and bench-gated separately.

Rebased 2026-07-06 onto current ark-release. Since #29 now owns perf struct v4 (the 32-bin PWM-phase histogram) and #30 added the turn-on grid compensation, the demag perf fields were renumbered to struct v5 (offsets 148–154), appended after the histogram; host_cmd stays frozen at 60. Both features coexist; all 244 offline tests pass.

What it does

After each zero-cross (when demag_comp_level is set, throttle > 20%, and the motor is up to speed), interruptRoutine() arms auto_blanking: changeCompInput() then configures the comparator EXTI with reversed polarity, so the first edge seen after commutation is the demag release edge — the moment the freewheel diode stops clamping the floating phase. The new demagEdgeRoutine() (RAM_FUNC) timestamps it: blanking_length = time-since-ZC − waitTime (measured against the snapshotted scheduling delay, see fixes) is the measured demag duration, and the comparator is flipped back to normal polarity to catch the true zero-cross.

If demag runs past half the commutation interval (the ZC is being swallowed), it counts demag_happened, powers off the bridge, cuts duty by 25/50/75% per compensation level, and re-enters interruptRoutine(). Bench-proven inadequate — see the status banner: this response path sustains desync under load rather than recovering from it.

Also included, as a deliberately separable commit (feat(bemf-timeout)): the stall threshold adapts to the commutation rate (average_interval * 4 once zero_crosses > 50, clamped to 45000 — see fixes) instead of the fixed 22.5 ms — revert alone if it misbehaves on aggressive throttle chops.

Fixes to the original PR logic (found during the port + code review)

• demag_happened was uint8_t on non-CAN builds (saturates at 255 — useless for hwci gating); now unconditionally volatile uint32_t.
• The level-3 duty cut was a mislabeled default: case; now an explicit case 3: with a no-cut default so out-of-range values can't apply the harshest cut.
• duty_cycle (volatile) was double-read while computing the cut; now snapshotted once.
• An early/noise edge (time_since_zc <= waitTime) now zeroes both the measurement and the derived active-freewheel time, so a garbage measurement can't persist.
• blanking_length is clamped to average_interval.
• auto_blanking/measurement state is reset on startup, desync, and bemf-timeout paths (via resetDemagState(), cleared before commutate() on start so a stale arm can't set the wrong polarity).
• [review] blanking_length is measured against a snapshotted scheduling delay (demag_wait_ticks), not the next-cycle waitTime that PeriodElapsedCallback recomputes before the demag edge fires.
• [review] Adaptive bemf stall timeout clamped to 45000 — the 16-bit INTERVAL_TIMER (ARR 0xffff) would otherwise make average_interval*4 unreachable at low RPM, disabling stall detection.
• [review] Demag duty cut handed to tenKhzRoutine via a latch/pending flag instead of a direct ISR write raced by the slew write-back.
• [review] Stale comparator EXTI pending cleared before unmask (all ported MCUs) so ring latched while masked can't fire demagEdgeRoutine with a bogus timestamp.
• [review] Makefile flag-stamp so HWCI_PERF/DEMAG_COMP changes force a rebuild (an A/B session could otherwise flash a stale artifact).

Scope & gating

MCU layer ported for f051, g071, g431, l431 (all compile; g431's uint32_t commutation_interval extern fix preserved). A HAS_DEMAG_COMP gate keeps every other MCU family fully inert (verified: SEQURE_4IN1_F421 builds with the feature compiled out). Both eeprom fields (bytes 184/185, in the CAN-block reserved space) default off via 0xff guards. New hot-path code is RAM_FUNC on F051.

hwci integration

• perf struct v5 (append-only after feat(perf): PWM-phase histogram of zero-crossings (v4) — hump mechanism identified #29's v4 histogram, host_cmd frozen at 60): demag_events (offset 148, mirror of demag_happened), blanking_len_last (152), blanking_len_max (154); total 156 bytes. Host decode with full v1–v5 back-compat (used live to decode the v4 ark-release firmware during the inertness A/B), fw_demag_events metric (a new key alongside the host-derived detection, so old baselines stay comparable), report, sim, and tests: 244 passed.
• Bench knob: make ARK_4IN1_F051 HWCI_PERF=1 DEMAG_COMP=2 forces the level at boot without touching the eeprom, so A/B sessions flip the feature by reflashing.

Memory (ARK_4IN1_F051, HWCI_PERF=1 DEMAG_COMP=2)

Region	Used	%age
FLASH	24496 B	89.3%
RAM	7856 B	98.2%

RAM headroom on HWCI builds is thin: the v5 struct now carries #29's 64-byte histogram and the demag block. The next RAM-costing F051 feature (or a comp-ON A/B that also wants the histogram) will need a trade — dropping the phase histogram from the bench build frees the most.

Bench validation — RESULTS (2026-07-06)

Full report and data pointers: hwci/DEMAG_BENCH_FINDINGS.md.

1. Inertness A/B (no prop, 25 V/3 A supply, noprop_smoke_3a) — PASS. vs ark-release HEAD: zero-cross jitter flat (2.31 % → 2.35 % mean, 12.2 % → 12.2 % max), CPU 62 % → 61 %, demag/bemf-timeout 0/0. The auto_blanking branch adds no jitter when off.
2. demag_step_stress A/B (HQ5136 prop + 6S) — comp-ON FAILS. comp-off ran the 90/95/100 % snap-steps clean (0 bemf timeouts, RPM held ~28 650 at 100 %); DEMAG_COMP=2 desynced hard (595 bemf-timeout samples, 3 host desync events, 290 fw_demag_events; step100 RPM collapsed to a mean ~8 500). fw_demag_events did not drop with comp on — it caused the desyncs. See report for the root cause and the rework fix path.
3. efficiency_sweep gate vs baselines/ARK_4IN1_F051_HQ5136.json — not run (blocked on the comp-ON failure; efficiency is moot until the feature works).
4. Adaptive-bemf-timeout — present in both A/B builds and clean with comp off (0 timeouts), so it is not implicated in the comp-ON desync.

🤖 Generated with Claude Code

https://claude.ai/code/session_011pvp2XLcgsviGSVn9PaaP6

[AlexKlimaj]

Bench validation complete on the ARK 4IN1 F051 + Flight Stand 50. Summary (full report: hwci/DEMAG_BENCH_FINDINGS.md, description updated):

• Inertness (comp OFF): PASS — no-prop A/B vs ark-release HEAD, zero added zero-cross jitter (2.31%→2.35% mean), no CPU regression.
• Demag comp (comp ON): net-harmful — do not enable. demag_step_stress with a prop + 6S: comp-off held ~28,650 RPM at 100% throttle with 0 bemf timeouts; DEMAG_COMP=2 collapsed to a mean ~8,500 RPM with 595 bemf-timeout samples. Root cause is the ungated/unconfirmed demag-edge ISR path + no arm stability check + the allOff+cut+re-entrant interruptRoutine() response.

Recommendation: merge as the comp-OFF path (adaptive timeout + perf v5 + review fixes; demag is off by default via eeprom 0xff). The compensation itself needs the rework in the report before it's enabled — best tracked on a follow-up experimental branch.