Default all USB Companions to ASCII across host sessions
This commit is contained in:
1 parent
794cf15395
commit
0938da5ea6
13 files changed
+398
-145
No files matched your search
@@ -1104,7 +1104,7 @@
|
||||
const picocom = "picocom -b 115200 --imap spchex --initstring $'\\r+++MESHCORE-TERM-START\\r' /dev/ttyACM0";
|
||||
section("Companion USB terminal (Linux / Bash)", [
|
||||
{ label: "Connect", commands: [picocom],
|
||||
text: "Run this in Bash on the Linux computer connected to the radio. The init string opens the ASCII CLI; the leading carriage return clears an unfinished input line. spchex displays binary control bytes safely during the transition." },
|
||||
text: "Run this in Bash on the Linux computer connected to the radio. Updated 1.17.1.6 USB Companions default to ASCII at boot and after an observable USB session reset; a valid app frame selects Binary Companion. The init string also opens the ASCII CLI on older firmware or a port left in Binary mode; the leading carriage return clears an unfinished input line. spchex displays binary control bytes safely during the transition." },
|
||||
{ label: "Recover scrambled terminal", commands: ["reset", picocom],
|
||||
text: "First exit picocom with Ctrl+A, then Ctrl+X. Run these commands in your Linux shell: reset repairs the terminal display, then picocom reconnects with safe input mapping." },
|
||||
], "Replace /dev/ttyACM0 with your radio's port, such as /dev/ttyACM1 or /dev/ttyUSB0. Use the primary USB data interface (00 when multiple interfaces appear), and close other apps using that port. At the radio prompt, run version and board to identify the node. Exit picocom with Ctrl+A, then Ctrl+X.");
|
||||
@@ -1209,8 +1209,8 @@
|
||||
guide.href = "https://github.com/mikecarper/MeshCore/blob/keymindCascade/docs/role_feature_switches.md";
|
||||
links.appendChild(guide);
|
||||
panel.appendChild(links);
|
||||
if (isFullCompanion(profile) || ["repeater", "room", "sensor"].includes(profile.role)) {
|
||||
panel.appendChild(createElement("p", "Use a data-capable USB cable and 115200 baud. Full Companion and infrastructure start in ASCII mode. " + (profile.role === "companion"
|
||||
if (isFullCompanion(profile) || (profile.role === "companion" && ["usb", "usb-ble"].includes(profile.mode)) || ["repeater", "room", "sensor"].includes(profile.role)) {
|
||||
panel.appendChild(createElement("p", "Use a data-capable USB cable and 115200 baud. Updated USB Companion and infrastructure builds start in ASCII mode. " + (profile.role === "companion"
|
||||
? "Open Companion USB terminal below for Linux connection and recovery commands. Use board and version to identify the node."
|
||||
: "Use board and ver to identify the node.")));
|
||||
}
|
||||
|
||||
@@ -368,7 +368,7 @@ itself.
|
||||
|
||||
| Platform | Interface | Purpose |
|
||||
| --- | --- | --- |
|
||||
| Both | USB, 115200 baud | ASCII after boot; automatically switches on the first complete Binary Companion frame |
|
||||
| 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 |
|
||||
@@ -433,7 +433,8 @@ Expose them only on a trusted LAN or temporary setup network. See
|
||||
|
||||
## USB Binary and text terminal modes
|
||||
|
||||
Full Companion USB starts in the ASCII terminal after boot. MeshCore apps and
|
||||
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:
|
||||
|
||||
@@ -443,7 +444,8 @@ 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 reboot or the explicit terminal start token. See
|
||||
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.
|
||||
@@ -649,10 +651,11 @@ Return to Binary mode with:
|
||||
+++MESHCORE-TERM-STOP
|
||||
```
|
||||
|
||||
Closing an armed ASCII USB data connection also changes the port to Binary
|
||||
mode when the hardware can report disconnect. A USB-to-UART bridge may not be
|
||||
able to report this event. A different baud rate, including 57600, does not
|
||||
select ASCII mode.
|
||||
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:
|
||||
|
||||
@@ -6,7 +6,7 @@ controls. Select On, Off, or Check to view and copy the commands; Companion
|
||||
MQTT and GPS show their app/WebConfig steps instead. See
|
||||
[feature switches by role](role_feature_switches.md) for the full reference.
|
||||
The [USB web console](https://flasher.meshcore.io/console) works with the
|
||||
default ASCII terminal on Full Companion and infrastructure roles.
|
||||
default ASCII terminal on USB Companion and infrastructure roles.
|
||||
|
||||
Pick the choices in any order. Every selection narrows all the other controls
|
||||
to firmware combinations that were actually built in the current release set.
|
||||
@@ -300,6 +300,11 @@ Full, USB and USB + Bluetooth Companion results include **Companion USB terminal
|
||||
(Linux / Bash)** under **Restore your settings after flashing**, with copyable
|
||||
connection and recovery commands.
|
||||
|
||||
Updated 1.17.1.6 USB Companions default to ASCII at boot and after an observable
|
||||
USB session reset. `picocom -b 115200 /dev/ttyACM0` is sufficient for a fresh
|
||||
session. A valid framed app command automatically selects Binary Companion.
|
||||
The command below also works with older firmware or a port left in Binary mode.
|
||||
|
||||
Run this in Bash on the Linux computer connected to your radio:
|
||||
|
||||
```bash
|
||||
@@ -310,7 +315,7 @@ picocom -b 115200 --imap spchex \
|
||||
|
||||
Replace `/dev/ttyACM0` with your radio's port, such as `/dev/ttyACM1` or
|
||||
`/dev/ttyUSB0`. Use the primary USB data interface (`00` when multiple interfaces
|
||||
appear), and close other apps using it. The init string opens the ASCII CLI;
|
||||
appear), and close other apps using it. The init string requests the ASCII CLI;
|
||||
its leading carriage return clears an unfinished input line. `--imap spchex`
|
||||
displays binary control bytes safely during the transition.
|
||||
|
||||
|
||||
@@ -23,7 +23,8 @@ for the corrected download; the earlier `aa20e927` Wireless Paper image has
|
||||
|
||||
Close the app or serial monitor using the USB port, then open a terminal at
|
||||
115200 baud, or use the [USB web console](https://flasher.meshcore.io/console).
|
||||
A fresh Full Companion boot starts in ASCII text mode. If it is already in Binary
|
||||
A fresh Full Companion boot or observable USB session reset starts in ASCII
|
||||
text mode. If it is already in Binary
|
||||
Companion mode, send this line once and wait for the terminal banner:
|
||||
|
||||
```text
|
||||
|
||||
@@ -1,19 +1,20 @@
|
||||
# Full Companion USB CLI and binary switcher
|
||||
# Companion USB CLI and binary switcher
|
||||
|
||||
Full Companion uses one primary USB serial interface for two incompatible wire
|
||||
USB Companion uses one primary USB serial interface for two incompatible wire
|
||||
formats:
|
||||
|
||||
- a human-readable ASCII command line;
|
||||
- the framed Binary Companion protocol used by MeshCore apps and `meshcli`.
|
||||
|
||||
The primary interface starts in the ASCII terminal after each boot. A Binary
|
||||
The primary interface starts in the ASCII terminal after each boot and returns
|
||||
to ASCII after a USB session reset that the hardware can observe. A Binary
|
||||
Companion client does not need to send a special mode command: its first valid
|
||||
frame automatically hands the interface to the binary parser.
|
||||
|
||||
This automatic behavior is compiled only into `companion_radio_full` targets.
|
||||
Ordinary USB Companion builds continue to use the explicit
|
||||
`+++MESHCORE-TERM-START` and `+++MESHCORE-TERM-STOP` controls described in the
|
||||
[Terminal Chat CLI guide](./terminal_chat_cli.md).
|
||||
This behavior applies to Full and ordinary USB Companion builds in the updated
|
||||
1.17.1.6 release. The explicit `+++MESHCORE-TERM-START` and
|
||||
`+++MESHCORE-TERM-STOP` controls remain available, including for older firmware.
|
||||
See the [Terminal Chat CLI guide](./terminal_chat_cli.md).
|
||||
|
||||
## Wire formats
|
||||
|
||||
@@ -61,7 +62,7 @@ boot ------> ASCII terminal Binary Companion
|
||||
+--------------------------------+
|
||||
|
||||
ASCII terminal -- +++MESHCORE-TERM-STOP ------> Binary Companion
|
||||
ASCII terminal -- observable USB disconnect ---> Binary Companion
|
||||
any mode ------- observable USB session reset ---> ASCII terminal
|
||||
ESP32 logging terminal -- usb.logging off -----> ASCII terminal
|
||||
any mode ------- reboot ------------------------> ASCII terminal
|
||||
```
|
||||
@@ -72,7 +73,7 @@ switched; they remain binary.
|
||||
|
||||
## How automatic detection works
|
||||
|
||||
1. Full Companion initializes the normal USB Binary Companion interface, then
|
||||
1. Companion initializes the normal USB Binary Companion interface, then
|
||||
gives its primary stream to the ASCII terminal before normal loop service
|
||||
begins.
|
||||
2. While the prompt has no buffered input, the terminal peeks at the next byte.
|
||||
@@ -144,7 +145,7 @@ mOTA traffic on the same stream.
|
||||
|
||||
| Situation | Primary USB behavior |
|
||||
| --- | --- |
|
||||
| Full Companion after boot | ASCII; a complete `<` frame switches to Binary Companion |
|
||||
| USB Companion after boot or observable session reset | ASCII; a complete `<` frame switches to Binary Companion |
|
||||
| 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 |
|
||||
@@ -178,17 +179,22 @@ leading/trailing whitespace, or a partial line remain ordinary terminal input.
|
||||
This mechanism is deliberately small and deterministic, but it is not a full
|
||||
protocol negotiation layer.
|
||||
|
||||
### It is startup selection, not per-connection negotiation
|
||||
### Session detection depends on the USB hardware
|
||||
|
||||
After the first complete binary frame, the device stays in Binary Companion
|
||||
mode. Closing `meshcli` does not automatically restore ASCII. Use the terminal
|
||||
start token or reboot when an ASCII prompt is needed again.
|
||||
mode for that session. Native USB with DTR/session events restores ASCII when
|
||||
the host closes or resets the connection. Old input, queued output and mOTA
|
||||
ownership are cleared before selecting the default for the next session.
|
||||
|
||||
Conversely, closing an ASCII terminal on native USB normally changes the port
|
||||
to binary mode because the firmware can observe USB DTR/data disconnect. The
|
||||
next client therefore sees binary mode, not a new ASCII session. A USB-to-UART
|
||||
bridge often cannot report disconnect, so it can remain in ASCII until the stop
|
||||
token or a reboot.
|
||||
ESP32 hardware USB Serial/JTAG reports bus reset and physical host loss, but
|
||||
cannot reliably report a terminal program closing its handle. A USB-to-UART
|
||||
bridge also usually cannot report that close. On those ports, use the terminal
|
||||
start token to return from Binary mode without rebooting. Idle time alone never
|
||||
changes the selected protocol.
|
||||
|
||||
An active network terminal temporarily delays restoring the USB ASCII prompt.
|
||||
If a fresh USB app sends a complete binary frame during that delay, its Binary
|
||||
mode remains selected when the network terminal closes.
|
||||
|
||||
### Detection works only at an empty prompt
|
||||
|
||||
|
||||
+17
-11
@@ -83,9 +83,15 @@ password fields masked; explicit local CLI getters return their values.
|
||||
|
||||
## Companion USB mode
|
||||
|
||||
An ordinary Companion USB build starts in the normal binary Companion protocol
|
||||
at 115200 baud. Use this command to switch the same USB connection into terminal
|
||||
mode as soon as `picocom` opens it:
|
||||
Updated 1.17.1.6 USB Companion builds, including ordinary and Full builds, start
|
||||
in ASCII at 115200 baud. A valid framed app command automatically selects Binary
|
||||
Companion. You can open a terminal without a start token:
|
||||
|
||||
```sh
|
||||
picocom --baud 115200 /dev/ttyACM0
|
||||
```
|
||||
|
||||
For older firmware or a port already in Binary mode, use:
|
||||
|
||||
```sh
|
||||
picocom --baud 115200 \
|
||||
@@ -119,10 +125,11 @@ Send the following exact sequence to return to the binary protocol:
|
||||
+++MESHCORE-TERM-STOP
|
||||
```
|
||||
|
||||
Closing the serial connection also returns native-USB devices to binary mode.
|
||||
Boards whose USB connector is implemented by a USB-to-UART bridge cannot
|
||||
observe the host closing the port; on those boards, use the stop sequence or
|
||||
reboot the device.
|
||||
An observable USB session reset restores ASCII after clearing the previous
|
||||
client's state. Native USB with DTR can detect a terminal closing; ESP32 hardware
|
||||
USB Serial/JTAG detects bus resets and physical host loss. USB-to-UART bridges
|
||||
usually cannot detect a terminal closing. Use the start token on ports that
|
||||
remain in Binary mode; idle time does not select ASCII.
|
||||
|
||||
Both modes use the same port at 115200. Selecting 57600 is not a portable mode
|
||||
switch: native USB CDC devices ignore the requested baud, while USB-to-UART
|
||||
@@ -130,10 +137,9 @@ devices really change the UART timing and receive corrupt data. Binary mode is
|
||||
the framed Companion API used by apps and `meshcli`; close the terminal before
|
||||
opening that port from an app.
|
||||
|
||||
Full Companion differs: its primary USB interface starts in ASCII after boot
|
||||
and automatically switches when it sees a complete `<`-prefixed Companion
|
||||
frame at an empty prompt. The explicit start/stop tokens remain available. See
|
||||
[Full Companion USB CLI and binary switcher](./full_companion_usb_switcher.md)
|
||||
All USB Companion builds automatically switch when they see a complete
|
||||
`<`-prefixed Companion frame at an empty prompt. The explicit start/stop tokens
|
||||
remain available. See [Companion USB CLI and binary switcher](./full_companion_usb_switcher.md)
|
||||
for the state machine and limitations.
|
||||
|
||||
## Commands
|
||||
|
||||
Reference in new issue
Block a user