ADR-110: ESP32-C6 firmware extension (#764)

Closes the firmware-side ADR-110 design at v0.7.0-esp32 after a 38-iter /loop SOTA sprint.

Headline (bench, COM9+COM12 ESP32-C6):
- 99.56% cross-board RX, 104.1 µs smoothed offset stdev (≤100 µs §2.4 target met)
- 3.95× EMA suppression, 1.4 ppm crystal skew preserved

4 firmware releases: v0.6.7 / v0.6.8 / v0.6.9 / v0.7.0-esp32.
42 ADR-110 unit tests, 1761 v2 workspace tests, full Firmware CI + QEMU green.
This commit is contained in:
rUv
2026-05-23 15:34:48 -04:00
committed by GitHub
parent 5d544126ee
commit 00a234eda8
63 changed files with 5864 additions and 63 deletions
@@ -0,0 +1,68 @@
/**
* @file c6_sync_espnow.h
* @brief ESP-NOW based cross-node time-sync — ADR-110 D1 workaround.
*
* After 4 systematic experiments confirmed the 802.15.4 RX path is broken
* in this user-code + IDF v5.4 combination (see WITNESS-LOG-110 §D1), the
* cross-node sync claim was unblocked by switching transport from IEEE
* 802.15.4 to ESP-NOW (WiFi-based peer-to-peer, runs on the same 2.4 GHz
* radio but uses the WiFi MAC layer that ESP-IDF's 802.11 driver fully
* supports).
*
* Trade vs. 802.15.4:
* - Loses the "frees WiFi airtime for CSI" property (uses WiFi for sync)
* - Gains a known-working RX path on every ESP32 family
* - Same API surface (epoch_us, is_valid, is_leader) so call sites that
* used to depend on c6_timesync drop in unchanged
*
* Works on both ESP32-S3 and ESP32-C6 — the cross-node sync becomes a
* cross-target feature, not C6-only.
*/
#pragma once
#ifdef __cplusplus
extern "C" {
#endif
#include "esp_err.h"
#include <stdint.h>
#include <stdbool.h>
/**
* Initialize the ESP-NOW sync module. Must be called AFTER WiFi STA is
* connected (ESP-NOW needs the WiFi driver active).
*
* @return ESP_OK on success.
*/
esp_err_t c6_sync_espnow_init(void);
/**
* Returns the synced wall-clock estimate in microseconds.
* If no leader heard within the timeout, returns the local
* esp_timer_get_time() value unchanged (offset = 0).
*/
uint64_t c6_sync_espnow_get_epoch_us(void);
bool c6_sync_espnow_is_leader(void);
bool c6_sync_espnow_is_valid(void);
int64_t c6_sync_espnow_get_offset_us(void);
/**
* EMA-smoothed offset (α=1/8, ~8-sample effective window at the 10 Hz
* beacon rate). Tracks the ≈1.4 ppm crystal drift between two C6 boards
* (measured in §A0.8) while suppressing the 540 µs per-beacon WiFi-MAC
* jitter. CSI frame timestamps should stamp from this value, not the raw
* offset — `c6_sync_espnow_get_epoch_us()` already does so internally.
*/
int64_t c6_sync_espnow_get_offset_us_smoothed(void);
/* Counters for the witness harness — exposed for tests/diagnostics. */
uint32_t c6_sync_espnow_tx_count(void);
uint32_t c6_sync_espnow_tx_fail(void);
uint32_t c6_sync_espnow_rx_count(void);
uint32_t c6_sync_espnow_rx_magic_match(void);
#ifdef __cplusplus
}
#endif