Add FM ANTCAP antenna calibration: HTTP sweep control + EEPROM persistence

Confirmed live tonight that the Si4684's automatic front-end tuning
(FE_VARM/VARB properties) is measurably suboptimal on this board: a
129-value ANTCAP sweep (0-128, AN851 Appendix A) at four different FM
frequencies found antcap=102 beats auto-tune by +6 to +11 dB RSSI and
+3 to +11 dB SNR everywhere tested, consistent with the front-end
network component mismatch already logged in
docs/si4684-rf-investigation-report.md — the board's actual matching
network differs from the AN851 reference network those auto-tune
constants were derived from, so a fixed empirical override
compensates for a gap the chip's own algorithm can't see.

Wiring, bottom to top:
- Si4684Driver::tuneFm() already took an antCap byte; threaded it
  through core::ITuner::tuneFm() and si4684::Si4684Tuner::tuneFm() as
  a new parameter (default 0 = auto, unchanged behaviour for every
  existing caller).
- TunerService::tuneFm() takes an optional override instead: omitted,
  it falls back to a new defaultFmAntCap_ member so every ordinary FM
  tune (seek, scan, station recall, live UI) benefits automatically
  once calibrated, not just calls that pass antcap explicitly.
- POST /api/tuner/tune gained an optional "antcap" field for sweeping
  live without touching the saved calibration.
- POST /api/tuner/calibrate-antenna commits a sweep result: writes it
  to the 24AA025E48 EEPROM's user-writable region (word address 0x00,
  separate from the factory-locked EUI-48 at 0xFA-0xFF) via a new
  Eeprom24aa::writeFmAntCap()/readFmAntCap() pair, and immediately
  updates the live TunerService default — no reboot needed to take
  effect, though HardwareBootstrap::boot() also loads it at every
  boot so it survives power cycles. Same net::AntennaCalibration
  function-pointer bridge pattern as PhoneStreamSink/BleProvisioning,
  so components/net stays free of eeprom24aa headers.

Verified end to end on hardware: swept and found 102, saved it via
the new endpoint, confirmed the live default changed immediately,
then power-cycled and confirmed the boot log reports "FM ANTCAP
calibration loaded: 102" and a subsequent default tune reflects it.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0178rASQ6ZETPMUamvpoR2KR
This commit is contained in:
2026-08-19 02:01:09 +02:00
co-authored by Claude Sonnet 5
parent 45098145cb
commit f610121fd3
22 changed files with 448 additions and 24 deletions
@@ -110,6 +110,7 @@ public:
*
* @dname tuneFm
* @param frequency Validated FM centre frequency.
* @param antCap Forwarded to Si4684Driver::tuneFm (0 = auto).
* @return Ok on success, or a mapped TunerError.
* @pubstate writes fmFrequency_ on success.
*
@@ -117,7 +118,7 @@ public:
* @date 2026-07-06
*/
[[nodiscard]] std::expected<void, core::TunerError> tuneFm(
core::FrequencyKHz frequency) override;
core::FrequencyKHz frequency, std::uint8_t antCap = 0U) override;
/**
* @brief seekFm — seek FM with band wrap.
@@ -225,12 +225,12 @@ std::expected<void, core::TunerError> Si4684Tuner::tuneDab(
}
std::expected<void, core::TunerError> Si4684Tuner::tuneFm(
core::FrequencyKHz frequency)
core::FrequencyKHz frequency, std::uint8_t antCap)
{
if (auto ready = ensureBandLoaded(core::TunerBand::Fm); !ready) {
return ready;
}
if (auto result = driver_.tuneFm(frequency); !result) {
if (auto result = driver_.tuneFm(frequency, antCap); !result) {
return std::unexpected(mapError(result.error()));
}
fmFrequency_ = frequency;