From cafc9dff26080e34e5a4aa38b78389fabfc95f45 Mon Sep 17 00:00:00 2001 From: Lars Nolden Date: Tue, 1 Sep 2026 11:33:04 +0200 Subject: [PATCH] firmware: rolling-hour duty-cycle guard (0.1% default) with measured justification --- docs/STANDARDS_GAPS.md | 36 +++++++++++++++++++++- firmware/main/console.c | 5 ++++ firmware/main/repeater.c | 65 ++++++++++++++++++++++++++++++++++++++-- firmware/main/repeater.h | 2 ++ 4 files changed, 105 insertions(+), 3 deletions(-) diff --git a/docs/STANDARDS_GAPS.md b/docs/STANDARDS_GAPS.md index 7782f10..09ccd84 100644 --- a/docs/STANDARDS_GAPS.md +++ b/docs/STANDARDS_GAPS.md @@ -8,7 +8,7 @@ repeater. Known deviations: | 1 | Repeats the raw telegram bit-exact, including hop-related fields | EN 13757-5 repeaters must manage the hop counter / C-field semantics so telegrams are not repeated endlessly | | 2 | Fixed development repeat delay 20-200 ms (default 50 ms) | OMS repeaters use randomized delays in the seconds range to avoid collisions | | 3 | Repeats every CRC-valid C1 telegram (optional dev whitelist) | Real repeaters filter by installation list | -| 4 | No duty-cycle accounting | EU 868.95 MHz band has duty-cycle limits (1% for 868.7-869.2 sub-band per ERC 70-03); a production repeater must budget its TX time | +| 4 | Rolling-hour duty-cycle guard, default 0.1 % (1000 ppm), suppresses repeats over budget and counts them (`tx_suppressed_duty`) | A production repeater needs proper duty-cycle management, or LBT+AFA, plus per-sub-band awareness | | 5 | Duplicate suppression is a 2.5 s hash ring | Standard requires proper duplicate/loop protection semantics | | 6 | No AES, no decryption, payload treated as opaque | OMS security profiles apply to end devices; a transparent repeater may pass ciphertext, but production behavior needs review | | 7 | T1 telegrams are detected (shared 0x543D sync) but dropped | A combined C/T repeater would need 3-of-6 decode/encode | @@ -16,3 +16,37 @@ repeater. Known deviations: None of these shortcuts may be carried into the production Solenos/Gebos gateway without explicit review. + +## Duty cycle — measured, and why it matters + +868.95 MHz falls in the 868.7-869.2 MHz sub-band, which ERC/REC 70-03 +(annex h1.6) limits to 25 mW e.r.p. with **<= 0.1 % duty cycle**, unless the +device implements LBT+AFA. + +Measured on this bench: + +``` +TX airtime per repeat : 10.4-14.6 ms (median 13.4 ms), frame-length dependent +observed repeat rate : ~5-6 repeats/min when repeating every valid telegram +resulting duty cycle : ~0.11-0.13 % +``` + +That is at or slightly above the 0.1 % ceiling — while repeating only the +CRC-valid C1 telegrams audible at a single indoor location. A production +repeater in a denser environment, or one that also handles T-mode, would +exceed the budget substantially. + +Consequences for the production gateway: + +- Duty-cycle budgeting is a first-class requirement, not an afterthought. + Repeating "every telegram we hear" is not a viable policy. +- Either implement LBT+AFA (which lifts the duty-cycle restriction in this + sub-band) or filter by installation list and/or rate-limit per meter. +- Frame length matters: airtime scales with it, so long encrypted telegrams + cost roughly 40 % more budget than short ones. + +The experimental firmware therefore enforces a rolling-hour airtime budget +(`set duty_budget_ppm N`, default 1000 ppm = 0.1 %, 0 disables) purely so +unattended multi-hour runs cannot drift into non-compliance. This guard is +an experiment-safety measure and is NOT the OMS/EN 13757-5 repeater +behaviour a product would need. diff --git a/firmware/main/console.c b/firmware/main/console.c index 35ff31e..8c59a67 100644 --- a/firmware/main/console.c +++ b/firmware/main/console.c @@ -44,6 +44,11 @@ static void handle_set(char *args) } else if (strcmp(key, "repeat_enabled") == 0) { g_cfg.repeat_enabled = (val[0] == '1'); ack("set repeat_enabled", true, NULL); + } else if (strcmp(key, "duty_budget_ppm") == 0) { + long v = strtol(val, NULL, 10); + if (v < 0 || v > 100000) { ack("set", false, "range 0..100000 ppm"); return; } + g_cfg.duty_budget_ppm = (uint32_t)v; + ack("set duty_budget_ppm", true, v == 0 ? "guard disabled" : NULL); } else if (strcmp(key, "preamble_bits") == 0) { long v = strtol(val, NULL, 10); uint8_t code; diff --git a/firmware/main/repeater.c b/firmware/main/repeater.c index f695fc7..58f2536 100644 --- a/firmware/main/repeater.c +++ b/firmware/main/repeater.c @@ -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 diff --git a/firmware/main/repeater.h b/firmware/main/repeater.h index cf4fbc4..0017dbf 100644 --- a/firmware/main/repeater.h +++ b/firmware/main/repeater.h @@ -16,6 +16,7 @@ typedef struct { uint64_t tx_airtime_us; // cumulative, for duty-cycle accounting uint32_t tx_failures; uint32_t tx_suppressed_dup; + uint32_t tx_suppressed_duty; // blocked by the duty-cycle guard uint32_t tx_suppressed_whitelist; uint32_t radio_reinit; uint32_t fem_reinit; @@ -24,6 +25,7 @@ typedef struct { typedef struct { uint32_t repeat_delay_ms; // 20..200 + uint32_t duty_budget_ppm; // rolling-hour TX airtime cap, 0 = disabled int8_t tx_power_dbm; // configured SX1262 level, not radiated power bool repeat_enabled; bool verbose;