michele/DigiRadio
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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:
michele
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
Download Patch File Download Diff File Expand all files Collapse all files
Software/components/net/include/net/NetBootstrap.hpp
+3
View File
@@ -87,6 +87,8 @@ public:
* @param ota Firmware OTA service for POST /api/system/ota.
* @param webRadio Streaming config for GET/POST /api/streaming.
* @param phoneStream I2S write-through for PUT /api/stream/phone.
* @param antennaCalibration EEPROM write-through for
* POST /api/tuner/calibrate-antenna.
* @param companionChips Boot flags exposed on GET /api/health.
* @param deviceIdentity EEPROM-derived SSID, hostname, and serial.
* @return NetBootstrap on success, or a NetError.
@@ -103,6 +105,7 @@ public:
ota::OtaService& ota,
webradio::WebRadioService& webRadio,
PhoneStreamSink& phoneStream,
AntennaCalibration& antennaCalibration,
core::CompanionChipStatus companionChips,
const core::DeviceIdentity& deviceIdentity);
Software/components/net/include/net/SetupWebServer.hpp
+23
View File
@@ -85,6 +85,25 @@ struct PhoneStreamSink {
std::size_t frameCount);
};
/**
* @brief AntennaCalibration — plain function pointer over EEPROM-backed
* FM ANTCAP storage, so net/ never includes eeprom24aa headers
* directly; main/ supplies it (HardwareBootstrap owns the I2C
* bus and EEPROM handle).
*
* @dname AntennaCalibration
* @return n/a (type)
* @pubstate Free function with process lifetime; no per-instance state.
*
* @author Michele Bigi
* @date 2026-08-19
*/
struct AntennaCalibration {
/** Persist a new FM ANTCAP calibration value to EEPROM.
* @return false on an I2C failure. */
bool (*save)(std::uint8_t antCap);
};
/**
* @brief HttpRouteContext — dependencies injected into HTTP handlers.
*
@@ -106,6 +125,7 @@ struct HttpRouteContext {
ota::OtaService* ota; ///< Firmware OTA streaming.
webradio::WebRadioService* webRadio; ///< Streaming config REST routes.
PhoneStreamSink* phoneStream; ///< PUT /api/stream/phone I2S write-through.
AntennaCalibration* antennaCalibration; ///< POST /api/tuner/calibrate-antenna.
core::CompanionChipStatus companionChips; ///< Boot flags for /api/health.
core::DeviceIdentity deviceIdentity; ///< EEPROM-derived unit identity.
};
@@ -187,6 +207,8 @@ public:
* @param ota Firmware OTA service for POST /api/system/ota.
* @param webRadio Streaming config for GET/POST /api/streaming.
* @param phoneStream I2S write-through for PUT /api/stream/phone.
* @param antennaCalibration EEPROM write-through for
* POST /api/tuner/calibrate-antenna.
* @param companionChips Boot flags for GET /api/health.
* @param deviceIdentity Unit identity for /api/health serialNumber.
* @return Ok on success, or NetError::HttpServerStartFailed.
@@ -204,6 +226,7 @@ public:
ota::OtaService& ota,
webradio::WebRadioService& webRadio,
PhoneStreamSink& phoneStream,
AntennaCalibration& antennaCalibration,
core::CompanionChipStatus companionChips,
const core::DeviceIdentity& deviceIdentity);
Software/components/net/src/NetBootstrap.cpp
+11 -5
View File
@@ -106,6 +106,7 @@ startSetupMode(core::ISecureStore& store, tuner::TunerService& tuner,
ota::OtaService& ota,
webradio::WebRadioService& webRadio,
PhoneStreamSink& phoneStream,
AntennaCalibration& antennaCalibration,
core::CompanionChipStatus companionChips,
const core::DeviceIdentity& deviceIdentity)
{
@@ -121,7 +122,8 @@ startSetupMode(core::ISecureStore& store, tuner::TunerService& tuner,
if (auto webResult =
webServer.start(store, NetState::SoftApSetup, tuner, audio,
bluetooth, stations, integration, ota, webRadio,
phoneStream, companionChips, deviceIdentity);
phoneStream, antennaCalibration, companionChips,
deviceIdentity);
!webResult) {
return std::unexpected(webResult.error());
}
@@ -168,6 +170,7 @@ startStaMode(core::ISecureStore& store, tuner::TunerService& tuner,
ota::OtaService& ota,
webradio::WebRadioService& webRadio,
PhoneStreamSink& phoneStream,
AntennaCalibration& antennaCalibration,
core::CompanionChipStatus companionChips,
const core::DeviceIdentity& deviceIdentity)
{
@@ -198,7 +201,8 @@ startStaMode(core::ISecureStore& store, tuner::TunerService& tuner,
if (auto webResult =
webServer.start(store, NetState::StaConnected, tuner, audio,
bluetooth, stations, integration, ota, webRadio,
phoneStream, companionChips, deviceIdentity);
phoneStream, antennaCalibration, companionChips,
deviceIdentity);
!webResult) {
return std::unexpected(webResult.error());
}
@@ -227,6 +231,7 @@ NetBootstrap::start(core::ISecureStore& store, tuner::TunerService& tuner,
ota::OtaService& ota,
webradio::WebRadioService& webRadio,
PhoneStreamSink& phoneStream,
AntennaCalibration& antennaCalibration,
core::CompanionChipStatus companionChips,
const core::DeviceIdentity& deviceIdentity)
{
@@ -241,7 +246,8 @@ NetBootstrap::start(core::ISecureStore& store, tuner::TunerService& tuner,
if (store.hasWifiCredentials()) {
auto staResult = startStaMode(store, tuner, audio, bluetooth, stations,
integration, ota, webRadio, phoneStream,
companionChips, deviceIdentity);
antennaCalibration, companionChips,
deviceIdentity);
if (staResult) {
return staResult;
}
@@ -253,8 +259,8 @@ NetBootstrap::start(core::ISecureStore& store, tuner::TunerService& tuner,
}
return startSetupMode(store, tuner, audio, bluetooth, stations, integration,
ota, webRadio, phoneStream, companionChips,
deviceIdentity);
ota, webRadio, phoneStream, antennaCalibration,
companionChips, deviceIdentity);
}
NetBootstrap::NetBootstrap(std::optional<SoftApHost> softAp,
Software/components/net/src/SetupWebServer.cpp
+67 -1
View File
@@ -99,6 +99,7 @@ extern const uint8_t index_html_gz_end[] asm(
.ota = nullptr,
.webRadio = nullptr,
.phoneStream = nullptr,
.antennaCalibration = nullptr,
.companionChips = {},
.deviceIdentity = core::DeviceIdentity::unknown(),
};
@@ -432,7 +433,10 @@ esp_err_t tunerTunePostHandler(httpd_req_t* req)
if (parsed->band == core::TunerBand::Dab) {
result = ctx->tuner->tuneDab(parsed->dabFreqIndex);
} else if (parsed->fmFrequency) {
result = ctx->tuner->tuneFm(*parsed->fmFrequency);
// Omitting antcap uses the board's saved calibration (or hardware
// auto-tune if never calibrated) — only an explicit value in the
// request overrides it, e.g. for a calibration sweep.
result = ctx->tuner->tuneFm(*parsed->fmFrequency, parsed->antCap);
}
if (!result) {
@@ -635,6 +639,58 @@ esp_err_t tunerFullScanPostHandler(httpd_req_t* req)
return httpd_resp_send(req, json.c_str(), json.size());
}
/**
* @brief tunerCalibrateAntennaPostHandler — save the FM ANTCAP found by
* a calibration sweep as the board's permanent default.
*
* @dname tunerCalibrateAntennaPostHandler
* @param req HTTP request handle from esp_http_server.
* @return ESP_OK on success, or an esp_err_t error code.
* @pubstate writes the 24AA025E48 via route context antenna calibration
* bridge, then updates the live tuner default immediately.
*
* @author Michele Bigi
* @date 2026-08-19
*/
esp_err_t tunerCalibrateAntennaPostHandler(httpd_req_t* req)
{
auto* ctx = routeContextFrom(req);
if (ctx == nullptr || ctx->tuner == nullptr
|| ctx->antennaCalibration == nullptr) {
httpd_resp_set_status(req, "503 Service Unavailable");
return httpd_resp_send(req, nullptr, 0);
}
std::array<char, 128> body{};
if (!readRequestBody(req, body)) {
httpd_resp_set_status(req, "400 Bad Request");
return httpd_resp_send(req, nullptr, 0);
}
const auto parsed =
core::parseAntennaCalibrationJson(std::string_view(body.data()));
if (!parsed) {
const std::string json = core::serializeTunerErrorJson("invalid_json");
httpd_resp_set_status(req, "400 Bad Request");
httpd_resp_set_type(req, "application/json");
return httpd_resp_send(req, json.c_str(), json.size());
}
if (!ctx->antennaCalibration->save(*parsed)) {
const std::string json = core::serializeTunerErrorJson("store_failed");
httpd_resp_set_status(req, "500 Internal Server Error");
httpd_resp_set_type(req, "application/json");
return httpd_resp_send(req, json.c_str(), json.size());
}
ctx->tuner->setDefaultFmAntCap(*parsed);
const std::string json =
std::string("{\"status\":\"saved\",\"antcap\":")
+ std::to_string(*parsed) + "}";
httpd_resp_set_type(req, "application/json");
return httpd_resp_send(req, json.c_str(), json.size());
}
/**
* @brief audioProfileGetHandler — serve GET /api/audio/profile JSON.
*
@@ -1865,6 +1921,7 @@ std::expected<void, NetError> SetupWebServer::start(
ota::OtaService& ota,
webradio::WebRadioService& webRadio,
PhoneStreamSink& phoneStream,
AntennaCalibration& antennaCalibration,
core::CompanionChipStatus companionChips,
const core::DeviceIdentity& deviceIdentity)
{
@@ -1889,6 +1946,7 @@ std::expected<void, NetError> SetupWebServer::start(
routeContext.ota = &ota;
routeContext.webRadio = &webRadio;
routeContext.phoneStream = &phoneStream;
routeContext.antennaCalibration = &antennaCalibration;
routeContext.companionChips = companionChips;
routeContext.deviceIdentity = deviceIdentity;
@@ -2001,6 +2059,14 @@ std::expected<void, NetError> SetupWebServer::start(
};
httpd_register_uri_handler(server_, &tunerFullScanUri);
const httpd_uri_t tunerCalibrateAntennaUri = {
.uri = "/api/tuner/calibrate-antenna",
.method = HTTP_POST,
.handler = tunerCalibrateAntennaPostHandler,
.user_ctx = routeCtx,
};
httpd_register_uri_handler(server_, &tunerCalibrateAntennaUri);
const httpd_uri_t audioProfileGetUri = {
.uri = "/api/audio/profile",
.method = HTTP_GET,