dandri/HaloKeymind
1
0
Fork 0
mirror of https://github.com/mikecarper/MeshCore.git synced 2026-09-17 02:54:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

RXPS: use measured preamble-symbol capture model

Browse Source
This commit is contained in:
Jarosław Domański
2026-09-05 00:02:13 +02:00
parent fde20d37d0
commit 6bbd34a296
15 changed files with 1090 additions and 189 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli_commands.md
+95 -31
View File
@@ -280,13 +280,16 @@ This document provides an overview of CLI commands that can be sent to MeshCore
#### View or change RX duty-cycle power saving
**Usage:**
- `get radio.rxps`
- `get radio.rxps.rfrx_disabled`
- `get rxps.wd`
- `set radio.rxps.rfrx_disabled <state>`
- `set radio.rxps off`
- `set radio.rxps on`
- `set radio.rxps conservative`
- `set radio.rxps balanced`
- `set radio.rxps max`
- `set radio.rxps max preamble <16|32>`
- `set radio.rxps overdrive`
- `set radio.rxps overdrive preamble <16|32>`
- `set radio.rxps riskyWorkingMax`
- `set radio.rxps riskyWorkingMax preamble <16|32>`
- `set radio.rxps <1-10>`
- `set radio.rxps level <1-10>`
- `set radio.rxps level <1-10> preamble <16|32>`
@@ -294,16 +297,14 @@ This document provides an overview of CLI commands that can be sent to MeshCore
**Parameters:**
- `rx_us`, `sleep_us`: Receive and sleep durations in microseconds (`1000`-`30000000`).
- `level`: A power-saving level from `1` (most conservative) to `10` (least power saving).
- `level`: `1`-`8`, expressed as **symbols of the sender's preamble the receiver catches** - how much of it lands inside an open RX window. Level `1` catches the most (15 symbols on the 16-symbol profile, 24 on the 32-symbol one) and costs the most power; level `8` catches 8 on both profiles and costs the least. Eight is the floor because that is what an LR11x0 needs to latch, so a level means the same geometry on either radio family. `9` (`overdrive`) and `10` (`riskyWorkingMax`) go below that floor and outside the datasheet timer condition; see below.
- `preamble`: LoRa preamble length in symbols; `16` or `32`.
- `state`: `on` or `off`.
**Notes:**
- `get rxps.wd` reports the RXPS watchdog's soft and hard recovery counts.
- `radio.rxps.rfrx_disabled` is a runtime-only diagnostic setting and resets to `off` after reboot.
- Its default `off` state keeps the host-controlled SX1262 receive path enabled during RX duty-cycle mode. Setting it to `on` reproduces the old missing-RF_RX behavior and can significantly reduce receive sensitivity, making remote commands harder to receive.
- `radio.rxps.rfrx_disabled` is supported only on SX1262 targets with a host-controlled RX enable pin.
- `on` and `conservative` select level `1` with a 16-symbol preamble; `balanced` selects level `5` with a 16-symbol preamble.
- `on` and `conservative` select level `3` (catches 13 symbols), `balanced` selects level `6` (catches 10), and `max` selects level `8` (catches 8); all three use a 16-symbol preamble.
- Levels `1`-`8` satisfy the SX1261/2 duty-cycle timer condition; `max` is the top of that range. `overdrive` (level `9`) and `riskyWorkingMax` (level `10`) trade that guarantee for lower measured duty cycles; see the fuller entries below.
- Like the other named profiles, `max`, `overdrive`, and `riskyWorkingMax` assume a 16-symbol sender preamble. At SF5-SF8 that is markedly less economical than the equivalent numeric level, which follows the SF onto the 32-symbol profile. Use the explicit `preamble 32` form to select the 32-symbol profile.
- Level-based settings automatically recalculate their timings when the spreading factor or bandwidth changes. Custom `<rx_us> <sleep_us>` timings remain fixed.
- The selected mode is applied immediately, persisted, and restored after reboot.
@@ -346,13 +347,19 @@ This document provides an overview of CLI commands that can be sent to MeshCore
- `set radio.rxps on`
- `set radio.rxps conservative`
- `set radio.rxps balanced`
- `set radio.rxps max`
- `set radio.rxps max preamble <symbols>`
- `set radio.rxps overdrive`
- `set radio.rxps overdrive preamble <symbols>`
- `set radio.rxps riskyWorkingMax`
- `set radio.rxps riskyWorkingMax preamble <symbols>`
- `set radio.rxps <level>`
- `set radio.rxps level <level>`
- `set radio.rxps level <level> preamble <symbols>`
- `set radio.rxps <rx_us> <sleep_us>`
**Parameters:**
- `level`: `1-10`; higher levels use shorter receive windows and longer sleep windows.
- `level`: `1-10`. Levels `1`-`8` are the guarded scale and are expressed in **symbols of the sender's preamble caught**: 15, 14, 13, 12, 11, 10, 9, 8 on the 16-symbol profile and 24, 20, 16, 14, 12, 10, 9, 8 on the 32-symbol one. Level `8` is named `max`. `9` (`overdrive`) and `10` (`riskyWorkingMax`) drop below the 8-symbol floor and outside the datasheet timer condition; only `10` is expected to lose packets.
- `symbols`: `16` or `32` preamble symbols.
- `rx_us`: receive-window duration in microseconds, `1000-30000000`.
- `sleep_us`: radio sleep duration in microseconds, `1000-30000000`.
@@ -360,23 +367,97 @@ This document provides an overview of CLI commands that can be sent to MeshCore
**Repeater default:** `off`
**Profiles:**
- `on` and `conservative`: level 1 with a 16-symbol preamble.
- `balanced`: level 5 with a 16-symbol preamble.
- `on` and `conservative`: level 3, catches 13 symbols, with a 16-symbol preamble.
- `balanced`: level 6, catches 10 symbols, with a 16-symbol preamble.
- `max`: level 8, catches the 8-symbol floor, the cheapest guarded setting that still works on both radio families, with a 16-symbol preamble.
- `overdrive`: level 9, with a 16-symbol preamble. Outside the datasheet timer condition; see below.
- `riskyWorkingMax`: level 10, with a 16-symbol preamble. The measured edge of what still works, and the only setting here that is expected to drop packets; see below.
- Every named profile assumes a 16-symbol sender, which is the worst case a mixed network can present. At SF5-SF8 this is less economical than a numeric level, because a 32-symbol profile cannot catch a 16-symbol preamble. `max preamble 32`, `overdrive preamble 32`, and `riskyWorkingMax preamble 32` select the 32-symbol profile explicitly.
- A numeric level, or `level <level>`, automatically uses 32 preamble symbols for SF5-SF8 and 16 for SF9-SF12.
- `level <level> preamble <symbols>` explicitly fixes the preamble used in the calculation.
- Explicit `rx_us sleep_us` values select manual timing (`level=0`).
Level-based settings are recalculated after SF or bandwidth changes. Manual timings are not recalculated. Settings are persisted in `/prefs.json`. Companion firmware does not expose this text command and applies its fixed level 5 / preamble 16 profile at startup and after radio-parameter changes.
**How the timings are derived:**
```text
sleep = (preamble - caught symbols) symbols
listen = whatever the duty-cycle timer condition needs at that sleep
```
The capture cost - 6 symbols on SX126x, 8 on LR11x0, both measured on the bench -
no longer enters this arithmetic; it is only a validation, since a level that
catches fewer symbols than the radio needs to latch is rejected. That is why the
same level produces the same periods on either family. The listen window is not
a free parameter:
it follows from the timer condition below. Three constraints are applied on top,
all of them measured rather than assumed:
- **Sleep floor.** The driver subtracts the sleep-to-RX transition (`tcxoDelay + 1000 us`) from the requested sleep before writing the register. Below that the arm call fails outright; just above it the SX1262 arms with no error and then detects no preambles at all. Levels whose own sleep falls under the floor are raised to it, and collapse onto the same timing as a result. If even the floor would break preamble capture - a short symbol leaves no room between the two - the level is rejected with `ERROR: RXPS does not fit this SF/BW with preamble <n>` rather than silently falling back to continuous RX.
- **Timer condition.** Semtech requires `Tpreamble + Theader <= 2 * rxPeriod + sleepPeriod`, because the radio restarts its receive timer with that value when it detects a preamble. Guarded levels `1`-`8` satisfy it; `overdrive` and `riskyWorkingMax` deliberately do not. When it is broken, an SX1262 usually still receives normally, but isolated `rxPeriod` register values one tick wide lose most of the packets they have already latched, and nothing in the value predicts which. LR11x0 has always enforced an equivalent rule in its driver.
- **Register granularity.** Both radio families program the duty cycle in 15.625 us ticks and truncate on the way in, so the reported periods are snapped to whole ticks and are the ones the hardware actually runs.
**`overdrive` (level 9):**
`overdrive` is the geometry that predates the timer condition being enforced: an
8-symbol receive window with the sleep at the capture limit. It breaks the
condition deliberately, in exchange for the lowest duty cycle available. The
name is meant in the overclocking sense - measured to work, outside the vendor's
stated envelope - rather than as a warning that it drops packets. It does not.
| Assumed sender preamble | `overdrive` | Level 10 | Saving |
|---|---|---|---|
| 32 symbols | 23.5% | 27.5% (SF8) - 33.4% (SF6) | 4.0 - 9.9 pp |
| 16 symbols | 44.4% | 49.7% (SF8) - 56.6% (SF6) | 5.3 - 12.2 pp |
Both figures are dimensionless in symbols, so they hold at any spreading factor.
The sleep floor and tick rounding still apply, and the receive window is moved
one tick if it lands on a register value measured to misbehave. That list of
values is not exhaustive, which is the whole of the residual risk: levels
`1`-`8` are safe on any register value, `overdrive` is safe on every value that
has been measured. It is a text-CLI setting only and is never selected by
companion firmware.
**`riskyWorkingMax` (level 10):**
The end of the road: the profile extrapolated past `overdrive` until packet
delivery started to fall, then stepped back to the last setting that still held. The
sleep goes past the capture budget on purpose, so a preamble sometimes arrives
while the radio is asleep - which is exactly why delivery falls. Measured at SF8
with an LR1110 receiver witnessing every transmission on the same link:
| Assumed sender preamble | Delivery | Sleep share | vs `overdrive` |
|---|---|---|---|
| 32 symbols | 196/200 (98.0%) | 79.3% | +2.8 pp sleep, -2.0 pp delivery |
| 16 symbols | 197/200 (98.5%) | 56.4% | +0.9 pp sleep, -1.0 pp delivery |
`overdrive` on the same link and in the same run read 200/200 and 199/200. So
this level buys a little sleep and pays for it in packets, which is the whole
trade and the reason the name is what it is. The command is case-sensitive and
has no short form. On a mesh that relies on retries the cost may be acceptable;
on a link that matters it is not.
Level-based settings are recalculated after SF or bandwidth changes. Manual timings are not recalculated. Settings are persisted in `/prefs.json`. Companion firmware does not expose this text command and applies its fixed `balanced` profile (level 6, catches 10 symbols, preamble 16) at startup and after radio-parameter changes.
`set radio.rxps` echoes the timings it applied, so the periods the radio really
runs are visible immediately:
```text
OK - on,level=9(overdrive),preamble=16,rx=32782,sleep=40954
OK - on,level=10,preamble=32,rx=40375,sleep=106500
OK - on,level=5,preamble=16,rx=49485,sleep=22750
```
`get radio.rxps` reports:
```text
desired=<on|off>,effective=<armed|continuous>,supported=<yes|no>,
level=<0-10>,preamble=<0|16|32>,rx=<us>,sleep=<us>,
level=<0-10>[(overdrive)|(riskyWorkingMax)][,catch=<symbols>],preamble=<0|16|32>,rx=<us>,sleep=<us>,
err=<RadioLib error>,fail=<count>[,erx=<us>,eslp=<us>]
```
- `desired` is the saved user setting.
- `level=9(overdrive)` and `level=10(riskyWorkingMax)` mark profiles that run outside the datasheet timer condition. Any other level is guarded.
- `catch` is how many symbols of a sender's preamble the node actually catches, and appears only for guarded levels. It is not simply the number the level asks for: the sleep floor can shorten the sleep further, and at SF6 with a 16-symbol profile that collapses levels 1-6 onto the same point. Reporting the requested value there would be a lie, so the effective one is reported instead.
- `effective=armed` means receive duty-cycle is active.
- `effective=continuous` means RXPS is disabled, unsupported, or the last arm attempt fell back to continuous RX.
- `fail` counts failed arm operations; each one falls back to continuous RX. `clear stats` resets both this total and the consecutive-failure backoff, granting three fresh arm attempts.
@@ -387,23 +468,6 @@ err=<RadioLib error>,fail=<count>[,erx=<us>,eslp=<us>]
---
#### Disable the host-controlled RF receive switch during RX power saving
**Usage:**
- `get radio.rxps.rfrx_disabled`
- `set radio.rxps.rfrx_disabled <state>`
**Parameters:**
- `state`: `on`|`off`
**Default:** `off`
**Notes:**
- This is a runtime-only diagnostic setting and resets to `off` after reboot.
- `on` reproduces the missing RF_RX assertion during SX1262 receive duty-cycle mode.
- Supported only on SX1262 targets with a host-controlled RX enable pin.
- Enabling it can significantly reduce receive sensitivity and make remote commands harder to receive.
---
### System