firmware: rolling-hour duty-cycle guard (0.1% default) with measured justification

This commit is contained in:
Lars Nolden
2026-09-01 11:33:04 +02:00
parent 6633cd6f92
commit cafc9dff26
4 changed files with 105 additions and 3 deletions
+63 -2
View File
@@ -20,6 +20,12 @@
repeater_cfg_t g_cfg = {
.repeat_delay_ms = 50,
// 868.7-869.2 MHz is limited to 0.1 % duty cycle (25 mW e.r.p.) by
// ERC/REC 70-03 annex h1.6, unless LBT+AFA is implemented. A repeater
// that echoes every telegram can exceed this in a dense meter
// environment, so the experiment enforces the budget itself rather than
// relying on traffic being sparse. See docs/STANDARDS_GAPS.md.
.duty_budget_ppm = 1000, // 1000 ppm = 0.1 %
.tx_power_dbm = -9,
.repeat_enabled = true,
#ifdef CONFIG_WMBUS_VERBOSE_DEFAULT
@@ -46,6 +52,45 @@ static uint32_t s_seq;
static struct { uint32_t hash; int64_t ts; } s_dup[DUP_RING];
static int s_dup_idx;
// Rolling-hour TX airtime ledger for the duty-cycle guard. At 0.1 % and
// ~13 ms per repeat the hourly ceiling is ~270 transmissions, so this ring
// cannot overflow within the window.
#define DUTY_RING 384
#define DUTY_WINDOW_US 3600000000LL
static struct { int64_t ts; uint32_t airtime_us; } s_duty[DUTY_RING];
static int s_duty_idx;
static uint64_t duty_used_us(int64_t now)
{
uint64_t sum = 0;
for (int i = 0; i < DUTY_RING; i++) {
if (s_duty[i].airtime_us && now - s_duty[i].ts < DUTY_WINDOW_US) {
sum += s_duty[i].airtime_us;
}
}
return sum;
}
static void duty_record(int64_t now, uint32_t airtime_us)
{
s_duty[s_duty_idx].ts = now;
s_duty[s_duty_idx].airtime_us = airtime_us;
s_duty_idx = (s_duty_idx + 1) % DUTY_RING;
}
// Would transmitting `bytes` now exceed the configured rolling-hour budget?
static bool duty_would_exceed(int64_t now, int bytes, uint64_t *used_out,
uint64_t *budget_out)
{
uint64_t budget_us = (uint64_t)g_cfg.duty_budget_ppm * 3600000000ULL / 1000000ULL;
uint64_t used = duty_used_us(now);
uint32_t want = (uint32_t)(bytes * US_PER_BYTE + 640);
if (used_out) *used_out = used;
if (budget_out) *budget_out = budget_us;
if (g_cfg.duty_budget_ppm == 0) return false;
return (used + want) > budget_us;
}
// ------------------------------------------------------------------ logging
static void print_hex(const uint8_t *d, int n)
@@ -466,6 +511,16 @@ static void handle_rx(int64_t rxdone_ts)
return;
}
uint64_t duty_used = 0, duty_budget = 0;
if (duty_would_exceed(now, total + 2, &duty_used, &duty_budget)) {
g_stats.tx_suppressed_duty++;
LOGJ("\"event\":\"tx_suppressed\",\"reason\":\"duty_cycle\","
"\"hash\":\"%08" PRIx32 "\",\"used_us\":%llu,\"budget_us\":%llu",
hash, (unsigned long long)duty_used,
(unsigned long long)duty_budget);
return;
}
// ---- repeat ----
static uint8_t txbuf[RX_PAYLOAD_LEN + 2];
txbuf[0] = buf[0];
@@ -476,6 +531,7 @@ static void handle_rx(int64_t rxdone_ts)
int64_t t0, t1;
const char *res = do_tx(txbuf, total + 2, &t0, &t1);
if (t1 > t0) duty_record(t0, (uint32_t)(t1 - t0));
remember_dup(hash, esp_timer_get_time());
log_tx(res, hash, total, frame_end_ts, t0, t1, txbuf, total + 2);
@@ -596,13 +652,16 @@ void repeater_print_status(void)
LOGJ("\"event\":\"status\",\"uptime_us\":%lld,"
"\"repeat_delay_ms\":%" PRIu32 ",\"configured_tx_dbm\":%d,"
"\"repeat_enabled\":%s,\"verbose\":%s,\"whitelist_len\":%d,"
"\"preamble_detect_code\":%u,\"reset_reason\":%d",
"\"preamble_detect_code\":%u,\"duty_budget_ppm\":%" PRIu32 ","
"\"duty_used_us\":%llu,\"reset_reason\":%d",
(long long)esp_timer_get_time(),
g_cfg.repeat_delay_ms, (int)g_cfg.tx_power_dbm,
g_cfg.repeat_enabled ? "true" : "false",
g_cfg.verbose ? "true" : "false",
g_cfg.whitelist_len,
sx126x_get_preamble_detect(),
g_cfg.duty_budget_ppm,
(unsigned long long)duty_used_us(esp_timer_get_time()),
(int)esp_reset_reason());
}
@@ -615,6 +674,7 @@ void repeater_print_stats(void)
"\"tx_attempts\":%" PRIu32 ",\"tx_success\":%" PRIu32 ","
"\"tx_timeout\":%" PRIu32 ",\"tx_failures\":%" PRIu32 ","
"\"tx_suppressed_dup\":%" PRIu32 ",\"tx_suppressed_whitelist\":%" PRIu32 ","
"\"tx_suppressed_duty\":%" PRIu32 ","
"\"radio_reinit\":%" PRIu32 ",\"fem_reinit\":%" PRIu32 ","
"\"recoveries\":%" PRIu32 ",\"tx_airtime_us\":%llu,"
"\"tx_duty_cycle_ppm\":%llu",
@@ -623,7 +683,8 @@ void repeater_print_stats(void)
g_stats.rx_not_c1, g_stats.rx_len_invalid, g_stats.rx_bytes,
g_stats.tx_attempts, g_stats.tx_success, g_stats.tx_timeout,
g_stats.tx_failures, g_stats.tx_suppressed_dup,
g_stats.tx_suppressed_whitelist, g_stats.radio_reinit,
g_stats.tx_suppressed_whitelist, g_stats.tx_suppressed_duty,
g_stats.radio_reinit,
g_stats.fem_reinit, g_stats.recoveries,
(unsigned long long)g_stats.tx_airtime_us,
(unsigned long long)(esp_timer_get_time() > 0