diff --git a/FEATURES.md b/FEATURES.md index f552a566..d43d28cf 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -441,6 +441,50 @@ Sequencing: hardware duty-cycle RX and APC are both done and in field test on `feat/power-saving`; see the status block at the top of this entry for what's left (PPK2 current measurement, multi-hop APC gating). +### ✅ Companion repeater + politeness knobs + diagnostics + +On-device repeater for the Solo companion, scoped to the SX1262 boards (Wio +Tracker L1 OLED/e-ink, GAT562 30S). All on `feature/companion-repeater-presets`. + +- **Repeater toggle** (`client_repeat`, Settings › Radio) — the companion relays + flood/direct traffic on its **current** frequency (no dedicated band), still + working as a normal companion. `MyMesh::allowPacketForward` gates it; loop + detection (`isRepeatLooped`, ported from `simple_repeater`) and an advert + flood-depth cap are always applied. Packet pool bumped 16→32 to match the + repeater workload (a too-small pool starved channel/DM reception once relaying + queued retransmits). +- **Politeness knobs** (all opt-in, default off, flood-only — a direct route's + named next hop is never dropped). Shown under Radio only while the repeater is + on: + - **Skip advert** — don't re-flood adverts (highest-volume flood). + - **Max hops** — drop a flood past N hops. + - **Yield** — scale the retransmit delay for *forwarded* floods only + (`getRetransmitDelay`); own sends pass their own delay to `sendFlood`, so the + companion's own traffic is never slowed. Widens the overhear window. + - **Min SNR** — drop a flood copy below a dB threshold (`-128` sentinel = off, + so an upgraded prefs file can't read as "filter at 0 dB"). + - **Suppress dup** — overhear cancel: a received flood whose hash matches a + queued retransmit cancels our copy (`Dispatcher::suppressQueuedDuplicate`, + `wantsOverhearSuppress` hook). MeshCore had no overhear-cancel before — the + unused `removeOutboundByIdx`/`getOutboundByIdx` finally have a caller. Packet + hash ignores the path for non-TRACE, so our copy and the peer's relayed copy + hash equal. Pairs with Yield (longer delay → wider window to hear a peer). +- **Diagnostics screen** (Tools › Diagnostics) — single read-only page: per-type + RX/TX counters (generic `Dispatcher::n_recv_by_type`/`n_sent_by_type`), uptime, + heap + stack (new `DeviceDiag` helper, nRF52 linker-symbol/`sbrk` heap + + FreeRTOS stack high-water), noise floor, RSSI/SNR, pool free, outbound queue, + and **Forwarded** (`Mesh::n_forwarded` — actual retransmits; backed out on + overhear cancel so it reflects what hits the air). Enter opens a confirm popup + to reset the cumulative counters (`resetStats` made virtual; `Mesh` override + also clears `n_forwarded`). +- Prefs persisted behind schema sentinels `0xC0DE000E` (four knobs) then + `0xC0DE000F` (suppress-dup), with stray-byte clamps for upgraders. +- **Open question:** the app-side dedicated-band gate in `CMD_SET_RADIO_PARAMS` + was commented out (not deleted) to match the on-device toggle's any-frequency + behaviour — undecided whether that gate was UX-only or regulatory. +- **Not done:** live two-device mesh verification (A→repeater→C); counters make + it observable but don't replace the field test. + ### SOS broadcast Configurable in Settings › System › SOS: diff --git a/README.md b/README.md index a1b2c96c..a20f5408 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ All firmware files are published on the [releases page](https://github.com/Marek - [Screen Lock](./docs/solo_features/screen_lock/screen_lock.md) — lock the device to prevent accidental keypresses, with a lock screen showing time and sensor data -- [Tools Screen](./docs/solo_features/tools_screen/tools_screen.md) — GPS trail & waypoints, compass, nearby nodes (with ping & navigate), ringtone editor, auto-reply bot, auto-advert +- [Tools Screen](./docs/solo_features/tools_screen/tools_screen.md) — GPS trail & waypoints, compass, nearby nodes (with ping & navigate), ringtone editor, auto-reply bot, auto-advert, diagnostics - **Battery saving (radio)** — two optional, independent toggles under Settings › Radio: - **Pwr save** — hardware duty-cycle receive (SX126x `SetRxDutyCycle`): the radio cycles RX↔sleep on its own and wakes on a preamble, cutting average RX current with only a little added receive latency @@ -97,7 +97,7 @@ Updating to a newer version usually does not require erasing flash unless the re | [Clock Screen](./docs/solo_features/clock_screen/clock_screen.md) | Clock page, date, configurable data fields | | [Settings Screen](./docs/solo_features/settings_screen/settings_screen.md) | All settings sections with values and interactions | | [Screen Lock](./docs/solo_features/screen_lock/screen_lock.md) | Lock/unlock sequence, lock screen, auto-lock | -| [Tools Screen](./docs/solo_features/tools_screen/tools_screen.md) | GPS trail & waypoints, compass, navigation, nearby nodes, ringtone editor, auto-reply bot, auto-advert | +| [Tools Screen](./docs/solo_features/tools_screen/tools_screen.md) | GPS trail & waypoints, compass, navigation, nearby nodes, ringtone editor, auto-reply bot, auto-advert, diagnostics | ### Upstream MeshCore diff --git a/docs/solo_features/settings_screen/settings_screen.md b/docs/solo_features/settings_screen/settings_screen.md index e175d881..516d621a 100644 --- a/docs/solo_features/settings_screen/settings_screen.md +++ b/docs/solo_features/settings_screen/settings_screen.md @@ -65,9 +65,28 @@ Lists all available home screen pages. For each entry: | Setting | Options | Notes | | --------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| TX power | 2–22 dBm | LEFT/RIGHT. With **Auto pwr** on this is the *ceiling* — the radio may transmit lower. | +| TX Pwr | 2–22 dBm | LEFT/RIGHT. With **Auto pwr** on this is the *ceiling* — the radio may transmit lower. | +| Preset | named presets | LEFT/RIGHT cycles community RF presets (region frequency + bandwidth/SF/CR). **Enter** opens a popup to pick one, save the current settings as a named preset, or delete a saved one. Applies frequency, bandwidth, SF and CR together. | +| Freq | chip range | **Enter** opens a digit-by-digit editor: LEFT/RIGHT moves between decimal places, UP/DOWN steps that digit. Bounds come from the radio chip's own validated range, so a value the radio would reject can't be entered. | +| SF | 5–12 | LEFT/RIGHT. Spreading factor. | +| BW | 7.8–500 kHz | LEFT/RIGHT cycles the standard LoRa bandwidths. | +| CR | 5–8 | LEFT/RIGHT. Coding rate (4/5–4/8). | +| Repeater | ON / OFF | When ON the companion also relays mesh traffic on its **current** frequency (no dedicated band needed), while still working as a normal companion. Loop-detection and flood-depth limits are always applied. Forwarding activity is visible in **Tools › Diagnostics**. | + +When **Repeater** is ON, five optional "politeness" sub-items appear below it (all default OFF, so a plain repeater is unaffected). They only filter **flood** traffic — on a direct route this node is the named next hop, so it never drops those. + +| Setting | Options | Notes | +| -------------- | ------------- | -------------------------------------------------------------------------------------------------------------- | +| Skip advert | ON / OFF | Don't re-flood **advert** packets (the highest-volume flood traffic); messages and acks still relay. | +| Max hops | Off / 1–8 | Drop a flood packet once it has already travelled this many hops. | +| Yield | Off / x2–x9 | Scales the retransmit delay for **forwarded** floods only (own sends are unaffected), so a mobile companion defers to better-sited fixed repeaters. Widens the window for **Suppress dup**. | +| Min SNR | Off / −20…10 dB | Drop a flood copy received below this signal-to-noise threshold, so marginal fringe traffic isn't re-flooded. | +| Suppress dup | ON / OFF | If the same flood packet is overheard from another node while still queued to retransmit, cancel our copy — a peer already relayed it. Cuts redundant airtime in dense meshes; pairs with **Yield**. | + +| Setting | Options | Notes | +| --------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Pwr save | ON / OFF | **Battery saver.** Hardware duty-cycle receive: the SX126x cycles RX↔sleep on its own and wakes on a preamble, cutting average RX current. Trades a little receive latency; leave OFF for lowest-latency reception. Requires an SX126x radio (otherwise stays on continuous RX). | -| Auto pwr | ON / OFF | **Adaptive Power Control.** Lowers actual TX power on strong links to save energy, ramping back up — to the **TX power** ceiling — on weak or lost links. Link quality comes from direct-message ACK SNR and, for channel messages (no ACK), from hearing a repeater rebroadcast your packet. The radio page / name bar shows the live power. Default OFF (fixed TX power). | +| Auto pwr | ON / OFF | **Adaptive Power Control.** Lowers actual TX power on strong links to save energy, ramping back up — to the **TX Pwr** ceiling — on weak or lost links. Link quality comes from direct-message ACK SNR and, for channel messages (no ACK), from hearing a repeater rebroadcast your packet. The radio page / name bar shows the live power. Default OFF (fixed TX power). | --- diff --git a/docs/solo_features/tools_screen/tools_screen.md b/docs/solo_features/tools_screen/tools_screen.md index 669a6e2a..ef28899b 100644 --- a/docs/solo_features/tools_screen/tools_screen.md +++ b/docs/solo_features/tools_screen/tools_screen.md @@ -8,7 +8,7 @@ | :-----------------------: | :-----------------------: | | ![](./tls_scr_1_oled.png) | ![](./tls_scr_1_eink.png) | -The Tools screen is a hub for GPS trail recording, nearby node browsing, ringtone editing, auto-reply bot, and auto-advert. Navigate the tool list with **UP/DOWN** and press **Enter** to open a tool. +The Tools screen is a hub for GPS trail recording, nearby node browsing, ringtone editing, auto-reply bot, auto-advert, compass, and device diagnostics. Navigate the tool list with **UP/DOWN** and press **Enter** to open a tool. --- @@ -287,3 +287,29 @@ With **Commands** ON, a DM beginning with `!` is answered with live node data, i Several commands can be combined in one message — `!batt !time !hops` is answered with a single `4.10V | 14:30 | 3 hops` reply (one transmission). A message with no recognised command falls through to the trigger bot. Commands also work on the **monitored channel** (the one selected for channel mode) — anyone there can query the node. Channel replies are broadcast to everyone, so unlike DM commands they respect quiet hours and use the shared per-channel cooldown. DM commands use the per-contact throttle. + +--- + +## Diagnostics + +A single read-only screen of live device and mesh stats, refreshed once a second. On a small OLED the rows scroll with **UP/DOWN**; on a larger e-ink display they all fit at once. + +| Row | Shows | +| ------------ | -------------------------------------------------------------------------------------------------- | +| Uptime | Time since boot (`d hh:mm:ss`) | +| Total rx/tx | All received / transmitted packets, summed across the categories below | +| Msg | Text and group-text packets, `rx/tx` | +| Advert | Advert packets, `rx/tx` | +| Ack/Path | Ack, path-return and trace packets, `rx/tx` | +| Other | Everything else (requests, responses, control, raw, …), `rx/tx` | +| Forwarded | Packets this node actually re-transmitted as a repeater (reflects overhear suppression, if on) | +| Heap free | Free / total heap | +| Stack free | Current task's minimum-ever stack headroom | +| Noise floor | Live radio noise floor (dBm) | +| RSSI/SNR | Signal strength / signal-to-noise of the last received packet | +| Pool free | Free entries in the packet pool | +| Queue | Packets waiting in the outbound queue | + +The packet counters and **Forwarded** are cumulative since boot. Press **Enter** to open a confirm popup that resets them (defaults to *Cancel*); the live readings (noise, RSSI/SNR, pool, queue, uptime) are not affected. **Cancel/Back** returns to the Tools list. + +The counters make the repeater behaviour observable: **Forwarded** confirms the node is actually relaying (not just configured to), and **Pool free** / **Queue** show whether forwarding is exhausting the packet pool. See **Settings › Radio › Repeater** for the relaying options.