diff --git a/docs/ble-lora-coexistence.md b/docs/ble-lora-coexistence.md new file mode 100644 index 00000000..762275c3 --- /dev/null +++ b/docs/ble-lora-coexistence.md @@ -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. diff --git a/docs/budka-sensor.md b/docs/budka-sensor.md new file mode 100644 index 00000000..fd3bac1c --- /dev/null +++ b/docs/budka-sensor.md @@ -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 `. 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 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. diff --git a/docs/cli_commands.md b/docs/cli_commands.md index 8d06a2ba..f1f48a01 100644 --- a/docs/cli_commands.md +++ b/docs/cli_commands.md @@ -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 "time {epoch}"`, the `meshcore-ble-bridge`/`meshcore-serial-bridge` scrape, or `tools/xiao_uf2_flash.sh`, which sets it right after every flash; diff --git a/docs/power.md b/docs/power.md new file mode 100644 index 00000000..3db23982 --- /dev/null +++ b/docs/power.md @@ -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 `. 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.