Add secure host CLI bridge and harden OTA workflows
Expose the Full Companion terminal over TCP and add an authenticated, replay-resistant host command service with documented CPU temperature, reboot, and allowlisted program examples.\n\nImprove LoRa OTA diagnostics and persistent CLI handling, reduce clock correction drift to ten minutes, and make mOTA stream flush behavior an explicit transport policy with regression coverage.
This commit is contained in:
1 parent
83c1dd95fe
commit
b699e552ec
46 files changed
+4364
-359
No files matched your search
+25
-4
@@ -196,6 +196,20 @@ saved credentials take priority. With no credentials, its WebConfig portal
|
||||
starts in setup-AP mode. With credentials, the WebUI is enabled by default on
|
||||
the station IP.
|
||||
|
||||
Full Companion can also be provisioned from its USB terminal or TCP port 5002:
|
||||
|
||||
```text
|
||||
get wifi.ssid
|
||||
get wifi.status
|
||||
set wifi.ssid SlowFi
|
||||
set wifi.pwd your-password
|
||||
```
|
||||
|
||||
Credential writes are persisted immediately. After the reply has drained, the
|
||||
Companion restarts its WiFi station with the saved pair. A port-5002 client is
|
||||
expected to disconnect and can reconnect at the new LAN IP. USB masks the
|
||||
password as it is entered; `get wifi.pwd` is intentionally unavailable.
|
||||
|
||||
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 has its own persisted `wifi.powersave`
|
||||
@@ -232,12 +246,19 @@ RXPS on at level 8 with a 16-symbol preamble, and WiFi modem power saving at
|
||||
When `ENABLE_OTA` is included, a WiFi companion also listens on:
|
||||
|
||||
- TCP 5001 for the OTA folder seeder used by `motatool serve --tcp`;
|
||||
- TCP 5002 for the OTA text console.
|
||||
- TCP 5002 for a text management console.
|
||||
|
||||
These ports do not replace the companion protocol on TCP 5000.
|
||||
On a `companion_radio_full` build, port 5002 additionally accepts bounded
|
||||
`tempradio`, `normalradio`, and `get/set wifi.powersave` commands, while LoRa
|
||||
staging and installation on the Companion itself are disabled.
|
||||
On a `companion_radio_full` build, port 5002 is the same role-specific text
|
||||
terminal available over USB, including chat, remote administration, radio and
|
||||
power settings, WiFi/WebConfig management, `tempradio`, and the source-only
|
||||
`ota` commands. Other
|
||||
OTA-enabled Companion builds keep the bounded `ota ...` console. LoRa staging
|
||||
and installation on the Full Companion itself remain disabled.
|
||||
|
||||
Port 5002 is plaintext and has no independent login gate. Use it only on a
|
||||
trusted LAN or temporary setup network, especially when entering a remote-node
|
||||
admin password with the terminal's `login` command.
|
||||
|
||||
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.
|
||||
|
||||
@@ -92,8 +92,9 @@ does not exist on that target:
|
||||
family require an ESP32 WebConfig build. FULL standalone repeater and
|
||||
room-server builds support the corresponding WiFi setters and status
|
||||
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.
|
||||
form and binary protocol; Full Companion exposes its complete role-specific
|
||||
text terminal over USB and TCP port 5002, including WiFi credentials,
|
||||
connection status, WebConfig, CLI-tab, and power-save controls.
|
||||
- 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.
|
||||
|
||||
@@ -53,6 +53,7 @@ fix, no WiFi connection, an inactive bridge, or an nRF52 bootloader without
|
||||
| Operational | [`erase`](cli_commands.md#erasefactory-reset) | Local serial | Serial | Serial | Serial |
|
||||
| Information | [`ver`](cli_commands.md#get-the-version) | All text CLI roles | Yes | Yes | Yes |
|
||||
| Information | [`board`](cli_commands.md#show-the-hardware-name) | All text CLI roles | Yes | Yes | Yes |
|
||||
| Diagnostics | [`get storage.layout`](cli_commands.md#show-the-storage-layout) | Internal layout and configured QSPI or SD storage | Yes | Yes | Yes |
|
||||
| Diagnostics | [`memory`](#memory) | ESP32 only | No | No | No |
|
||||
| Diagnostics | [`sensor`](#sensor-hardware-summary) | Hardware wiring summary | Yes | Yes | Yes |
|
||||
| Diagnostics | [`powerlog`](#powerlog) | Reset, shutdown, and boot-voltage summary | Yes | Yes | Yes |
|
||||
@@ -87,6 +88,7 @@ fix, no WiFi connection, an inactive bridge, or an nRF52 bootloader without
|
||||
| System | [`get/set owner.info`](cli_commands.md#view-or-change-this-nodes-owner-info) | All text CLI roles | Yes | Yes | Yes |
|
||||
| System | [`get/set adc.multiplier`](cli_commands.md#fine-tune-the-battery-reading) | Board ADC override support | Feature | Feature | Feature |
|
||||
| System | [`send text.flood <message>`](cli_commands.md#send-a-repeater-flood-text) | Repeater | Yes | Yes | Yes |
|
||||
| System | [`host <text>`; `get host`](cli_commands.md#ask-a-usb-connected-host-service-over-lora-repeater-only) | Repeater with host bridge; `host` requires a remote administrator and a USB/MQTT service | Yes | Yes | Yes |
|
||||
| System | [`get/set battery.alert`; `get battery.alert.region`](cli_commands.md#view-or-change-battery-alert-state) | Repeater | Yes | Yes | Yes |
|
||||
| System | [`get/set battery.alert.low`; `get/set battery.alert.critical`](cli_commands.md#view-or-change-battery-alert-thresholds) | Repeater | Yes | Yes | Yes |
|
||||
| System | [`get/set rx.watchdog`](cli_commands.md#enable-or-disable-the-rx-inactivity-watchdog-repeater-only) | Repeater | Yes | Yes | Yes |
|
||||
@@ -213,6 +215,7 @@ fix, no WiFi connection, an inactive bridge, or an nRF52 bootloader without
|
||||
| Operational | [`erase`](cli_commands.md#erasefactory-reset) | Local serial | Serial | Serial | Serial | Serial | Serial |
|
||||
| Information | [`ver`](cli_commands.md#get-the-version) | All text CLI roles | Yes | Yes | Yes | Yes | Yes |
|
||||
| Information | [`board`](cli_commands.md#show-the-hardware-name) | All text CLI roles | Yes | Yes | Yes | Yes | Yes |
|
||||
| Diagnostics | [`get storage.layout`](cli_commands.md#show-the-storage-layout) | Detected flash size and live partition table | Yes | Yes | Yes | Yes | Yes |
|
||||
| Diagnostics | [`memory`](#memory) | ESP32 heap and PSRAM summary | Yes | Yes | Yes | Yes | Yes |
|
||||
| Diagnostics | [`sensor`](#sensor-hardware-summary) | Hardware wiring summary | Yes | Yes | Yes | Yes | Yes |
|
||||
| Diagnostics | [`powerlog`](#powerlog) | Reset-reason summary | Yes | Yes | Yes | Yes | Yes |
|
||||
@@ -247,6 +250,7 @@ fix, no WiFi connection, an inactive bridge, or an nRF52 bootloader without
|
||||
| System | [`get/set owner.info`](cli_commands.md#view-or-change-this-nodes-owner-info) | Full parser | Yes | Yes | Yes | Yes | Yes |
|
||||
| System | [`get/set adc.multiplier`](cli_commands.md#fine-tune-the-battery-reading) | Board ADC override support | Feature | Feature | Feature | Feature | Feature |
|
||||
| System | [`send text.flood <message>`](cli_commands.md#send-a-repeater-flood-text) | Repeater | Yes | Yes | Yes | Yes | Yes |
|
||||
| System | [`host <text>`; `get host`](cli_commands.md#ask-a-usb-connected-host-service-over-lora-repeater-only) | Repeater with host bridge; `host` requires a remote administrator and a USB/MQTT service | Yes | Yes | Yes | Yes | Yes |
|
||||
| System | [`get/set battery.alert`; `get battery.alert.region`](cli_commands.md#view-or-change-battery-alert-state) | Repeater | Yes | Yes | Yes | Yes | Yes |
|
||||
| System | [`get/set battery.alert.low`; `get/set battery.alert.critical`](cli_commands.md#view-or-change-battery-alert-thresholds) | Repeater | Yes | Yes | Yes | Yes | Yes |
|
||||
| System | [`get/set rx.watchdog`](cli_commands.md#enable-or-disable-the-rx-inactivity-watchdog-repeater-only) | Repeater | Yes | Yes | Yes | Yes | Yes |
|
||||
|
||||
+62
-4
@@ -107,6 +107,38 @@ arguments such as node names, passwords, and keys is left unchanged.
|
||||
|
||||
---
|
||||
|
||||
### Ask a USB-connected host service over LoRa (Repeater Only)
|
||||
|
||||
**Usage:**
|
||||
|
||||
- `host <text>` - authenticated remote administrator only
|
||||
- `get host` - show bridge state and byte limits
|
||||
|
||||
`host` hands one remote LoRa CLI request to a service on the repeater's USB
|
||||
host and returns that service's reply over LoRa. It does not execute the text
|
||||
inside the firmware. The service has 4 seconds to prove the exact request is
|
||||
still pending, then 6 seconds to execute and reply. A second remote command
|
||||
receives busy while either phase is pending.
|
||||
|
||||
Request text is limited to 155 UTF-8 bytes, or 152 bytes when a companion uses
|
||||
its legacy three-byte correlation prefix. The complete LoRa reply is limited to
|
||||
162 bytes. USB records use Base64URL text, a random 64-bit nonce, and the
|
||||
repeater identity's Ed25519 signature. Before executing anything, the service
|
||||
must return a random one-time challenge and receive the repeater's signed live
|
||||
proof. This avoids any dependency on repeater/Pi clock agreement. Every
|
||||
`host.reply` USB command must carry the matching request ID and nonce; it is not
|
||||
accepted from LoRa or the Ethernet CLI.
|
||||
|
||||
The included Raspberry Pi endpoint supports exact commands for `help`,
|
||||
`cpu-temp`, `hostname`, `uptime`, `load`, `memory`, and `disk-free`. It also
|
||||
provides `reboot` as an opt-in action example and `run <alias> [arguments]` for
|
||||
locally allowlisted executables with typed arguments. Reboot is disabled by
|
||||
default, arbitrary executables are never accepted, and no action uses a shell.
|
||||
See [LoRa CLI host service](host_cli_service.md) for the complete
|
||||
`meshcoretomqtt` setup and security model.
|
||||
|
||||
---
|
||||
|
||||
### Start or stop an Over-The-Air (OTA) firmware update
|
||||
**Usage:**
|
||||
- `start ota`
|
||||
@@ -214,8 +246,12 @@ 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
|
||||
WiFi card. Full Companion exposes the same role-specific text terminal over
|
||||
USB and TCP port 5002, including the standalone `wifi.ssid`, `wifi.status`,
|
||||
`wifi.powersave`, `wifi.cli`, and WebConfig command families. Credential
|
||||
writes reply before restarting the WiFi station, so a TCP client should expect
|
||||
to reconnect at the new address; USB password input is masked. 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
|
||||
@@ -539,6 +575,28 @@ It also does not change the node-storage capture controlled by `log start` and
|
||||
|
||||
---
|
||||
|
||||
### Show the storage layout
|
||||
**Usage:** `get storage.layout`
|
||||
|
||||
Reports a compact, read-only summary of the storage compiled into the running
|
||||
firmware:
|
||||
|
||||
- ESP32 reports the detected internal flash size and the live partition table.
|
||||
Partition addresses after `@` are hexadecimal, sizes after `+` are KiB, and
|
||||
`*` marks the running application. `...` means later entries did not fit in
|
||||
the CLI reply.
|
||||
- nRF52 reports the physical internal flash size, linked application range,
|
||||
InternalFS range, and any configured external store. Raw QSPI OTA storage
|
||||
includes its detected size and JEDEC ID; SD storage includes total, used, and
|
||||
free space.
|
||||
- RP2040 and STM32 report their fixed internal flash and filesystem geometry.
|
||||
|
||||
The command does not write, format, or resize storage. A raw-QSPI or SD build
|
||||
may briefly probe, wake, or mount its configured external storage to read its
|
||||
capacity. Remote use follows the existing administrator-command permissions.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Radio
|
||||
@@ -953,7 +1011,7 @@ send text.flood checking ridge link
|
||||
- `clock.sync.mesh`: `on` for all repeater, sensor, and room-server builds
|
||||
- `clock.sync.mesh.edge`: `on`
|
||||
- `clock.sync.internet`: `off`
|
||||
- `clock.sync.drift`: `3600` seconds
|
||||
- `clock.sync.drift`: `600` seconds (10 minutes)
|
||||
- `clock.sync.samples`: `9`
|
||||
|
||||
When either source is enabled, the node makes its first clock-bootstrap
|
||||
@@ -1092,7 +1150,7 @@ replays until corrected time passes the previously observed value.
|
||||
|
||||
**Example:**
|
||||
```text
|
||||
set clock.sync.drift 1800
|
||||
set clock.sync.drift 600
|
||||
set clock.sync.samples 3
|
||||
set clock.sync.mesh on
|
||||
set clock.sync.mesh.edge on
|
||||
|
||||
@@ -51,7 +51,7 @@ Heltec `_femon` Companion firmware can switch the external FEM receive gain at
|
||||
runtime, so the Companion bulk-build commands omit the redundant legacy
|
||||
`_femoff` targets. Those targets remain available through an explicit
|
||||
`build-firmware` command for compatibility. In WebConfig, use the **FEM RX
|
||||
boost** switch. From the USB terminal, use:
|
||||
boost** switch. From the text terminal (USB, or TCP 5002 on ESP32), use:
|
||||
|
||||
```text
|
||||
get radio.rxgain
|
||||
@@ -71,7 +71,7 @@ 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:
|
||||
with the **Device power saving** switch or from the text terminal:
|
||||
|
||||
```text
|
||||
powersaving
|
||||
@@ -80,15 +80,28 @@ 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:
|
||||
the WebConfig **WiFi** card, or use the Full Companion text terminal:
|
||||
|
||||
```text
|
||||
get wifi.ssid
|
||||
get wifi.status
|
||||
get wifi.powersave
|
||||
get wifi.cli
|
||||
get webui
|
||||
set wifi.ssid MyNetwork
|
||||
set wifi.pwd my-password
|
||||
set wifi.powersave min
|
||||
set wifi.powersave max
|
||||
set wifi.cli on
|
||||
start webconfig
|
||||
stop webconfig
|
||||
```
|
||||
|
||||
SSID and password writes return their reply first, then restart the Companion
|
||||
WiFi station with the saved credentials. A TCP terminal therefore disconnects
|
||||
shortly after either write; reconnect to the IP reported by the new network.
|
||||
The password is write-only and is masked while it is entered over USB.
|
||||
|
||||
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
|
||||
@@ -96,7 +109,7 @@ USB, BLE, or TCP port 5000 without entering terminal mode. The saved values are
|
||||
`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
|
||||
On radios with RX duty-cycle support, WebConfig and the text terminal also
|
||||
expose the persisted RXPS setting:
|
||||
|
||||
```text
|
||||
@@ -172,7 +185,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`, `normalradio`, and `wifi.powersave` console |
|
||||
| ESP32 | TCP 5002 | Full Companion text terminal; same role commands as the USB terminal |
|
||||
| nRF52 | USB mOTA mode | Host `.mota` folder from `motatool serve --serial` |
|
||||
|
||||
Delivery-required replies are returned only to the interface which supplied the
|
||||
@@ -201,7 +214,7 @@ ESP32 ports 5000, 5001, 5002, and WebConfig have no independent login layer.
|
||||
Expose them only on a trusted LAN or temporary setup network. See
|
||||
[WiFi setup](./WiFi.md) for credential setup and reconnect behavior.
|
||||
|
||||
## USB Binary and terminal modes
|
||||
## USB Binary and text terminal modes
|
||||
|
||||
USB starts in Binary mode for MeshCore apps and `meshcli`:
|
||||
|
||||
@@ -228,9 +241,24 @@ The terminal supports Companion chat commands, including `channels`,
|
||||
`login <admin-password>` and `cmd <remote-command>`, and routed
|
||||
`trace [recipient-name-or-prefix]`, plus local `ota`, `tempradio`, and
|
||||
`normalradio` controls. ESP32 builds also provide local
|
||||
`get/set wifi.powersave`. Logging artifacts additionally provide session-only
|
||||
WiFi credential, status, WebConfig, CLI-tab, and power-save controls. Logging
|
||||
artifacts additionally provide session-only
|
||||
`get/set usb.logging`; turning it off suppresses live USB diagnostics without
|
||||
disabling Companion frames or terminal replies. For example:
|
||||
disabling Companion frames or terminal replies.
|
||||
|
||||
ESP32 Full Companion exposes this same text terminal on TCP port 5002. Connect
|
||||
with `nc DEVICE_IP 5002`; no USB control token is needed. USB terminal mode and
|
||||
the TCP terminal share recipient, login, command, trace, and display state, so
|
||||
only one may own the terminal at a time. Entering USB terminal mode closes an
|
||||
active TCP terminal session. Disconnecting TCP clears pending terminal-only
|
||||
state without cancelling Binary Companion delivery or radio retries.
|
||||
|
||||
Port 5002 is plaintext and has no device-local login gate. A remote-admin
|
||||
password entered with `login` is sent across the LAN connection as typed even
|
||||
though the terminal does not echo it. Use port 5002 only on a trusted LAN or a
|
||||
temporary setup network.
|
||||
|
||||
For example:
|
||||
|
||||
```text
|
||||
channels
|
||||
|
||||
@@ -90,7 +90,7 @@ set flood.retry.ignore none
|
||||
| `clock.sync.mesh` | Defaults on for all repeater, sensor, and room-server builds; a saved setting overrides that default. It estimates UTC as soon as the configured number of fresh signed-advert or valid Public-channel sources is collected, with a 30-minute bootstrap/retry timer when evidence is still insufficient, then repeats lazily seven days after each successful estimate. New evidence retriggers evaluation after a no-consensus result. `clock.sync.mesh now` queues an immediate LoRa-only attempt without bypassing quorum or source suppression. Only timestamps from firmware build time through build time plus ten years are recorded. Successful CLI, GPS, or WiFi/NTP clock updates suppress LoRa time collection until reboot; after reboot LoRa is the fallback if NTP cannot sync. Status reports the reason a clock was not set; its `.table` and `.1` through `.16` forms inspect collected samples. | `get clock.sync.mesh`, `set clock.sync.mesh <on|off>`, `clock.sync.mesh now`, `get clock.sync.status[.table|.1-.16]` | `set clock.sync.mesh on` |
|
||||
| `clock.sync.mesh.edge` | Defaults on so edge infrastructure nodes can collect clock evidence when all packets arrive through one relay path. Verified evidence is observed before the forwarding decision, so disabled forwarding and forwarding filters do not prevent collection. Signed adverts are deduplicated by public key and Public-channel timestamps by case-insensitive display name; all may share one receive path. Public display names are unauthenticated and can be spoofed. Changing this setting clears current clock samples. | `get clock.sync.mesh.edge`, `set clock.sync.mesh.edge <on|off>` | `set clock.sync.mesh.edge on` |
|
||||
| `clock.sync.internet` | Adds a read-only internet/NTP estimate at the same initial and seven-day checks on WiFi MQTT repeater-observer builds. Other builds retain the setting but report internet unavailable. | `get clock.sync.internet`, `set clock.sync.internet <on|off>` | `set clock.sync.internet on` |
|
||||
| `clock.sync.drift` | Absolute correction threshold in seconds. The clock is moved forward or backward only when the estimate differs by more than this value. | `get clock.sync.drift`, `set clock.sync.drift <30-86400>` | `set clock.sync.drift 3600` |
|
||||
| `clock.sync.drift` | Absolute correction threshold in seconds; the default is 600 seconds (10 minutes). The clock is moved forward or backward only when the estimate differs by more than this value. | `get clock.sync.drift`, `set clock.sync.drift <30-86400>` | `set clock.sync.drift 600` |
|
||||
| `clock.sync.samples` | Minimum fresh evidence count before mesh time can be used: distinct receive paths in normal mode or distinct advert keys/Public-channel display names in edge mode. A strict majority of all fresh samples is also required. Range `3-16`; default `9`. | `get clock.sync.samples`, `set clock.sync.samples <3-16>` | `set clock.sync.samples 9` |
|
||||
| `outpath` | Overrides the primary direct route used for replies to the current remote client. | `get outpath`, `set outpath <hops>`, `set outpath direct`, `set outpath clear`, `set outpath flood` | `set outpath A1B2C3,D4E5F6` |
|
||||
| `altpath` | Adds a secondary direct route for repeater replies to the current remote client. | `get altpath`, `set altpath <hops>`, `set altpath direct`, `set altpath clear`, `set altpath flood` | `set altpath 71CE82,BA09F0` |
|
||||
|
||||
@@ -0,0 +1,182 @@
|
||||
# LoRa CLI Host Service
|
||||
|
||||
The repeater `host <text>` command lets an authenticated LoRa administrator
|
||||
request a small, explicitly allowed operation from a USB-connected computer.
|
||||
The included Raspberry Pi endpoint supports these exact requests:
|
||||
|
||||
```text
|
||||
cmd host help
|
||||
cmd host cpu-temp
|
||||
cmd host hostname
|
||||
cmd host uptime
|
||||
cmd host load
|
||||
cmd host memory
|
||||
cmd host disk-free
|
||||
cmd host reboot
|
||||
cmd host run <alias> [arguments]
|
||||
```
|
||||
|
||||
The first six actions after `help` are read-only. `reboot` is an opt-in action
|
||||
example and is disabled unless the endpoint is started with `--allow-reboot`.
|
||||
Text such as `reboot now`, `cpu-temp; reboot`, and embedded newlines is not a
|
||||
command: the endpoint accepts only an exact allowlist match.
|
||||
|
||||
The bridge is included in normal repeater firmware. The specialized Wio-E5
|
||||
RS232 bridge image omits it because the RS232 application already fills its
|
||||
fixed 240 KiB application partition; use the normal Wio-E5 repeater image when
|
||||
the USB/MQTT host service is needed.
|
||||
|
||||
## Run alongside meshcoretomqtt
|
||||
|
||||
`meshcoretomqtt` must remain the only process that opens the repeater USB serial
|
||||
port. The endpoint communicates with it through the same MQTT broker, which can
|
||||
be local to the Raspberry Pi:
|
||||
|
||||
```text
|
||||
LoRa -> repeater -> USB -> meshcoretomqtt -> MQTT -> host endpoint
|
||||
LoRa <- repeater <- USB <- meshcoretomqtt <- MQTT <- host endpoint
|
||||
```
|
||||
|
||||
Launch `meshcoretomqtt` with its existing arguments plus `--debug`; its current
|
||||
debug-topic parser needs that flag to publish the repeater request record. Do
|
||||
not open the serial TTY from the host endpoint too.
|
||||
|
||||
This feature does not compare the repeater wall clock with the Pi clock.
|
||||
Minutes of drift, an unset repeater clock, and later clock corrections are safe:
|
||||
request freshness comes from a live one-time challenge. The normal
|
||||
`meshcoretomqtt` `sync_time` setting may remain enabled for its other uses, but
|
||||
host-command authorization does not depend on it.
|
||||
|
||||
Generate a dedicated service key using the Python environment installed by
|
||||
`meshcoretomqtt`:
|
||||
|
||||
```sh
|
||||
sudo /opt/mctomqtt/venv/bin/python3 host_cli_service.py \
|
||||
--generate-key /etc/mctomqtt/host-cli-key.json
|
||||
sudo chown mctomqtt:mctomqtt /etc/mctomqtt/host-cli-key.json
|
||||
sudo chmod 600 /etc/mctomqtt/host-cli-key.json
|
||||
```
|
||||
|
||||
Add the printed public key to the existing `meshcoretomqtt` configuration:
|
||||
|
||||
```toml
|
||||
[remote_serial]
|
||||
enabled = true
|
||||
allowed_companions = [
|
||||
"SERVICE_PUBLIC_KEY_PRINTED_ABOVE"
|
||||
]
|
||||
nonce_ttl = 120
|
||||
command_timeout = 10
|
||||
```
|
||||
|
||||
Restart `meshcoretomqtt`, then run the endpoint. Replace `USA` with the exact
|
||||
three-character IATA namespace configured in the broker and supply the
|
||||
repeater's complete 64-character public key:
|
||||
|
||||
```sh
|
||||
sudo -u mctomqtt /opt/mctomqtt/venv/bin/python3 host_cli_service.py \
|
||||
--broker 127.0.0.1 \
|
||||
--iata USA \
|
||||
--repeater-key REPEATER_PUBLIC_KEY \
|
||||
--service-key /etc/mctomqtt/host-cli-key.json
|
||||
```
|
||||
|
||||
Add `--username NAME --password-file FILE` for broker authentication. Add
|
||||
`--tls`, and optionally `--ca-cert FILE`, for TLS. Custom installations can use
|
||||
`--request-topic` and `--command-topic` to match their broker namespace. The
|
||||
endpoint source and its systemd/configuration details are in
|
||||
[`examples/host_cli_service`](https://github.com/mikecarper/MeshCore/tree/keymindCascade/examples/host_cli_service).
|
||||
|
||||
## Allowlisted programs and arguments
|
||||
|
||||
Add `--programs-file FILE` to expose locally selected programs as
|
||||
`host run <alias> [arguments]`. The example JSON file fixes each executable,
|
||||
fixed leading arguments, maximum 1-5 second runtime, and the exact remote
|
||||
argument schema. For example:
|
||||
|
||||
```text
|
||||
cmd host run fan on 15
|
||||
```
|
||||
|
||||
The example maps that request to the fixed process argument vector:
|
||||
|
||||
```text
|
||||
/usr/local/bin/mesh-fan-control --source lora on 15
|
||||
```
|
||||
|
||||
The supported argument rules are an explicit non-option `choice`, a bounded
|
||||
nonnegative `integer`, or a short `token` using a restricted ASCII character
|
||||
set. Alias lookup and every argument validation happen before process creation.
|
||||
Execution uses an absolute configured path, no stdin, `shell=False`, a minimal
|
||||
environment, and `/` as its working directory. Extra arguments, leading-option
|
||||
injection, shell syntax, control characters, and invalid quoting are rejected.
|
||||
The allowlist file and executable must not be group- or world-writable.
|
||||
|
||||
Copy and edit
|
||||
[`programs.example.json`](https://github.com/mikecarper/MeshCore/blob/keymindCascade/examples/host_cli_service/programs.example.json),
|
||||
then give the service account only the operating-system permissions needed by
|
||||
those trusted programs.
|
||||
|
||||
## Opt-in reboot example
|
||||
|
||||
To enable only the exact `host reboot` action, give the service account narrow
|
||||
permission in `/etc/sudoers.d/meshcore-host-cli`:
|
||||
|
||||
```text
|
||||
mctomqtt ALL=(root) NOPASSWD: /usr/bin/systemctl reboot
|
||||
```
|
||||
|
||||
Set that file to mode `440`, test it locally, and add `--allow-reboot` to the
|
||||
endpoint command. Its default response is `OK - host reboot scheduled in 5s`.
|
||||
The delay can be set from 3 through 60 seconds with `--reboot-delay`.
|
||||
|
||||
The implementation always invokes the fixed argument vector
|
||||
`/usr/bin/sudo -n /usr/bin/systemctl reboot`; no LoRa text is placed in a shell,
|
||||
path, or process argument. Do not grant the service account a wildcard sudo
|
||||
rule.
|
||||
|
||||
## Trust and injection controls
|
||||
|
||||
The MQTT broker transports records but does not establish their authenticity.
|
||||
The endpoint checks the configured repeater identity and verifies its Ed25519
|
||||
signature over the complete request ID, random nonce, and Base64URL request. It
|
||||
also validates framing, UTF-8, and byte limits. It does not execute that first
|
||||
record.
|
||||
|
||||
Instead, the endpoint stores the request in memory, creates a random 64-bit
|
||||
challenge, and sends `@claim=<random>` through `meshcoretomqtt`'s signed serial
|
||||
channel. The repeater accepts it only from physical USB while the exact ID and
|
||||
nonce are pending, then signs a `CLAIMED` proof containing the challenge. Only
|
||||
a matching live proof lets the endpoint perform allowlist matching and execute
|
||||
the action. It consumes the proof before execution, so MQTT redelivery cannot
|
||||
execute an action twice.
|
||||
|
||||
A captured request only causes a new challenge that an idle repeater refuses.
|
||||
A captured proof does not match a new challenge, and restarting the endpoint
|
||||
forgets pending challenges. Repeater/Pi clock drift therefore cannot turn an
|
||||
old `reboot` or `run` record into a valid action. The reply and claim commands
|
||||
still use short-lived JWTs; `meshcoretomqtt` checks their signer allowlist,
|
||||
target, expiration, signature, and separate replay nonce. If the endpoint and
|
||||
`meshcoretomqtt` are on different computers, those two host clocks must be
|
||||
compatible for JWT validation. They naturally share a clock when both run on
|
||||
the same Pi.
|
||||
|
||||
Newlines and other reply control characters are converted to spaces and are
|
||||
also independently rejected by the firmware parser.
|
||||
|
||||
Protect the service private key and use broker ACLs that allow it to subscribe
|
||||
only to the selected repeater debug topic and publish only to that repeater
|
||||
serial-command topic. A private key listed in `allowed_companions` is trusted to
|
||||
sign serial requests.
|
||||
|
||||
## Limits
|
||||
|
||||
- The request is at most 155 UTF-8 bytes after `host `, or 152 bytes with the
|
||||
legacy three-byte companion correlation prefix.
|
||||
- The complete LoRa reply is at most 162 UTF-8 bytes.
|
||||
- Only one host request can be pending per repeater.
|
||||
- The live claim must complete within 4 seconds; after it is accepted, the
|
||||
program and reply have 6 seconds.
|
||||
- `host.reply` is accepted only through physical USB, not LoRa or Ethernet.
|
||||
|
||||
Use `cmd get host` to report the bridge state and limits.
|
||||
@@ -7,6 +7,7 @@ Below are a few quick start guides.
|
||||
- [Frequently Asked Questions](./faq.md)
|
||||
- [Firmware Picker](./firmware_picker.md)
|
||||
- [CLI Commands](./cli_commands.md)
|
||||
- [LoRa CLI Host Service](./host_cli_service.md)
|
||||
- [Filter Policy Playground](./filter_tool.md)
|
||||
- [Telemetry Decoder](./telemetry_decoder.md)
|
||||
- [CLI Availability by Firmware Build](./cli_build_matrix.md)
|
||||
|
||||
@@ -343,8 +343,11 @@ An ESP32 `companion_radio_full` uses WiFi for both dedicated source links:
|
||||
```
|
||||
|
||||
Port 5002 defaults automatically when it is omitted from
|
||||
`--source-cli-tcp`. The source-only Companion never stages or installs the
|
||||
image itself; it streams the host folder to other nodes over LoRa. See the
|
||||
`--source-cli-tcp`. Current Full Companion firmware exposes its complete
|
||||
role-specific text terminal there; the runner uses only `ota`, `tempradio`,
|
||||
and `normalradio`, and remains compatible with older bounded port-5002
|
||||
consoles. The source-only Companion never stages or installs the image itself;
|
||||
it streams the host folder to other nodes over LoRa. See the
|
||||
[full Companion guide](./companion_radio_full.md) for manual operation and
|
||||
interface details.
|
||||
|
||||
@@ -412,6 +415,9 @@ Useful controls:
|
||||
restores both values before the relay leaves TempRadio.
|
||||
- `--work-dir PATH` chooses a new, non-existent work directory.
|
||||
- `--meshcli PATH` and `--motatool PATH` select binaries not on `PATH`.
|
||||
- `--debug` prints redacted child commands, timeouts, process status, stdout,
|
||||
and stderr. Admin passwords are never printed, but node names, addresses,
|
||||
paths, and command replies can still be sensitive; share the log carefully.
|
||||
|
||||
For offline package preparation only:
|
||||
|
||||
|
||||
+3
-2
@@ -134,8 +134,9 @@ motatool serve --dir ./motas --tcp <source-host>:5001 -v
|
||||
|
||||
Port `5001` is separate from the companion application port (`5000`) and the
|
||||
HTTP configuration/browser-OTA port (`80`, depending on the role). An ESP32
|
||||
`companion_radio_full` also has a local OTA/TempRadio console on port `5002`;
|
||||
see the [full Companion guide](./companion_radio_full.md). On a FULL repeater or room
|
||||
`companion_radio_full` also has its complete role-specific text terminal on
|
||||
port `5002`; OTA automation uses its `ota` and TempRadio subset. See the
|
||||
[full Companion guide](./companion_radio_full.md). On a FULL repeater or room
|
||||
server, `start webconfig` can bring up the saved WiFi connection. Other FULL
|
||||
roles with browser OTA support can raise `MeshCore-OTA` with `start ota` and
|
||||
use `192.168.4.1:5001`. The TCP seeder auto-attaches; do not also run
|
||||
|
||||
@@ -11,6 +11,37 @@ repeater's public key. Match that 16-character hex value against the public-key
|
||||
prefix recorded for your repeaters. It comes from the telemetry payload itself,
|
||||
so it is available even when only the payload was copied.
|
||||
|
||||
## Send raw telemetry packets
|
||||
|
||||
From an administrator CLI session, first configure a direct route to the MQTT
|
||||
observer that will receive and upload the raw packets. Use `direct` when the
|
||||
observer is a zero-hop neighbor:
|
||||
|
||||
```text
|
||||
set telemetry.tx direct
|
||||
send telemetry.tx now
|
||||
```
|
||||
|
||||
For a routed observer, provide its comma-separated hop hashes instead:
|
||||
|
||||
```text
|
||||
set telemetry.tx A1B2,C3D4
|
||||
send telemetry.tx now
|
||||
```
|
||||
|
||||
Configuring the route also enables the default two-day schedule. To keep the
|
||||
route but use it only for manual tests, turn off the schedule before sending:
|
||||
|
||||
```text
|
||||
set telemetry.tx schedule off
|
||||
send telemetry.tx now
|
||||
```
|
||||
|
||||
The `send telemetry.tx now` command queues one `TTB1` temperature packet and
|
||||
one `TVB1` voltage packet containing all currently available samples, up to 165
|
||||
per packet. There is no temperature-only CLI command. The command requires at
|
||||
least one collected sample and works even when the automatic schedule is off.
|
||||
|
||||
## Decode a packet
|
||||
|
||||
<div class="telemetry-tool" data-telemetry-decoder>
|
||||
|
||||
Reference in new issue
Block a user