docs: power, budka sensor and BLE/LoRa coexistence notes under public paths
pub-release / release (push) Failing after 22s

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
tthandClaude Opus 5.5 committed 2026-11-12 11:56:30 +01:00
1 parent d1d04f98ef
commit 6fe0c0f8e1
4 files changed
+426 -1

No files matched your search

+229
View File
@@ -0,0 +1,229 @@
# BLE/LoRa coexistence — bench reproduction attempt
Working notes for the DIRECT-forward loss seen on `mast-three` (SenseCap Solar,
`SenseCap_Solar_repeater_ble`). Written down because the result is mostly
**negative**, and a negative result is only worth anything if the method and its
limits are recorded with it.
## The claim under test
Commit `f6e9aeca` widened the BLE connection interval from 15–30 ms to 60–80 ms
after an A/B on the mast showed ~40 % of DIRECT-route forwards silently lost
with an **idle** BLE connection at 15–30 ms. The stated mechanism is that the
SoftDevice's per-connection-event preemption disturbs the SX126x TX path
(`startTransmit` fail / send-complete timeout).
The fix is deployed. What was never established is whether a bench rig can
**detect** the effect at all — a measurement that reads zero in both the
treatment and the control has shown nothing.
## Rig
Isolated test mesh on **866.5 MHz** (BW 62.5, SF 8, CR 5). Isolation is by
frequency, not by tx power: a hilltop repeater with `RX_BOOSTED_GAIN` hears a
few mW just fine. The override is compile-time (`platformio.local.ini`) because
`MyMesh.cpp` seeds `_prefs.freq` from `LORA_FREQ`, so the firmware cannot come
up on the production frequency even after `erase`.
| node | board | role |
|---|---|---|
| `bench-board` | XIAO nRF52840 + Wio-SX1262 | forwarder under test |
| `bench-board` | same | paired control / radiating witness |
| `bench-board`, `bench-board` | same | probe sources |
| `bench-rpt` | SenseCap Solar Node | forwarder, mast-identical hardware |
| `tth-s2-rpt` | same | paired control |
Paired controls differ **only** in `ADVERT_NAME`, verified by diffing strings in
the ELF. Any other difference invalidates them.
### Oracle
The measured quantity is the node's own `direct_rx − direct_tx` from
`stats-packets`: how many DIRECT packets it accepted for forwarding versus how
many it actually sent. This is self-normalising — it does not depend on channel
conditions or on a receiver hearing anything. `tx_start_fail` and `tx_timeout`
are the mechanism-level counters. A second repeater with `repeat off` acts as a
radiating witness, so "counted a TX" can be distinguished from "actually
radiated".
Route forcing: a contact is injected into the sender's companion with an
explicit `out_path`, so the DM must traverse the node under test.
**`out_path_len` is not a hop count** — it is a packed byte, top two bits =
hash size − 1, low six = hop count (`Packet.h:85`). One hop with a 2-byte hash
is `0x41`, not `1`. The receiver reads the size out of the packet
(`Mesh.cpp:93`), so a forced path works regardless of the node's
`path.hash.mode`.
## What was measured
All cells at a **verified** 22.50 ms connection interval — `bleconn` reports the
parameters actually negotiated, because `bleOnSecured()` only requests them and
the central may refuse. Without that read-back none of the null results below
would mean anything.
| `blepwr` | ≈RSSI at central | link up | direct_rx | direct_tx | lost | tx_timeout |
|---:|---:|---:|---:|---:|---:|---:|
| BLE off | — | — | 8 | 8 | 0 | 0 |
| 0 dBm | −67 | 100 % | 8 | 8 | 0 | 0 |
| −8 | −75 | 100 % | 8 | 8 | 0 | 0 |
| −12 | −79 | 100 % | 8 | 8 | 0 | 0 |
| −16 | −83 | 87 % | 8 | 8 | 0 | 0 |
| −20 | −87 | 27 % | 8 | 8 | 0 | 0 |
The −20 dBm row is a bonus condition: the link held only a quarter of the
window, so the node spent the rest advertising and re-connecting — close to the
reconnect churn the mast reports as HCI 0x3E.
**Ruled out as the missing factor: BLE link margin.** The whole −75..−90 window
the mast sits in is covered, at the known-bad interval, with zero loss.
### Why idle + weak link does nothing
In idle the connection events carry empty PDUs, whose retransmission costs
almost no radio time. The cost of a retransmission scales with payload size, and
the mast has a bridge actively draining the console. Hence the `poll` mode in
the harness.
Direction matters too, and it is the reason to weaken **our** side rather than
the central's: a connection event ends as soon as either side misses a packet,
so if the central misses our PDU we must re-send it at the next anchor — an
extra slave TX. If we miss the central's PDU we never transmit in that event at
all, and the SoftDevice uses *less* radio.
## On mast hardware, with the file log on
Two SenseCap Solar nodes (`bench-rpt` forwarder, `tth-s2-rpt` paired control) —
the same board as the mast, so InternalFS logging, INA226/solar telemetry and
the SenseCap SPI layout are all in play. Again at a verified 22.50 ms interval
(`bleconn`).
| file log | BLE | direct_rx | direct_tx | lost | tx_timeout | witness |
|---|---|---:|---:|---:|---:|---:|
| off | off | 8 | 8 | 0 | 0 | +39 |
| off | idle, 88 % of window | 8 | 8 | 0 | 0 | +37 |
| **on** | off | 8 | 8 | 0 | 0 | +39 |
| **on** | idle, 90 % of window | 8 | 8 | 0 | 0 | +40 |
The logging condition was real, not nominal: `log` afterwards held 69 entries
with RX/TX lines timestamped inside the measurement window, i.e. an InternalFS
write per packet — the mechanism behind the known deaf windows.
**Ten cells, 80 forced forwards, zero lost, `tx_timeout` and `tx_start_fail` at
zero throughout.** Against the mast's reported ~40 % loss rate this is not a
weak null: a single 8-probe cell would miss a true 40 % effect with probability
0.6⁸ ≈ 1.7 %, and ten cells make it vanishing. Whatever the mast is doing, it is
not reproduced by the connection interval, the BLE link margin, the board, or
InternalFS logging — alone or together.
## Still open
**Loaded LoRa channel** is the one uncontrolled difference left. Ours is idle;
the mast relays flood traffic, so its forwards contend for a busy channel and
the TX window lands on a BLE connection event far more often. This cannot be
tested legally here: 866.5 is capped at 1 % duty and the 10 % sub-band
(869.4–869.65) is where production lives.
Practical consequence: **f6e9aeca can be neither confirmed nor refuted on the
bench.** Deciding whether the 60–80 ms interval is still needed requires
measuring on `mast-three` itself — the counters (`stats-packets`, and now
`bleconn` to prove which interval is actually in force) are all reachable over
its BLE console.
## Airtime is a hard limit, and the firmware will not enforce it
866.5 MHz sits in 865–868 (CZ VO-R/10): 25 mW ERP, **1 % duty cycle = 36 s of
transmission per hour**. The firmware does not police this — `airtime_factor`
defaults to 0 (= 100 %) and is clamped to 9, so the lowest duty MeshCore can
enforce is 10 %. The first sweep consumed `tx_air_secs` 27 s in 18 minutes of
uptime, a rate of ~2.5 %. Budget the probes: `stats-radio.tx_air_secs` is the
ground truth, and the harness aborts before crossing a configured cap.
`stats-core.queue_len` and `errors` are a required control, not decoration: when
the airtime budget runs out the Dispatcher **defers** a forward
(`next_tx_time`, `Dispatcher.cpp:101`), which looks identical to loss in the
counters. Both were zero throughout.
## Traps worth remembering
- **USB and BLE consoles share one `command[160]`.** Two concurrent consoles
interleave into one line and crash the node. The harness keeps a strict
sequence: counters over USB → close USB → BLE client → probes → stop BLE →
counters over USB.
- **`Bluefruit.setTxPower()` is advertising-only** (see the commit message for
`blepwr`); the connection runs at the SoftDevice default 0 dBm.
- **Weakening the link can lock you out of BLE.** Below about −16 dBm the
node's replies stop arriving and the value is re-applied on every reconnect
(and, since 6. 10. 2026, saved). The way back is `blepwr` over the mesh admin
CLI.
- **~~Runtime `set tx` does not change radiated LoRa power~~ — retracted.** The
original reading (+2 dBm → RSSI −44.1, −9 dBm → −44.0) was made with an
instrument that could not report failure: `RadioLibWrapper::setTxPower()`
discarded RadioLib's status, so a refused request looked exactly like an
accepted one. Re-measured 2026-08-04 on the repeater build with `txpwr`
confirming each step, x1 transmitting and x4 as witness:
| `txpwr` | witness `last_rssi` |
|---:|---:|
| +22 | 0 dBm *(saturated)* |
| +14 | −1 dBm *(saturated)* |
| +6 | −7 dBm |
| 0 | −18 dBm |
| −9 | −28 dBm |
31 dB of command produced 28 dB of RSSI, and the witness `recv` counter rose
by one at every step, so no point was missed. Radiated power does follow the
setting. The top two points are saturated — the boards were ~10 cm apart — so
the usable range of that particular rig starts around +6 dBm; characterising
the top end needs attenuation or distance, not a bigger number.
The lesson is not about tx power. It is that a null result from an instrument
which cannot distinguish "refused" from "no effect" is not a result at all.
## The two commands this bench added
Both live in `examples/simple_repeater/main.cpp` and are repeater-only.
### `bleconn` — what the link is actually doing
```
bleconn
-> BLE conn: interval 75.00 ms (req 60-80), latency 0, sup timeout 4000 ms [live]
```
Reports the **negotiated** connection parameters, not the requested ones. The
central is free to ignore a peripheral's request, so this is the only way to
know whether a change like `f6e9aeca` (widening the requested interval to
60–80 ms) is in force on a node you cannot see. The trailing `[live]` /
`[last]` says whether a client is connected right now or these are the values
from the last one; before any client has ever connected it answers
`nothing seen yet`.
### `blepwr [dBm]` — connection TX power, saved
```
blepwr # report: BLE conn tx: 0 dBm, adv tx: 8 dBm
blepwr 8 # set, apply to live connections and save
blepwr default # forget the saved value, back to RPT_BLE_CONN_TX_POWER
```
The reply carries how many live connections accepted the value
(`OK - BLE conn tx 8 dBm (1/1 conn), saved`) because the nRF52840 only takes
−40, −20, −16, −12, −8, −4, 0 and 2..8 dBm; anything else is rejected and is
*not* latched or saved, so a typo cannot arm itself for the next reconnect.
The value lives in `/ble_pwr` in InternalFS, so it survives a reboot and also a
reflash with a different build default: an explicit value is pinned even when
it equals the default (no file = follow `RPT_BLE_CONN_TX_POWER`, which
mast-three's env sets to 8).
Sets `BLE_GAP_TX_POWER_ROLE_CONN`, which is **independent of**
`Bluefruit.setTxPower()` — that one only affects advertising, despite reading
like a global. The connection otherwise runs at the SoftDevice default of
0 dBm; the compile-time starting value is `RPT_BLE_CONN_TX_POWER`.
The value is re-applied on every 'secured' event and saved, so a setting weak
enough to break the link persists across reconnects and reboots — at −40 dBm
during this bench it locked the BLE console out. Fix it over the mesh admin
CLI (`blepwr 0`), which does not depend on BLE. Until 6. 10. 2026 a weakening
auto-reverted after 5 minutes and nothing was saved; that went away once the
value started to be saved, because a revert that the next reboot undoes again
only made the state harder to read.
+64
View File
@@ -0,0 +1,64 @@
# Budka link — a Chytra Budka as a sensor source
A Chytra Budka (ESP32-S3 bird box) sends its readings over a one-way UART line
to a XIAO nRF52840 running `simple_sensor`; the sensor serves them as
CayenneLPP telemetry to anyone on the mesh. The line format and the budka side
are documented in the chytra-budka repo, `firmware/MESHCORE.md`.
## Build
`BudkaLinkSensorManager` (`src/helpers/sensors/`) replaces the variant's
`EnvironmentSensorManager` when the env defines `BUDKA_LINK_RX_PIN`; every
other env is unchanged.
```ini
[env:Xiao_x1_budka] ; platformio.local.ini
extends = env:Xiao_nrf52_sensor
build_flags =
${env:Xiao_nrf52_sensor.build_flags}
${test_radio.build_flags} ; bench: test band only
-D BUDKA_LINK_RX_PIN=0 ; D0 = the only pad LoRa + I²C leave free
```
Optional: `BUDKA_LINK_TX_PIN` (default `LED_GREEN` — nothing is ever sent, the
idle-high line keeps that LED dark), `BUDKA_LINK_BAUD` (115200),
`BUDKA_LINK_METERS` (3), `BUDKA_LINK_STALE_MS` (120 s).
## Wiring
Budka `mc_tx` pad → XIAO **D0**, GND ↔ GND, each board on its own USB. A
1 kΩ series resistor protects against back-powering when one side is off.
## Telemetry layout
| channel | content |
|---|---|
| 1 | the node itself |
| next | budka: temperature, humidity, pressure, motion count (generic sensor) |
| next + k | UC96 meter *k*: voltage, current, power (analog input), energy (kWh) |
A line with a bad checksum is dropped whole; a value not refreshed for 2 min is
left out. Meter channels stay reserved while a meter is missing.
Read it with `tools/budka_telem.py <companion-port> <sensor-name>`. The sensor
answers only clients in its ACL — a request from anyone else is dropped
(`recv matches no peers` in a `MESH_DEBUG` build). Add the companion from the
sensor's USB console with `setperm <companion-pubkey> 1`, or log in as admin.
The port may be a pyserial URL (`socket://…` for an openHop companion), and the
name may be the sensor's public key when the companion does not have it yet.
## Bench result (13. 10. 2026)
x1 (sensor, test band) fed by the bench budka; x4 as USB companion:
```
ch2 temp_C 25.3 humidity_% 59.0 generic 29
ch3 voltage_V 4.94 current_A 0.10 analog_in 0.49 energy_kWh 0.111
ch4 voltage_V 4.94 current_A 0.18 analog_in 0.89 energy_kWh 0.311
```
## Not done
Alerts (reed opened, budka WiFi down) and the return direction (mesh → budka).
The sensor build has no `dfu` console command — reflash with
`pio run -t upload`, one touch per power session.
+1 -1
View File
@@ -97,7 +97,7 @@ I2C RTC the clock is volatile: it starts at the build epoch and only ticks from
transmits and a receiver drops a stale timestamp as a replay. Automatic sources,
in order of preference:
- **GPS** (`gps duty` is enough — see `docs/power-saving.md`);
- **GPS** (`gps duty` is enough — see `docs/power.md`);
- **an attached host** — `tools/ble_cli.py <MAC> "time {epoch}"`, the
`meshcore-ble-bridge`/`meshcore-serial-bridge` scrape, or
`tools/xiao_uf2_flash.sh`, which sets it right after every flash;
+132
View File
@@ -0,0 +1,132 @@
# Power saving on a solar repeater — what it costs, measured
Everything here was measured on the deployment hardware (SenseCAP Solar Node
P1-Pro, nRF52840 + SX1262 + L76K) on 2026-08-05/06 with `tools/power_ab.py`, not
taken from a datasheet. Numbers are input current on the 5 V USB side; the delta
between two states is what the paired design measures, and that is what these
figures are.
## The order that matters
| lever | measured | verdict |
|---|---|---|
| **GPS running continuously** | **46.0 mA** (spread 43.7-47.5) | `gps duty` recovers 42-45 of it |
| BLE advertising + Bluefruit's blinking LED | see below | defaults changed, LED off, 1 s interval |
| `powersaving on` (MCU light sleep) | **~1 mA, not separable from zero** | keep it on (free), but it is not a lever |
| RX duty cycle (EasySkyMesh "rxps") | ~2 mA on our SF7 preset | **not worth pre-release code** whose failure mode is a deaf repeater |
| `radio.rxgain off` | ~0.7 mA | **no** — 1-3 dB of sensitivity is what a mast node is for |
| FEM LNA control | n/a | SenseCap has no FEM, only an RXEN switch |
A whole node in the shipping configuration, with the battery charged and GPS
duty-cycled, sits at **~24 mA**. Continuous GPS alone would nearly triple that.
## GPS is the whole game
The receiver on this board draws 46 mA, and a mast repeater runs GPS for one
reason only: the RTC is volatile, and a node whose clock is wrong has its
replies dropped by clients. It does not need a continuous fix — it needs the
clock set.
GPS is no longer the *only* way to get that (since 7. 8. 2026 a node starts at
its build epoch and any attached host sets it — see `docs/cli_commands.md` under
`time`). A reboot still throws the clock back to the build epoch: carrying it
across one in retained RAM was tried and measured not to work, because the
bootloader's stack owns the top of RAM. GPS is still
what makes a mast node's clock **absolutely** right months after the flash, with
nobody there to set it, so this reasoning stands for anything on a mast. What
changed is that a node without GPS is no longer stuck in 2024.
`gps duty` (`gps_enabled == 2`, so no prefs-layout change) powers the receiver
only around a sync, once a day (until 11/2026 every 30 minutes, the cadence
`gps on` re-syncs at). The LF crystal is ±20 ppm plus ~40 ppm at −10 °C, so a
day costs ~5 s of clock — far below what the mesh notices — and a reboot syncs
at once anyway. Verified on hardware in both paths (with the old 30 min / 1 h
timers):
- with sky (`mast-three`): `duty, asleep, fix, 7 sats` — got a fix, set the clock,
cut power to the receiver;
- without (indoors, `bench-rpt`): `awake` for exactly 300 s
(`GPS_DUTY_MAX_AWAKE_SECS`), then `asleep` with an hourly retry, so a blocked
sky cannot turn duty mode back into "always on".
Worst case (fix never obtained) still saves 42 mA; a normal 30 s fix saves 45.
Going from 30 min to 24 h saves another 0.25–0.75 mA (hot vs. warm start, not
measured per window), and the retry from 1 h to 6 h takes a node whose dome is
under snow from 3.8 mA (300 s at 46 mA hourly) to 0.64 mA.
Knobs: `GPS_DUTY_SYNC_INTERVAL_SECS` (86400), `GPS_DUTY_MAX_AWAKE_SECS` (300),
`GPS_DUTY_RETRY_SECS` (21600).
Upstream later (v1.18 dev, 11/2026) added its own `gps period <s>`. It is not a
replacement: a periodic acquisition has no timeout until the first fix ever, so
the indoor case above would stay at 46 mA for good. `gps duty` sets the period
to 0, and `gps on` / `gps off` leave duty mode.
**One visible side effect:** `querySensors()` only adds the GPS channel to
telemetry while the receiver is powered, so a duty-cycled node reports position
in telemetry only during its sync windows (well under 1 % of the time). What a repeater
*advertises* is unaffected — that comes from prefs via `set advert.loc prefs` (formerly `gps advert prefs`) — and
`node_lat/lon` keep the last fix. Confirmed in the field: `mast-three`'s scrape now
carries `voltage/temperature/humidity` and no `gps` field.
## BLE: two defaults that were quietly expensive
- **The blinking LED.** Bluefruit drives `LED_BLUE` while advertising and holds
it on while connected. On SenseCap Solar that pin is **12 — the same pin as
`P_LORA_TX_LED`**, so a sealed mast node spent solar charge blinking an LED
nobody can see, and the LoRa TX indicator lied as a bonus.
`RPT_BLE_CONN_LED` now defaults to 0.
- **The advertising rate.** Upstream leaves the slow interval at 244 units =
152.5 ms, i.e. three channels ~6.5 times a second, forever.
`RPT_BLE_ADV_SLOW` now defaults to 1600 = 1 s; the first
`RPT_BLE_ADV_FAST_SECS` (30) after boot or disconnect stay fast so discovery
is still immediate when someone is looking.
Bench boards keep both upstream behaviours (`-D RPT_BLE_CONN_LED=1`,
`-D RPT_BLE_ADV_SLOW=244` in `xiao_analyzer`): on a desk the blinking LED is the
"this thing is alive" indicator.
`ble off` remains the big BLE lever for a deployed node, but the deployment rule
stands: ship with BLE **on**, verify the node on site, and only then turn it off
over the mesh — otherwise a node that does not come up has no way in.
## MCU sleep
`powersaving on` makes the nRF52 wait in WFE between events (it wakes on any
interrupt, including LoRa DIO1). Upstream ships it **off**, and it was missing
from our provisioning, so every node built from that file ran the core at 64 MHz
around the clock. It is now in `tools/provision/repeater-cz-silent.txt`.
**But it buys about 1 mA, not the 3-4 that seemed obvious.** Measured with GPS
held off so its sync windows could not pollute the cells: paired estimate
-0.96 mA over three pairs, spread -1.97 to +0.07, against a measured
cell-to-cell repeatability of 1.16 mA — i.e. the effect is the same size as this
rig's noise and cannot be told from zero. That fits the mechanism: the loop
still polls the SX1262 over SPI on every pass and the SoftDevice wakes the core
for each advertising event, so there is not much idle left to sleep through.
Keep it on (it is free and cannot hurt), but do not budget for it.
One fork-specific fix goes with it: the sleep is also held off while the BLE
console still has queued output (`bleTxPending()`), because on the observer node
a half-drained `rxlog`/`pktlog` page would otherwise wait for the next
connection event — the bridge drains those on a 2-minute duty cycle, so a slower
drain directly costs collected frames.
## Measuring this yourself — two traps
1. **A solar node measured on its USB side measures the CHARGER.** With a
charging cell the meter reads 500-700 mA, pulsing, and the node's own tens of
mA ride on top of a drifting number. Wait for the charge to finish (it fell
0.71 → 0.53 → 0.22 → 0.05 A over about an hour here) or the numbers are
fiction. There is **no INA226 on this board** to cross-check with — the `i2c`
command reports nothing at all on the only bus the variant has — on three
separate P1-Pro units (`bench-rpt`, `mast-rpt-two`, `tth-mast-repeater-one`),
against a sensor table that expects `38 76 70 44 5C 42 40 41 5A 29 77`. So it
is the board, not one dead part, and the cross-check for a power measurement
has to be a second *board*.
2. **With `gps duty` enabled you cannot measure anything under ~5 mA.** A sync
window lands in a random cell and adds ~17 mA to a 10-minute average (seen:
40.9 mA against 24.1-24.5 in its neighbours). Put `gps off` in every cell of
such a run and restore `gps duty` afterwards.
See `tools/README.md` (`power_ab.py`) for the alternating-cell design that makes
these deltas trustworthy in the first place.