Share Companion hardware diagnostics and protect RXEN reconfiguration

This commit is contained in:
mikecarper committed 2026-10-23 08:57:51 -07:00
1 parent 04c4fdb240
commit 807343de8d
28 files changed
+1393 -277

No files matched your search

+6
View File
@@ -96,6 +96,12 @@ over the normal binary USB, BLE, or TCP connection:
| Command | Availability |
|---|---|
| `stats-core`, `stats-radio`, `stats-radio-diag`, `stats-packets` | Local terminal and binary command `0x42` |
| [`clear stats`, `get rxps.wd`, `get cad`](companion_radio_diagnostics.md) | Companion terminal and command `0x42`; clearing statistics also clears sticky packet error flags |
| [`get/set radio.rxps.rfrx_disabled`](companion_radio_diagnostics.md) | Supported radio with an RXEN pin; applies for this boot and preserves radio ownership |
| [`power`, `get pwrmgt.support`, `get pwrmgt.source`, `get pwrmgt.bootmv`](companion_power_diagnostics.md) | Board power capabilities determine available readings |
| [`get system.watchdog`](companion_power_diagnostics.md) | Actual nRF52 hardware status; Companion does not provide a saved on/off setter |
| [`get bootloader.ver`](cli_commands.md#view-the-bootloader-version-nrf52-only) | nRF52 Companion terminal and command `0x42`; unidentifiable metadata returns `unknown` |
| [`get/set sdcard`](test-results/companion_cli_parity_2026-10-23.md#shared-sd-commands) | nRF52 builds with SD OTA storage; maintenance retains OTA and Ethernet ownership guards |
| `erase` | Local terminal and binary command `0x42`; reboot after erasing stored settings |
| `set freq <MHz>` | Local terminal, binary command `0x42`, and authorized LoRa CLI; reboot to apply |
| [`get public.key`](cli_commands.md#view-this-nodes-public-key) | Companion text terminal and binary command `0x42`; read-only, no private-key export feature required |
+12 -1
View File
@@ -2781,6 +2781,11 @@ before relying on automatic forwarding limits.
- The nRF52 hardware cannot stop a watchdog after it has started. Disabling is persisted immediately, then the current firmware stops feeding it so the board performs one watchdog restart within 60 seconds. It remains off after that restart.
- This setting is nRF52-only. The SoftDevice flash deadlock does not apply to ESP32, whose existing watchdog behavior is unchanged.
Companion supports the getter and reports the actual hardware running state.
Its application always feeds the watchdog and has no saved on/off policy;
`set system.watchdog ...` therefore reports that control is unavailable. The
persistent on/off behavior above applies to infrastructure firmware.
---
#### Estimate and correct infrastructure-node time after startup
@@ -6605,10 +6610,16 @@ off at boot and is deliberately controlled only for the current boot:
get eth
set eth on
set eth off
get sdcard [free]
get sdcard free
ota cache [on|off]
```
SD-capable nRF52 Companion builds also share the infrastructure SD commands:
`get sdcard ls [page]`, `get sdcard dir [page]`, maintenance history, and
`set sdcard format|erase [--force]`. Bare `get sdcard` reports maintenance
history; use `get sdcard free` for capacity. See the
[SD command details and ownership guards](test-results/companion_cli_parity_2026-10-23.md#shared-sd-commands).
Before `set eth on`, remove the SD card and finish/cancel any active OTA
capture, transfer, serving, or host-folder work. The command rejects an
inserted card or a busy archive instead of taking the shared bus. Turn
+36
View File
@@ -0,0 +1,36 @@
# Companion power and system-watchdog diagnostics
Companion text commands are available through its existing USB terminal and
framed CLI paths, with the same admission rules as other diagnostics:
```text
power
get pwrmgt.support
get pwrmgt.source
get pwrmgt.bootmv
get system.watchdog
```
`power` reports the current battery millivolts, USB power, solar charging,
external power and charger state. A board without a dedicated USB or solar
detector reports `n/a` for that field. External or charging power does not prove
that USB data is connected.
`get pwrmgt.support` reports whether the board includes nRF52 power management.
On supported builds, `get pwrmgt.source` reports `external` or `battery`, and
`get pwrmgt.bootmv` reports the boot-time voltage sample. The boot sample differs
from the live battery reading. Other builds return an explicit unsupported
reply for the source and boot-voltage queries.
On nRF52, `get system.watchdog` reports the hardware watchdog's actual running
state as `on` or `off`. It does not start or feed the watchdog. This also works
when a build disables normal watchdog feeding or inherits a running watchdog
from its bootloader. Other platforms report unsupported; this command does not
describe an ESP32 task watchdog or the radio-recovery watchdogs.
Companion normally starts and feeds its nRF52 watchdog in the application loop.
Its timeout is normally 60 seconds. Companion has no saved watchdog enable
preference, so `set system.watchdog` returns an explicit error. Infrastructure
roles retain their existing saved on/off policy. Implementing that control in
Companion would also require preference storage and feed-loop integration:
an already running nRF52 watchdog cannot be stopped directly.
+23
View File
@@ -0,0 +1,23 @@
# Companion radio diagnostics
Companion exposes these commands through USB terminal, the app's framed CLI
(command `0x42`, including Bluetooth), and its existing admitted admin CLI.
| Command | Result |
| --- | --- |
| `get rxps.wd` | RX power-saving recovery history: `soft=<count>,hard=<count>`. |
| `get radio.rxps.rfrx_disabled` | Whether duty-cycle receive suppresses the radio's external RXEN output. Unsupported radios report an error. |
| `set radio.rxps.rfrx_disabled on` / `off` | Changes that RXEN policy for this boot. The radio must have a supported RXEN pin and admit a safe reconfiguration. |
| `get cad` / `get radio.cad` | Existing CAD scan/retry/deadline information, followed by `busy=<count>` for busy-channel observations. |
| `clear stats` | Resets the same statistics as infrastructure roles: radio packet/error counts, mesh flood/direct packet counts, sticky mesh error flags, and table duplicate counters. |
RXEN changes preserve the configured receive power-saving policy and timings.
A carrier/Morse transmission, beacon, BUSY interval, transmission, or unread
packet can reject the change. If receive restoration fails, the old RXEN policy
is restored for the normal bounded receive-retry path and the command reports
an error. The setting is not saved across reboot.
`clear stats` retains watchdog recovery counts, airtime totals, receive activity
timestamps, queued packets, duplicate-detection history, and all saved settings.
Record a failure's statistics before clearing them; the command deliberately
clears the sticky error flags shown by `stats-core`.
+4
View File
@@ -16,6 +16,10 @@ For runtime on/off commands and board exceptions, see
For practical on/off commands and update directions, see
[Full Companion feature switches](full_companion_features.md).
Shared hardware commands include [power and watchdog diagnostics](companion_power_diagnostics.md),
[radio recovery and RXEN diagnostics](companion_radio_diagnostics.md), and
[SD card management on supported builds](test-results/companion_cli_parity_2026-10-23.md#shared-sd-commands).
`companion_radio_full` combines every qualified Companion transport for its
platform into one artifact and acts as a host-backed LoRa mOTA source for
updating other nodes. Most targets can run those transports simultaneously;
@@ -0,0 +1,87 @@
# Companion hardware command parity, 2026-10-23
The audit baseline was `04c4fdb240318d0151947b8c11ce09a3e2aec65c`.
That revision already closed `get bootloader.ver`: Companion calls the same
board reader and preserves the bootloader's full version suffix. The follow-up
changes share the missing hardware diagnostics and SD command implementation.
This records source behavior and native regression tests, not hardware
qualification or a claim that every board or firmware type was built. Existing
local/remote authorization and platform/backend capability gates remain in use.
## Commands added after the audit
| Command | Behavior and limits | Implementation |
| --- | --- | --- |
| `get pwrmgt.support` | Reports actual board/build power-management support. | [Power diagnostics](../../src/helpers/CompanionPowerDiagnostics.h#L28) |
| `get pwrmgt.source` | Reports external/battery power when supported. External power does not establish that USB data is connected. | [Power diagnostics](../../src/helpers/CompanionPowerDiagnostics.h#L33) |
| `get pwrmgt.bootmv` | Reports the boot voltage sample, distinct from current battery voltage in `stats-core`. | [Power diagnostics](../../src/helpers/CompanionPowerDiagnostics.h#L34) |
| `get system.watchdog` | Reports actual running state where supported. Companion does not pretend to have Repeater's persisted watchdog switch; its setter explicitly reports unavailable. | [Watchdog diagnostics](../../src/helpers/CompanionPowerDiagnostics.h#L46) |
| `get rxps.wd` | Reports the radio driver's separate soft/hard recovery counts. These are not included in `stats-radio-diag`. | [Radio diagnostics](../../src/helpers/CompanionRadioDiagnostics.h#L17) |
| `get/set radio.rxps.rfrx_disabled` | Reads/changes the supported radio's RF RX policy for this boot. Retains driver ownership and receiver-restoration checks; does not persist a preference. | [Radio diagnostics](../../src/helpers/CompanionRadioDiagnostics.h#L31) |
| `power` | Reports current battery voltage and supported USB, solar, external-power and charger states. | [Power diagnostics](../../src/helpers/CompanionPowerDiagnostics.h#L15) |
| `clear stats` | Resets radio/mesh packet counters, sticky packet error flags and table duplicate counters. RXPS recovery history, queues and saved settings remain intact. | [Radio diagnostics](../../src/helpers/CompanionRadioDiagnostics.h#L23) |
| `get cad` / `get radio.cad` | Retains timing details and appends the channel-busy count. | [CAD diagnostics](../../src/helpers/CompanionRadioDiagnostics.h#L70) |
The watchdog setter requires more than an alias: Companion would need a saved
policy and feed-loop integration. An already running nRF52 watchdog cannot be
stopped directly; the existing
[disable path deliberately resets](../../src/helpers/NRF52Board.cpp#L328).
## Shared SD commands
All nRF52 builds that already enable `OTA_SD_STORE` use the same
[SD handler](../../src/helpers/SdCardCLI.cpp#L60) through
[CommonCLI](../../src/helpers/CommonCLI.cpp#L4033) or the Companion command router.
This adds no SD capability to unsupported boards.
| Command | Meaning |
| --- | --- |
| `get sdcard` / `get sdcard *` | Format/erase history for this boot. Bare `get sdcard` now follows CommonCLI's history reply; use `free` for space. |
| `get sdcard free` | Used and free space. |
| `get sdcard ls [page]` / `get sdcard dir [page]` | Paginated file listing; page must be 1-65535. |
| `get sdcard format` / `get sdcard erase` | Time since the corresponding successful maintenance operation, or `never`. These getters do not modify the card. |
| `set sdcard format [--force]` | Formats the card. |
| `set sdcard erase [--force]` | Erases and then formats the card. |
The setters preserve the existing five-minute per-action cooldown; `--force`
bypasses only that cooldown. Pending apply and unrelated occupied internal/NOR
update slots still block maintenance. The handler closes/checkpoints shared
archive work before card-wide changes and rebuilds the source view afterward
([guards and reset sequence](../../src/helpers/SdCardCLI.cpp#L99)).
RAK Ethernet ownership blocks space/list/maintenance access before allocating
an OTA context or changing update state
([bus exclusion](../../src/helpers/SdCardCLI.cpp#L22)); the card backend retains
its own bus and firmware-authorization checks. Failed context allocation or
card operations return an error without bypassing these checks.
The former Ethernet-only Companion SD query branch was removed. Ethernet's
own enable/disable admission and lifecycle callbacks remain separate.
## Existing commands and intentional distinctions
Companion already had `get pwrmgt.bootreason` / `powerlog`, USB debug/logging,
USB watchdog commands, sleep diagnostics, storage layout, ADC calibration,
regulator controls, and core/radio/packet statistics. Shared helper dispatch
must be checked before treating an absent literal command name as a gap.
ESP32 CPU frequency and power-test commands are also shared and remain
platform-specific.
`get/set radio.watchdog` is the
[Observer/MQTT inactivity policy](../../src/helpers/CommonCLI_Observer.cpp#L928),
not the universal nRF52 hardware watchdog. Repeater `get/set rx.watchdog` is a
separate [receive-inactivity policy](../../examples/simple_repeater/MyMesh.cpp#L13034).
Neither is copied into Companion without its underlying policy.
## SD validation
The shared production `.cpp` is compiled and executed under five native SD
profiles with address/undefined-behavior sanitizers. Tests cover malformed
commands, allocation failure, Ethernet ownership, card failures, bounded
replies, cooldown/clock wrap and history. Existing RAK seeder and context-handoff
suites also pass; the occupied-store matrix retains its negative regression
that detects destructive loss of an unrelated update.
Relevant suites: [SD CLI parity](../../test/test_sdcard_cli_parity.py),
[RAK seeder](../../test/test_rak15002_sd_seeder.py), and
[SD context handoff](../../test/test_rak_sd_context_handoff.py).