meshcore-dev/meshcore-cli
1
0
Fork 0
mirror of https://github.com/meshcore-dev/meshcore-cli.git synced 2026-04-20 22:13:48 +00:00
Code Issues Projects Releases Packages Wiki Activity

documentation ...

Browse source
This commit is contained in:
Florent 2025-04-30 09:19:58 +02:00
parent 7da64a0728
commit f332d2fc2b
3 changed files with 73 additions and 61 deletions
Download patch file Download diff file Expand all files Collapse all files

125
README.md
View file

@ -20,9 +20,9 @@ If you want meshcore-cli to remember last BLE device, you should have some `$HOM
$ meshcli <args> <commands> $ meshcli <args> <commands>
</pre> </pre>
If using BLE, don't forget to pair your device first (using `bluetoothctl` for instance on Linux) or meshcli won't be able to communicate. If using BLE, don't forget to pair your device first (using `bluetoothctl` for instance on Linux) or meshcli won't be able to communicate. There is a device selector for BLE, you'll just have to use `meshcli -S` to select your device, subsequent calls to meshcli will be send to that device.
## Configuration ### Configuration
Configuration files are stored in ```$HOME/.config/meshcore``` Configuration files are stored in ```$HOME/.config/meshcore```
@ -35,7 +35,7 @@ If there is an initialization script file called ```init```, it will be executed
Arguments mostly deals with ble connection Arguments mostly deals with ble connection
<pre> <pre>
-h : prints this help -h : prints this help
-j : json output -j : json output
-D : print debug messages -D : print debug messages
-S : BLE device selector -S : BLE device selector
@ -53,49 +53,68 @@ Arguments mostly deals with ble connection
Commands are given after arguments, they can be chained and some have shortcuts. Also prefixing a command with a dot ```.``` will force it to output json instead of synthetic result. Commands are given after arguments, they can be chained and some have shortcuts. Also prefixing a command with a dot ```.``` will force it to output json instead of synthetic result.
<pre> <pre>
General commands General commands
chat : enter the chat (interactive) mode chat : enter the chat (interactive) mode
chat_to &lt;ct&gt; : enter chat with contact to chat_to &lt;ct> : enter chat with contact to
script &lt;file&gt; : executes script stored in file script &lt;filename> : execute commands in filename
infos : print informations about the node i infos : print informations about the node i
card : export this node URI e card : export this node URI e
ver : firmware version v ver : firmware version v
reboot : reboots node reboot : reboots node
sleep &lt;secs&gt; : sleeps for a given amount of secs s sleep &lt;secs> : sleeps for a given amount of secs s
wait_key : wait until user presses &lt;Enter> wk
Messenging Messenging
msg &lt;name&gt; &lt;msg&gt; : send message to node by name m { msg &lt;name> &lt;msg> : send message to node by name m {
wait_ack : wait an ack wa } wait_ack : wait an ack wa }
chan &lt;nb&gt; &lt;msg&gt; : send message to channel number &lt;nb&gt; ch chan &lt;nb> &lt;msg> : send message to channel number <nb> ch
public : send message to public channel (0) dch public &lt;msg> : send message to public channel (0) dch
recv : reads next msg r recv : reads next msg r
sync_msgs : gets all unread msgs from the node sm
wait_msg : wait for a message and read it wm wait_msg : wait for a message and read it wm
sync_msgs : gets all unread msgs from the node sm
msgs_subscribe : display msgs as they arrive ms
Management Management
advert : sends advert a advert : sends advert a
floodadv : flood advert floodadv : flood advert
get &lt;param&gt; : gets a param, "get help" for more get &lt;param> : gets a param, "get help" for more
set &lt;param&gt; &lt;value&gt; : sets a param, "set help" for more set &lt;param> &lt;value> : sets a param, "set help" for more
time &lt;epoch&gt; : sets time to given epoch time &lt;epoch> : sets time to given epoch
clock : get current time clock : get current time
clock sync : sync device clock st clock sync : sync device clock st
cli : send a cmd to node's cli (if avail) @ cli : send a cmd to node's cli (if avail) @
Contacts Contacts
contacts / list : gets contact list lc contacts / list : gets contact list lc
share_contact &lt;ct&gt; : share a contact with others sc share_contact &lt;ct> : share a contact with others sc
export_contact &lt;ct&gt; : get a contact's URI ec export_contact &lt;ct> : get a contact's URI ec
remove_contact &lt;ct&gt; : removes a contact from this node remove_contact &lt;ct> : removes a contact from this node
reset_path &lt;ct&gt; : resets path to a contact to flood rp reset_path &lt;ct> : resets path to a contact to flood rp
change_path &lt;ct&gt; &lt;pth&gt; : change the path to a contact cp change_path &lt;ct> &lt;pth> : change the path to a contact cp
Repeaters Repeaters
login &lt;name&gt; &lt;pwd&gt; : log into a node (rep) with given pwd l [[ login &lt;name> &lt;pwd> : log into a node (rep) with given pwd l
wait_login : wait for login (timeouts after 5sec) wl ]] logout &lt;name> : log out of a repeater
cmd &lt;name&gt; &lt;cmd&gt; : sends a command to a repeater (no ack) c [ cmd &lt;name> &lt;cmd> : sends a command to a repeater (no ack) c [
wmt8 : wait for a msg (reply) with a timeout ] wmt8 : wait for a msg (reply) with a timeout ]
req_status &lt;name&gt; : requests status from a node rs req_status &lt;name> : requests status from a node rs
wait_status : wait and print reply ws
</pre> </pre>
### Examples ### Interactive Mode
aka Instant Message or chat mode ...
Chat mode lets you interactively interact with your node or remote nodes. It is automatically triggered when no option is given on the command line.
You'll get a prompt with the name of your node. From here you can type meshcore-cli commands. The prompt has history and a basic completion (pressing tab will display possible command or argument options).
The `to` command is specific to chat mode, it lets you enter the recipient for next command. By default you're on your node but you can enter other nodes or public rooms. Here are some examples :
* `to <nodename>` : will enter nodename
* `to /`, `to ~` : will go to the root (your node)
* `to ..` : will go to the last node (it will switch between the two last nodes, this is just a 1-depth history)
* `to !` : will switch to the node you received last message from
When you are connected to a node, the behaviour will depend on the node type, if you're on a chat node, it will send messages by default and you can chat. On a repeater or a room server, it will send commands (autocompletioin has been set to comply with the CommonCli class of meshcore). To send a message through a room you'll have to prefix the message with a quote or use the send command.
You can alse set a channel as recipient, `to public` will switch to the public channel, and `to ch1` to channel 1.
## Examples
<pre> <pre>
# gets info from first ble MC device it finds (was -s but now used for serial port) # gets info from first ble MC device it finds (was -s but now used for serial port)
@ -131,32 +150,25 @@ INFO:meshcore:BLE Connection started
"time": 1744957249 "time": 1744957249
} }
# Using -j, meshcli will return a json array of replies ... # Using -j, meshcli will return replies in json format ...
$ meshcli -j -a C2:2B:A1:D5:3E:B6 clock $ meshcli -j -a C2:2B:A1:D5:3E:B6 clock
[
{ {
"time": 1744957261 "time": 1744957261
} }
]
# So if I reboot the node, and want to set time, I can chain the commands # So if I reboot the node, and want to set time, I can chain the commands
# and get that kind of output (even better by feeding it to jq) # and get that kind of output (even better by feeding it to jq)
$ meshcli reboot $ meshcli reboot
INFO:meshcore:BLE Connection started INFO:meshcore:BLE Connection started
$ meshcli -j clock clock sync clock | jq $ meshcli -j clock clock sync clock | jq -c
[ { "time": 1715770371 }
{ { "ok": "time synced" }
"time": 1715770360 { "time": 1745996105 }
},
{},
{
"time": 1744957460
}
]
# Now check if time is ok with human output (I don't read epoch time yet) # Now check if time is ok with human output (I don't read epoch time yet)
$ meshcli clock $ meshcli clock
INFO:meshcore:BLE Connection started INFO:meshcore:BLE Connection started
Current time : 2025-04-18 08:26:25 (1744957585) Current time : 2025-04-30 08:56:27 (1745996187)
# Now you'll probably want to send some messages ... # Now you'll probably want to send some messages ...
# For that, there is the msg command, wait_ack # For that, there is the msg command, wait_ack
@ -172,33 +184,26 @@ INFO:meshcore:BLE Connection started
t114_fdl(0): Hello T-Echo t114_fdl(0): Hello T-Echo
# And reply using json output for more verbosity # And reply using json output for more verbosity
[ # here I've used jq with -cs to get a compact array
{ $ meshcli msg t114_fdl hello wa | jq -cs
"type": 0, [{"type":0,"expected_ack":"4802ed93","suggested_timeout":2970},{"code":"4802ed93"}]
"expected_ack": "83059275",
"suggested_timeout": 4446
},
{
"code": "83059275"
}
]
# But this could have been done easier using the chat mode # But this could have been done interactively using the chat mode
# Here from the techo side. Note that un-acked messages will be # Here from the techo side. Note that un-acked messages will be
# signaled with an ! at the start of the prompt # signaled with an ! at the start of the prompt (or red color in color mode)
$ meshcli chat $ meshcli chat
INFO:meshcore:BLE Connection started INFO:meshcore:BLE Connection started
Interactive mode, most commands from terminal chat should work. Interactive mode, most commands from terminal chat should work.
Use "to" to selects contact, "list" to list contacts, "send" to send a message ... Use "to" to selects contact, "list" to list contacts, "send" to send a message ...
Line starting with "$" or "." will issue a meshcli command. Line starting with "$" or "." will issue a meshcli command.
"quit" or "q" will end interactive mode "quit" or "q" will end interactive mode
t114_fdl(D): Hello T-Echo t114_fdl(D): Hello T-Echo
EnsibsRoom> Hi EnsibsRoom> Hi
!EnsibsRoom> to t114_fdl !EnsibsRoom> to t114_fdl
t114_fdl> Hi t114_fdl> Hi
t114_fdl(D): It took you long to reply ... t114_fdl(D): It took you long to reply ...
t114_fdl> I forgot to set the recipient with the to command t114_fdl> I forgot to set the recipient with the to command
t114_fdl(D): It happens ... t114_fdl(D): It happens ...
t114_fdl> t114_fdl>
# Loging into repeaters and sending commands is also possible # Loging into repeaters and sending commands is also possible
@ -209,13 +214,13 @@ Interactive mode, most commands from terminal chat should work.
Use "to" to selects contact, "list" to list contacts, "send" to send a message ... Use "to" to selects contact, "list" to list contacts, "send" to send a message ...
Line starting with "$" or "." will issue a meshcli command. Line starting with "$" or "." will issue a meshcli command.
"quit" or "q" will end interactive mode "quit" or "q" will end interactive mode
Techo_fdl(0): Cool to receive some msgs from you Techo_fdl(0): Cool to receive some msgs from you
Techo_fdl(D): Hi Techo_fdl(D): Hi
Techo_fdl(D): I forgot to set the recipient with the to command Techo_fdl(D): I forgot to set the recipient with the to command
FdlRoom> $login FdlRoom password wl FdlRoom> login password
Login success Login success
FdlRoom> $cmd FdlRoom clock FdlRoom> clock
FdlRoom(0): 06:40 - 18/4/2025 UTC FdlRoom(0): 06:40 - 18/4/2025 UTC
FdlRoom> FdlRoom>
</pre> </pre>

2
pyproject.toml
View file

@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project] [project]
name = "meshcore-cli" name = "meshcore-cli"
version = "0.7.4" version = "0.7.5"
authors = [ authors = [
{ name="Florent de Lamotte", email="florent@frizoncorrea.fr" }, { name="Florent de Lamotte", email="florent@frizoncorrea.fr" },
] ]

7
src/meshcore_cli/meshcore_cli.py
View file

@ -21,6 +21,9 @@ from prompt_toolkit.shortcuts import radiolist_dialog
from meshcore import TCPConnection, BLEConnection, SerialConnection from meshcore import TCPConnection, BLEConnection, SerialConnection
from meshcore import MeshCore, EventType, logger from meshcore import MeshCore, EventType, logger
# Version
VERSION = "0.7.5"
# default ble address is stored in a config file # default ble address is stored in a config file
MCCLI_CONFIG_DIR = str(Path.home()) + "/.config/meshcore/" MCCLI_CONFIG_DIR = str(Path.home()) + "/.config/meshcore/"
MCCLI_ADDRESS = MCCLI_CONFIG_DIR + "default_address" MCCLI_ADDRESS = MCCLI_CONFIG_DIR + "default_address"
@ -1406,6 +1409,7 @@ def usage () :
Arguments : Arguments :
-h : prints this help -h : prints this help
-v : prints version
-j : json output (disables init file) -j : json output (disables init file)
-D : debug -D : debug
-S : performs a ble scan and ask for device -S : performs a ble scan and ask for device
@ -1462,6 +1466,9 @@ async def main(argv):
return return
case "-T" : case "-T" :
timeout = float(arg) timeout = float(arg)
case "-v":
print (f"meshcore cli version {VERSION}")
return
case "-l" : case "-l" :
devices = await BleakScanner.discover(timeout=timeout) devices = await BleakScanner.discover(timeout=timeout)
if len(devices) == 0: if len(devices) == 0: