Commit 22eb9b87 ("Revert 'Merge remote-tracking branch origin/dev...'")
reverted an entire upstream merge to escape a bad merge state, dropping
860 lines across 66 files. Among the collateral never reconciled on a
later re-merge was eb4fa032's token-bucket duty-cycle enforcement — the
mechanism that keeps nodes under a configured airtime budget (and EU
868 MHz nodes under the legally-mandated duty cycle). The fork had fallen
back to fixed per-packet spacing (getAirtimeBudgetFactor reverted to 2.0),
losing the windowed enforcement.
This was never an intentional design choice, so restoring it re-aligns the
fork with upstream and REDUCES the merge-conflict surface: Dispatcher.{h,cpp}
now diverge from upstream by watchdog additions only (77 insertions, 0
deletions) instead of rewriting checkSend()/loop().
Restored from upstream: updateTxBudget/tx_budget_ms/duty_cycle_window_ms/
getRemainingTxBudget/getDutyCycleWindowMs and the windowed budget logic in
Dispatcher; getOutboundTotal() and the 0xFFFFFFFF count-all sentinel in
StaticPoolPacketManager; the getOutboundTotal() call in StatsFormatHelper.
Re-applied the fork's MQTT radio-watchdog on top as pure additions
(#ifdef WITH_MQTT_BRIDGE), keeping formatRadioDiag.
Stored airtime_factor settings keep their meaning: fork's t*factor spacing
and upstream's 1/(1+factor) windowed budget yield the same steady-state
duty cycle; upstream additionally allows short bursts within the window.
Phase 2 (CAD / radio_fem_rxgain, which touch NodePrefs persistence and
per-board FEM wiring) is documented in RESTORE_UPSTREAM_NOTES.md, not done
here. Builds: Heltec_v3 observer + plain repeater. NEEDS ON-DEVICE
duty-cycle validation before merge.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
4.2 KiB
Restoring accidentally-reverted upstream features
Background
On 2026-03-20, commit 22eb9b87 — Revert "Merge remote-tracking branch 'origin/dev' into mqtt-bridge-implementation" — reverted an entire upstream merge to escape a bad merge state, deleting 860 lines across 66 files. That was not intentional feature removal; it wholesale dropped a batch of upstream progress. When upstream was later re-merged, some collateral came back (MicroNMEA claim()/release(), the GAT562 board) but several upstream features were never reconciled and remained missing.
This branch restores them. They are pure upstream code the fork accidentally dropped, so restoring re-aligns the fork with upstream and reduces the future merge-conflict surface rather than adding to it.
Phase 1 — duty-cycle enforcement (done on this branch)
Restored the token-bucket duty-cycle enforcement and its cluster:
src/Dispatcher.{h,cpp}— restored upstream'supdateTxBudget(),tx_budget_ms,duty_cycle_window_ms,getRemainingTxBudget(),getDutyCycleWindowMs(), and the windowedcheckSend()/loop()budget logic. The fork's MQTT radio watchdog was re-applied on top as pure additions (behind#ifdef WITH_MQTT_BRIDGE).src/helpers/StaticPoolPacketManager.{h,cpp}— restoredgetOutboundTotal()and the0xFFFFFFFFcount-all sentinel incountBefore().src/helpers/StatsFormatHelper.h— restored thegetOutboundTotal()call; kept the fork'sformatRadioDiagtemplate.
Net effect: these files now diverge from upstream by watchdog additions only (0 deletions) instead of rewriting upstream's TX logic.
Why this is safe (no reinterpretation of stored settings)
getAirtimeBudgetFactor() changed meaning between fork and upstream, but the resulting
duty cycle is the same formula:
- Fork:
next_tx = t · factor→ duty ≈1/(1+factor) - Upstream:
duty = 1/(1+factor)enforced over a rolling window
So a device's stored airtime_factor (a NodePrefs field, unchanged) keeps its meaning.
The only behavioral difference is upstream enforces it over a 1-hour window (allowing
short bursts) instead of rigid per-packet spacing — a strict improvement, and the
mechanism that keeps EU 868 MHz nodes under the legally-mandated duty cycle.
Must be validated on-device before merge
This touches core TX timing. Confirm on hardware:
- Normal traffic still flows (repeater forwards, observer uplinks).
- Sustained TX is throttled to the configured duty cycle (watch
getairtime/queue stats; verifynext_tx_timespacing under load). - The observer radio watchdog still recovers a stuck radio (
radio_watchdog_minutes).
Phase 2 — CAD and FEM RX gain (NOT done; needs care + device testing)
Still missing at HEAD, also dropped by 22eb9b87, still present upstream:
cad_enabled— hardware Channel Activity Detection (listen-before-talk) before TX. TheDispatcher/Radiointerface (setCADEnabled/getCADEnabled) is restored by Phase 1, so CAD currently stays off by default (unchanged behavior). To make it configurable again, restore:NodePrefs.cad_enabledfield, its CLI get/set, and its persistence inCommonCLI.cpp(loadPrefsInt/savePrefs). Offset care: this branch's/com_prefslayout is carefully managed — addcad_enabledfollowing the same append-and-size-guard pattern used forrx_boosted_gain/flood_max_*, and add a host-side round-trip test (seescratchpad/migtest).- The
MyMesh::getCADEnabled()override returning_prefs.cad_enabled. RadioLibWrappers::setCADEnabled()override so the hardware CAD is actually driven (the fork's wrapper currently doesn't override it).
radio_fem_rxgain— LoRa front-end-module RX gain. RestoreNodePrefs.radio_fem_rxgain- CLI + persistence (same offset care), plus the per-board FEM wiring reverted across
~20
variants/*/target.cppand theheltec_tracker_v2/LoRaFEMControl.{cpp,h}files. This is board-specific and only affects FEM-equipped hardware.
- CLI + persistence (same offset care), plus the per-board FEM wiring reverted across
~20
Phase 2 is lower urgency than duty-cycle enforcement (CAD/FEM are capability gaps, not a compliance regression) and is best done as its own change with per-board hardware testing.