feat: consolidate full companion runtime profiles
This commit is contained in:
mikecarper committed
1 parent
d17c250137
commit
c6476b8ba8
42 files changed
+731
-561
No files matched your search
@@ -388,22 +388,9 @@
|
||||
if (!profile || profile.role !== "companion" || profile.mode !== "full") {
|
||||
return false;
|
||||
}
|
||||
if (profile.installKinds.includes("zip")) return true;
|
||||
const target = String(profile.target || "").toLowerCase();
|
||||
if (/^heltec_v4(?:_2_v4_3|_3)?(?:_r8)?(?:_tft)?_companion_radio_full(?:_|$)/
|
||||
.test(target)) {
|
||||
return true;
|
||||
}
|
||||
return [
|
||||
"lilygo_tbeam_1w_companion_radio_full",
|
||||
"station_g2_companion_radio_full",
|
||||
"station_g3_esp32_companion_radio_full",
|
||||
"xiao_s3_wio_companion_radio_full",
|
||||
"heltec_tracker_v2_companion_radio_full_femon",
|
||||
"meshnology_w12_companion_radio_full",
|
||||
"nibble_screen_connect_companion_radio_full_",
|
||||
"nibble_zero_connect_companion_radio_full_",
|
||||
].includes(target);
|
||||
// Native nRF52 Serial DFU packages use .zip. ESP32 Full Companion always
|
||||
// has one USB TTY and never receives the dedicated-port capability.
|
||||
return profile.installKinds.includes("zip");
|
||||
}
|
||||
|
||||
function isFullCompanion(profile) {
|
||||
@@ -487,11 +474,12 @@
|
||||
return (profiles || []).map(function (profile) {
|
||||
if (!isFullCompanion(profile)) return profile;
|
||||
|
||||
// Every Full Companion has a runtime USB logging mode. Dual-CDC targets
|
||||
// add an independent plaintext interface after reboot; single-TTY
|
||||
// targets switch their existing port between framed and plaintext modes.
|
||||
// Every Full Companion has a runtime USB logging mode. nRF52 adds an
|
||||
// independent plaintext interface after reboot. Every ESP32 target
|
||||
// switches its one TTY between framed and plaintext modes.
|
||||
profile.logging = "usb-runtime";
|
||||
profile.loggingModes = ["none", "usb"];
|
||||
profile.dedicatedUsbLogging = false;
|
||||
if (isDualCdcFullCompanion(profile)) {
|
||||
profile.dedicatedUsbLogging = true;
|
||||
}
|
||||
@@ -830,7 +818,7 @@
|
||||
);
|
||||
} else {
|
||||
extra.push(
|
||||
"Full Companion starts with USB logging off and Binary Companion on its single TTY. Enter the text terminal and use set usb.logging on for plaintext logs; that TTY still accepts set usb.logging off and automatically returns to Binary Companion after the reply."
|
||||
"Full Companion starts in its ASCII terminal with USB logging off. Use set usb.logging on for plaintext logs; set usb.logging off stops those logs but stays in normal ASCII mode. Then send +++MESHCORE-TERM-STOP or let a Companion app send a valid framed probe to switch the TTY to Binary Companion."
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -72,8 +72,8 @@ retain 50 because their MQTT discovery tables are constrained by internal DRAM.
|
||||
| ESP32 MQTT observer or ESP-NOW bridge | Always uses the expanded FULL partition profile. The build never substitutes a reduced CLI to fit the legacy application slot. |
|
||||
| FULL ESP32 USB + WiFi | Uses the matching MQTT target with packet logging on, verbose debug off, and the complete command surface supported by that role and hardware. `get/set logging.output off\|usb\|wifi\|both` selects and persists the active output paths. |
|
||||
| FULL ESP32 logging fallback | Uses the matching non-MQTT target only when no WiFi MQTT sibling exists, with debug and packet logging enabled and the complete command surface supported by that role and hardware. Its persistent USB gate also covers output-off operation, avoiding a second FULL ESP-NOW image. |
|
||||
| Dual-CDC Full Companion | nRF52 and qualified native-USB ESP32-S3 Full images use one physical USB connection. Fresh installs expose only interface `00`; it starts as an ASCII terminal and automatically hands a complete `<` frame to framed Companion. The same interface also carries exclusive serial mOTA traffic. Enabling logging and rebooting adds interface `02` for plaintext logs. They also provide BLE and source-only LoRa OTA; ESP32 additionally provides WiFi. `get/set usb.logging` persistently controls whether the logging interface is present. |
|
||||
| Single-TTY Full Companion | ESP32 Full images without dual CDC start with the ASCII terminal on their one TTY and automatically hand a complete `<` frame to framed Companion. `set usb.logging on` switches it to an input-capable plaintext logging terminal; `set usb.logging off` replies and then restores framed Companion automatically. A saved logging-on setting starts directly in that logging terminal and disables automatic frame detection. BLE, WiFi, and source-only LoRa OTA remain available. |
|
||||
| nRF52 dual-CDC Full Companion | Fresh installs expose only interface `00`; it starts as an ASCII terminal and automatically hands a complete `<` frame to framed Companion. The same interface also carries exclusive serial mOTA traffic. Enabling logging and rebooting adds interface `02` for plaintext logs. BLE and source-only LoRa OTA remain available. `get/set usb.logging` persistently controls whether the logging interface is present. |
|
||||
| ESP32 single-TTY Full Companion | Every ESP32 Full image starts with the ASCII terminal on its one USB TTY and automatically hands a complete `<` frame to framed Companion. `set usb.logging on` switches that TTY to an input-capable plaintext logging terminal and makes framed Companion unavailable on USB; `set usb.logging off` stops logging but leaves the TTY in normal ASCII mode. The terminal stop token or a valid incoming framed probe then performs the ordinary switch to Binary Companion. A saved logging-on setting starts directly in that logging terminal and disables automatic frame detection. BLE, WiFi, and source-only LoRa OTA remain available. ESP32 Full uses Arduino-ESP32 2.x where supported; RC32 and ESP32-C6 keep their board-required Arduino 3.x platform but still expose only one TTY. |
|
||||
| `no_external_sensors` | Removes optional external-sensor drivers and their settings; it does not remove core repeater discovery, routing, or runtime RS-232 commands. RAK3401 and RAK4631 profiles retain the four common INA I2C voltage/current monitors. GPS-preserving RAK nRF52 OTA profiles retain their GPS commands and provider; RAK4631 defaults the bridge to UART 2 because GPS uses UART 1. Legacy target suffixes remain stable for OTA identity compatibility. |
|
||||
|
||||
`logging`, `OTA`, and `FULL` describe independent build features in historical
|
||||
@@ -98,10 +98,11 @@ available from a canonical image:
|
||||
separate USB, BLE, ordinary WiFi, hardware-serial, Ethernet Companion, and
|
||||
USB packet-logging Companion artifacts.
|
||||
It provides BLE and source-only LoRa OTA; ESP32 also provides ordinary WiFi.
|
||||
Dual-CDC builds keep framed traffic on interface `00` and add logging on
|
||||
interface `02` after a reboot. Single-TTY builds switch interface `00` into
|
||||
an input-capable logging terminal and restore Binary Companion when that
|
||||
terminal session ends.
|
||||
nRF52 keeps framed traffic on interface `00` and can add logging on interface
|
||||
`02` after a reboot. Every ESP32 Full build instead switches its one USB TTY
|
||||
into an input-capable logging terminal. Turning logging off restores the
|
||||
normal ASCII terminal; the usual stop token or a valid framed probe then
|
||||
switches it to Binary Companion.
|
||||
Its LoRa OTA support is source-only: it can serve a host file to another node
|
||||
but has no staging store and cannot update itself over LoRa.
|
||||
Installing an ESP32 Full Companion may require one merged-image erase/flash
|
||||
@@ -127,8 +128,8 @@ The old aliases still work with `build-firmware` and
|
||||
collapsed; they retain their exact storage, bootloader, role, and target
|
||||
identity contracts. Companion boards keep transport-specific canonical images
|
||||
only when no exact Full recipe has passed the combined flash/RAM qualification.
|
||||
Dual CDC is not required: a qualified single-TTY Full image safely makes Binary
|
||||
Companion and plaintext USB logging mutually exclusive.
|
||||
ESP32 deliberately uses one TTY: Binary Companion and plaintext USB logging
|
||||
are mutually exclusive there. nRF52 retains its optional second CDC port.
|
||||
|
||||
## Complete CLI policy
|
||||
|
||||
|
||||
@@ -72,7 +72,7 @@ fix, no WiFi connection, an inactive bridge, or an nRF52 bootloader without
|
||||
| Statistics | [`set telemetry.gps`; `get/set/send telemetry.tx`](cli_commands.md#read-repeater-telemetry-history) | Non-STM32 repeater; GPS setting requires a provider; remote access requires administrator | Yes | Yes | Yes |
|
||||
| Logging | [`log start`; `log stop`; `log erase`](cli_commands.md#logging) | Storage-backed roles retain data; other roles can return empty data | Yes | Yes | Yes |
|
||||
| Logging | [`log`](cli_commands.md#print-the-captured-log-to-the-serial-terminal) | Local serial | Serial | Serial | Serial |
|
||||
| Logging | [`get/set usb.logging`; unified FULL `get/set logging.output`](cli_commands.md#control-live-usb-logging) | Ordinary safe-USB artifacts; CommonCLI USB gate is persistent; unified ESP32 FULL selects off/USB/WiFi/both; Full Companion uses either a reboot-controlled second CDC or an input-capable single-TTY logging terminal | Yes | Yes | No |
|
||||
| Logging | [`get/set usb.logging`; unified FULL `get/set logging.output`](cli_commands.md#control-live-usb-logging) | Ordinary safe-USB artifacts; CommonCLI USB gate is persistent; unified ESP32 FULL selects off/USB/WiFi/both; nRF52 Full Companion can add a reboot-controlled second CDC | Yes | Yes | No |
|
||||
| Radio | [`get radio`; `set radio ...`](cli_commands.md#view-or-change-this-nodes-radio-parameters) | All text CLI roles | Yes | Yes | Yes |
|
||||
| Radio | [`get tx`; `set tx <dbm>`](cli_commands.md#view-or-change-this-nodes-transmit-power) | Board TX-power limits apply | Yes | Yes | Yes |
|
||||
| Radio | [`tempradio ...`; `normalradio`](cli_commands.md#change-the-radio-parameters-for-a-set-duration) | Full parser | Yes | Yes | Yes |
|
||||
@@ -236,7 +236,7 @@ fix, no WiFi connection, an inactive bridge, or an nRF52 bootloader without
|
||||
| Statistics | [`set telemetry.gps`; `get/set/send telemetry.tx`](cli_commands.md#read-repeater-telemetry-history) | Non-STM32 repeater; GPS setting requires a provider; remote access requires administrator | Yes | Yes | Yes | Yes | Yes |
|
||||
| Logging | [`log start`; `log stop`; `log erase`](cli_commands.md#logging) | Storage-backed roles retain data | Yes | Yes | Yes | Yes | Yes |
|
||||
| Logging | [`log`](cli_commands.md#print-the-captured-log-to-the-serial-terminal) | Local serial | Serial | Serial | Serial | Serial | Serial |
|
||||
| Logging | [`get/set usb.logging`; unified FULL `get/set logging.output`](cli_commands.md#control-live-usb-logging) | Ordinary safe-USB artifacts; CommonCLI USB gate is persistent; unified ESP32 FULL selects off/USB/WiFi/both; Full Companion uses either a reboot-controlled second CDC or an input-capable single-TTY logging terminal | Yes | Yes | No | No | Yes |
|
||||
| Logging | [`get/set usb.logging`; unified FULL `get/set logging.output`](cli_commands.md#control-live-usb-logging) | Ordinary safe-USB artifacts; CommonCLI USB gate is persistent; unified ESP32 FULL selects off/USB/WiFi/both; every ESP32 Full Companion uses an input-capable single-TTY logging terminal with framed USB Companion disabled while logging | Yes | Yes | No | No | Yes |
|
||||
| Radio | [`get radio`; `set radio ...`](cli_commands.md#view-or-change-this-nodes-radio-parameters) | All text CLI roles | Yes | Yes | Yes | Yes | Yes |
|
||||
| Radio | [`get tx`; `set tx <dbm>`](cli_commands.md#view-or-change-this-nodes-transmit-power) | Board TX-power limits apply | Yes | Yes | Yes | Yes | Yes |
|
||||
| Radio | [`tempradio ...`; `normalradio`](cli_commands.md#change-the-radio-parameters-for-a-set-duration) | Full parser | Yes | Yes | Yes | Yes | Yes |
|
||||
|
||||
+19
-16
@@ -624,26 +624,29 @@ Binary `get/set` parameter namespace. Open interface `00`, send
|
||||
`meshcli ... get usb.logging` directly can instead return
|
||||
`Unknown var usb.logging` because that is a different protocol operation.
|
||||
|
||||
Dual-CDC Full Companion instead defaults logging to off and enumerates only
|
||||
USB interface `00`, which carries Companion, terminal, and serial mOTA traffic.
|
||||
Enabling logging adds interface `02`, its dedicated plaintext logging port, on
|
||||
the next boot. Disabling it removes interface `02` on the next boot. A command
|
||||
without the optional `reboot` argument saves the choice and reports that a
|
||||
reboot is required when the USB interface count must change. The exact
|
||||
nRF52 Full Companion defaults logging to off and enumerates only USB interface
|
||||
`00`, which carries Companion, terminal, and serial mOTA traffic. Enabling
|
||||
logging adds interface `02`, its dedicated plaintext logging port, on the next
|
||||
boot. Disabling it removes interface `02` on the next boot. A command without
|
||||
the optional `reboot` argument saves the choice and reports that a reboot is
|
||||
required when the USB interface count must change. The exact
|
||||
`set usb.logging on reboot` and `set usb.logging off reboot` forms save the
|
||||
choice, send their reply, and reboot one second later only when needed. This
|
||||
behavior includes nRF52 and dual-CDC native-USB ESP32-S3 Full images.
|
||||
choice, send their reply, and reboot one second later only when needed.
|
||||
|
||||
On a single-TTY ESP32 Full Companion, enter the USB text terminal and use
|
||||
On every ESP32 Full Companion, enter the USB text terminal and use
|
||||
`set usb.logging on` to turn that TTY into a logging-repeater-style plaintext
|
||||
stream. It remains an input-capable CLI, so `set usb.logging off` works on the
|
||||
same TTY and automatically restores Binary Companion after its reply. No
|
||||
reboot is needed because the USB interface count does not change.
|
||||
stream. Framed Binary Companion is unavailable on USB while logging is on. The
|
||||
TTY remains an input-capable CLI, so `set usb.logging off` works on the same
|
||||
TTY. After its reply, logging stops and the TTY remains in the normal ASCII
|
||||
terminal, just as it does after a fresh Full installation. Send
|
||||
`+++MESHCORE-TERM-STOP`, or let a Companion app send a valid framed probe, to
|
||||
switch it to Binary Companion. No reboot is needed because the USB interface
|
||||
count does not change.
|
||||
|
||||
Turning USB logging off does not disable CLI replies. Dual-CDC builds keep
|
||||
Companion frames active on interface `00`; single-TTY builds resume frames when
|
||||
their terminal session ends. This setting does not change the node-storage
|
||||
capture controlled by `log start` and `log stop`.
|
||||
Turning USB logging off does not disable CLI replies. nRF52 keeps Companion
|
||||
frames active on interface `00`; ESP32 resumes the ordinary ASCII/Binary
|
||||
switcher after the logging terminal turns logging off. This setting does not
|
||||
change the node-storage capture controlled by `log start` and `log stop`.
|
||||
|
||||
Unified ESP32 FULL builds add one saved selector for both output paths:
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ firmware as an mOTA image.
|
||||
| USB Binary Companion | Yes | Yes |
|
||||
| BLE Binary Companion | Yes | Yes |
|
||||
| USB ASCII terminal | Yes | Yes |
|
||||
| Dedicated USB plaintext logging | Qualified native-USB ESP32-S3 profiles | 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 |
|
||||
@@ -29,13 +29,15 @@ passed the combined-transport size check:
|
||||
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, Heltec Wireless Tracker,
|
||||
Wireless Paper, E213, and CT62; LilyGo T3S3 SX1262/SX1276, T-Deck, TETH Elite,
|
||||
classic T-Beam SX1262/SX1276, and T-Beam S3 Supreme; Ebyte EoRa-S3;
|
||||
Meshadventurer SX1262/SX1268; and XIAO S3. 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.
|
||||
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.
|
||||
|
||||
List the available targets:
|
||||
|
||||
@@ -69,8 +71,8 @@ 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. Dual-CDC builds separate framed traffic and logs;
|
||||
single-TTY builds make those modes mutually exclusive. In WebConfig, use the
|
||||
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
|
||||
@@ -103,8 +105,15 @@ set display.rotation 0
|
||||
|
||||
`0` resets the screen to that board's compiled default orientation.
|
||||
|
||||
Heltec E290 and T190 use one `usb_ble` Companion artifact for simultaneous USB
|
||||
and BLE rather than publishing separate USB-only and BLE-only images.
|
||||
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:
|
||||
@@ -196,8 +205,8 @@ started before WiFi on any combined ESP32 WiFi+BLE Companion to avoid heap
|
||||
fragmentation. 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 whenever
|
||||
the board uses dual CDC.
|
||||
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 together. The T-Beam 1W Full
|
||||
@@ -318,23 +327,31 @@ WiFi credential, status, WebConfig, CLI-tab, and power-save controls. Every
|
||||
Full Companion provides persistent `get/set usb.logging` and starts with
|
||||
logging off on a fresh installation.
|
||||
|
||||
### Single USB serial port
|
||||
### ESP32 single USB serial port
|
||||
|
||||
On an ESP32 Full Companion without dual CDC, interface `00` has 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`, then run `set usb.logging on`; the same TTY emits
|
||||
plaintext packet/debug logs and continues accepting CLI commands, including
|
||||
`set usb.logging off`. Turning it off sends the command reply and then returns
|
||||
that TTY to Binary Companion automatically, including on USB-UART bridges that
|
||||
cannot detect a cable disconnect. A saved logging-on preference boots directly
|
||||
into this input-capable logging terminal. BLE and Wi-Fi Companion remain
|
||||
available while USB is logging.
|
||||
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`, then run `set usb.logging on`; the same
|
||||
TTY 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.
|
||||
|
||||
### Dual USB serial ports
|
||||
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.
|
||||
|
||||
Current nRF52 Full Companion and qualified native-USB ESP32-S3 Full Companion
|
||||
firmware can expose two CDC ACM serial interfaces on one physical USB cable:
|
||||
### 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
|
||||
@@ -362,35 +379,30 @@ When logging is on, Linux normally shows two `/dev/ttyACM*` devices. Match the s
|
||||
`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. Qualified S3 boards
|
||||
temporarily expose the ESP32-S3 ROM USB-JTAG serial port during a wired flash.
|
||||
its normal DFU serial interface during an update.
|
||||
|
||||
Opening the logging port prints `MeshCore USB logging port` followed by its
|
||||
portable identity, `USB CDC 1; interface 02; Linux stable suffix: -if02`.
|
||||
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.
|
||||
|
||||
Dual-CDC ESP32-S3 targets are Heltec V4, T-Beam 1W, Station G2/G3, XIAO S3
|
||||
WIO, Heltec Tracker V2, Meshnology W12, and Nibble Screen/Zero Connect. The
|
||||
base Heltec V4 profile has completed live two-interface, ROM-flashing, and
|
||||
logging-off one-interface validation. Full recipes with only one usable TTY
|
||||
still replace separate transport images; they use the exclusive terminal/log
|
||||
mode above because firmware cannot add a second interface to a USB-UART bridge
|
||||
or a single-port USB peripheral.
|
||||
|
||||
Every ESP32-S3 Full Companion image uses DIO flash mode, including the RAK3112
|
||||
and RC32 profiles that do not expose dual CDC. The S3 ROM supports DIO while
|
||||
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.
|
||||
|
||||
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 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
|
||||
|
||||
+31
-26
@@ -178,12 +178,18 @@ board-qualified serial or Ethernet Companion transport. Bulk builds therefore
|
||||
omit separate attached-transport, Terminal Chat, and USB-logging artifacts
|
||||
whenever the exact Full recipe exists. RAK4631 repeater and room-server
|
||||
Ethernet images remain separate roles. Fresh installs default to logging off.
|
||||
Heltec V3 and base OLED V4 Full images also contain the former direct Wi-Fi
|
||||
MQTT Companion capability, configured at runtime through WebConfig, so their
|
||||
separate `companion_radio_wifi_mqtt` artifacts are omitted from canonical
|
||||
builds as well.
|
||||
|
||||
When Full Companion does not fit but a matching USB Companion does, that USB
|
||||
artifact also supplies Terminal Chat and replaces its standalone release image.
|
||||
Heltec E290 and T190 publish a combined USB + BLE Companion. SSD1306 Full
|
||||
Companion builds use `set display.rotation 90|180|270`; `0` restores the board
|
||||
default, so a separate rotated release image is not recommended.
|
||||
Heltec E290 and T190 now publish one Full USB + BLE + WiFi Companion; their old
|
||||
combined and single-transport names are explicit-build compatibility aliases.
|
||||
SSD1306 Full Companion builds use `set display.rotation 90|180|270`; `0`
|
||||
restores the board default, so a separate rotated release image is not
|
||||
recommended.
|
||||
|
||||
Ordinary non-OTA roles also use one artifact for normal operation and USB
|
||||
logging. Select the saved mode with `set usb.logging off|on`; no `-logging-`
|
||||
@@ -191,23 +197,22 @@ artifact is emitted. KISS, BLE-only Companion, and constrained LoRa-OTA
|
||||
receiver images retain their protocol/partition contracts and do not inherit
|
||||
plaintext USB logging.
|
||||
|
||||
Dual-CDC nRF52 and qualified native-USB ESP32-S3 builds keep the multi-role
|
||||
primary interface on `00`; it starts as an ASCII terminal and automatically
|
||||
hands a complete `<` frame to Binary Companion. `set usb.logging on reboot`
|
||||
adds plaintext interface `02`.
|
||||
Single-TTY ESP32 builds instead use `set usb.logging on` to switch that TTY to
|
||||
an input-capable plaintext logging terminal. `set usb.logging off` stops the
|
||||
logs and returns the TTY to Binary Companion after its reply. BLE and Wi-Fi
|
||||
remain usable while the USB TTY is logging.
|
||||
nRF52 Full Companion keeps the multi-role primary interface on `00`; it starts
|
||||
as an ASCII terminal and automatically hands a complete `<` frame to Binary
|
||||
Companion. `set usb.logging on reboot` adds its plaintext interface `02`.
|
||||
|
||||
The dual-CDC ESP32-S3 subset includes Heltec V4, T-Beam 1W, Station G2/G3,
|
||||
XIAO S3 WIO, Heltec Tracker V2, Meshnology W12, and Nibble Screen/Zero Connect
|
||||
layouts. Existing single-TTY Full recipes include RAK3112, Heltec RC32,
|
||||
Heltec V3/WSL3, ThinkNode M2/M5/M7/M9, Heltec V2, LilyGo T-LoRa V2.1.1.6,
|
||||
and XIAO C3. Additional qualified single-TTY ESP32 profiles include M5Stack
|
||||
Unit C6L, Heltec Wireless Tracker/Paper/E213/CT62, LilyGo T3S3
|
||||
SX1262/SX1276, T-Deck, TETH Elite, classic T-Beam SX1262/SX1276, T-Beam S3
|
||||
Supreme, Ebyte EoRa-S3, Meshadventurer SX1262/SX1268, and XIAO S3.
|
||||
Every ESP32 Full Companion instead exposes one USB TTY. Logging is off by
|
||||
default, so the TTY serves the ASCII/Binary Companion switcher. Use
|
||||
`set usb.logging on` to turn that same TTY into an input-capable plaintext
|
||||
CLI/logging stream; framed Binary Companion is unavailable on USB while
|
||||
logging owns it. `set usb.logging off` stops the logs and leaves the 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 from there to Binary Companion. BLE and Wi-Fi Companion remain usable
|
||||
while the USB TTY is logging. ESP32 Full builds use the repository's
|
||||
Arduino-ESP32 2.x base where the board supports it; RC32 and ESP32-C6 retain
|
||||
their board-required Arduino 3.x platform but still expose only one USB TTY.
|
||||
A second ESP32 CDC interface is not part of the release profile.
|
||||
|
||||
## Installation methods
|
||||
|
||||
@@ -244,11 +249,11 @@ saving, controllable FEM receive gain, and radio-chip receive gain are saved
|
||||
settings rather than separate recommended firmware files. Do not substitute a
|
||||
similarly named physical target.
|
||||
|
||||
For hardware with a dual-CDC Full Companion image, the picker recommends that
|
||||
one normal image instead of separate USB, BLE, ordinary WiFi, and USB-logging
|
||||
images. Full Companion provides the attached transports and a dedicated
|
||||
plaintext logging port when enabled without mixing logs into framed Companion
|
||||
traffic. Logging is off by default, so only primary interface `00` appears; it
|
||||
starts in ASCII and automatically changes to framed Companion when a complete
|
||||
`<` frame arrives. Enabling logging and rebooting adds interface `02`.
|
||||
The picker recommends one Full Companion image instead of separate USB, BLE,
|
||||
ordinary WiFi, and USB-logging images. On ESP32, logging is off by default so
|
||||
the one USB TTY starts in ASCII and automatically changes to framed Companion
|
||||
when a complete `<` frame arrives. Enabling logging gives that TTY to the
|
||||
plaintext CLI/logger and disables framed USB Companion until logging is turned
|
||||
off and the normal ASCII-to-binary mode switch occurs. nRF52 Full Companion
|
||||
retains its optional dedicated interface `02`.
|
||||
Exact filename search still finds old aliases from earlier releases.
|
||||
@@ -62,6 +62,7 @@ boot ------> ASCII terminal Binary Companion
|
||||
|
||||
ASCII terminal -- +++MESHCORE-TERM-STOP ------> Binary Companion
|
||||
ASCII terminal -- observable USB disconnect ---> Binary Companion
|
||||
ESP32 logging terminal -- usb.logging off -----> ASCII terminal
|
||||
any mode ------- reboot ------------------------> ASCII terminal
|
||||
```
|
||||
|
||||
@@ -144,14 +145,21 @@ mOTA traffic on the same stream.
|
||||
| Situation | Primary USB behavior |
|
||||
| --- | --- |
|
||||
| Full Companion after boot | ASCII; a complete `<` frame switches to Binary Companion |
|
||||
| Dual-CDC logging enabled | Primary interface still follows the switcher; logs use the optional second interface |
|
||||
| Single-TTY logging enabled at boot | Logging terminal owns primary USB; automatic `<` detection is disabled |
|
||||
| nRF52 logging enabled | Primary interface still follows the switcher; logs use the optional second interface |
|
||||
| ESP32 logging enabled at boot | Logging terminal owns the only USB TTY; automatic `<` detection is disabled |
|
||||
| nRF52 USB serial mOTA active | mOTA owns primary USB; ASCII and Binary Companion are unavailable there |
|
||||
| BLE/WiFi/Ethernet/hardware serial | Always Binary Companion and unaffected by the USB mode |
|
||||
|
||||
On a single-TTY build, use `set usb.logging off` in its logging terminal before
|
||||
trying to use primary USB with an app. BLE and WiFi Companion transports remain
|
||||
available while primary USB is logging.
|
||||
On every ESP32 Full Companion, use `set usb.logging off` in its logging terminal
|
||||
before trying to use USB with an app. That command stops logging and returns to
|
||||
the ordinary ASCII terminal; it does not select Binary Companion. The app's
|
||||
first valid framed probe can perform the normal automatic switch, or a human
|
||||
can send `+++MESHCORE-TERM-STOP` first. The framed/binary Companion parser is
|
||||
disabled while logging owns that TTY. BLE and WiFi Companion transports remain
|
||||
available while USB is logging. ESP32 Full builds use the Arduino-ESP32 2.x
|
||||
base where supported; RC32 and ESP32-C6 keep their board-required Arduino 3.x
|
||||
platform but follow the same one-TTY policy. No ESP32 Full build enumerates a
|
||||
second CDC interface.
|
||||
|
||||
On nRF52, serial `motatool` is also text-first. Its exact initial
|
||||
`ota folder on` line is recognized in either startup ASCII or Binary Companion
|
||||
@@ -235,7 +243,7 @@ prefix it with another character if it is needed as command text.
|
||||
If `meshcli` cannot connect:
|
||||
|
||||
1. close every terminal or logging reader using the primary interface;
|
||||
2. confirm that saved single-TTY logging is off;
|
||||
2. on ESP32, confirm that saved USB logging is off;
|
||||
3. reboot and let `meshcli` be the first process to open the data interface;
|
||||
4. use the stable `/dev/serial/by-id/*-if00` path on Linux when available;
|
||||
5. if a prompt appears after one second, the client's first frame was not
|
||||
|
||||
@@ -120,10 +120,13 @@ set usb.logging {on|off} [reboot]
|
||||
Shows or changes persistent live USB debug and packet output in an ordinary
|
||||
USB-loggable Companion or Full Companion. USB Companion and Full start off on
|
||||
a fresh install with logging disabled to protect framed traffic.
|
||||
Dual-CDC Full changes its interface count after a reboot and keeps Companion on
|
||||
interface `00`. Single-TTY Full needs no reboot: logging uses the active text
|
||||
terminal, which continues accepting `set usb.logging off` and automatically
|
||||
restores Binary Companion after that reply.
|
||||
nRF52 Full changes its interface count after a reboot and keeps Companion on
|
||||
interface `00`. Every ESP32 Full Companion has one TTY and needs no reboot:
|
||||
logging uses the active text terminal, disables framed Binary Companion on
|
||||
USB, and continues accepting `set usb.logging off`. Turning logging off leaves
|
||||
the port in the normal ASCII terminal, matching fresh firmware. Send
|
||||
`+++MESHCORE-TERM-STOP`, or let a Companion app send a valid framed probe, to
|
||||
switch it to Binary Companion afterward.
|
||||
|
||||
```
|
||||
reboot
|
||||
|
||||
Reference in new issue
Block a user