Expand full Companion terminal tooling
This commit is contained in:
1 parent
88ba5b26cb
commit
4e91cc9487
10 files changed
+1235
-41
No files matched your search
@@ -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
|
||||
|
||||
@@ -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
@@ -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.
|
||||
Reference in new issue
Block a user