Expand full Companion terminal tooling

This commit is contained in:
mikecarper committed 2026-08-10 14:53:39 -07:00
1 parent 88ba5b26cb
commit 4e91cc9487
10 files changed
+1235 -41

No files matched your search

+58 -6
View File
@@ -81,15 +81,59 @@ USB starts in Binary mode for MeshCore apps and `meshcli`:
meshcli -s /dev/ttyACM0 -b 115200 ver
```
Open the port at 115200 and send the terminal start token as an exact line:
Open the port with the terminal start token sent automatically:
```bash
picocom -b 115200 /dev/ttyACM0
+++MESHCORE-TERM-START
picocom -b 115200 \
--imap spchex \
--initstring '+++MESHCORE-TERM-START' \
/dev/ttyACM0
```
The terminal supports Companion chat commands plus local `ota`, `tempradio`,
and `normalradio` controls. Return to Binary mode with:
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. For example:
```text
channels
channel #rgdata Hello from Eugene 👋
to Hilltop Repeater
login my-admin-password
cmd ver
trace
```
The `to` command selects the remote-administration target. 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>`. Remote ACL permissions determine which commands the
target accepts.
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
@@ -146,12 +190,20 @@ motatool serve --dir ./motas --tcp 192.168.1.50:5001 -v
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' \
/dev/ttyACM1
```
```text
+++MESHCORE-TERM-START
tempradio 909.950,250,7,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
+14 -5
View File
@@ -129,11 +129,20 @@ meshcli -r -s /dev/ttyACM1 -b 115200 "ota status"
The command must print an `OTA | ... target:XXXXXXXX` status.
For an nRF52 full Companion, open the source port in a terminal, send
`+++MESHCORE-TERM-START`, and run `ota status`. It must report `OTA seeder`,
`install:disabled`, and target `00000000`; send `+++MESHCORE-TERM-STOP` before
closing the terminal. The automation detects and performs this token-wrapped
preflight itself, so no extra command-line option is needed.
For an nRF52 full Companion, open the source port with terminal mode selected
automatically:
```bash
picocom -b 115200 \
--imap spchex \
--initstring '+++MESHCORE-TERM-START' \
/dev/ttyACM1
```
Run `ota status`. It must report `OTA seeder`, `install:disabled`, and target
`00000000`; send `+++MESHCORE-TERM-STOP` before closing the terminal. The
automation detects and performs this token-wrapped preflight itself, so no
extra command-line option is needed.
For an ESP32 full Companion, test its separate WiFi control console instead:
+122 -9
View File
@@ -5,13 +5,31 @@ Below are the commands you can enter into the Terminal Chat clients:
## Companion USB mode
A Companion USB build starts in the normal binary Companion protocol at
115200 baud. To use this terminal from the same firmware image, connect a
serial terminal and send this exact sequence:
115200 baud. Use this command to switch the same USB connection into terminal
mode as soon as `picocom` opens it:
```sh
picocom --baud 115200 \
--imap spchex \
--initstring '+++MESHCORE-TERM-START' \
/dev/ttyACM0
```
`--initstring` sends this exact terminal-start sequence automatically:
```
+++MESHCORE-TERM-START
```
Binary Companion frames can contain terminal control bytes. The `spchex` input
map renders those bytes as bracketed hexadecimal during the short transition
instead of allowing them to change the local terminal's character set or
display state. It leaves high-bit bytes unchanged so a UTF-8 terminal displays
emoji and non-ASCII text normally. Do not add `8bithex` unless you explicitly
want UTF-8 bytes displayed as sequences such as `[f0][9f][91][8b]`. Once the
terminal banner appears, the start sequence has already succeeded; do not
enter it again as a terminal command.
Send the following exact sequence to return to the binary protocol:
```
@@ -29,12 +47,6 @@ 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.
For example:
```sh
picocom --baud 115200 /dev/ttyACM0
```
## Commands
```
@@ -120,11 +132,90 @@ to {name-prefix}
```
Sets the recipient to the _first_ matching contact (in 'list') by the name prefix. (ie. you don't have to type whole name)
```
login {admin-password}
```
Sends a remote login request to the current recipient. Select a repeater,
room, or other remotely managed node with `to {name-prefix}` first. The
password is masked with `*` while it is entered and must be 1-15 UTF-8 bytes;
longer passwords are rejected instead of truncated.
Login results arrive asynchronously. A successful modern response displays
the remote ACL permissions byte and server protocol level. A wrong password,
an unreachable target, or a server that does not support remote login normally
produces a timeout because those nodes do not send a rejection packet.
```
cmd {remote-command}
```
Sends CLI data to the current recipient. Wait for the login result before
sending the first command. The remote node applies its own ACL permissions,
and any reply appears asynchronously as `CLI -> from {name}`.
For example:
```text
to Hilltop Repeater
login my-admin-password
LOGIN -> Hilltop Repeater accepted (ACL permissions 0x03, server v13)
cmd ver
cmd get radio
```
The exact commands and permissions depend on the target firmware. `cmd` does
not run a command on the local Companion; it sends the text over LoRa to the
selected node.
```
send {text}
```
Sends the text message (as DM) to current recipient.
```
trace
```
Traces the saved round-trip route to the current recipient and displays the
SNR at each hop. Select the recipient first with `to {name-prefix}`.
```
trace {name-prefix}
```
Traces a recipient directly without changing the current `to` selection. A
trace requires a known direct path; use normal messaging or path discovery
first if the terminal reports that no valid path is available. Only one
terminal trace can be pending at a time, and a missing response is reported as
a timeout.
For example:
```text
to Hilltop Repeater
trace
trace Downtown
```
The displayed route uses one- or two-byte node hashes and per-hop SNR values.
Saved three-byte paths are traced with two-byte prefixes because the trace
packet format has no three-byte hash-size mode.
To trace an explicit route instead of a saved contact path, provide the prefix
size followed by the complete ordered route:
```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
```
Prefix separators may be spaces, commas, or any mixture of them. Each prefix
must contain exactly 2, 4, or 8 hexadecimal digits for a 1-, 2-, or 4-byte
trace respectively. Three-byte traces are not supported.
The prefixes are used exactly in the order entered. To receive the trace
result, enter the complete outward route followed by its return route, as in
the mirrored examples above. A route that does not return to this node will
eventually report a timeout.
```
reset path
```
@@ -133,4 +224,26 @@ Resets the path to current recipient, for new path discovery.
```
public {text}
```
Sends the text message to the built-in 'public' group channel
Sends the text message to the built-in `Public` group channel.
```
channels
```
Lists the configured channel slots and names without exposing their secrets.
```
channel {name-or-slot} {text}
```
Sends a message to any configured channel by its exact name or numeric slot.
Use the slot shown by `channels` when a channel name contains spaces.
For example:
```text
channels
channel #rgdata Hello from Eugene 👋
channel 2 Another message
```
Messages are UTF-8. Emoji use multiple bytes toward the available message
length, which also includes the sender-name prefix added over the air.