Hierarchical region gating via TX duty cycle (simple_repeater)

[khagele]

Implements the proposal in #2747: autonomous, per-repeater gating that sheds inter-region traffic when a repeater's own TX duty cycle is high, so the local cluster keeps working during high-traffic/disruption events without needing admin access.

This is a reference implementation of the proposal, opened to move the discussion to concrete code. Credit to @fizzyfuzzle, whose POC in the issue thread this tracks and generalizes, and to the NL/CZ operators (@LennertVA, @DreitTheDragon, @onnozweers, @titusn) whose feedback shaped the design.

How it works

Reuses the existing RegionMap parent hierarchy and Dispatcher airtime budget. When TX duty cycle exceeds a threshold, regions are gated from the outermost layer inward — wildcard * first, then the broadest named regions — always protecting the innermost cluster. Recovery re-enables regions inside-out once duty cycle falls below threshold − hysteresis, with per-step random jitter to desync recovery across repeaters. Multiple regions on the same hierarchy level gate together; their leaves stay protected.

Design / safety

• Transient overlay: a new non-persisted rt_flags field on RegionEntry is OR'd with config flags in the forward path, so a region save or reboot mid-event can never make a deny permanent.
• Self-healing state: the gate level is re-asserted every check interval, so region edits or a bulk region load commit (which rebuild entries with cleared rt_flags) cannot desync the gate; disabling the feature while gated lifts the gate immediately.
• Idle-safe recovery: Dispatcher::getTxDutyCyclePercent() refreshes the airtime budget before reading, so recovery still fires when traffic (and thus TX) stops.

Config (opt-in, off by default; persisted with upgrade-safe append)

set dc.gate <0|1> · set dc.gate.thresh <1-100> (default 70) · set dc.gate.hyst <0-50> (default 10) · get dc.gate[.thresh|.hyst] · get dc.gate.status (live duty % + gate level).

Gate state is intentionally not added to the region tree dump for now — that format is parsed and round-tripped by deployed apps, so surfacing per-region gate state in "Manage Regions" is left as an open question. Live state is available via get dc.gate.status.

Verification

• Full Heltec_E290_repeater firmware builds & links.
• Native gtest suite (test/test_region_gating/) covering wildcard-first ordering, leaf protection, inside-out recovery, config/runtime separation, same-level regions, and edge cases; native mocks (Arduino.h/Stream.h/SHA256.h) extended so RegionMap builds off-device.

Open questions / out of scope

• Duty-cycle metric uses the existing fixed 1-hour window → strong hysteresis but slow recovery; the window could be made configurable later (override getDutyCycleWindowMs(), mirroring getAirtimeBudgetFactor()).
• On an unbalanced tree, a whole-depth gate can drop a shallow branch's leaf before the deepest branch's; a per-branch "never gate a childless leaf" refinement is a possible follow-up.
• Reserved admin airtime (@titusn) and a flat priority-number model (@onnozweers) are noted as separate follow-ups.
• Only wired into simple_repeater; simple_room_server would be a trivial follow-up.

🤖 Generated with Claude Code

[titusn]

/nitpick: should this not expect all four regions to not be gated and would splitting this test up into multiple tests make it more readable, especially for later debugging if the test ever fails? If this is according to the current coding guidelines, no problem of course. However a basic rule is: a test should contain one expect. Same can be said about the tests below.

[khagele]

Good point, thanks - addressed in 13935ba. The suite is now one-scenario-per-test: each gate level, each recovery transition, and each invariant is its own test, and the baseline/level tests assert the state of every region rather than a subset. I kept a handful of expects per test where they jointly define a single behaviour (e.g. "level 2 gates * and eu, and nothing else"), since a strict one-expect split would obscure that. Failure output still points at the exact region and level that broke.

[khagele]

Pushed 13935ba, which adds a home region exemption to the gating, following a question raised in the Dutch community discussion: should the home region or the innermost layer have the highest priority?

Previously gating protected only the deepest layer of the hierarchy, so a repeater with home set to nl-ge in * > eu > nl > nl-ge > nl-ge-nij would gate its own home region at max level while protecting the deeper nl-ge-nij. Since the home region is an explicit operator statement of which cluster the repeater serves (a better signal than the depth heuristic), it is now never gated, in addition to the always-protected innermost layer. Repeaters without a home region keep the pure depth-based behaviour.

One trade-off worth discussing: if an operator sets home to a broad region (e.g. home = eu), that region stays ungated and load-shedding is largely defeated on that repeater. The depth rule can't be misconfigured that way; the home rule can. Guidance would be "set home to your local cluster region", but if people feel this is too footgun-prone, the exemption could be restricted (e.g. only exempt home if it's within the deepest N layers).

The same commit also restructures the unit tests into one-scenario-per-test cases with complete per-region assertions, and adds coverage for the exemption.

[LennertVA]

One trade-off worth discussing: if an operator sets home to a broad region (e.g. home = eu), that region stays ungated and load-shedding is largely defeated on that repeater. The depth rule can't be misconfigured that way; the home rule can.

But then the behaviour reverts to the current default behaviour (right?), which I would think is not a problem; it has no active negative effects, only a lack of positive effects. Not getting a bonus because you configured your machines badly is acceptable - there are far worse things that can happen if you screw up other settings.

Nice work! Hope to see this in stable release soon.

[khagele]

Can also be tested here: https://mcimages.weebl.me/?commitId=13935ba

[DreitTheDragon]

At this point, wouldn't it be simpler to implement what @onnozweers mentioned in #2747 (comment) ?
It's not complaint, just reminder/suggestion.