diff --git a/README.md b/README.md index 6cc45d7f..6dedba4a 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,93 @@ +## About this fork (meshcore-tth) + +A fork of [meshcore-dev/MeshCore](https://github.com/meshcore-dev/MeshCore) +that runs the repeaters, sensors and bench boards of a small Czech network on +the CZ mesh (869.432 MHz). Upstream `main` and `dev` are merged automatically +twice a day; everything below is on top of that. Our code is marked +`CUSTOM (TeTeHacko)` in the source. Nothing here changes the wire protocol. + +### Repeater: antispam (all of it off-switchable, none of it upstream) + +* **FairnessLimiter** -- token buckets on forwarded floods, keyed on the 1-byte + ids already in the clear (channel hash, sender hash, advert origin). Port of + Beanow's proposal [#1502](https://github.com/meshcore-dev/MeshCore/pull/1502), + limits re-sized from 30 days of real CZ traffic (`tools/fairness_replay.py`). + `fairness [on|off|grid|cap|refill]`; direct-routed traffic is never limited. +* **Per-origin advert window** -- each node's flood advert forwarded at most + once per N hours (`fairness advert |clear`), ported from + [DutchMeshCore](https://github.com/Dutch-MeshCore/MeshCore)'s AdvertLimiter. + Aimed at nodes that re-advertise every minute. +* **Dry-run** -- `fairness dryrun on` counts every verdict but forwards anyway; + `fairness air` reports the airtime shed (or that would be) per reason. +* **Channel filter** -- on channels whose key the repeater knows (Public and + `#hashtag` channels), stop forwarding messages of listed sender names + (`filter add|del|list`). Names are spoofable: it contains a runaway bot, + it is not security. +* **Channel-hash deny-forward** -- `filter hash add `: keyless, works on + private channels too; reception is unaffected, only forwarding. + +### Repeater: diagnostics and operations + +* Passive analyzer in the console: `nodes` (heard repeaters/rooms, multi-path + join key), `rxlog` (every frame heard, type/path/SNR/RSSI), `pktlog` (raw + frames for an observer feed), big paged replies. +* Channel bot for the analyzer build (`!link`, path questions, per-sender + cooldown, ignore list) -- answers without repeating. +* `dfu [uf2|serial|ota]` (deterministic reboot into the bootloader), `blink`, + `txpwr` with RadioLib's verdict, `i2c` bus scan, TX-failure counters in the + status reply, reset reason printed at boot. +* Text console over BLE next to USB ("dock-quiet": BLE stays dark while USB + holds DTR), persisted connection TX power (`blepwr`), `bleconn`, a + non-blocking BLE TX pump and connection parameters that hold on a weak link. +* `RADIO_DIAG` build flag: `radiostat` / `radiokick` for an SX1262 receiver + that stops receiving. +* DIO1-less operation (`LORA_POLL_IRQ`) for a board with a dead IRQ line. + +### Core fixes + +* TRACE no longer appends its path past the end of the payload; TRACE/PATH + parsing and `Packet::readFrom` are bounds-checked. +* `markSeen` is idempotent again (the send path was eating the dedup window). +* `calcMaxPacketMillis` fallback no longer underflows (a node went deaf on it). +* Path-hash width comes from the node's prefs on every TX path, including + `sendZeroHop`; 2-byte path hashes are the default (`PATH_HASH_MODE_DEFAULT`). +* Failed transmits are re-queued with backoff instead of dropped. +* Per-packet RSSI captured at RX; `ContactInfo` zeroed before a partial fill. + +### Power, clock, GPS + +* GPS duty cycle (`gps duty`), also on the T1000-E, which had none; a position + request warms the duty-cycled receiver for next time. +* A node without GPS starts at its build epoch, not in 2024; the clock and a + hardfault record survive a warm reset (`.noinit`); `clkreboot`. +* No blinking LED and slower BLE advertising on solar nodes; battery level as + an icon at the end of the advertised name (opt-in). + +### Sensors and companions + +* `simple_sensor`: telemetry from an external station over UART + (`BudkaLinkSensorManager`, one LPP channel per meter), `sensor read`. +* Companion: `gps duty` persists, key export / PIN gated on an unauthenticated + USB link, bounded build-date copy. KISS modem: off-by-one in the name clamp. + +### Build, CI, tools + +* Version stamping in every nRF52 env (`v1.18.0-tth`, `+` = dirty tree), + base version from the upstream tag. +* `variants/tth_fleet`: our mast envs with an exact, pinned dependency set + (PlatformIO has no lockfile); mast images are built and signed in CI. +* Automatic upstream merge (`.gitea/upstream-sync.sh`), lint gate for + `tools/` (`tools/lint.sh`: ruff, mypy, shfmt, shellcheck, yamllint, actionlint). +* `tools/`: BLE DFU and flashing helpers, bench fleet test, power A/B, RF + window comparison against CoreScope, walk/trip reports, telemetry readers, + node id generator without path-hash collisions -- see `tools/README.md`. +* `hardware/cavity-box`: parametric enclosure for a cavity filter on a mast. + +Our notes on hardware, power and RF live in `docs/` (`rf-hardware.md`, +`power-saving.md`, `mesh-analyzer.md`, `budka-link.md`). + +--- + ## About MeshCore MeshCore is a lightweight, portable C++ library that enables multi-hop packet routing for embedded projects using LoRa and other packet radios. It is designed for developers who want to create resilient, decentralized communication networks that work without the internet.