rich/MeshCore
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add WebConfig CLI and standalone WiFi controls

Browse Source
This commit is contained in:
mikecarper committed 2026-07-31 01:19:17 -07:00
1 parent 7bbde76380
commit 3f5e497ca6
24 files changed
+2698 -1224
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/WiFi.md
+70 -10
View File
@@ -133,6 +133,7 @@ Useful checks are:
get wifi.ssid
get wifi.status
get wifi.powersave
get wifi.cli
get bridge.enabled
get mqtt.rx
get mqtt.tx
@@ -217,6 +218,17 @@ removes the TCP folder. Port 5001 has no login layer, so expose it only on a
trusted LAN or temporary setup network. Firmware target and hash checks still
apply at the receiving node, along with its configured signature/trust policy.
When the shared seeder is running, `get wifi.status` appends its live state:
```text
OTA TCP 5001: listening
OTA TCP 5001: client connected
```
The first state means WiFi is usable and the node is waiting for
`motatool serve --tcp`. The second means a `motatool` folder is currently
attached and available for LoRa OTA service.
## WiFi companion with MQTT
A `*_companion_radio_wifi_mqtt` build combines both systems:
@@ -244,26 +256,73 @@ disconnects WiFi and turns the WiFi radio off. There is no persistent MQTT
connection keeping WiFi active.
FULL standard and FULL logging repeater/room-server builds provide these
read-only CLI checks even though they do not include MQTT:
CLI controls and status checks even though they do not include MQTT:
```text
get wifi.ssid
get wifi.status
get wifi.powersave
get wifi.cli
get webui
set wifi.ssid SlowFi
set wifi.pwd your-password
set wifi.powersave none
set wifi.cli on
```
`get wifi.status` distinguishes an unconfigured node, an inactive WiFi radio, a
station connection attempt, the setup AP, a connection failure, and a working
LAN connection. For a LAN connection it reports the SSID, IP address, and RSSI.
If the shared OTA seeder is active, the same reply also reports whether TCP
port 5001 is listening or has a `motatool` client attached.
`get wifi.powersave` reports the saved standalone WebConfig setting as `none`,
`min`, or `max`.
An inactive status is normal when `webui` is off: run `start webconfig` to
connect temporarily. Change standalone WiFi credentials through WebConfig;
the MQTT observer `set wifi.*` CLI belongs to observer builds.
connect temporarily. Standalone credentials can be changed through WebConfig
or with the listed CLI commands. Changing the SSID or password stops an active
WebConfig session; start it again to connect with the new values. Use
`set wifi.pwd` with no value for an open network. The password is write-only
and is never returned by `get`.
`get webui` starts with the saved boot setting, then reports the current
session. For example, `> off, http://192.168.1.130/` means automatic WebConfig
startup is saved as off, but a temporary session started by `start webconfig`
is currently active at that URL.
### WebConfig CLI terminal
The terminal defaults to on. Enable or disable it from an existing admin CLI:
```text
set wifi.cli on
set wifi.cli off
get wifi.cli
```
The saved `on` setting becomes active only when the WiFi station client is
connected and WebConfig is running in LAN mode. It is never exposed on the open
setup access point. When active, the WebConfig page has a **CLI** tab for sending
commands directly to the repeater or room server. It uses the local
administrator command parser and displays one reply at a time. The terminal is
protected by the WebConfig admin login and uses remote-administrator
permissions, so commands explicitly restricted to a physical serial connection
remain unavailable.
Use **Single command** for the normal prompt, or select **Command block** to
paste up to 100 commands with one command per line. Blank lines are ignored.
The browser validates all lines first, then sends one command at a time and
waits for its reply before sending the next. The block queue is kept in the
browser only, so closing the page or losing its WiFi connection stops the
commands that have not yet been sent. Ctrl+Enter or Command+Enter starts a
block.
The up/down arrow keys recall commands entered during the current browser
session in single-command mode. Commands available in the terminal still
depend on the firmware role and build profile. Commands such as
`stop webconfig`, `set wifi.cli off`, WiFi credential changes, and reboot
operations stop the remaining block and can disconnect the page before it
receives their final reply.
## Build profiles
`build.sh` produces several profiles. A profile changes the features compiled
@@ -292,7 +351,7 @@ updates using the same layout normally preserve them.
## WiFi power behavior
MQTT observers support:
MQTT observers and FULL standalone ESP32 repeater/room-server builds support:
```text
set wifi.powersave none
@@ -311,12 +370,13 @@ WiFi only, not LoRa transmit power.
## Recognizing the wrong firmware
`get wifi.status` and `get wifi.ssid` are available on MQTT observers and on
FULL non-MQTT repeater/room-server builds with WebConfig. MQTT commands such as
`get mqtt.status` and `set mqtt1.preset ...` still require an MQTT observer
target. If the response is `Unsupported in this firmware`, the running image
does not contain that configuration command, or it is not the expected target.
Older portable builds report the same condition as `unknown portable config`.
`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.
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
firmware` when a command was intentionally cut for space.
Check the complete firmware filename and role. In particular:
docs/cli_build_matrix.md
+115
View File
@@ -0,0 +1,115 @@
# CLI Availability by Firmware Build
MeshCore command availability is determined in three layers:
1. **Role** - repeater, room server, sensor, companion, bridge, or KISS modem.
2. **Build profile** - standard, portable, logging, OTA, or FULL.
3. **Compiled hardware features** - WiFi, MQTT, GPS, external sensors, PSRAM,
Ethernet, and similar optional support.
The complete command descriptions are in [CLI Commands](cli_commands.md). This
page describes the commands intentionally omitted or limited by build profile.
## Role comes first
| Role | Text administration CLI |
|---|---|
| Repeater | Full repeater administration surface, subject to the profile differences below |
| Room server | Room-server administration surface, subject to the profile differences below |
| Sensor | Sensor command surface; it does not acquire the repeater administration tree |
| Serial, USB, BLE, or WiFi companion | Uses the companion protocol; any serial diagnostics are target-specific |
| KISS modem | Uses the KISS/TNC frame interface, not the repeater text CLI |
| Bridge | Uses its base role plus commands for the bridge transport compiled into that target |
A command belonging to a different role is not considered a profile cut. For
example, adding FULL features to a sensor does not turn it into a repeater
administrator.
## Profile matrix
| Build/profile | Command availability |
|---|---|
| Standard non-MQTT repeater or room server | Keeps the normal role CLI. Size-constrained ESP32 artifacts can omit WebConfig and browser WiFi OTA, so their WebConfig/WiFi commands are unavailable. |
| Standard logging | Logging does not remove commands by itself. It has the same CLI as the selected role/profile and adds the compiled logging behavior. |
| LoRa-OTA (`-ota-`) | LoRa OTA adds the `ota ...` commands; it does not otherwise reduce the role CLI. A portable OTA artifact can still have the portable restrictions described below. |
| Portable MQTT observer | Keeps MQTT/WiFi commissioning, bridge control, radio essentials, update commands, basic identity/status commands, `neighbors`, and `discover.neighbors`. The large repeater administration tree is omitted to fit the legacy ESP32 application slot. |
| Portable ESP-NOW bridge | Keeps the repeater's role-specific handlers and a reduced common configuration surface containing radio and bridge essentials. |
| FULL ESP32 | Removes size-based CLI cuts and restores the complete command surface supported by the role and hardware. |
| FULL ESP32 logging | Same command coverage as FULL ESP32, with debug and packet logging enabled. |
| `no_external_sensors` | Removes optional external-sensor drivers and their settings; it does not remove core repeater discovery or routing commands. |
`logging`, `OTA`, and `FULL` describe independent build features. Do not infer
that a command is missing merely because `logging` appears in the filename.
## Portable MQTT observer retained surface
The portable MQTT observer keeps these command groups:
- lifecycle and identity: `reboot`, `poweroff`, `shutdown`, `ver`, `board`,
`password`, and `erase` on the local console;
- radio operation: `advert`, `advert.zerohop`, `clock`, `clock sync`, `time`,
`memory`, `neighbors`, and `discover.neighbors`;
- browser/update control when compiled: `start ota`, `stop ota`, `ota check`,
and `ota update`;
- radio essentials through `get`/`set`: radio parameters, TX power, CAD,
interference threshold, AGC reset interval, RX gain, repeat state, and
applicable FEM controls;
- MQTT, WiFi, NTP, bridge, and alert commands implemented by the observer
feature set;
- region and onboard-GPS commands that fit and are compiled into the selected
target.
Everything in the repeater-only administration tree that is not listed above is
intentionally cut from this portable profile. The main omissions include ACL
editing, flood filter/moderation/scope administration, advanced mesh-clock
controls, recent-repeater/path administration, battery-alert/RX-watchdog
controls, stored-log management, and external-sensor administration. Use the
matching FULL ESP32 build when those commands are required.
Some observer commands have their own hardware limit:
- `discover.scopes` and MQTT neighbor-table publishing require PSRAM.
- `discover.neighbors` does **not** require MQTT or PSRAM.
- full NTP connectivity diagnostics are omitted from the portable profile.
## Discovery invariant
`discover.neighbors` sends the zero-hop node-discovery request used to refresh
the repeater neighbor table. It is available in every repeater build profile,
including portable MQTT, standard, logging, OTA, FULL, and FULL logging builds.
The exact command is:
```text
discover.neighbors
```
It accepts no options and returns:
```text
OK - Discover sent
```
Some MQTT room-server targets also expose the command as part of their compiled
neighbor-table feature. It is not a cross-role guarantee: companion, KISS,
sensor, and ordinary room-server firmware use different interfaces or do not
maintain the repeater administrator neighbor table.
## Feature-dependent commands
Even in a FULL build, a command can be unavailable when its underlying feature
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.
- MQTT commands require an MQTT observer target.
- `discover.scopes` requires MQTT neighbor support and PSRAM.
- GPS and external-sensor commands require their drivers and pins.
- Ethernet and bridge commands require the corresponding transport.
- LoRa OTA commands require an artifact with OTA enabled.
- `uf2reset` applies only to nRF52.
When diagnosing an unavailable command, check the role first, then the filename
profile, and finally the target's compiled hardware features.
docs/cli_commands.md
+55 -6
View File
@@ -2,6 +2,10 @@
This document provides an overview of CLI commands that can be sent to MeshCore Repeaters, Room Servers and Sensors.
See [CLI Availability by Firmware Build](cli_build_matrix.md) for the role and
profile matrix, including the commands intentionally omitted from portable
firmware.
The first word of a command is case-insensitive, so `set`, `Set`, and `SET`
are equivalent, as are `get`, `Get`, and the other command verbs. The case of
arguments such as node names, passwords, and keys is left unchanged.
@@ -134,6 +138,12 @@ folder transport.
- `get webui`
- `get wifi.ssid`
- `get wifi.status`
- `get wifi.powersave`
- `get wifi.cli`
- `set wifi.ssid <network name>`
- `set wifi.pwd [password]`
- `set wifi.powersave <none|min|max>`
- `set wifi.cli <on|off>`
`set webui on` is the persistent master switch. It starts the portal now and
again after future reboots; `set webui off` closes it and disables that boot
@@ -152,17 +162,50 @@ WiFi SSID, the command starts the open `MeshCore-Setup-XXXX` captive AP at
<http://192.168.4.1/> instead.
`start webconfig ap` forces captive-AP mode. It will not interrupt an active
MQTT bridge, so run `set bridge off` first. Use `stop webconfig` to close either
mode for the current boot. (`stop webconfig` does not change a saved `webui on`.)
MQTT bridge, so run `set bridge.enabled off` first. Use `stop webconfig` to
close either mode for the current boot. (`stop webconfig` does not change a
saved `webui on`.)
LAN mode otherwise remains active until reboot; setup mode stops after 10 minutes
with no connected client.
The saved `wifi.cli` setting defaults to `on`. Use `set wifi.cli off` to disable
the **CLI** tab.
`get wifi.cli` reports `off`, `on, waiting for WiFi client`, or `on, active`.
The saved setting becomes active only in station/LAN mode while the WiFi client
is connected. It is deliberately unavailable on the open setup access point.
The tab sends one command at a time through the local administrator command
parser and displays the reply in the browser. It uses remote-administrator
command permissions, so commands explicitly restricted to a physical serial
connection remain unavailable.
Select **Command block** to paste up to 100 commands with one command per line.
Blank lines are ignored, and every nonblank line must fit the normal 159-byte
CLI command limit. The browser sends the lines sequentially and waits for each
reply before sending the next line. The queue exists only in that browser page;
closing it stops any commands that have not yet been sent. A lost connection
also stops the remaining block.
Up/down arrow keys recall commands from the current browser session in
single-command mode. A command that stops WebConfig, changes its WiFi
connection, disables `wifi.cli`, or reboots the node stops the remaining block
and can close the page before its reply is collected.
On FULL standard and FULL logging ESP32 repeater/room-server builds,
`get wifi.ssid` reports the saved standalone WebConfig network and
`get wifi.status` reports whether WiFi is unconfigured, off, connecting,
running the setup AP, failed, or connected. A connected result includes the
SSID, LAN IP, and RSSI. WiFi being off is normal while WebConfig is inactive;
run `start webconfig` when a temporary connection is wanted.
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`.
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
password stops an active WebConfig session; run `start webconfig` again to use
the new credentials. `set wifi.pwd` with no value selects an open network.
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.
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
@@ -207,6 +250,10 @@ remain available.
**Usage:**
- `discover.neighbors`
This command is available in every repeater build profile, including portable
MQTT, standard, logging, OTA, FULL, and FULL logging artifacts. It does not
require MQTT or PSRAM.
---
### Discover neighbor scopes (MQTT observer, PSRAM only)
@@ -1017,7 +1064,7 @@ hardware busy-result count.
---
#### View or change the radio watchdog interval
#### View or change the radio watchdog interval (MQTT observer only)
**Usage:**
- `get radio.watchdog`
- `set radio.watchdog <minutes>`
@@ -1027,7 +1074,9 @@ hardware busy-result count.
**Default:** `5`
**Note:** On quiet meshes, increasing this can reduce false recoveries when no traffic is expected.
**Note:** This watchdog belongs to the MQTT observer runtime and is not
available on a standalone FULL repeater. On quiet meshes, increasing it can
reduce false recoveries when no traffic is expected.
---
docs/index.md
+1
View File
@@ -6,6 +6,7 @@ Below are a few quick start guides.
- [Frequently Asked Questions](./faq.md)
- [CLI Commands](./cli_commands.md)
- [CLI Availability by Firmware Build](./cli_build_matrix.md)
- [Easy LoRa OTA: ESP32 full images and nRF52 deltas](./ota_easy.md)
- [GPS Tracking](./gps_tracking.md)
- [Companion Protocol](./companion_protocol.md)