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
2026-08-19 02:01:09 +02:00
parent 45098145cb
commit f610121fd3
22 changed files with 448 additions and 24 deletions
@@ -1,7 +1,7 @@
 idf_component_register(
    SRCS "src/Eeprom24aa.cpp"
    INCLUDE_DIRS "include"
-    REQUIRES core driver esp_driver_i2c
+    REQUIRES core driver esp_driver_i2c freertos
 )

 target_compile_features(${COMPONENT_LIB} PUBLIC cxx_std_23)
@@ -13,27 +13,40 @@
 #pragma once

 #include "core/IDeviceIdentitySource.hpp"
+#include "core/IdentityError.hpp"

 #include "driver/i2c_master.h"

 #include <cstdint>
+#include <expected>
+#include <optional>

 namespace eeprom24aa {

 /**
- * @brief    Eeprom24aa — reads the factory EUI-48 from Microchip 24AA025E48.
+ * @brief    Eeprom24aa — reads the factory EUI-48 from Microchip 24AA025E48;
+ *           also stores one board-specific calibration byte in the chip's
+ *           user-writable region.
 *
 * @dname    Eeprom24aa
 * @return   n/a (type)
 * @pubstate Borrows an existing I2C master bus (shared with ADAU1701). The
- *           EUI-48 lives at word address 0xFA..0xFF per the 24AA025E48
- *           datasheet (DS20001191).
+ *           EUI-48 lives at word address 0xFA..0xFF (read-only, factory
+ *           programmed) per the 24AA025E48 datasheet (DS20001191); the FM
+ *           ANTCAP calibration byte lives at word address 0x00 in the
+ *           remaining user-writable 250 bytes.
 *
 * @author   Michele Bigi
 * @date     2026-07-07
 */
 class Eeprom24aa : public core::IDeviceIdentitySource {
 public:
+    /** Valid FM ANTCAP calibration values are 0-128 (AN649/AN851); any
+     *  stored byte above this, including the EEPROM's blank/erased 0xFF,
+     *  reads back as "never calibrated" — no separate sentinel write
+     *  needed for a fresh chip. */
+    static constexpr std::uint8_t kFmAntCapMax = 128U;
+
    /**
     * @brief    Eeprom24aa — bind to a running I2C master bus and 7-bit addr.
     *
@@ -60,6 +73,38 @@ public:
    [[nodiscard]] std::expected<core::DeviceIdentity, core::IdentityError>
    readDeviceIdentity() override;

+    /**
+     * @brief    readFmAntCap — read the stored FM antenna calibration byte.
+     *
+     * @dname    readFmAntCap
+     * @return   Calibrated ANTCAP (0-kFmAntCapMax) if one was ever saved via
+     *           writeFmAntCap(), nullopt if the byte is blank/out of range,
+     *           or IdentityError on an I2C failure.
+     * @pubstate performs one I2C read of one byte at word address 0x00.
+     *
+     * @author   Michele Bigi
+     * @date     2026-08-19
+     */
+    [[nodiscard]] std::expected<std::optional<std::uint8_t>, core::IdentityError>
+    readFmAntCap();
+
+    /**
+     * @brief    writeFmAntCap — persist an FM antenna calibration value.
+     *
+     * @dname    writeFmAntCap
+     * @param    value  ANTCAP to store, 0-kFmAntCapMax (AN851 Appendix A
+     *                  calibration procedure; found via a sweep, not
+     *                  computed).
+     * @return   Ok on success, or IdentityError::I2cFailed.
+     * @pubstate performs one I2C byte write at word address 0x00, then
+     *           blocks for the chip's write-cycle time before returning.
+     *
+     * @author   Michele Bigi
+     * @date     2026-08-19
+     */
+    [[nodiscard]] std::expected<void, core::IdentityError>
+    writeFmAntCap(std::uint8_t value);
+
 private:
    i2c_master_bus_handle_t bus_;
    std::uint8_t addr7_;
@@ -15,6 +15,8 @@

 #include "driver/i2c_master.h"
 #include "esp_log.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/task.h"

 #include <array>

@@ -25,7 +27,13 @@ namespace {
 constexpr char kTag[] = "Eeprom24aa";
 /** EUI-48 word address per Microchip 24AA025E48 datasheet (DS20001191). */
 constexpr std::uint8_t kEui48WordAddress = 0xFAU;
+/** FM ANTCAP calibration byte, in the chip's user-writable region (anywhere
+ *  below the factory-locked 0xFA-0xFF EUI-48 block). */
+constexpr std::uint8_t kFmAntCapWordAddress = 0x00U;
 constexpr int kI2cTimeoutMs = 100;
+/** DS20001191 §"Page Write"/"Byte Write": max write cycle time after STOP
+ *  before the chip acknowledges further I2C traffic. */
+constexpr int kI2cWriteCycleMs = 5;

 } // namespace

@@ -69,4 +77,75 @@ Eeprom24aa::readDeviceIdentity()
    return core::DeviceIdentity::fromEui48(core::Eui48::fromBytes(payload));
 }

+std::expected<std::optional<std::uint8_t>, core::IdentityError>
+Eeprom24aa::readFmAntCap()
+{
+    if (bus_ == nullptr) {
+        return std::unexpected(core::IdentityError::I2cFailed);
+    }
+
+    i2c_device_config_t devCfg = {};
+    devCfg.dev_addr_length = I2C_ADDR_BIT_LEN_7;
+    devCfg.device_address = addr7_;
+    devCfg.scl_speed_hz = 100000;
+
+    i2c_master_dev_handle_t dev = nullptr;
+    if (i2c_master_bus_add_device(bus_, &devCfg, &dev) != ESP_OK) {
+        ESP_LOGW(kTag, "i2c_master_bus_add_device failed");
+        return std::unexpected(core::IdentityError::I2cFailed);
+    }
+
+    const std::uint8_t wordAddress = kFmAntCapWordAddress;
+    std::uint8_t value = 0xFFU;
+    const esp_err_t err = i2c_master_transmit_receive(
+        dev, &wordAddress, 1U, &value, 1U, kI2cTimeoutMs);
+
+    i2c_master_bus_rm_device(dev);
+
+    if (err != ESP_OK) {
+        ESP_LOGW(kTag, "FM ANTCAP read failed (err=0x%x)",
+                 static_cast<unsigned>(err));
+        return std::unexpected(core::IdentityError::ReadFailed);
+    }
+
+    if (value > kFmAntCapMax) {
+        return std::optional<std::uint8_t>{};
+    }
+    return std::optional<std::uint8_t>{value};
+}
+
+std::expected<void, core::IdentityError>
+Eeprom24aa::writeFmAntCap(std::uint8_t value)
+{
+    if (bus_ == nullptr) {
+        return std::unexpected(core::IdentityError::I2cFailed);
+    }
+
+    i2c_device_config_t devCfg = {};
+    devCfg.dev_addr_length = I2C_ADDR_BIT_LEN_7;
+    devCfg.device_address = addr7_;
+    devCfg.scl_speed_hz = 100000;
+
+    i2c_master_dev_handle_t dev = nullptr;
+    if (i2c_master_bus_add_device(bus_, &devCfg, &dev) != ESP_OK) {
+        ESP_LOGW(kTag, "i2c_master_bus_add_device failed");
+        return std::unexpected(core::IdentityError::I2cFailed);
+    }
+
+    const std::array<std::uint8_t, 2> payload = {kFmAntCapWordAddress, value};
+    const esp_err_t err =
+        i2c_master_transmit(dev, payload.data(), payload.size(), kI2cTimeoutMs);
+
+    i2c_master_bus_rm_device(dev);
+
+    if (err != ESP_OK) {
+        ESP_LOGW(kTag, "FM ANTCAP write failed (err=0x%x)",
+                 static_cast<unsigned>(err));
+        return std::unexpected(core::IdentityError::I2cFailed);
+    }
+
+    vTaskDelay(pdMS_TO_TICKS(kI2cWriteCycleMs));
+    return {};
+}
+
 } // namespace eeprom24aa
@@ -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;