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:
mikecarper committed 2026-08-23 15:29:30 -07:00
1 parent 83c1dd95fe
commit b699e552ec
46 files changed
+4364 -359

No files matched your search

+25 -4
View File
@@ -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.
+3 -2
View File
@@ -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.
+4
View File
@@ -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
View File
@@ -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
+37 -9
View File
@@ -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
+1 -1
View File
@@ -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` |
+182
View File
@@ -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.
+1
View File
@@ -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)
+8 -2
View File
@@ -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
View File
@@ -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
+31
View File
@@ -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>