RXPS v2

docs/cli_commands.md

@@ -280,30 +280,31 @@ 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>`
 - `set radio.rxps <rx_us> <sleep_us>`
 
 **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,37 +347,117 @@ 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`.
 
 **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
 

examples/companion_radio/MyMesh.cpp

@@ -278,7 +278,9 @@ static void applyCompanionRxPowerSaving(uint8_t sf, float bw) {
   uint32_t rx_us = 0;
   uint32_t sleep_us = 0;
   bool ok = calcRxPowerSavingLevel(RX_POWERSAVING_BALANCED_LEVEL, sf, bw,
-                                   RX_POWERSAVING_PROFILE_PREAMBLE, &rx_us, &sleep_us) &&
+                                   RX_POWERSAVING_PROFILE_PREAMBLE, &rx_us, &sleep_us,
+                                   rxPowerSavingCaptureCost(control),
+                                   rxPowerSavingTransition(control)) &&
             control->setRxPowerSaving(true, rx_us, sleep_us);
   if (!ok) {
     control->setRxPowerSaving(false, RX_POWERSAVING_DEFAULT_RX_US,

examples/simple_repeater/MyMesh.cpp

@@ -11,8 +11,9 @@ static RxPowerSavingControl* getRxPowerSavingControl() {
 }
 
 static void applyRxPowerSavingConfig(NodePrefs& prefs, uint8_t sf, float bw) {
-  normalizeRxPowerSavingConfig(&prefs.rxps, sf, bw);
   RxPowerSavingControl* control = getRxPowerSavingControl();
+  normalizeRxPowerSavingConfig(&prefs.rxps, sf, bw, rxPowerSavingCaptureCost(control),
+                               rxPowerSavingTransition(control));
   bool ok = control != nullptr
       ? control->setRxPowerSaving(
             prefs.rxps.enabled != 0, prefs.rxps.rx_us, prefs.rxps.sleep_us)

platformio.ini

@@ -29,6 +29,15 @@ build_flags = -w -DNDEBUG -DRADIOLIB_STATIC_ONLY=1 -DRADIOLIB_GODMODE=1
   -D LORA_FREQ=869.618
   -D LORA_BW=62.5
   -D LORA_SF=8
+  ; TCXO startup delay in microseconds, written by CustomSX1262/CustomLR1110
+  ; after begin(). RadioLib defaults to 5000 and nothing used to override it, so
+  ; every board paid 5 ms on every duty-cycle wake. Lowest working value measured
+  ; on five modules: T096 400, Tracker V2 300, Waveshare 150, ThinkNode M3 200,
+  ; T1000-E 200 us - 1600 keeps 4x margin over the worst of them. It also feeds
+  ; the RXPS sleep floor and timer guard (transition = this + 1000), so lowering
+  ; it makes low-SF profiles armable that were not. A board needing its own value
+  ; puts -D MC_TCXO_DELAY_US=... in its own build_flags; the later -D wins.
+  -D MC_TCXO_DELAY_US=1600
   -D ENABLE_ADVERT_ON_BOOT=1
   -D ENABLE_PRIVATE_KEY_IMPORT=1   ; NOTE: comment these out for more secure firmware
   -D ENABLE_PRIVATE_KEY_EXPORT=1

src/helpers/CommonCLI.cpp

@@ -655,8 +655,6 @@ void CommonCLI::handleSetCmd(uint32_t sender_timestamp, char* command, char* rep
     } else {
       strcpy(reply, "Error: state must be on or off");
     }
-  } else if (strncmp(config, "radio.rxps.rfrx_disabled ", 25) == 0) {
-    RXPowerSavingCLI::setRfRxDisabled(&config[25], _rxps_control, reply, 160);
   } else if (memcmp(config, "radio.rxps ", 11) == 0) {
     if (RXPowerSavingCLI::set(&config[11], _prefs->sf, _prefs->bw, &_prefs->rxps,
                               _rxps_control, reply, 160)) {
@@ -677,7 +675,8 @@ void CommonCLI::handleSetCmd(uint32_t sender_timestamp, char* command, char* rep
       _prefs->bw = bw;
       bool rxps_retuned = recalcRxPowerSavingFromLevel(
           _prefs->rxps.level, _prefs->sf, _prefs->bw, _prefs->rxps.preamble,
-          &_prefs->rxps.rx_us, &_prefs->rxps.sleep_us);
+          &_prefs->rxps.rx_us, &_prefs->rxps.sleep_us,
+          rxPowerSavingCaptureCost(_rxps_control), rxPowerSavingTransition(_rxps_control));
       _callbacks->savePrefs();
       strcpy(reply, rxps_retuned ? "OK - reboot to apply (rxps retuned)" : "OK - reboot to apply");
     } else {
@@ -949,10 +948,14 @@ void CommonCLI::handleGetCmd(uint32_t sender_timestamp, char* command, char* rep
     } else {
       sprintf(reply, "> %s", _board->isLoRaFemPaGainEnabled() ? "on" : "off");
     }
-  } else if (strcmp(config, "radio.rxps.rfrx_disabled") == 0) {
-    RXPowerSavingCLI::getRfRxDisabled(_rxps_control, reply, 160);
-  } else if (strcmp(config, "radio.rxps") == 0) {
-    RXPowerSavingCLI::get(&_prefs->rxps, _rxps_control, reply, 160);
+  } else if (memcmp(config, "radio.rxps", 10) == 0 &&
+             (config[10] == 0 || config[10] == ' ')) {
+    // Exact match plus an optional trailing space, the same shape as the `tx`
+    // key below. A plain strcmp() looks stricter but is a trap here: `get
+    // radio.rxps ` fails it, falls through to the `radio` prefix branch further
+    // down and cheerfully answers with the frequency and bandwidth. Every other
+    // key in this chain is a prefix match and so never noticed the space.
+    RXPowerSavingCLI::get(&_prefs->rxps, _rxps_control, _prefs->sf, _prefs->bw, reply, 160);
   } else if (memcmp(config, "radio", 5) == 0) {
     char freq[16], bw[16];
     strcpy(freq, StrHelper::ftoa(_prefs->freq));

src/helpers/radiolib/CustomLR1110.h

@@ -14,6 +14,23 @@ class CustomLR1110 : public LR1110 {
   public:
     CustomLR1110(Module *mod) : LR1110(mod) { }
 
+    // See CustomSX1262::begin - same reasoning, LR11x0 flags and calibration.
+    int16_t begin(float freq = 434.0, float bw = 125.0, uint8_t sf = 9, uint8_t cr = 7,
+                  uint8_t syncWord = RADIOLIB_LR11X0_LORA_SYNC_WORD_PRIVATE, int8_t power = 10,
+                  uint16_t preambleLength = 8, float tcxoVoltage = 1.6) {
+      int16_t state = LR1110::begin(freq, bw, sf, cr, syncWord, power, preambleLength,
+                                    tcxoVoltage);
+      if (state == RADIOLIB_ERR_NONE) applyMeshCoreTcxoDelay();
+      return state;
+    }
+
+    void applyMeshCoreTcxoDelay() {
+      if (tcxoVoltage <= 0.0f) return;
+      setTCXO(tcxoVoltage, MC_TCXO_DELAY_US);
+      calibrate(0x3F);          // all blocks; setTCXO moved the gating window
+      delay(50);
+    }
+
     size_t getPacketLength(bool update) override {
       size_t len = LR1110::getPacketLength(update);
       if (len == 0 && getIrqStatus() & RADIOLIB_LR11X0_IRQ_HEADER_ERR) {
@@ -29,6 +46,10 @@ class CustomLR1110 : public LR1110 {
 
     float getFreqMHz() const { return freqMHz; }
 
+    // The sleep -> RX transition RadioLib subtracts from a duty-cycle sleep.
+    // Protected in the RadioLib base, so the RXPS layer reads it through here.
+    uint32_t getTcxoDelay() const { return tcxoDelay; }
+
     // Restores the LF clock configuration RadioLib's begin() installs. Arming
     // the duty cycle switches it to RC + BUSY-release (required by Semtech for
     // SetRxDutyCycle); without this the change would outlive RXPS being turned

src/helpers/radiolib/CustomLR1110Wrapper.h

@@ -6,6 +6,20 @@
 
 class CustomLR1110Wrapper : public RadioLibWrapper {
 public:
+  // Measured on ThinkNode M3 and T1000-E: this family needs roughly one symbol
+  // more margin than SX126x before a duty-cycled receiver latches a preamble.
+  float rxPowerSavingCaptureCostSymbols() const override {
+    return RX_POWERSAVING_CAPTURE_COST_SYMBOLS_LR11X0;
+  }
+
+  // Same reasoning as the SX126x wrapper. This family never showed either
+  // duty-cycle failure on the bench, which is unsurprising: its driver has
+  // always enforced an extended-period rule equivalent to the timer guard the
+  // SX126x side only just gained.
+  uint32_t rxPowerSavingTransitionUs() const override {
+    return ((CustomLR1110 *)_radio)->getTcxoDelay() + 1000;
+  }
+
   CustomLR1110Wrapper(CustomLR1110& radio, mesh::MainBoard& board) : RadioLibWrapper(radio, board) { }
 
   void setParams(float freq, float bw, uint8_t sf, uint8_t cr) override {