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

Software/components/core/include/core/ITuner.hpp

@@ -100,6 +100,14 @@ public:
      *
      * @dname    tuneFm
      * @param    frequency  Validated FM centre frequency.
+     * @param    antCap     Front-end antenna varactor override (0-128).
+     *                      0 = automatic (chip's own FE_VARM/VARB-derived
+     *                      tuning); other values force a specific varactor
+     *                      setting, for antenna calibration sweeps. Chip-
+     *                      specific concept (AN851 Appendix A on the
+     *                      Si4684), exposed here only because ANTCAP has no
+     *                      other reasonable home without duplicating the
+     *                      whole tune path per driver.
      * @return   Ok on success, or WrongBand / TuneFailed / NotBooted.
      * @pubstate writes last tune target in the adapter.
      *
@@ -107,7 +115,7 @@ public:
      * @date     2026-07-06
      */
     [[nodiscard]] virtual std::expected<void, TunerError> tuneFm(
-        FrequencyKHz frequency) = 0;
+        FrequencyKHz frequency, std::uint8_t antCap = 0U) = 0;
 
     /**
      * @brief    seekFm — seek to the next valid FM station.

Software/components/core/include/core/TunerJson.hpp

@@ -41,6 +41,8 @@ struct TunerTuneRequest {
     TunerBand band;              ///< Target band (Dab or Fm).
     std::uint8_t dabFreqIndex;   ///< Band III ensemble index (0–37) when band is Dab.
     std::optional<FrequencyKHz> fmFrequency; ///< FM centre frequency when band is Fm.
+    std::optional<std::uint8_t> antCap; ///< FM antenna varactor override (0–128),
+                                        ///< for calibration sweeps; ignored for Dab.
 };
 
 /**
@@ -239,4 +241,19 @@ struct TunerFmScannedStation {
 [[nodiscard]] std::string serializeTunerFmBandScanJson(
     const std::vector<TunerFmScannedStation>& stations);
 
+/**
+ * @brief    parseAntennaCalibrationJson — validate POST
+ *           /api/tuner/calibrate-antenna body.
+ *
+ * @dname    parseAntennaCalibrationJson
+ * @param    json  Untrusted request body from the HTTP handler.
+ * @return   ANTCAP value (0-128) on success, or a ParseError.
+ * @pubstate none
+ *
+ * @author   Michele Bigi
+ * @date     2026-08-19
+ */
+[[nodiscard]] std::expected<std::uint8_t, ParseError>
+parseAntennaCalibrationJson(std::string_view json);
+
 } // namespace core

Software/components/core/src/TunerJson.cpp

@@ -200,6 +200,10 @@ std::expected<TunerTuneRequest, ParseError> parseTunerTuneJson(
             return std::unexpected(freq.error());
         }
         req.fmFrequency = *freq;
+        unsigned long antCap = 0U;
+        if (extractJsonUint(json, "antcap", antCap) && antCap <= 128U) {
+            req.antCap = static_cast<std::uint8_t>(antCap);
+        }
     } else {
         return std::unexpected(ParseError::InvalidJson);
     }
@@ -336,4 +340,17 @@ std::string serializeTunerFmBandScanJson(
     return out.str();
 }
 
+std::expected<std::uint8_t, ParseError> parseAntennaCalibrationJson(
+    std::string_view json)
+{
+    if (json.find('{') == std::string_view::npos) {
+        return std::unexpected(ParseError::InvalidJson);
+    }
+    unsigned long antCap = 0U;
+    if (!extractJsonUint(json, "antcap", antCap) || antCap > 128U) {
+        return std::unexpected(ParseError::MissingField);
+    }
+    return static_cast<std::uint8_t>(antCap);
+}
+
 } // namespace core

Software/components/core/test/integration_service_test.cpp

@@ -117,7 +117,7 @@ public:
     }
 
     [[nodiscard]] std::expected<void, core::TunerError> tuneFm(
-        core::FrequencyKHz) override
+        core::FrequencyKHz, std::uint8_t) override
     {
         tunedFm = true;
         return {};

Software/components/core/test/station_service_test.cpp

@@ -59,7 +59,7 @@ public:
     }
 
     [[nodiscard]] std::expected<void, core::TunerError> tuneFm(
-        core::FrequencyKHz) override
+        core::FrequencyKHz, std::uint8_t) override
     {
         return {};
     }