1080 lines
54 KiB
Markdown
1080 lines
54 KiB
Markdown
<!-- meshcore-hosted-doc-link:start -->
|
||
<p class="meshcore-hosted-doc-link"><a href="https://mikecarper.github.io/MeshCore/companion_radio_full/">View this page on MeshCore Docs</a>.</p>
|
||
<!-- meshcore-hosted-doc-link:end -->
|
||
|
||
# Full Companion
|
||
|
||
Configure message alerts with the [Companion notification builder](notifications.md).
|
||
It generates CLI rules for contacts, rooms and channels, previews patterns, and
|
||
can apply/test them over USB. Trusted contacts and rooms can send `!notify`
|
||
strings with no GPIO and a 15-second playback limit.
|
||
|
||
For runtime on/off commands and board exceptions, see
|
||
[feature switches by role](role_feature_switches.md). Open the
|
||
[USB web console](https://flasher.meshcore.io/console) for the default ASCII terminal.
|
||
|
||
For practical on/off commands and update directions, see
|
||
[Full Companion feature switches](full_companion_features.md).
|
||
|
||
`companion_radio_full` combines every qualified Companion transport for its
|
||
platform into one artifact and acts as a host-backed LoRa mOTA source for
|
||
updating other nodes. Most targets can run those transports simultaneously;
|
||
the SenseCAP Indicator exception selects one secondary wireless transport per
|
||
boot as described below.
|
||
|
||
Fresh Full Companion installs default to Bluetooth on and infrastructure WiFi off.
|
||
WiFi remains compiled in: use `set wifi.enabled 1` through the USB or Bluetooth
|
||
CLI to enable it, or `set wifi.enabled 0` to disable it persistently. Existing
|
||
saved WiFi enablement is honored after an upgrade. The SenseCAP Indicator
|
||
requires a reboot to apply its exclusive transport selection; primary ESP-NOW
|
||
mesh operation is unaffected by the infrastructure-WiFi default.
|
||
|
||
The full Companion is deliberately not a LoRa OTA destination: it has no
|
||
firmware staging store, refuses `ota install`, and never advertises its own
|
||
firmware as an mOTA image.
|
||
|
||
Preference changes through the Companion protocol, WebConfig, or USB terminal
|
||
report a storage error if saving fails, and restore their previous values.
|
||
Settings that also change GPS or radio power-saving state restore that state;
|
||
a busy radio rollback remains pending for recovery instead of reporting success.
|
||
|
||
| Capability | ESP32 full | nRF52 full |
|
||
| --- | --- | --- |
|
||
| USB Binary Companion | Yes | Yes |
|
||
| BLE Binary Companion | Yes | Yes |
|
||
| USB ASCII terminal | Yes | Yes |
|
||
| Dedicated USB plaintext logging | No - shares the one USB TTY | Yes |
|
||
| Host-backed LoRa mOTA source | WiFi TCP 5001 | Exclusive USB mode or encrypted BLE |
|
||
| WiFi Companion/WebConfig | Yes | No - nRF52840 has no WiFi |
|
||
| Hardware serial Companion | On targets with assigned serial pins | On targets with assigned serial pins |
|
||
| Ethernet Companion | On targets with an Ethernet module | On RAK4631 with RAK13800 |
|
||
| LoRa self-update | No | No |
|
||
| Optional self-update | WiFi on existing dual-app layouts; USB on single-app layouts | Bluetooth DFU with a compatible bootloader; USB always supported |
|
||
|
||
### Screenless nRF52 spoken button confirmations
|
||
|
||
Full Companion builds for T1000-E, RAK WisMesh Tag, MeshTracker X1,
|
||
Muziworks R1 Neo and ThinkNode M3 use prerecorded spoken confirmations for
|
||
their shared single-button controls. Other roles, legacy USB/BLE-only builds,
|
||
screened boards and all Wio profiles retain their existing audio behavior.
|
||
Set `MESH_GPS_VOICE=0` at build time to retain tones on an eligible Full build.
|
||
|
||
| User-button gesture | Action / spoken confirmation |
|
||
| --- | --- |
|
||
| One press | Acknowledge an active notification: "Notification cleared"; otherwise "Ready" |
|
||
| Two presses | "Advert queued" or "Advert failed" |
|
||
| Three presses | "Sound on" or "Sound off" after the preference is saved |
|
||
| Four presses | "GPS on" or "GPS off" when the GPS setting is available |
|
||
| Hold more than three seconds | "Shutting down"; shutdown remains nonblocking while audio drains |
|
||
| Hold during the first eight seconds of UI startup | "USB setup" for terminal/rescue mode |
|
||
|
||
MeshTracker X1's three-press gesture instead cycles "Sound and vibration",
|
||
"Sound only", "Vibration only", and "Silent". The new setting must save before
|
||
either live alert output changes. A failed save restores both preferences and
|
||
announces "Action failed". An explicit mute or alert-mode change permits one
|
||
courtesy confirmation without unmuting ordinary notifications. The four
|
||
additional mode clips are compiled only for `HAS_DRV2605` builds.
|
||
Notification timers cannot cancel control speech, and the committed alert
|
||
mode remains authoritative for vibration even if a notification-mask save fails.
|
||
|
||
Power-on and wake wiring remain board-specific. Speech is nonblocking and uses
|
||
the existing nRF52 PWM player; each buzzer still needs a physical listening
|
||
test for intelligibility. All spoken button, alert-mode and GPS recordings use
|
||
Microsoft Zira Desktop with the selected compressed Companion voice profile.
|
||
GPS on/off use three stored audio spans: one shared encoded GPS prefix and two
|
||
phrase tails. Advert queued/failed also share an identical encoded prefix;
|
||
Sound off/Sound only share one only on `HAS_DRV2605` boards. The tails are not
|
||
independently decodable words. Playback treats each prefix and tail as one
|
||
continuous compressed stream, without resetting its codec, bit position,
|
||
interpolation or DMA at the seam. The approved full-phrase PCM and PWM output
|
||
remain bit-for-bit identical, including pronunciation and pauses.
|
||
|
||
The IMA audio payload is 3,881 bytes smaller on ordinary voice boards, or
|
||
4,971 bytes smaller on vibration-equipped boards, before the small segmented
|
||
descriptor/decoder overhead. Tiny shared silence prefixes are not split.
|
||
A representative Cortex-M4 GCC 14.2 size-optimized/LTO player-and-catalog
|
||
build saves 3,732 or 4,792 bytes respectively after that overhead; final
|
||
firmware savings can vary with toolchain and surrounding code.
|
||
The existing generators still synthesize the two complete GPS phrases and
|
||
button confirmations, then share byte-identical encoded prefixes; they do not
|
||
try to identify word boundaries or splice independently spoken words. Windows
|
||
Zira synthesis still requires Windows' local `System.Speech` tooling.
|
||
R1 Neo's buzzer pin aliases its optional QSPI clock, so voice is
|
||
not default-enabled when `QSPIFLASH` is selected. ThinkNode M4 is deliberately
|
||
excluded: its former
|
||
buzzer definitions incorrectly claimed I2C SDA and a battery-status LED, not
|
||
verified audio hardware. Its Companion recipes no longer drive those pins as
|
||
a buzzer.
|
||
|
||
The optional ESP32 RC32-without-display recipe is not part of this nRF52
|
||
extension: its fitted audio hardware needs verification and its `ui-new`
|
||
controls require an ESP32 playback backend, not the nRF52 PWM player.
|
||
|
||
#### Experimental G.726 speech
|
||
|
||
Ordinary builds still use the approved Zira IMA recordings. G.726 is a hardware
|
||
test option only: set both `MESH_BUTTON_AUDIO_HIL=1` and
|
||
`MESH_GPS_VOICE_G726_BITRATE=16` or `24`. Invalid bitrates or a missing test gate
|
||
are rejected. The generated catalog selects exactly one bitrate, retains the
|
||
original sample counts, and omits the X1-only mode prompts on other boards.
|
||
|
||
The decoder needs 52 bytes of state, no heap or full-clip buffer, and about
|
||
1.2 KiB of Cortex-M4 code/tables. Its packing, resets and PWM lifecycle are
|
||
checked against independently pinned FFmpeg output. At 24 kbps the audio
|
||
payload is 25% smaller; at 16 kbps it is 50% smaller with more waveform error.
|
||
Neither software comparisons nor successful builds qualify physical buzzer
|
||
intelligibility or the refill deadline under Bluetooth/radio load.
|
||
|
||
`scripts/generate_g726_voice.py` regenerates both experimental catalogs from
|
||
the approved mono 8 kHz Zira WAVs using FFmpeg's MSB-first `g726` encoder.
|
||
Production IMA headers cannot be selected as its output. The decoder's Sun
|
||
provenance, attributed FFmpeg MIX interpolation and LGPL license are retained
|
||
in `src/helpers/ui/g726`; no claim of independent ITU conformance is made.
|
||
|
||
### nRF52 Bluetooth reconnect qualification
|
||
|
||
Full Companions persist the paired client's notification subscriptions (CCCDs)
|
||
alongside its bond keys. A RAM-only subscription cache is insufficient: after
|
||
reboot, a phone can retain its bond and subscription while the node has disabled
|
||
notifications. Bluetooth then shows Connected, but Companion replies do not
|
||
reach the app. The RAM cache remains useful for warm reconnects; the persistent
|
||
bond record restores subscriptions after reboot.
|
||
|
||
The nRF52 build force-includes `SoftDeviceSvcCompat.h` in both application and
|
||
framework compilation. It prevents LTO from discarding memory reads and writes
|
||
performed by Nordic supervisor calls, including queries used to save CCCDs.
|
||
`test/test_nrf52_svc_compat.py` compiles a real ARM regression with the build's
|
||
LTO and pointer-analysis options and compares it with the unprotected wrapper.
|
||
|
||
On an already paired test node, run the hardware regression with `bleak`:
|
||
|
||
```sh
|
||
python3 scripts/check_nrf52_ble_reconnect.py \
|
||
--address D1:A0:86:CD:BB:C6 --board "Seeed Tracker T1000-E" \
|
||
--version <expected-firmware-hash> --reboot
|
||
```
|
||
|
||
This checks app-style NUL-terminated CLI commands, reboots the selected node,
|
||
and reads the saved subscription before the host subscribes again. It also
|
||
observes release of a secured link with no Companion traffic, followed
|
||
by a normal reconnect and working CLI. It does not clear pairing keys or change
|
||
preferences. Fresh pairing with the current PIN is a separate initial gate.
|
||
A link drop alone does not prove the firmware watchdog fired: confirm the cause
|
||
in the node debug log or Bluetooth trace. Link timeout reasons `0x08` and `0x22`
|
||
must not be counted as a confirmed firmware-requested disconnect (`0x13` at the
|
||
central).
|
||
|
||
### SenseCAP Indicator transport and rendering exception
|
||
|
||
Both SenseCAP Indicator Full layouts keep USB available and start exactly one
|
||
secondary wireless Companion transport per boot: BLE or infrastructure WiFi.
|
||
The saved `companion.transport` selection takes effect after reboot. BLE mode
|
||
does not start infrastructure WiFi, WebConfig, MQTT, TCP Companion, or network
|
||
OTA services. WiFi mode never initializes BLE and releases its controller and
|
||
host memory. LoRa remains the primary radio on the LoRa layout. ESP-NOW remains
|
||
the primary mesh radio in both ESP-NOW modes, including BLE mode; only the
|
||
infrastructure-WiFi services are omitted.
|
||
|
||
The requested 4-bit internal render profiles are:
|
||
|
||
| Primary radio | Secondary Companion transport | Canvas |
|
||
|---|---|---:|
|
||
| LoRa | Infrastructure WiFi | Native 480x480 |
|
||
| LoRa | BLE | Native 480x480 |
|
||
| ESP-NOW | Infrastructure WiFi | Native 480x480 |
|
||
| ESP-NOW | BLE | 320x320, scaled 1.5x to the 480x480 panel |
|
||
|
||
All four modes retain the same 160x160 logical UI. If a contiguous native
|
||
DMA-capable block is unavailable, startup keeps the device usable with the
|
||
320x320 emergency fallback and reports the canvas actually retained. Such a
|
||
fallback is not a successful native-480 validation result.
|
||
|
||
## Build and install
|
||
|
||
The target is synthesized by `build.sh` only for an exact board recipe that has
|
||
passed the combined-transport size check:
|
||
|
||
- The normal automatic path requires matching WiFi, USB, and BLE recipes on
|
||
ESP32, or matching USB and BLE recipes on nRF52.
|
||
- A measured qualification list also promotes an exact BLE recipe when the
|
||
same board can safely add its platform's remaining transports. It never
|
||
substitutes the pin map or peripherals from another board.
|
||
|
||
The measured ESP32 additions are M5Stack Unit C6L; XIAO C6/S3, Meshimi,
|
||
WHY2025 Badge, LilyGo T-LoRa C6, T3S3 SX1262/SX1276, T-Deck, TETH Elite,
|
||
classic T-Beam SX1262/SX1276, and T-Beam S3 Supreme; Heltec Wireless Tracker,
|
||
Wireless Paper, E213, E290, T190, CT62, and V4 expansion-kit TFT; Generic
|
||
ESP-NOW; SenseCAP Indicator ESP-NOW/LoRa; Ebyte EoRa-S3; and Meshadventurer
|
||
SX1262/SX1268. The measured nRF52 additions are GAT562 Mesh Watch13, LilyGo
|
||
T-Echo Lite, LilyGo T-Impulse Plus, and Wio Tracker L1 E-Ink. Their old
|
||
transport-specific names remain available for explicit compatibility builds,
|
||
but the Full image is the canonical release artifact.
|
||
|
||
Every ESP32 Full image includes ordinary WiFi Companion, WebConfig, and the TCP
|
||
mOTA services, even when its historical build base was USB- or BLE-only. On
|
||
`Generic_ESPNOW` and `SenseCapIndicator-ESPNow`, ESP-NOW is also the primary
|
||
mesh radio and shares the same 2.4 GHz hardware. Those two Full images retain
|
||
B/G/N for ordinary clients alongside ESP-NOW LR. Their ESP-NOW mesh, setup AP,
|
||
and infrastructure connection all use one persisted channel, which defaults
|
||
to 1. Configure the router's 2.4 GHz radio and every other primary ESP-NOW node
|
||
for that same fixed channel. Turning Companion WiFi off stops its TCP/AP
|
||
services but deliberately leaves the ESP-NOW mesh radio running on the
|
||
selected channel.
|
||
|
||
Every ESP32 Full Companion with a station connection synchronizes its UTC clock
|
||
from NTP after boot and explicitly refreshes it every 24 hours. The common WiFi
|
||
path owns this for non-MQTT and runtime-unconfigured nodes; a configured MQTT
|
||
bridge owns the same boot-and-daily schedule. Successful sync updates an
|
||
attached hardware RTC as well as the ESP32 clock and suppresses LoRa clock
|
||
fallback for that boot. Reconnecting WiFi preserves the existing daily
|
||
deadline. A timeout leaves the existing clock and fallback intact and retries
|
||
without blocking radio work.
|
||
|
||
Inspect or change the shared channel from the Full Companion text terminal:
|
||
|
||
```text
|
||
get espnow.channel
|
||
set espnow.channel 6
|
||
reboot
|
||
```
|
||
|
||
The accepted range is 1 through 13; use only a channel permitted in your region
|
||
and supported by the router. The setter persists the selection, but the
|
||
running radio stays on its current channel until reboot. Coordinate the change
|
||
across every primary ESP-NOW node and the router before rebooting, or the node
|
||
will lose one or both links. This primary-radio setting is not
|
||
`bridge.channel`; that command belongs to the separate ESP-NOW bridge feature.
|
||
To attach a LoRa-primary `*_repeater_bridge_espnow` gateway to these nodes,
|
||
match its `bridge.channel` and select `set bridge.format raw`; the bridge's
|
||
backward-compatible default is the distinct wrapped format.
|
||
WiFi power saving cannot put infrastructure WiFi and ESP-NOW on different
|
||
channels. On these two primary-ESP-NOW Full targets, `max` is unavailable
|
||
because maximum modem sleep can make the station miss ESP-NOW broadcasts; use
|
||
`min` for WiFi/BLE/ESP-NOW coexistence. The firmware also holds the ESP-IDF RF
|
||
wake reference for the primary mesh radio, so the ESP-NOW receiver remains
|
||
continuous even though the reported coexistence setting is `min`.
|
||
|
||
List the available targets:
|
||
|
||
```bash
|
||
bash build.sh list | grep companion_radio_full
|
||
```
|
||
|
||
Build by using one exact listed name:
|
||
|
||
```bash
|
||
bash build.sh build-firmware heltec_v4_r8_companion_radio_full \
|
||
--firmware-version v1.17.0
|
||
|
||
bash build.sh build-firmware RAK_4631_companion_radio_full \
|
||
--firmware-version v1.17.0
|
||
```
|
||
|
||
To build every canonical full Companion target, select the corresponding
|
||
interactive menu item or run:
|
||
|
||
```bash
|
||
bash build.sh build-full-companion-firmwares \
|
||
--firmware-version v1.17.0
|
||
```
|
||
|
||
Canonical Companion bulk builds also omit legacy `_ps` and `_femoff` aliases.
|
||
Power saving and controllable FEM receive gain are persisted runtime settings;
|
||
the old names remain available through an explicit `build-firmware` command
|
||
for compatibility. Full Companion replaces separate USB, BLE, ordinary WiFi,
|
||
hardware-serial, Ethernet Companion, Terminal Chat, and USB-only packet-logging
|
||
release artifacts whenever the exact board supports those combined transports.
|
||
Direct builds of the legacy targets remain available. RAK4631 repeater and room
|
||
server Ethernet builds remain separate because they are different standalone
|
||
roles, not Companion transports. nRF52 separates framed traffic and logs;
|
||
ESP32 makes those modes mutually exclusive on its one USB TTY. In WebConfig, use the
|
||
**FEM RX boost** switch. From the text terminal (USB, or TCP 5002 on ESP32), 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
|
||
get radio.fem.txgain
|
||
set radio.fem.txgain off
|
||
set radio.fem.txgain on
|
||
```
|
||
|
||
`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.
|
||
|
||
SSD1306 display builds also persist a runtime orientation. This replaces the
|
||
separate rotated Full Companion release image:
|
||
|
||
```text
|
||
get display.rotation
|
||
set display.rotation 90
|
||
set display.rotation 180
|
||
set display.rotation 270
|
||
set display.rotation 0
|
||
```
|
||
|
||
`0` resets the screen to that board's compiled default orientation.
|
||
|
||
Heltec E290 and T190 now use their Full Companion artifacts for simultaneous
|
||
USB, BLE, and WiFi. Their older `usb_ble`, USB-only, and BLE-only names remain
|
||
available only as explicit compatibility builds.
|
||
|
||
Heltec V3 and base OLED V4 Full Companion also include the former direct WiFi
|
||
MQTT Companion capability. Configure and enable MQTT at runtime through
|
||
WebConfig; the canonical release therefore publishes the Full image instead of
|
||
a second `companion_radio_wifi_mqtt` image. V4 TFT and expansion-kit layouts
|
||
remain separate hardware images because their display and I2C wiring differs.
|
||
|
||
Device power saving is separate from LoRa RXPS. It can be changed in WebConfig
|
||
with the **Device power saving** switch or from the text terminal:
|
||
|
||
```text
|
||
get powersaving
|
||
set powersaving on
|
||
set 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 text terminal:
|
||
|
||
```text
|
||
get wifi.ssid
|
||
get wifi.status
|
||
get wifi.powersave
|
||
get webui
|
||
set wifi.ssid MyNetwork
|
||
set wifi.pwd my-password
|
||
set wifi.powersave min
|
||
set wifi.powersave max
|
||
start webconfig
|
||
stop webconfig
|
||
```
|
||
|
||
ESP32 WiFi Companions with WebConfig, including Full Companion, expose a
|
||
**CLI** tab at the node's LAN address. It defaults to on; use `get wifi.cli`,
|
||
`set wifi.cli on`, or `set wifi.cli off`. Older builds that report the browser
|
||
terminal as unavailable need a firmware update. The open setup AP does not
|
||
expose this tab.
|
||
|
||
The browser accepts Companion configuration commands, including `get powersaving`,
|
||
`set usb.logging on|off`, WiFi controls, and MQTT settings. `set mqtt.enabled on|off` controls MQTT
|
||
without erasing broker settings; `get mqtt.enabled`, `get mqtt.running`, and
|
||
`get mqtt.status` distinguish the saved switch from current connections.
|
||
`set logging.output off|usb|wifi|both` selects both outputs together. The browser
|
||
also uses the complete Companion terminal for `card`, `import meshcore://...`,
|
||
`list`, `to`, `send`, `login`, `cmd`, and delayed replies, with the same syntax
|
||
as USB and TCP port 5002. See the [terminal command guide](terminal_chat_cli.md)
|
||
for contact import and session ownership. USB MOTA session commands require
|
||
the USB connection; WiFi host folders use port 5001.
|
||
|
||
On the two primary-ESP-NOW Full targets, the same terminal also provides
|
||
`get espnow.channel` and `set espnow.channel <1-13>`. A channel change is
|
||
persisted and requires a reboot, unlike a WiFi power-save change.
|
||
|
||
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.
|
||
Password entry is masked over USB. `get wifi.pwd` reads the saved password from
|
||
any local connection, including binary command `0x42`; LoRa cannot read it. It may
|
||
be empty for an open network, an ordinary passphrase of up to 63 characters, or
|
||
an exact 64-character hexadecimal WPA/WPA2 PSK. Other 64-character values and
|
||
all longer values are rejected.
|
||
|
||
The normal binary Companion connection can also read or write this setting over
|
||
USB, BLE, or TCP port 5000 without entering terminal mode. The mode values are
|
||
`0` for `min`, `1` for `none`, and `2` for `max`; see the
|
||
[Companion protocol](./companion_protocol.md#commands). A Full Companion that
|
||
runs WiFi and BLE simultaneously rejects `none` because coexistence requires
|
||
modem sleep. A primary-ESP-NOW Full target also rejects `max`; unlike
|
||
infrastructure traffic, peer ESP-NOW broadcasts cannot be buffered by the
|
||
access point while the station sleeps. If an older image saved a conflicting
|
||
value, firmware applies and reports `min` instead. The SenseCAP Indicator uses
|
||
the active-mode constraints in the exception above: LoRa + WiFi accepts all
|
||
three values, ESP-NOW + WiFi accepts `none|min`, LoRa + BLE accepts `min|max`
|
||
for the inactive WiFi setting, and ESP-NOW + BLE requires `min`. Fresh Cascade
|
||
builds select `min`, and an existing valid saved selection takes precedence.
|
||
|
||
On radios with RX duty-cycle support, WebConfig and the text terminal also
|
||
expose the persisted RXPS setting:
|
||
|
||
```text
|
||
get radio.rxps
|
||
set radio.rxps off
|
||
set radio.rxps on
|
||
set radio.rxps level 8 preamble 16
|
||
set radio.rxps 65625 60000
|
||
```
|
||
|
||
Fresh Cascade-profile Full Companion builds start with RXPS on at level 8 and
|
||
a 16-symbol preamble. Changing it takes effect immediately and remains selected
|
||
after reboot.
|
||
|
||
Companion firmware defaults device power saving to on. Version 1.17.1.2 also
|
||
turns it on once when upgrading an older Companion preference file, including
|
||
one written by the short-lived default-off regression. After that one-time
|
||
migration, an explicit `set powersaving off` selection remains persistent.
|
||
|
||
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. Active Full Companion transports remain available in
|
||
both states; on the SenseCAP Indicator this means USB plus the selected BLE or
|
||
infrastructure-WiFi secondary transport. WiFi modem sleep stays enabled when
|
||
BLE and the ESP32 WiFi radio are active together because coexistence 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
|
||
`WiFi: OFF` or `WiFi: ON`, and the selected state is retained after reboot. When
|
||
WiFi is off, TCP ports 5000-5002, WebConfig, and MQTT are stopped; USB, BLE, the
|
||
display, GPS, and LoRa continue to operate. Press BOOT again to restore WiFi,
|
||
including the saved station or setup-AP mode. On boot, BLE starts two seconds
|
||
after WiFi/WebConfig so their peak startup allocations do not overlap.
|
||
|
||
Artifacts are written to `out/` by default.
|
||
|
||
Full Companion behavior is selected with independent capability macros for
|
||
TempRadio, the OTA CLI, the TCP terminal, USB folder seeding, and memory
|
||
diagnostics. The legacy `COMPANION_RADIO_FULL` flag remains an input for older
|
||
target recipes, but application behavior no longer uses that umbrella as an
|
||
unrelated compile guard. In particular, ESP32 WiFi/WebConfig terminal controls
|
||
are compiled from their actual WiFi/WebConfig capability. On targets that run
|
||
ESP32 WiFi and BLE simultaneously, BLE is started first to avoid heap
|
||
fragmentation. The SenseCAP Indicator starts only its selected secondary
|
||
transport. Compile-time prerequisite checks reject inconsistent feature flags.
|
||
After linking, the capability sidecar verifies USB, BLE, the OTA CLI,
|
||
TempRadio, and each platform's host-folder transport; it also verifies the TCP
|
||
terminal, WebConfig, and WiFi seeder on ESP32, plus dedicated logging on
|
||
nRF52.
|
||
|
||
On 4 MB ESP32 boards, the full target uses a single 3 MB application partition
|
||
so WiFi, BLE, WebConfig, and source-only mOTA fit in one artifact. The T-Beam 1W
|
||
Full Companion uses that same LilyGo factory-compatible boot layout on its 16
|
||
MB flash because this source-only role does not install updates into a second
|
||
app slot. Flash the generated `-merged.bin` when first installing this
|
||
partition layout. Other boards with 8 MB or more retain dual application
|
||
partitions.
|
||
Heltec V2 and TLora V2 use 100 contacts, 8 group channels, and a 16-frame offline
|
||
queue in this combined profile because of internal DRAM limits. Meshadventurer
|
||
SX1262 and SX1268 use 100 contacts, 30 group channels, and a 16-frame queue.
|
||
These capacities preserve the required 8 KiB static internal-DRAM reserve
|
||
alongside MOTA and all Full transports; their ordinary transport-specific
|
||
images retain 160 contacts, 40 channels, and 128 queued frames.
|
||
|
||
The 1.17.1.5 memory replacements for Generic ESP-NOW, Heltec Wireless Paper,
|
||
Wireless Tracker, CT62, V3, Tracker V2, and XIAO C3 Full Companion use **150
|
||
contacts** and retain their **256-frame queue** and Full transports. Export
|
||
contacts before updating if you have more than 150; entries beyond the new
|
||
limit may be unavailable and a later save may omit them.
|
||
|
||
Full Companions normally retain 256 pending Companion message frames. ESP32
|
||
boards with configured PSRAM retain 512 and allocate that queue from PSRAM
|
||
before WiFi and BLE start. If PSRAM is unavailable at runtime, allocation falls
|
||
back through 256 and 128 frames, then to a 16-frame internal buffer. The Full
|
||
Companion startup memory line reports the capacity actually allocated as
|
||
`offline_queue=<frames>`. The queue is volatile and shared by all channels and
|
||
direct messages; it is not flash-backed history. See
|
||
[Companion offline message queue](./companion_offline_queue.md) for all platform
|
||
defaults and full-queue behavior.
|
||
|
||
Every corrected nRF52 Full profile keeps **256 offline frames normally** and
|
||
temporarily lends 128 slots to mOTA to leave room for
|
||
Bluetooth tasks, displays and UI allocations. Queue sharing preserves the
|
||
board's contacts, channels, and USB/Bluetooth mOTA sending. See the [memory correction](old-releases/1.17.1.5.md#t096-full-companion-bluetooth-and-menu-freeze-report).
|
||
If an explicit OTA source, discovery, download, install, or temporary-radio
|
||
request needs that workspace while more than 128 unread frames are queued, the
|
||
oldest volatile frames are consumed until 128 remain. The command reports the
|
||
number removed. Read-only OTA status queries do not remove messages. Sync the
|
||
queue to an app before starting OTA when those unread messages matter.
|
||
|
||
The nRF52 target inherits the board's ordinary USB Companion installation
|
||
format and adds BLE plus the serial mOTA source. It does not enable an SD cache
|
||
or any other board-specific storage behavior; host files are streamed as they
|
||
are requested. Its image is bounded by the board's normal application region,
|
||
not the smaller OTAFIX in-place workspace reserved for firmware that can update
|
||
itself.
|
||
|
||
## Interfaces
|
||
|
||
| Platform | Interface | Purpose |
|
||
| --- | --- | --- |
|
||
| Both | USB, 115200 baud | ASCII after boot or observable USB session reset; automatically switches on the first complete Binary Companion frame |
|
||
| Both | BLE | Binary Companion; display builds show a random session PIN, while headless builds default to `123456` |
|
||
| 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 | Full Companion text terminal; same role commands as the USB terminal |
|
||
| nRF52 | USB mOTA mode | Host `.mota` folder from `motatool serve --serial` |
|
||
| nRF52 | Encrypted BLE mOTA service | Paired phone/tablet/Linux host `.mota` catalog |
|
||
|
||
Delivery-required replies are returned only to the interface which supplied the
|
||
latest command. A contact-list stream keeps that route locked from
|
||
`CONTACTS_START` through `END_OF_CONTACTS`; commands waiting on another
|
||
interface are read after the stream finishes. Best-effort asynchronous
|
||
observations such as adverts remain broadcast so passive clients can refresh
|
||
their views. Companion session state is device-wide, so use one active
|
||
Companion application at a time. On nRF52, BLE remains available while USB is
|
||
in terminal or mOTA mode.
|
||
|
||
The Companion TCP listener starts only after a usable WiFi station or setup-AP
|
||
address exists. If opening the socket fails, it closes any failed-start socket
|
||
and retries with a delay capped at 30 seconds, without restarting the WiFi
|
||
connection or disturbing BLE, WebConfig, OTA, or a healthy accepted TCP client.
|
||
Turning WiFi off or suspending it cancels the listener request; retry service
|
||
cannot turn it back on. Use `get wifi.tcp` through BLE, USB, or the browser CLI
|
||
to inspect listener state, registration, accepted clients, completed RX/TX
|
||
frames, and errors without a PC port probe. `get display.wifi` also shows the
|
||
actual `tcp` listener flag independently of the network-services flag. A
|
||
listening socket alone cannot detect LAN firewall or guest-network isolation.
|
||
|
||
ESP32 TCP sends are non-blocking, and inbound commands are serviced alongside
|
||
outgoing data rather than waiting for an empty transmit queue. Unsolicited
|
||
radio logs therefore cannot keep the app handshake unread. A live client with
|
||
pending output is disconnected after 10 seconds without write progress;
|
||
other transports continue running. Required replies retain their queue slots,
|
||
so a new command waits if no reply can be admitted. Partially sent frames
|
||
remain pinned to preserve framing, while already queued replies keep the same
|
||
reconnection rules below.
|
||
|
||
On WiFi TCP port 5000, reconnecting from the same IP retains queued outgoing
|
||
frames. A different IP takes over immediately, but never receives the previous
|
||
IP's replies: up to four queued frames are parked separately for 30 seconds
|
||
from takeover. The old IP can reconnect within that window to retrieve them.
|
||
Only one displaced IP's backlog is retained; if another client also needs that
|
||
slot, the older backlog is discarded so the new connection is not delayed.
|
||
This reuses an existing fixed buffer instead of allocating additional frame
|
||
storage. Pending commands, signing sessions, and contact streams belonging to
|
||
the displaced WiFi session are canceled immediately; already accepted radio
|
||
message transmissions are not canceled. Queued frames are retained, not a
|
||
resumable command session, and IP matching is not authentication. Turning WiFi
|
||
off clears both queues. Stored message history is unaffected.
|
||
|
||
Ethernet also retains complete queued frames for the same IP. Unlike WiFi, it
|
||
has no spare backlog buffer: a different IP cancels the old owner's pending
|
||
operations and discards its queued frames before the new socket is exposed.
|
||
This keeps Ethernet's existing four-frame memory limit. On both transports, a
|
||
live same-IP replacement preserves pending operations; an observed disconnect,
|
||
disabled transport, or rejected input cancels them. Already queued frames can
|
||
still be replayed on a same-IP reconnect, but canceled operations are not resumed.
|
||
|
||
Partial TCP writes retain the unsent bytes without interleaving later frames.
|
||
After a reconnect, an incomplete frame restarts from its header; the new TCP
|
||
connection must not receive only the old connection's trailing bytes.
|
||
|
||
Binary WiFi/Ethernet frames must declare 1–176 payload bytes. Illegal lengths
|
||
close the connection immediately, without waiting for the announced body or
|
||
executing a truncated command. An incomplete binary header or payload has a
|
||
five-second deadline once reception starts; reconnect to send a fresh frame.
|
||
Ethernet raw-line terminal input has no typing deadline, but an overlong line
|
||
also closes the connection instead of executing its prefix.
|
||
|
||
USB Binary output is queued as complete length-prefixed frames. Temporary CDC
|
||
or UART backpressure pauses the contact stream; a frame may drain through a
|
||
smaller hardware FIFO in ordered chunks, but its remainder is retained and no
|
||
later frame can interleave with it or cause it to be discarded.
|
||
|
||
Binary login, status, telemetry, path-discovery, binary-request, and trace
|
||
results also have bounded producer retention when that transport queue is
|
||
full. One request result and one trace result can wait independently, on their
|
||
original captured interfaces. Their required `SENT` frames are retained and
|
||
admitted before the final result. A first valid radio result gets up to ten
|
||
seconds for whole-frame queue admission; a still-blocked `SENT` keeps its
|
||
earlier ten-second deadline. Duplicate callbacks cannot replace the retained
|
||
result or extend these deadlines. Disconnect, cancellation, or expiry drops
|
||
an unadmitted result. Queue admission is not proof of physical host receipt.
|
||
|
||
Reflected request tags are matched against the complete peer public key.
|
||
Recent request and trace history has eight slots each, reserved before radio
|
||
transmission; live entries are never evicted to accept a newer request. A full
|
||
history or a quarantined identifier returns `ERR_BAD_STATE`, so clients must
|
||
back off. Retired reflected tags and trace tag/auth tuples are suppressed for
|
||
at least ten seconds and through the original radio deadline plus ten seconds
|
||
when longer. Login retries to the same peer have at least a thirty-second
|
||
quarantine. Positively matched newer status/telemetry/binary replies still work
|
||
after login, but otherwise unsolicited responses from that login peer can be
|
||
suppressed during the quarantine.
|
||
|
||
These guards are finite and clear at reboot. Login replies carry a server
|
||
timestamp, not an echoed request nonce; sufficiently late replies or a
|
||
timestamp collision cannot always be distinguished without a protocol change.
|
||
Trace tag/auth fields are correlation data, not cryptographic authentication.
|
||
The guards do not authenticate a host process or retract frames already
|
||
accepted by a transport. In particular, the same-IP TCP queue replay described
|
||
above remains unchanged, including its lack of authentication.
|
||
|
||
When a BLE client requests pairing, a display-equipped build wakes the screen,
|
||
switches to the first home page, and keeps the active six-digit PIN visible
|
||
until Bluetooth connects or the two-minute pairing window expires. USB, WiFi,
|
||
Ethernet, and hardware-serial connections do not suppress this screen. With no
|
||
saved BLE PIN, display builds generate a new PIN at boot; builds without a
|
||
physical display use `123456`. Use `set pin 654321` in the Companion CLI to save
|
||
a fixed pairing PIN, then `reboot` to activate it. `set pin 0` restores the
|
||
default/generated PIN policy. A PIN saved through the Companion protocol also
|
||
takes effect after reboot. See the [PIN command reference](cli_commands.md#set-the-bluetooth-pairing-pin-companion).
|
||
|
||
The Bluetooth device name is independently configurable. In the text terminal,
|
||
use `get bluetooth.name` and `set bluetooth.name <name>`; use
|
||
`set bluetooth.name default` to restore `MeshCore-<node name>`. The WebConfig
|
||
Node card exposes the same optional field on Bluetooth-capable ESP32 builds.
|
||
Custom names replace the complete Bluetooth label rather than inheriting the
|
||
prefix, accept up to 31 valid UTF-8 bytes, and take effect after reboot. This
|
||
does not change the node's mesh advertisement name.
|
||
|
||
Every Bluetooth Companion also supports `get bluetooth.mac` and
|
||
`set bluetooth.mac <address|random|random-every-boot|random-after-connect|default>`.
|
||
A literal address is a BLE random-static identity, `random` creates one
|
||
persistent identity, `random-every-boot` rotates it on startup, and
|
||
`random-after-connect` rotates it on the first boot after an authenticated
|
||
connection while leaving unused boots unchanged. `default` (or `clear`)
|
||
restores the chipset address. None of these values changes the stealth flag.
|
||
Reboot and re-pair after changing modes or after a rotation. Address rotation
|
||
clears stale local bonds. On nRF52 this affects the MeshCore application only,
|
||
not the OTAFIX bootloader's separate BLE DFU identity.
|
||
|
||
`get bluetooth.stealth` and `set bluetooth.stealth on|off` control an independent
|
||
flag, defaulting to off. Combine it with a custom address or `random` to retain
|
||
the address and bond across boots. With stealth on, normal discovery ends
|
||
after the first authenticated pairing and only the saved peer may reconnect.
|
||
Rotating MAC policies still rotate and reopen first pairing when they do;
|
||
stealth remains enabled. Repeating `on` keeps an existing bond. Toggle `off`,
|
||
then `on`, then reboot to reset first pairing. All flag changes need reboot.
|
||
The node still sends directed or allowlisted BLE packets; it is not radio silent.
|
||
|
||
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 text terminal modes
|
||
|
||
Full Companion USB starts in the ASCII terminal after boot or an observable USB
|
||
session reset. MeshCore apps and
|
||
`meshcli` send a `<`-prefixed framed command, which automatically hands the
|
||
untouched frame to the Binary Companion parser:
|
||
|
||
```bash
|
||
meshcli -s /dev/ttyACM0 -b 115200 ver
|
||
```
|
||
|
||
The automatic probe runs only at an empty prompt. A complete frame confirms
|
||
binary mode; an incomplete probe returns to ASCII after one second. Binary mode
|
||
then remains selected until an observable USB session reset, reboot, or the
|
||
explicit terminal start token. See
|
||
[Full Companion USB CLI and binary switcher](./full_companion_usb_switcher.md)
|
||
for the byte-level state machine, logging and mOTA ownership, recovery paths,
|
||
and known limitations.
|
||
|
||
Immediately after boot, an ordinary terminal can issue ASCII commands without
|
||
a start token. If the device is already in Binary Companion mode, open the port
|
||
with the terminal start token sent automatically:
|
||
|
||
```bash
|
||
picocom -b 115200 \
|
||
--imap spchex \
|
||
--initstring $'+++MESHCORE-TERM-START\r' \
|
||
/dev/ttyACM0
|
||
```
|
||
|
||
The input map prevents any Binary Companion control bytes received during the
|
||
mode transition from changing the local terminal's character set or display
|
||
state while leaving UTF-8 emoji intact. The banner confirms that terminal mode
|
||
is active; do not enter the start token again after it appears.
|
||
|
||
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. `board` reports the exact hardware target. ESP32 Full
|
||
Companion also provides `memory`, which reports heap, internal allocation,
|
||
PSRAM, and offline-queue usage; it is omitted from non-ESP32 help. ESP32 builds
|
||
also provide local WiFi credential, status, WebConfig, and power-save controls.
|
||
Every Full Companion provides persistent `get/set usb.logging` and starts with
|
||
logging off on a fresh installation.
|
||
|
||
### ESP32 single USB serial port
|
||
|
||
Every ESP32 Full Companion exposes one USB TTY with two exclusive modes. It
|
||
starts as the ASCII terminal unless a saved logging-on preference boots
|
||
directly into the logging terminal. If it is already binary, enter its text
|
||
terminal with `+++MESHCORE-TERM-START`. For an ESP32 1.17.1.5 USB logging session,
|
||
run these separate commands:
|
||
|
||
```text
|
||
set powersaving off
|
||
set usb.logging on
|
||
```
|
||
|
||
The first command is the release's USB power-saving workaround. The same
|
||
TTY then emits plaintext packet/debug logs and continues accepting CLI commands,
|
||
including `set usb.logging off`. Framed Binary Companion is unavailable on USB
|
||
while logging owns the TTY. Turning logging off sends the command reply, stops
|
||
the logs, and leaves that TTY in the normal ASCII terminal, matching a fresh
|
||
Full installation. Send `+++MESHCORE-TERM-STOP`, or let a Companion app send a
|
||
valid framed probe, to switch it to Binary Companion afterward. A saved
|
||
logging-on preference boots directly into this input-capable logging terminal.
|
||
BLE and Wi-Fi Companion remain available while USB is logging on simultaneous
|
||
targets. On the SenseCAP Indicator, only the selected BLE or Wi-Fi Companion
|
||
transport remains available alongside the logging terminal.
|
||
|
||
ESP32 Full Companion uses the repository's Arduino-ESP32 2.x platform base
|
||
where the board supports it. RC32 and ESP32-C6 retain their board-required
|
||
Arduino 3.x platform, but follow the same one-TTY policy. No ESP32 Full image
|
||
creates an optional second CDC interface. The single-TTY behavior applies to
|
||
native-USB ESP32-S3 boards and boards using a USB-UART bridge.
|
||
|
||
### nRF52 dual USB serial ports
|
||
|
||
Current nRF52 Full Companion firmware can expose two CDC ACM serial interfaces
|
||
on one physical USB cable:
|
||
|
||
- USB interface `00` is the primary Companion, text-terminal, and serial-mOTA
|
||
source port. It is always present, starts in ASCII after boot, and
|
||
automatically hands a complete `<` frame to Binary Companion.
|
||
- USB interface `02` is the optional write-only plaintext packet/debug logging
|
||
port. Host input on this interface is ignored and cannot invoke firmware
|
||
commands.
|
||
|
||
A fresh Full Companion starts with USB logging off and therefore enumerates
|
||
only interface `00`. Use `set usb.logging on` to save logging on; the reply says
|
||
that a reboot is required. Use `set usb.logging on reboot` to save it and have
|
||
the node reboot automatically after the reply. The second interface appears
|
||
after that reboot. Likewise, `set usb.logging off reboot` removes interface
|
||
`02`. The optional `reboot` word is accepted only in these exact command forms
|
||
and triggers a reboot only when the USB logging mode or descriptor needs to change.
|
||
|
||
For serial bridges that use one port for both commands and packets, including
|
||
unmodified Cisien/meshcoretomqtt, use `set usb.logging stream reboot` instead.
|
||
This saved packet-stream mode keeps only interface `00` and emits plaintext
|
||
RAW/RX/TX records together with repeater-style ` -> ` CLI replies. Configure
|
||
the bridge with the stable `*-if00` path. Binary Companion and serial mOTA are
|
||
unavailable on that port while logging is enabled; `set usb.logging off` stops
|
||
the stream and leaves the ASCII terminal active. BLE remains available.
|
||
`get usb.logging` reports `stream` and the primary port after reboot. To return
|
||
to separate logging, use `set usb.logging on reboot`.
|
||
|
||
These are Full Companion **text-terminal** commands. The superficially similar
|
||
`meshcli ... get usb.logging` command uses the Binary Companion parameter
|
||
registry and can report `Unknown var usb.logging`; it does not forward that
|
||
line to the text terminal. Enter terminal mode on interface `00` with the
|
||
`+++MESHCORE-TERM-START` token as described above, then issue the command.
|
||
|
||
When logging is on, Linux normally shows two `/dev/ttyACM*` devices. Match the stable
|
||
`/dev/serial/by-id/*-if00` and `*-if02` links, or use a udev rule matching
|
||
`ID_USB_INTERFACE_NUM`, rather than assuming which tty number is assigned. On
|
||
Windows they appear as two COM ports; identify them by USB interface instead of
|
||
depending on a particular COM number. The nRF52 bootloader temporarily exposes
|
||
its normal DFU serial interface during an update.
|
||
|
||
Opening the nRF52 logging port prints `MeshCore USB logging port` followed by
|
||
its portable identity, `USB CDC 1; interface 02; Linux stable suffix: -if02`.
|
||
`get usb.logging` reports the same endpoint. Firmware cannot print the exact
|
||
`/dev/ttyACM*` or `COM*` name because Linux, macOS, or Windows assigns that name
|
||
after USB enumeration; use the `*-if02` link on Linux to obtain the exact path.
|
||
For example, `readlink -f /dev/serial/by-id/*-if02` prints the host-assigned
|
||
`/dev/ttyACM*` name.
|
||
|
||
Every ESP32-S3 Full Companion image uses DIO flash mode, including the RAK3112
|
||
and RC32 profiles. The S3 ROM supports DIO while
|
||
loading the software bootloader, and some flash configurations fail before the
|
||
application starts when a merged image inherits QIO. DIO trades some maximum
|
||
flash-read throughput for compatibility; it does not change a board's PSRAM
|
||
type or any ordinary non-Full firmware profile.
|
||
|
||
On nRF52, point MeshCore Companion software, `meshcli`, and `motatool` at
|
||
interface `00`. When enabled and rebooted, point a plaintext reader or
|
||
USB-connected MQTT service at interface `02`. On ESP32, use its only USB TTY
|
||
for Binary Companion while logging is off, or for the plaintext CLI/logger
|
||
while logging is on; close one consumer before switching modes. Turning
|
||
logging off returns to ASCII, so the normal stop token or a valid framed probe
|
||
is still required before Binary Companion owns the port.
|
||
|
||
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. The idle startup USB prompt yields to
|
||
a TCP connection when no USB data client or partial command is present, and is
|
||
restored when TCP disconnects. An active USB session rejects TCP; entering USB
|
||
terminal mode later closes an active TCP session. On USB-Serial-JTAG and
|
||
USB-to-UART hardware, the firmware cannot observe an idle host open, so actual
|
||
buffered USB activity—not the physical cable alone—claims ownership.
|
||
Disconnecting TCP clears pending terminal-only state without cancelling Binary
|
||
Companion delivery or radio retries.
|
||
|
||
Both terminal transports accept `reboot`. The reply is sent first and the
|
||
device reboots one second later, so a script can distinguish an accepted reboot
|
||
from an abruptly lost connection.
|
||
|
||
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
|
||
channel #rgdata Hello from Eugene 👋
|
||
show
|
||
show channels on
|
||
to Hilltop Repeater
|
||
path A1B2C3,D4E5F6
|
||
path 7773D0 7E7662
|
||
login my-admin-password
|
||
cmd ver
|
||
trace
|
||
```
|
||
|
||
The terminal `list [n]` command displays favorite contacts first and orders
|
||
each favorite/non-favorite group by its most recent advertisement. This does
|
||
not alter the binary Companion contact-list protocol.
|
||
|
||
Unsolicited terminal output starts in a quiet mode: advertisements and
|
||
ordinary channel messages are hidden, while `#emergency` messages remain
|
||
visible. Use `show adverts on|off`, `show channels on|off`, and
|
||
`show emergency on|off` to control each category independently; plain `show`
|
||
reports their state. These runtime filters affect terminal printing only and
|
||
reset to their defaults after reboot.
|
||
|
||
The `to` command selects the remote-administration target. `path` shows its
|
||
saved outgoing route; `path direct`, `path clear`, or a list separated by
|
||
spaces, commas, or both changes the route used by subsequent `login`, `send`,
|
||
and `cmd` commands. Every hop must use the same 2-, 4-, or 6-digit hexadecimal
|
||
width. Login passwords are masked during entry and limited by the radio
|
||
protocol to 15 UTF-8 bytes. Wait for the asynchronous login result before using
|
||
`cmd`; command replies appear as `CLI -> from <name>` and use a response window
|
||
of 300% of the route estimate. `DIRECT via path <hop,...>` displays the exact
|
||
saved prefixes copied into the packet. Remote ACL permissions determine which
|
||
commands the target accepts. The matching reply reports its round-trip time
|
||
from local queueing through result reception, including radio transit and
|
||
remote execution. Only one terminal `cmd` can be pending at a time.
|
||
|
||
Incoming unicast replies are labeled `ROUTED`. Their exact return prefixes are
|
||
not available at the destination because each forwarder consumes its prefix;
|
||
use `trace` to verify the return route.
|
||
|
||
With no argument, `trace` uses the current `to` recipient. A name-prefix
|
||
argument traces that contact directly without changing the current recipient.
|
||
The contact must already have a known direct path; results show the SNR at each
|
||
hop, or a timeout if the round trip does not return.
|
||
|
||
An explicit route can use 1-, 2-, or 4-byte hexadecimal prefixes. Spaces,
|
||
commas, and mixed separators are accepted:
|
||
|
||
```text
|
||
trace path 1 12 34 56 34 12
|
||
trace path 2 1234,ABCD,5678,ABCD,1234
|
||
trace path 4 12345678, ABCDEF01 89ABCDEF, ABCDEF01,12345678
|
||
```
|
||
|
||
The entered route must include both the outward and return prefixes. Exact
|
||
three-byte traces are not supported.
|
||
|
||
Return to Binary mode with:
|
||
|
||
```text
|
||
+++MESHCORE-TERM-STOP
|
||
```
|
||
|
||
An observable USB session reset restores ASCII, including after a Binary client
|
||
disconnects. Native USB with DTR can detect a terminal closing; ESP32 hardware
|
||
USB Serial/JTAG detects bus resets and physical host loss. UART bridges usually
|
||
cannot report a terminal closing, so use the start token if they remain in
|
||
Binary mode. A different baud rate, including 57600, does not select ASCII.
|
||
|
||
On an ESP32 Full Companion built with `OTA_FOLDER_SERIAL`, `motatool` can keep
|
||
the USB serial port open as an mOTA folder source when WiFi is unavailable:
|
||
|
||
```sh
|
||
motatool serve --serial /dev/ttyACM0 --dir ./motas -v
|
||
```
|
||
|
||
The tool sends the exact completed `ota folder on` line when it opens the port.
|
||
Firmware recognizes it in startup ASCII or idle Binary Companion mode, then
|
||
transfers the port to exclusive USB mOTA ownership before binary request/reply
|
||
frames begin. The text terminal and Binary Companion are unavailable on that
|
||
TTY until `motatool` detaches the folder. This matches the nRF52 ownership
|
||
behavior described below. TCP port 5001 remains the preferred unattended
|
||
source transport.
|
||
|
||
## nRF52 USB mOTA mode
|
||
|
||
The nRF52 full target has a third, exclusive USB mode for the host folder.
|
||
Unmodified `motatool serve --serial` sends `ota folder on` when it opens the
|
||
port. The startup ASCII terminal recognizes that exact completed line, leaves
|
||
terminal mode, and gives the stream directly to exclusive mOTA handling. If
|
||
the port is already in Binary Companion mode, the idle binary parser recognizes
|
||
the same control sequence. The sequence is not examined inside a framed Binary
|
||
Companion packet. See the
|
||
[switcher guide](./full_companion_usb_switcher.md#logging-and-mota-ownership)
|
||
for the ownership transitions.
|
||
|
||
While mOTA mode owns USB:
|
||
|
||
- mOTA manifests and blocks stream from the computer on demand.
|
||
- USB Binary and the USB text terminal are unavailable.
|
||
- BLE Binary Companion remains available.
|
||
- `motatool` sending `ota folder off`, or disconnecting the USB data session,
|
||
detaches the folder and restores Binary mode.
|
||
|
||
No modified `motatool` build, terminal token, or preliminary mode change is
|
||
required.
|
||
|
||
## nRF52 Bluetooth mOTA source
|
||
|
||
Protocol v14 also lets a phone, tablet, or Bluetooth-capable Linux host feed
|
||
the `.mota` catalog to an nRF52 Full Companion. Normal Companion commands stay
|
||
on the Nordic UART service. Firmware data uses a separate GATT service, so
|
||
binary app traffic cannot be mistaken for a firmware block.
|
||
|
||
The client must pair with the Companion PIN, subscribe to the mOTA Device
|
||
Request characteristic, and send `CMD_BLE_MOTA_SOURCE` action `start` over the
|
||
normal Binary Companion connection. The source is available only while that
|
||
encrypted MITM-authenticated connection remains active. Disconnecting,
|
||
unsubscribing, overflowing a frame, or receiving malformed data automatically
|
||
detaches the catalog. USB and BLE source modes are mutually exclusive.
|
||
|
||
The included Raspberry Pi reference client validates each `.mota` with
|
||
`motatool`, schedules the local TempRadio window, serves until interrupted,
|
||
then detaches and restores the normal radio tuple:
|
||
|
||
```bash
|
||
python3 tools/ble_mota/ble_mota_seeder.py \
|
||
--device MeshCore-MyCompanion \
|
||
--dir ./motas \
|
||
--local 'tempradio 909.950,250,5,5,120'
|
||
```
|
||
|
||
Prefer this relative `tempradio` form when the phone/Pi and radio clocks may
|
||
disagree. It starts a duration on the Companion and does not compare their
|
||
wall clocks. Use the absolute `tempradioat` scheduler only after synchronizing
|
||
the participating nodes.
|
||
|
||
Use `--pair` when the Linux host has not already bonded. BlueZ must have an
|
||
agent capable of entering or confirming the six-digit PIN. Use `--source
|
||
status` without `--dir` for a read-only channel/status check. The complete
|
||
UUID, frame, action, and status definitions are in the
|
||
[Companion protocol](./companion_protocol.md#bluetooth-lora-mota-source).
|
||
|
||
This reference process stands in for the phone application. A mobile app can
|
||
use the same sequence while retaining its normal contact and Repeater Admin
|
||
UI: log in to the destination, put each required node on the same bounded
|
||
TempRadio tuple, start the local Bluetooth catalog, then send the normal remote
|
||
`ota ls`, `ota pull`, and `ota install` commands. The destination still checks
|
||
container geometry, hardware identity, hashes, signature policy, and the
|
||
OTAFIX bootloader before installation.
|
||
|
||
## Serve mOTA images manually
|
||
|
||
First put the destination, required relays, controller, and source on the same
|
||
bounded TempRadio tuple. The example frequency below is not legal everywhere;
|
||
choose a legal tuple supported by every participating radio.
|
||
|
||
### ESP32 source
|
||
|
||
Use the local console to start TempRadio:
|
||
|
||
```bash
|
||
nc 192.168.1.50 5002
|
||
```
|
||
|
||
```text
|
||
tempradio 909.950,250,5,5,120
|
||
ota status
|
||
```
|
||
|
||
Then start the dedicated TCP seeder:
|
||
|
||
```bash
|
||
motatool serve --dir ./motas --tcp 192.168.1.50:5001 -v
|
||
```
|
||
|
||
### nRF52 source
|
||
|
||
Use the USB terminal briefly to schedule TempRadio, then return to Binary mode
|
||
and close the terminal:
|
||
|
||
```bash
|
||
picocom -b 115200 \
|
||
--imap spchex \
|
||
--initstring $'+++MESHCORE-TERM-START\r' \
|
||
/dev/ttyACM1
|
||
```
|
||
|
||
```text
|
||
tempradio 909.950,250,5,5,120
|
||
+++MESHCORE-TERM-STOP
|
||
```
|
||
|
||
After sending the stop token, exit `picocom` with Ctrl-A, Ctrl-X.
|
||
|
||
Start the serial seeder on that same port:
|
||
|
||
```bash
|
||
motatool serve --dir ./motas --serial /dev/ttyACM1 --baud 115200 -v
|
||
```
|
||
|
||
`motatool` switches the port into mOTA mode automatically. Stop it with
|
||
Ctrl-C to detach the folder. Reopen the terminal and use `normalradio` if the
|
||
source should return early; otherwise the saved radio settings return when the
|
||
bounded window expires.
|
||
|
||
As a cable-free alternative, keep the normal Companion BLE session open and
|
||
run the Bluetooth reference client shown in the nRF52 Bluetooth section. Do
|
||
not run the USB seeder at the same time.
|
||
|
||
Both platforms intentionally refuse firmware installation commands such as:
|
||
|
||
```text
|
||
ota pull <id> flash
|
||
ota install
|
||
ota dev ...
|
||
```
|
||
|
||
## Script a complete update
|
||
|
||
The Bash and PowerShell wrappers accept a release ZIP or ready `.mota`, set up
|
||
TempRadio, run `motatool`, monitor the exact image, install it on the
|
||
destination, and restore the radio path. Use a separate Companion as the
|
||
controller.
|
||
|
||
For an ESP32 full source:
|
||
|
||
```bash
|
||
export MESHCORE_ADMIN_PASSWORD='target-admin-password'
|
||
|
||
./tools/lora_ota/lora_ota.sh ./release.zip "Roof Node" \
|
||
--controller-serial /dev/ttyACM0 \
|
||
--source-tcp 192.168.1.50:5001 \
|
||
--source-cli-tcp 192.168.1.50:5002
|
||
```
|
||
|
||
For an nRF52 full source, the script automatically detects the token-switched
|
||
terminal and uses the same source port sequentially for control and seeding:
|
||
|
||
```bash
|
||
export MESHCORE_ADMIN_PASSWORD='target-admin-password'
|
||
|
||
./tools/lora_ota/lora_ota.sh ./release.zip "Roof Node" \
|
||
--controller-serial /dev/ttyACM0 \
|
||
--source-serial /dev/ttyACM1
|
||
```
|
||
|
||
```powershell
|
||
$env:MESHCORE_ADMIN_PASSWORD = 'target-admin-password'
|
||
|
||
& .\tools\lora_ota\lora_ota.ps1 '.\release.zip' 'Roof Node' `
|
||
--controller-serial COM7 `
|
||
--source-serial COM8
|
||
```
|
||
|
||
See the [start-to-finish LoRa OTA guide](./lora_ota_automation.md) for package
|
||
selection, nRF52 in-place deltas, relays, trust checks, and recovery behavior.
|