Expose Companion WiFi and radio power controls
This commit is contained in:
1 parent
818f610ba3
commit
0c4619bcc3
27 files changed
+1840
-1349
No files matched your search
+34
-13
@@ -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
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
```
|
||||
|
||||
Reference in new issue
Block a user