Repeater Firmware v1.16.0.fwdfilter7

📖 Dokumentation / Documentation

🇩🇪 Was diese Firmware kann: Forward-Filter-Handbuch · Flash-Anleitung
🇬🇧 What this firmware does: Forward-filter manual · Flashing guide

Diese Release-Note beschreibt nur die Änderungen dieser Version — die vollständige, aktuelle Funktionsbeschreibung steht in den Handbüchern oben.
These notes only record what changed in this version — the complete, current feature reference is in the manuals above.

---

Bugfix release. Fixes #2 (guard getEstAirtimeFor against getTimeOnAir error codes).

Version string now carries a leading v (#1).

Targets: RAK4631 and Heltec V3 are hardware-tested; SenseCap Solar Node P1 is build-validated only.

Repeater Firmware 1.16.0.fwdfilter6

⚠️ Veraltet / Outdated

Diese Version ist überholt. Bitte die neueste verwenden: repeater-v1.16.0.fwdfilter7
This release is superseded. Please use the latest: repeater-v1.16.0.fwdfilter7

📖 Dokumentation / Documentation

🇩🇪 Was diese Firmware kann: Forward-Filter-Handbuch · Flash-Anleitung
🇬🇧 What this firmware does: Forward-filter manual · Flashing guide

Diese Release-Note beschreibt nur die Änderungen dieser Version — die vollständige, aktuelle Funktionsbeschreibung steht in den Handbüchern oben.
These notes only record what changed in this version — the complete, current feature reference is in the manuals above.

---

🇬🇧 New: airtime reserve for scoped traffic

set fwd.scoped.reserve <0..100> — reserve this % of the TX duty-cycle budget for scoped (region-coded) flood traffic. Under sustained airtime pressure, unscoped floods (no region code) are dropped so that message delivery between correctly-configured repeaters keeps its airtime; scoped floods and direct traffic always pass. Default 0 = off — no behaviour change unless you set it.

Load-adaptive (unscoped passes when the channel is quiet, chokes only under sustained pressure) and purely local — no protocol change; mixed networks and partial adoption are safe.

• get fwd.scoped.reserve · get fwd.scoped.stats (forwarded/dropped counters + airtime saved; since-boot, RAM-only)
• Persisted in /fwd_prefs (TLV tag 0x50)
• HW-validated on RAK4631; live gate + scoped-bypass proven on-air
• Also: hashfilter match/drop refactor + advert-prob docs (no behaviour change)

🇩🇪 Neu: Airtime-Reserve für Scoped-Traffic

set fwd.scoped.reserve <0..100> — reserviert diesen Prozentsatz des TX-Duty-Cycle-Budgets für scoped (region-codierten) Flood-Traffic. Unter anhaltendem Airtime-Druck werden unscoped Floods (ohne Region-Code) verworfen, damit die Nachrichtenzustellung zwischen korrekt konfigurierten Repeatern ihr Airtime behält; scoped Floods und Direct-Traffic laufen immer durch. Default 0 = aus — keine Verhaltensänderung, außer du setzt es.

Lastadaptiv (unscoped läuft bei ruhigem Kanal, drosselt nur unter anhaltendem Druck) und rein lokal — keine Protokolländerung; Mixed-Networks und Teil-Verbreitung sind sicher.

• get fwd.scoped.reserve · get fwd.scoped.stats (Fwd-/Drop-Zähler + gespartes Airtime; since-boot, RAM-only)
• Persistiert in /fwd_prefs (TLV-Tag 0x50)
• HW-validiert auf RAK4631; Gate + Scoped-Bypass live nachgewiesen
• Außerdem: hashfilter Match/Drop-Refactor + Advert-Prob-Doku (keine Verhaltensänderung)

Repeater Firmware 1.16.0.fwdfilter5

⚠️ Veraltet / Outdated

Diese Version ist überholt. Bitte die neueste verwenden: repeater-v1.16.0.fwdfilter7
This release is superseded. Please use the latest: repeater-v1.16.0.fwdfilter7

📖 Dokumentation / Documentation

🇩🇪 Was diese Firmware kann: Forward-Filter-Handbuch · Flash-Anleitung
🇬🇧 What this firmware does: Forward-filter manual · Flashing guide

Diese Release-Note beschreibt nur die Änderungen dieser Version — die vollständige, aktuelle Funktionsbeschreibung steht in den Handbüchern oben.
These notes only record what changed in this version — the complete, current feature reference is in the manuals above.

---

Repeater 1.16.0 fwdfilter5

Adds a new build target to the fwdfilter repeater line. No firmware/behaviour changes to the existing boards — same filter feature set as repeater-1.16.0.fwdfilter4.

New board

• SenseCAP Solar Node P1 (SenseCap_Solar_repeater) — nRF52840 + SX1262, RAK4631-class hardware.
  • ⚠️ BUILD-VALIDATED ONLY — NOT HARDWARE-TESTED. No P1 device was available to verify on real hardware. The forward-filter code is board-agnostic and compiles cleanly (Flash 54.1 % / RAM 13.0 %, emits a BLE-DFU firmware.zip), but treat this binary as untested until validated on an actual P1.

Hardware-tested boards (unchanged)

• RAK4631 (RAK_4631_repeater) — nRF52840 + SX1262
• Heltec V3 (Heltec_v3_repeater) — ESP32 + SX1262

Filter feature set (carried from fwdfilter4)

• Fork-private /fwd_prefs TLV prefs file (no collision with mainline /com_prefs)
• Hash-size forward filter, advert blacklist, last-hop whitelist
• Per-payload flood-hop caps (flood.max.request/.anon.request/.response)
• set/get symmetry across the full fwd.* CLI surface; RF-admin + serial both supported

Built on meshcore/main. Diff vs mainline remains confined to MyMesh.{cpp,h} + FwdPrefs.{h,cpp}; CommonCLI untouched.

Repeater Firmware 1.16.0.fwdfilter4

⚠️ Veraltet / Outdated

Diese Version ist überholt. Bitte die neueste verwenden: repeater-v1.16.0.fwdfilter7
This release is superseded. Please use the latest: repeater-v1.16.0.fwdfilter7

📖 Dokumentation / Documentation

🇩🇪 Was diese Firmware kann: Forward-Filter-Handbuch · Flash-Anleitung
🇬🇧 What this firmware does: Forward-filter manual · Flashing guide

Diese Release-Note beschreibt nur die Änderungen dieser Version — die vollständige, aktuelle Funktionsbeschreibung steht in den Handbüchern oben.
These notes only record what changed in this version — the complete, current feature reference is in the manuals above.

---

Repeater forward filter v4 (1.16.0.fwdfilter4)

🇩🇪 Deutsche Version unten / German version below.

Opt-in, default-OFF net-health forward controls for repeater builds (RAK4631 + Heltec V3), on a clean mainline MeshCore 1.16 base. Behaviour is identical to stock 1.16.0 until a filter is enabled. Three stages — hash-size filter, per-pubkey policy table, last-hop whitelist — plus per-payload flood hop caps.

Changes since fwdfilter3

• Forward-filter prefs moved to their own file (/fwd_prefs). All fwd.* settings now persist to a dedicated, self-describing TLV file instead of the shared /com_prefs blob. /com_prefs tracks mainline byte-for-byte (CommonCLI is untouched), so future mainline merges can never silently misalign radio/region prefs against our fields. Upgrade note: fwd config resets to defaults on first boot of fwdfilter4 — re-add your whitelist/blacklist entries; radio/region prefs are preserved.
• Replanted onto mainline meshcore/main (was an agessaman-based fork). Filter code is identical; only the base and the prefs storage changed.
• New: per-payload flood hop caps (PR meshcore-dev#2797) — see below.
• New: get fwd.hashfilter.prob dedicated getter (set/get symmetry).

Why

1-byte path hashes occupy a 256-value space (the hash is a prefix of the node pub_key), so in large networks they cannot be uniquely attributed and direct-route matching can resolve ambiguously. These opt-in forwarding controls let an operator reduce unattributable relay traffic, steer floods, and encourage migration to multibyte hashes. All controls are scope-independent, default OFF, and available locally and over RF (admin login required).

Forward controls (admin CLI)

Stage 1 — hash-size filter

• set fwd.hashfilter off|advert|all — advert: stop forwarding 1-byte adverts; all: all 1-byte flood/direct traffic. Default off.
• set fwd.hashfilter.prob 0..100 — probability a matched packet is dropped (100 = always; default 100).
• get fwd.hashfilter — reports mode and probability, e.g. > advert prob=75. get fwd.hashfilter.prob (new in v4) reports just the probability.

Stage 2 — per-pubkey policy table (up to 16 entries)

• set fwd.block.add <64-hex-pubkey> [prune|advert|both]
  • prune — drop flood copies whose path traverses this node. Runs before duplicate-suppression, so a copy arriving via another path can still win → path-steering. Reliable at multibyte hash sizes.
  • advert — do not forward adverts originated by this node (exact pubkey match, any hash size).
  • both — both of the above.
• set fwd.block.del <hex-or-prefix> · set fwd.block.clear · get fwd.block (lists entries)

Stage 3 — last-hop whitelist

Only relay a flood if its immediate sender (the last path hop) is allow-listed.

• set fwd.whitelist on|off
• set fwd.whitelist.0hop allow|drop (0-hop floods, default allow)
• set fwd.whitelist.add <64hex> / .del <hex> / .clear
• get fwd.whitelist
• Hook filterRecvFloodPacket (pre-hasSeen, so a whitelisted copy still wins). Exemptions prevent admin lockout: adverts, ANON_REQ, and floods addressed to this node always pass. Last-hop is matched at the packet hash size — pair with fwd.hashfilter all to drop collision-prone 1-byte floods.

Per-payload flood hop caps (new in v4, PR meshcore-dev#2797)

• set/get flood.max.request | flood.max.anon.request | flood.max.response — caps how far flooded REQ / ANON_REQ / RESPONSE packets travel (mis-configured automation traffic). Default 64 (no-op). Keep at 64 on backbone high-sites — lowering them drops RF-admin login traffic.

Validation (hardware, RAK4631)

CLI + persistence 19/19 (incl. reboot survival = /fwd_prefs round-trip), RF forward-drop 4/4 (blacklisted advert dropped over the air), RF-admin 8/8 over the air. Builds clean for RAK4631 (nRF52) and Heltec V3 (ESP32).

Safe deployment

Run these in order. Nothing enforces until step 4 — steps 1-3 only populate and verify, so they are safe to run on a live node.

1. Identify the real backbone neighbours from active relay-adjacency / TRACE — not the on-device neighbour table (that lists nodes you hear, not the ones that actually relay your traffic).
2. With the whitelist still OFF (the default), add each confirmed backbone pubkey — set fwd.whitelist.add <64hex> (repeat per key). This only fills the table; forwarding is unchanged.
3. Verify the table is exactly what you intend: get fwd.whitelist.
4. Only now enable enforcement — hashfilter first, so the whitelist matches at multibyte instead of collision-prone 1-byte: set fwd.hashfilter all, then set fwd.whitelist on. Leave 0hop allow (the default) until you've confirmed the backbone still relays through you.

Remote / masthead caution: fwd.whitelist on stops relaying for any non-whitelisted last hop. Admin login still works (adverts and ANON_REQ are always exempt), but multi-hop paths through this node to nodes beyond it break if the whitelist is wrong. On a node with no backhaul, have a fallback route (local USB/BLE, or a node you can still reach) before step 4. Roll back any time with set fwd.whitelist off and set fwd.hashfilter off.

Assets / flashing

• RAK4631 (nRF52840): .uf2 (double-tap reset → drag-drop onto the UF2 drive) or .zip (adafruit-nrfutil serial DFU / pio run -t upload).
• Heltec V3 (ESP32-S3): -merged.bin (flash at 0x0, e.g. esptool / web flasher) or the app .bin.

---

🇩🇪 Repeater Forward Filter v4 (1.16.0.fwdfilter4) — Deutsch

Opt-in, standardmäßig deaktivierte Forward-Kontrollen für die Netzgesundheit für Repeater-Builds (RAK4631 + Heltec V3), auf einer sauberen Mainline-MeshCore-1.16-Basis. Das Verhalten ist identisch zum Standard-1.16.0, solange kein Filter aktiviert ist. Drei Stufen — Hash-Size-Filter, Pubkey-Policy-Tabelle, Last-Hop-Whitelist — plus Hop-Limits für geflutete Pakete pro Typ.

Änderungen seit fwdfilter3

• Forward-Filter-Einstellungen in eigene Datei ausgelagert (/fwd_prefs). Alle fwd.*-Einstellungen werden jetzt in einer eigenen, selbstbeschreibenden TLV-Datei gespeichert statt im gemeinsamen /com_prefs-Blob. /com_prefs folgt damit Byte-für-Byte der Mainline (CommonCLI bleibt unangetastet), sodass künftige Mainline-Merges die Funk-/Regions-Einstellungen nie mehr unbemerkt gegen unsere Felder verschieben können. Hinweis zum Update: Die Forward-Konfiguration wird beim ersten Start von fwdfilter4 auf Standardwerte zurückgesetzt — Whitelist-/Blacklist-Einträge bitte neu hinzufügen; Funk-/Regions-Einstellungen bleiben erhalten.
• Auf Mainline meshcore/main neu aufgesetzt (vorher ein agessaman-basierter Fork). Der Filter-Code ist identisch; geändert haben sich nur die Basis und die Speicherung der Einstellungen.
• Neu: Hop-Limits für geflutete Pakete pro Typ (PR meshcore-dev#2797) — siehe unten.
• Neu: get fwd.hashfilter.prob als eigener Getter (Symmetrie von set/get).

Hintergrund

1-Byte-Path-Hashes belegen einen 256-Werte-Raum (der Hash ist ein Präfix des Node-Pubkey), daher können sie in großen Netzen nicht eindeutig zugeordnet werden und Direct-Route-Matching kann mehrdeutig auflösen. Diese optionalen Forwarding-Kontrollen erlauben es einem Betreiber, nicht zuordenbaren Relay-Traffic zu reduzieren, Floods zu steuern und die Migration zu Mehrbyte-Hashes zu fördern. Alle Kontrollen sind scope-unabhängig, standardmäßig deaktiviert und lokal sowie über Funk verfügbar (Admin-Login erforderlich).

Forward-Kontrollen (Admin-CLI)

Stufe 1 — Hash-Size-Filter

• set fwd.hashfilter off|advert|all — advert: 1-Byte-Adverts nicht mehr weiterleiten; all: jeglicher 1-Byte-Flood-/Direct-Traffic. Standard off.
• set fwd.hashfilter.prob 0..100 — Wahrscheinlichkeit, mit der ein passendes Paket verworfen wird (100 = immer; Standard 100).
• get fwd.hashfilter — meldet Modus und Wahrscheinlichkeit, z. B. > advert prob=75. get fwd.hashfilter.prob (neu in v4) meldet nur die Wahrscheinlichkeit.

Stufe 2 — Pubkey-Policy-Tabelle (bis zu 16 Einträge)

• set fwd.block.add <64-hex-pubkey> [prune|advert|both]
  • prune — Flood-Kopien verwerfen, deren Pfad diesen Knoten durchläuft. Läuft vor der Duplikat-Unterdrückung, sodass eine über einen anderen Pfad eintreffende Kopie noch gewinnen kann → Pfad-Steuerung. Zuverlässig bei Mehrbyte-Hashgrößen.
  • advert — Adverts dieses Knotens nicht weiterleiten (exakter Pubkey-Vergleich, jede Hashgröße).
  • both — beides.
• set fwd.block.del <hex-oder-präfix> · set fwd.block.clear · get fwd.block (listet Einträge)

Stufe 3 — Last-Hop-Whitelist

Einen Flood nur weiterleiten, wenn sein unmittelbarer Absender (letzter Pfad-Hop) auf der Allowlist steht.

• set fwd.whitelist on|off
• set fwd.whitelist.0hop allow|drop (0-Hop-Floods, St...

Repeater Firmware 1.16.0.fwdfilter3

⚠️ Veraltet / Outdated

Diese Version ist überholt. Bitte die neueste verwenden: repeater-v1.16.0.fwdfilter7
This release is superseded. Please use the latest: repeater-v1.16.0.fwdfilter7

📖 Dokumentation / Documentation

🇩🇪 Was diese Firmware kann: Forward-Filter-Handbuch · Flash-Anleitung
🇬🇧 What this firmware does: Forward-filter manual · Flashing guide

Diese Release-Note beschreibt nur die Änderungen dieser Version — die vollständige, aktuelle Funktionsbeschreibung steht in den Handbüchern oben.
These notes only record what changed in this version — the complete, current feature reference is in the manuals above.

---

Repeater forward filter v3 (1.16.0.fwdfilter3)

Opt-in, default-OFF net-health forward controls for repeater builds (RAK4631 + Heltec V3),
mainline MeshCore 1.16. Stage 1 hash-size filter + Stage 2 per-pubkey policy table + Stage 3
last-hop whitelist.

Changes since fwdfilter2

• Fix: get fwd.whitelist / get fwd.block reply-buffer overflow. The reply handlers capped output
  at 200 bytes, but the admin reply buffer is ~160 bytes — a near-full table queried over RF could
  overflow the stack buffer. Now capped safely; a long list truncates in the display instead of overflowing.
• RF remote-admin of the whitelist verified end-to-end (get/set over the air via the admin CLI).

Stage 3 — last-hop whitelist

Only relay a flood if its immediate sender (last path hop) is allow-listed.

• set fwd.whitelist on|off
• set fwd.whitelist.0hop allow|drop (0-hop floods, default allow)
• set fwd.whitelist.add <64hex> / .del <hex> / .clear
• get fwd.whitelist
• Hook filterRecvFloodPacket (pre-hasSeen). Exemptions prevent admin lockout: adverts, ANON_REQ, and
  floods addressed to this node always pass. Last-hop matched at the packet hash size — pair with
  fwd.hashfilter all to drop collision-prone 1-byte floods.

Stage 1 / Stage 2 (unchanged)

• set fwd.hashfilter off|advert|all + fwd.hashfilter.prob 0..100
• set fwd.block.add <64hex> [prune|advert|both] / .del / .clear

Safe deployment

Populate the list while OFF, then enable: set fwd.hashfilter all → add trusted backbone pubkeys →
verify get fwd.whitelist → set fwd.whitelist on. Keep 0hop allow until the backbone path is confirmed.
All forward controls default OFF; CLI is available locally and over RF (admin login required).

Assets

• RAK_4631_repeater-...uf2 — double-tap reset, copy onto the USB drive.
• Heltec_v3_repeater-...-merged.bin — flash at 0x0.

Repeater Firmware 1.16.0.fwdfilter2

⚠️ Veraltet / Outdated

Diese Version ist überholt. Bitte die neueste verwenden: repeater-v1.16.0.fwdfilter7
This release is superseded. Please use the latest: repeater-v1.16.0.fwdfilter7

📖 Dokumentation / Documentation

🇩🇪 Was diese Firmware kann: Forward-Filter-Handbuch · Flash-Anleitung
🇬🇧 What this firmware does: Forward-filter manual · Flashing guide

Diese Release-Note beschreibt nur die Änderungen dieser Version — die vollständige, aktuelle Funktionsbeschreibung steht in den Handbüchern oben.
These notes only record what changed in this version — the complete, current feature reference is in the manuals above.

---

Repeater forward filter v2 (1.16.0.fwdfilter2)

Opt-in, default-OFF net-health forward controls for repeater builds (RAK4631 + Heltec V3),
on mainline MeshCore 1.16. Adds Stage 3: last-hop whitelist on top of the v1 hash-size filter
and per-pubkey policy table. Repeater builds only; no effect unless explicitly enabled by an admin.

What's in this release

• Stage 1 — hash-size filter (set fwd.hashfilter off|advert|all + fwd.hashfilter.prob 0..100):
  throttle/drop forwarding of collision-prone 1-byte path-hash floods/adverts.
• Stage 2 — per-pubkey policy table (set fwd.block.add <64hex> [prune|advert|both], .del, .clear):
  path-prune flood copies through a node, or drop a node's adverts.
• Stage 3 — last-hop whitelist (NEW): only relay a flood if its immediate sender (last path hop)
  is allow-listed.
  • set fwd.whitelist on|off
  • set fwd.whitelist.0hop allow|drop (0-hop floods, default allow)
  • set fwd.whitelist.add <64hex> / .del <hex> / .clear
  • get fwd.whitelist
  • Hook filterRecvFloodPacket (pre-hasSeen, so a whitelisted copy still wins). Exemptions prevent
    admin lockout: adverts, ANON_REQ, and floods addressed to this node always pass. Last-hop matched
    at the packet hash size — pair with fwd.hashfilter all to drop collision-prone 1-byte floods.

Safe deployment

Populate the list while OFF, then enable: set fwd.hashfilter all → set fwd.whitelist.add <trusted backbone pubkeys>
→ verify get fwd.whitelist → set fwd.whitelist on. This avoids an "on + empty list = drop everything" window.
Keep 0hop allow until the backbone path is confirmed.

Verification

Builds clean (pio run -e RAK_4631_repeater, RAM 14.0% / Flash 63.2%). Stage-3 hardware-verified on a
2-node bench rig: CLI round-trip, persistence across reboot, advert exemption, 0-hop policy, and last-hop
match on live multi-hop traffic. All forward controls default OFF.

Assets

• RAK_4631_repeater-...uf2 — double-tap reset, copy onto the USB drive.
• Heltec_v3_repeater-...-merged.bin — flash at 0x0 (e.g. esptool / web flasher).

Repeater Firmware 1.16.0.fwdfilter1

⚠️ Veraltet / Outdated

Diese Version ist überholt. Bitte die neueste verwenden: repeater-v1.16.0.fwdfilter7
This release is superseded. Please use the latest: repeater-v1.16.0.fwdfilter7

📖 Dokumentation / Documentation

🇩🇪 Was diese Firmware kann: Forward-Filter-Handbuch · Flash-Anleitung
🇬🇧 What this firmware does: Forward-filter manual · Flashing guide

Diese Release-Note beschreibt nur die Änderungen dieser Version — die vollständige, aktuelle Funktionsbeschreibung steht in den Handbüchern oben.
These notes only record what changed in this version — the complete, current feature reference is in the manuals above.

---

MeshCore repeater firmware, base v1.16.0, with an optional, default-off forward filter for
1-byte path-hash traffic. Behaviour is identical to stock 1.16.0 until a filter is enabled.

Why

1-byte path hashes occupy a 256-value space (the hash is a prefix of the node pub_key), so in large
networks they cannot be uniquely attributed and direct-route matching can resolve ambiguously. This
build adds opt-in forwarding controls so an operator can reduce unattributable relay traffic and steer
floods, and encourage migration to multibyte hashes. All controls are scope-independent.

Controls (admin CLI)

Stateless hash-size filter

• set fwd.hashfilter off|advert|all — advert: stop forwarding 1-byte adverts; all: all 1-byte
  flood/direct traffic. Default off.
• set fwd.hashfilter.prob 0..100 — probability a matched packet is dropped (100 = always; default 100).
• get fwd.hashfilter — reports both mode and probability, e.g. > advert prob=75. (There is no
  separate get fwd.hashfilter.prob; this one command shows both.)

Per-pubkey forward policy table (up to 16 entries)

• set fwd.block.add <64-hex-pubkey> [prune|advert|both]
  • prune — drop flood copies whose path traverses this node. Runs before duplicate-suppression, so a
    copy arriving via another path can still win → path-steering. Reliable at multibyte hash sizes.
  • advert — do not forward adverts originated by this node (exact pubkey match, any hash size).
• set fwd.block.del <hex-or-prefix> · set fwd.block.clear · get fwd.block (lists entries)

Boards in this release

• RAK4631 (nRF52840): .uf2 (double-tap reset → drag-drop) or .zip (adafruit-nrfutil serial DFU)
• Heltec V3 (ESP32-S3): -merged.bin (flash at 0x0) or the app .bin

Verification

Filter logic verified on hardware (RAK4631 + Heltec V3): 1-byte adverts dropped / multibyte forwarded,
per-pubkey advert-drop, and path-prune on relayed multibyte floods. A separate _debug build variant
(not shipped here) adds serial drop/prune logging for bench testing.