Expose Companion WiFi and radio power controls

This commit is contained in:
mikecarper committed 2026-08-18 16:51:59 -07:00
1 parent 818f610ba3
commit 0c4619bcc3
27 files changed
+1840 -1349

No files matched your search

+34 -13
View File
@@ -77,6 +77,8 @@ Fresh MQTT observer settings are:
- slot 1 set to `analyzer-us`;
- slot 2 set to `analyzer-eu`;
- slots 3 through 6 disabled;
- WiFi modem power saving set to `min` in the Cascade profile and `none` in
target-default builds;
- WiFi SSID and IATA code empty.
Up to six broker configurations can be saved. The number that can be active at
@@ -196,8 +198,17 @@ the station IP.
If the configured network remains unavailable for two minutes, the companion
opens its setup AP so the credentials can be repaired. It continues retrying
the saved network. WiFi modem sleep is forced off on WiFi companions because
modem-sleep pauses can interfere with timely LoRa radio servicing.
the saved network. WiFi modem sleep has its own persisted `wifi.powersave`
setting and is independent of the Companion device `powersaving` setting. The
WiFi card in Companion WebConfig exposes `none`, `min`, and `max`. Fresh
Cascade-profile builds select `min`; target-default builds select `none`.
A saved setting takes precedence after an upgrade.
WiFi-only Companions can use all three modes. A Full Companion also runs BLE,
so ESP32 WiFi/Bluetooth coexistence requires at least minimum modem sleep. It
reports `min` when an old or target-default `none` value is found and rejects a
new `none` selection while Bluetooth is compiled in. Device power saving can
therefore be turned on or off without changing the selected WiFi modem policy.
WiFi companions do not have the repeater/room-server admin CLI password model,
so their LAN WebConfig page is intentionally unauthenticated. Use them only on
@@ -207,14 +218,16 @@ The WebConfig **Advanced** card exposes device power saving on WiFi Companion,
repeater, and room-server builds. It also exposes RX power saving on radio chips
that support receive duty cycling. RXPS can select continuous receive, levels
1-10, automatic or explicit 16/32-symbol preambles, or manual receive/sleep
windows. Both settings are persisted across reboots.
windows. The WebConfig **WiFi** card exposes WiFi modem power saving. All three
settings are persisted across reboots.
The two settings are independent. A WiFi Companion keeps its transports
The three settings are independent. A WiFi Companion keeps its transports
available while device power saving reduces CPU and GPS idle power. An
infrastructure node can sleep when device power saving is enabled, so its WiFi
services may be temporarily unavailable. RXPS only duty-cycles the LoRa
receiver. Fresh Cascade-profile builds default to device power saving on and
RXPS on at level 8 with a 16-symbol preamble.
receiver. Fresh Cascade-profile builds default to device power saving on,
RXPS on at level 8 with a 16-symbol preamble, and WiFi modem power saving at
`min` on every build that includes ESP32 WiFi.
When `ENABLE_OTA` is included, a WiFi companion also listens on:
@@ -223,8 +236,8 @@ When `ENABLE_OTA` is included, a WiFi companion also listens on:
These ports do not replace the companion protocol on TCP 5000.
On a `companion_radio_full` build, port 5002 additionally accepts bounded
`tempradio` and `normalradio` commands, while LoRa staging and installation on
the Companion itself are disabled.
`tempradio`, `normalradio`, and `get/set wifi.powersave` commands, while LoRa
staging and installation on the Companion itself are disabled.
FULL ESP32 builds share the port 5001 folder seeder. It starts whenever that
role has a usable WiFi station or setup access point and stops when WiFi stops.
@@ -395,10 +408,16 @@ set wifi.powersave min
set wifi.powersave max
```
The default is `none`, which gives the most predictable MQTT and radio
performance at the highest power use. `min` and `max` reduce power but may add
latency or reduce reliability on busy nodes. WiFi companions always disable
modem sleep regardless of this observer setting.
Fresh Cascade-profile builds default to `min`; target-default builds use
`none`, which gives the most predictable MQTT and radio performance at the
highest power use. `min` and `max` reduce power but may add latency or reduce
reliability on busy nodes. A saved operator setting takes precedence on an
upgrade. ESP32 WiFi Companions expose the same values in their WebConfig WiFi
card. Full Companion also accepts the text commands from its USB terminal and
TCP port 5002. The normal binary Companion protocol can read or write the
setting over USB, BLE, or TCP port 5000 without entering terminal mode. Full
Companion rejects `none` because its simultaneous BLE transport requires WiFi
modem sleep.
MQTT observer targets normally limit ESP32 WiFi transmit power to 11 dBm unless
the board configuration overrides `MQTT_WIFI_TX_POWER`. This setting affects
@@ -408,7 +427,9 @@ WiFi only, not LoRa transmit power.
`get wifi.status`, `get wifi.ssid`, `get wifi.powersave`, and `get wifi.cli`
are available on MQTT observers and on FULL non-MQTT repeater/room-server
builds with WebConfig.
builds with WebConfig. ESP32 WiFi Companions expose `wifi.powersave` through
their role-specific interfaces described above; they do not expose the full
infrastructure WiFi CLI family.
MQTT commands such as `get mqtt.status` and `set mqtt1.preset ...` still require
an MQTT observer target. Unknown settings return `Error: unknown setting:
<name>`. Older portable builds can instead report `Unsupported in this
+3 -1
View File
@@ -113,7 +113,9 @@ does not exist on that target:
- WebConfig and the `wifi.ssid`, `wifi.status`, `wifi.powersave`, and `wifi.cli` command
family require an ESP32 WebConfig build. FULL standalone repeater and
room-server builds support the corresponding WiFi setters and status
commands.
commands. ESP32 WiFi Companion exposes `wifi.powersave` in its WebConfig
form and binary protocol; Full Companion also exposes the text getter and
setter on its USB terminal and TCP port 5002.
- MQTT commands require an MQTT observer target.
- `discover.scopes` requires an MQTT observer with compiled neighbor support;
it does not independently require PSRAM or the FULL parser.
+11 -1
View File
@@ -201,7 +201,9 @@ SSID, LAN IP, and RSSI. When the shared OTA seeder is running, the reply appends
`OTA TCP 5001: listening` or `OTA TCP 5001: client connected`. WiFi being off
is normal while WebConfig is inactive; run `start webconfig` when a temporary
connection is wanted. `get wifi.powersave` reports the saved standalone setting
as `none`, `min`, or `max`; the default is `none`.
as `none`, `min`, or `max`. Fresh Cascade-profile builds default to `min`;
target-default builds use `none`. A saved setting takes precedence after an
upgrade.
The WiFi `set` commands work on MQTT observers and on FULL standalone
ESP32 repeater/room-server builds. On a standalone build, changing the SSID or
@@ -211,6 +213,14 @@ Power-save changes are applied immediately when WiFi is running and otherwise
take effect on the next connection. `get wifi.pwd` is intentionally unavailable
so the standalone password is never returned by the CLI.
ESP32 WiFi Companion WebConfig exposes the same `wifi.powersave` values in its
WiFi card. Full Companion also accepts `get/set wifi.powersave` from its USB
terminal and TCP port 5002. Binary Companion clients can use command bytes
`0x46` and `0x47` over USB, BLE, or TCP port 5000 without the terminal-start
token. WiFi-only Companions accept all three modes; Full Companion rejects
`none` because its simultaneous BLE transport requires modem sleep. Companion
device `powersaving` and LoRa `radio.rxps` remain independent.
The browser portal is not compiled into the two 4 MB
`LilyGo_TLora_V2_1_1_6_*_observer_mqtt` targets because it does not fit while
retaining the two app slots required for LoRa OTA. Their normal CLI settings
+37
View File
@@ -219,10 +219,47 @@ catalog; bytes `0x2C`-`0x31` are parked and `0x35` is unused.
| `0x3F` / `0x40` | `CMD_SET_DEFAULT_FLOOD_SCOPE` / `CMD_GET_DEFAULT_FLOOD_SCOPE` | Write or read the default flood scope. |
| `0x41` | `CMD_SEND_RAW_PACKET` | Queue a fully encoded raw mesh packet. |
| `0x42` / `0x43` | `CMD_GET_RADIO_FEM_RXGAIN` / `CMD_SET_RADIO_FEM_RXGAIN` | Read or set FEM receive gain. |
| `0x44` / `0x45` | `CMD_GET_RADIO_RXGAIN` / `CMD_SET_RADIO_RXGAIN` | Read or set the radio chip's boosted receive-gain mode. |
| `0x46` / `0x47` | `CMD_GET_WIFI_POWER_SAVE` / `CMD_SET_WIFI_POWER_SAVE` | Read or set ESP32 Companion WiFi modem sleep. |
The sections below detail the most common frames. Refer to the source named
above for command bodies that are not expanded here.
The additive hardware-setting commands `0x42`-`0x47` do not change any existing
version-13 frame layout. Clients should probe the command they need and treat
`ERR_CODE_UNSUPPORTED_CMD` as feature absence.
Both gain-command pairs can be used over the normal binary Companion
connection; USB does not need to enter terminal mode. Inside the transport's
normal Companion frame, send a GET command as its single command byte. Send a
SET command followed by one byte (`0` for off, `1` for on). A GET reply is
`RESP_CODE_OK` followed by the saved state; a successful SET reply is
`RESP_CODE_OK`. Invalid states return `ERR_CODE_ILLEGAL_ARG`. A temporarily
busy radio returns `ERR_CODE_BAD_STATE`; unsupported boosted gain returns
`ERR_CODE_UNSUPPORTED_CMD`. The FEM pair also returns
`ERR_CODE_UNSUPPORTED_CMD` when the board cannot control its external LNA. Raw
text such as `set radio.rxgain off` still requires the USB terminal start token.
The WiFi power-save pair is available on ESP32 WiFi Companion builds over the
normal binary USB, BLE, or TCP port 5000 transport. `CMD_GET_WIFI_POWER_SAVE`
has no body and replies with `RESP_CODE_OK` followed by one mode byte.
`CMD_SET_WIFI_POWER_SAVE` is followed by that mode byte and replies with
`RESP_CODE_OK` after saving it:
| Value | Mode |
|---:|---|
| `0` | `min` - minimum modem sleep |
| `1` | `none` - no modem sleep |
| `2` | `max` - maximum modem sleep |
An out-of-range value returns `ERR_CODE_ILLEGAL_ARG`. A non-WiFi Companion
returns `ERR_CODE_UNSUPPORTED_CMD`. Full Companion has Bluetooth enabled and
therefore returns `ERR_CODE_BAD_STATE` for `none`, because ESP32 WiFi/Bluetooth
coexistence requires modem sleep. A storage failure also returns
`ERR_CODE_BAD_STATE`. If an already-saved mode cannot be applied to the active
WiFi driver, SET still returns `RESP_CODE_OK` and the mode is applied on the
next connection. Device `powersaving` does not overwrite this setting.
### 1. App Start
**Purpose**: Initialize communication with the device. Must be sent first after connection.
+33 -9
View File
@@ -54,6 +54,9 @@ runtime, so the Companion bulk-build commands omit the redundant legacy
boost** switch. From the USB terminal, use:
```text
get radio.rxgain
set radio.rxgain off
set radio.rxgain on
get radio.fem.rxgain
set radio.fem.rxgain off
set radio.fem.rxgain on
@@ -62,8 +65,10 @@ set radio.fem.txgain off
set radio.fem.txgain on
```
The selected states are applied immediately and retained after reboot. FEM TX
gain is reported as unsupported on boards without software-selectable PA gain.
`radio.rxgain` controls the radio chip's boosted receive-gain mode; the FEM
commands control the external receive and transmit paths. The selected states
are applied immediately and retained after reboot. FEM TX gain is reported as
unsupported on boards without software-selectable PA gain.
Device power saving is separate from LoRa RXPS. It can be changed in WebConfig
with the **Device power saving** switch or from the USB terminal:
@@ -74,6 +79,23 @@ powersaving on
powersaving off
```
On ESP32, WiFi modem power saving is a third independent setting. Select it in
the WebConfig **WiFi** card, or use the Full Companion USB terminal or TCP port
5002:
```text
get wifi.powersave
set wifi.powersave min
set wifi.powersave max
```
The normal binary Companion connection can also read or write this setting over
USB, BLE, or TCP port 5000 without entering terminal mode. The saved values are
`0` for `min`, `1` for `none`, and `2` for `max`; see the
[Companion protocol](./companion_protocol.md#commands). Full Companion rejects
`none` because simultaneous WiFi and BLE require modem sleep. Fresh Cascade
builds select `min`, and an existing saved selection takes precedence.
On radios with RX duty-cycle support, WebConfig and the USB terminal also
expose the persisted RXPS setting:
@@ -98,11 +120,12 @@ On ESP32, enabling it lowers the CPU clock to 80 MHz, enables idle yielding,
and enables the configured GPS duty cycle. Disabling it restores the normal CPU
clock and keeps GPS awake. Full Companion transports remain available in both
states; WiFi modem sleep stays enabled when BLE is present because coexistence
requires it. While a native-USB host is enumerated, the platform sleep attempt
is held off so USB CDC remains responsive; detaching the host releases that
guard. CPU, radio-modem, and GPS power-saving settings remain active, and USB
power from a charger alone does not create a Companion session. The selected
state is retained after reboot.
requires it. Changing device power saving does not overwrite the saved WiFi
power-save mode. While a native-USB host is enumerated, the platform sleep
attempt is held off so USB CDC remains responsive; detaching the host releases
that guard. CPU, radio-modem, and GPS power-saving settings remain active, and
USB power from a charger alone does not create a Companion session. The
selected state is retained after reboot.
On the LilyGo T-Beam 1W Full Companion, press the physical `BOOT` button once
to turn the ESP32 WiFi radio and all WiFi services off or on. The screen confirms
@@ -139,7 +162,7 @@ itself.
| ESP32 | TCP 5000 | Binary Companion over WiFi |
| ESP32 | HTTP 80 | Companion WebConfig and first-boot WiFi setup |
| ESP32 | TCP 5001 | Host `.mota` folder from `motatool serve --tcp` |
| ESP32 | TCP 5002 | Local `ota`, `tempradio`, and `normalradio` console |
| ESP32 | TCP 5002 | Local `ota`, `tempradio`, `normalradio`, and `wifi.powersave` console |
| nRF52 | USB mOTA mode | Host `.mota` folder from `motatool serve --serial` |
Delivery-required replies are returned only to the interface which supplied the
@@ -194,7 +217,8 @@ The terminal supports Companion chat commands, including `channels`,
`channel <name-or-slot> <message>`, remote administration with
`login <admin-password>` and `cmd <remote-command>`, and routed
`trace [recipient-name-or-prefix]`, plus local `ota`, `tempradio`, and
`normalradio` controls. For example:
`normalradio` controls. ESP32 builds also provide local
`get/set wifi.powersave`. For example:
```text
channels
+30 -4
View File
@@ -85,16 +85,42 @@ set af {air-time-factor}
Sets the transmit air-time-factor. Deprecated - use `set dutycycle` instead.
```
powersaving
powersaving {on|off}
set powersaving {on|off}
```
Shows or changes Companion device power saving. On ESP32 this controls CPU and
GPS idle behavior; it does not change LoRa RXPS or WiFi modem sleep.
```
get radio.rxps
set radio.rxps {off|on|level 1-10 [preamble 16|32]|rx_us sleep_us}
```
Shows or changes LoRa receive duty cycling on supported radios. Fresh Cascade
builds select level 8 with a 16-symbol preamble.
```
get wifi.powersave
set wifi.powersave {none|min|max}
```
Shows or changes the persisted WiFi modem-sleep policy on ESP32 WiFi Companion
builds. Full Companion requires at least `min` while BLE is present and rejects
`none`. The WebConfig WiFi card and the normal binary Companion protocol expose
the same setting; binary clients do not need the terminal-start token.
```
get radio.rxgain
set radio.rxgain {on|off}
get radio.fem.rxgain
set radio.fem.rxgain {on|off}
get radio.fem.txgain
set radio.fem.txgain {on|off}
```
Shows or changes the external FEM receive-path LNA or transmit-path gain on
`radio.rxgain` changes the radio chip's boosted receive-gain mode. The FEM
settings control the external receive-path LNA or transmit-path gain on
supported boards. Changes are applied immediately and saved across reboots;
changing RX gain also recalibrates the radio noise floor. These settings are
separate from the SX126x `radio.rxgain` setting. Boards without the respective
control report it as unsupported.
changing either receive-gain path also recalibrates the radio noise floor.
Boards without the respective control report it as unsupported.
```