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
+35 -1
View File
@@ -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.
+5
View File
@@ -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;
+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
+2
View File
@@ -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;