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

update help and readme

Browse source
This commit is contained in:
Florent 2025-11-11 10:38:54 +01:00
parent b8096dd163
commit ae30ef71af
2 changed files with 162 additions and 75 deletions
Download patch file Download diff file Expand all files Collapse all files

132
README.md
View file

@ -40,22 +40,25 @@ Init files can also be defined for a given device, meshcore-cli will look for `&
### Arguments ### Arguments
Arguments mostly deals with ble connection Arguments mostly deals with connection to the node
<pre> <pre>
-h : prints this help -h : prints this help
-v : prints version -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 : scan for devices and show a selector
-l : list available ble devices and exit -l : list available ble/serial devices and exit
-T &lt;timeout> : timeout for the ble scan (-S and -l) default 2s -T &lt;timeout&gt; : timeout for the ble scan (-S and -l) default 2s
-a &lt;address> : specifies device address (can be a name) -a &lt;address&gt; : specifies device address (can be a name)
-d &lt;name> : filter meshcore devices with name or address -d &lt;name&gt; : filter meshcore devices with name or address
-t &lt;hostname> : connects via tcp/ip -P : forces pairing via the OS
-p &lt;port> : specifies tcp port (default 5000) -t &lt;hostname&gt; : connects via tcp/ip
-s &lt;port> : use serial port &lt;port> -p &lt;port&gt; : specifies tcp port (default 5000)
-b &lt;baudrate> : specify baudrate -s &lt;port&gt; : use serial port &lt;port&gt;
-b &lt;baudrate&gt; : specify baudrate
-C : toggles classic mode for prompt
-c &lt;on/off&gt; : disables most of color output if off
</pre> </pre>
### Available Commands ### Available Commands
@ -63,60 +66,70 @@ 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>
?&lt;cmd&gt; may give you some more help about cmd
General commands General commands
chat : enter the chat (interactive) mode chat : enter the chat (interactive) mode
chat_to &lt;ct> : enter chat with contact to chat_to &lt;ct&gt; : enter chat with contact to
script &lt;filename> : execute commands in filename script &lt;filename&gt; : execute commands in filename
infos : print informations about the node i infos : print informations about the node i
self_telemetry : print own telemtry t self_telemetry : print own telemtry t
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> : sleeps for a given amount of secs s sleep &lt;secs&gt; : sleeps for a given amount of secs s
wait_key : wait until user presses &lt;Enter> wk wait_key : wait until user presses &lt;Enter&gt; wk
Messenging apply_to &lt;f&gt; &lt;cmds&gt; : sends cmds to contacts matching f at
msg &lt;name> &lt;msg> : send message to node by name m { Messaging
msg &lt;name&gt; &lt;msg&gt; : send message to node by name m {
wait_ack : wait an ack wa } wait_ack : wait an ack wa }
chan &lt;nb> &lt;msg> : send message to channel number &lt;nb> ch chan &lt;nb&gt; &lt;msg&gt; : send message to channel number &lt;nb&gt; ch
public &lt;msg> : send message to public channel (0) dch public &lt;msg&gt; : send message to public channel (0) dch
recv : reads next msg r recv : reads next msg r
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 sync_msgs : gets all unread msgs from the node sm
msgs_subscribe : display msgs as they arrive ms msgs_subscribe : display msgs as they arrive ms
get_channel &lt;n> : get info for channel n get_channels : prints all channel info
get_channel &lt;n&gt; : get info for channel (by number or name)
set_channel n nm k : set channel info (nb, name, key) set_channel n nm k : set channel info (nb, name, key)
remove_channel &lt;n&gt; : remove channel (by number or name)
scope &lt;s&gt; : sets node's flood scope
Management Management
advert : sends advert a advert : sends advert a
floodadv : flood advert floodadv : flood advert
get &lt;param> : gets a param, "get help" for more get &lt;param&gt; : gets a param, \"get help\" for more
set &lt;param> &lt;value> : sets a param, "set help" for more set &lt;param&gt; &lt;value&gt; : sets a param, \"set help\" for more
time &lt;epoch> : sets time to given epoch time &lt;epoch&gt; : 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
node_discover &lt;filter&gt; : discovers nodes based on their type nd
Contacts Contacts
contacts / list : gets contact list lc contacts / list : gets contact list lc
contact_info &lt;ct> : prints information for contact ct ci reload_contacts : force reloading all contacts rc
contact_timeout &lt;ct> v : sets temp default timeout for contact contact_info &lt;ct&gt; : prints information for contact ct ci
share_contact &lt;ct> : share a contact with others sc contact_timeout &lt;ct&gt; v : sets temp default timeout for contact
export_contact &lt;ct> : get a contact's URI ec share_contact &lt;ct&gt; : share a contact with others sc
import_contact &lt;URI> : import a contact from its URI ic export_contact &lt;ct&gt; : get a contact's URI ec
remove_contact &lt;ct> : removes a contact from this node import_contact &lt;URI&gt; : import a contact from its URI ic
path &lt;ct> : diplays path for a contact remove_contact &lt;ct&gt; : removes a contact from this node
reset_path &lt;ct> : resets path to a contact to flood rp path &lt;ct&gt; : diplays path for a contact
change_path &lt;ct> &lt;pth> : change the path to a contact cp disc_path &lt;ct&gt; : discover new path and display dp
change_flags &lt;ct> &lt;f> : change contact flags (tel_l|tel_a|star)cf reset_path &lt;ct&gt; : resets path to a contact to flood rp
req_telemetry &lt;ct> : prints telemetry data as json rt change_path &lt;ct&gt; &lt;pth&gt; : change the path to a contact cp
req_mma &lt;ct> : requests min/max/avg for a sensor rm change_flags &lt;ct&gt; &lt;f&gt; : change contact flags (tel_l|tel_a|star)cf
req_acl &lt;ct> : requests access control list for sensor req_telemetry &lt;ct&gt; : prints telemetry data as json rt
req_mma &lt;ct&gt; : requests min/max/avg for a sensor rm
req_acl &lt;ct&gt; : requests access control list for sensor
pending_contacts : show pending contacts pending_contacts : show pending contacts
add_pending &lt;key> : manually add pending contact from key add_pending &lt;pending&gt; : manually add pending contact
flush_pending : flush pending contact clist flush_pending : flush pending contact list
Repeaters Repeaters
login &lt;name> &lt;pwd> : log into a node (rep) with given pwd l login &lt;name&gt; &lt;pwd&gt; : log into a node (rep) with given pwd l
logout &lt;name> : log out of a repeater logout &lt;name&gt; : log out of a repeater
cmd &lt;name> &lt;cmd> : sends a command to a repeater (no ack) c [ cmd &lt;name&gt; &lt;cmd&gt; : 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> : requests status from a node rs req_status &lt;name&gt; : requests status from a node rs
req_neighbours &lt;name&gt; : requests for neighbours in binary form rn
trace &lt;path&gt; : run a trace, path is comma separated
</pre> </pre>
### Interactive Mode ### Interactive Mode
@ -138,6 +151,43 @@ When you are connected to a node, the behaviour will depend on the node type, if
You can alse set a channel as recipient, `to public` will switch to the public channel, and `to ch1` to channel 1. You can alse set a channel as recipient, `to public` will switch to the public channel, and `to ch1` to channel 1.
#### Flood Scope in interactive mode
Flood scope has recently been introduced in meshcore (from `v1.10.0`). It limits the scope of packets to regions, using transport codes in the frame.
When entering chat mode, scope will be reset to `*`, meaning classic flood.
You can switch scope using the `scope` command, or postfixing the `to` command with `%<scope>`.
Scope can also be applied to a command using `%` before the scope name. For instance `login%#Morbihan` will limit diffusion of the login command (which is usually sent flood to get the path to a repeater) to the `#Morbihan` region.
### Issuing batch commands to contacts with apply to
`apply_to <f> <cmd>` : applies cmd to contacts matching filter `<f>` it can be used to apply the same command to a pool of repeaters, or remove some contacts matching a condition.
Filter is constructed with comma separated fields :
- `u`, matches modification time `<` or `>` than a timestamp (can also be days hours or minutes ago if followed by `d`,`h` or `m`)
- `t`, matches the type (1: client, 2: repeater, 3: room, 4: sensor)
- `h`, matches number of hops
- `d`, direct, similar to `h>-1`
- `f`, flood, similar to `h<0` or `h=-1`
Commands should be written as if in interactive mode, if writing from the commandline don't forget to use commas to clearly delimit fields.
Note: Some commands like `contact_name` (aka `cn`), `reset_path` (aka `rp`), `forget_password` (aka `fp`) can be chained. There is also a `sleep` command taking an optional time parameter. The sleep will be issued after the command, it helps limiting rate through repeaters ...
#### Examples
```
# removes all clients that have not been updated in last 2 days
at u<2d,t=1 remove_contact
# gives traces to repeaters that have been updated in the last 24h and are direct
at t=2,u>1d,d cn trace
# tries to do flood login to all repeaters
at t=2 rp login
```
## Examples ## Examples
<pre> <pre>

105
src/meshcore_cli/meshcore_cli.py
View file

@ -1746,19 +1746,7 @@ async def next_cmd(mc, cmds, json_output=False):
match cmds[1]: match cmds[1]:
case "help" : case "help" :
argnum = 1 argnum = 1
print("""Available parameters : get_help_for("set")
pin <pin> : ble pin
radio <freq,bw,sf,cr> : radio params
tuning <rx_dly,af> : tuning params
tx <dbm> : tx power
name <name> : node name
lat <lat> : latitude
lon <lon> : longitude
coords <lat,lon> : coordinates
print_snr <on/off> : toggle snr display in messages
print_adverts <on/off> : display adverts as they come
print_new_contacts <on/off> : display new pending contacts when available
print_path_updates <on/off> : display path updates as they come""")
case "max_flood_attempts": case "max_flood_attempts":
msg_ack.max_flood_attempts=int(cmds[2]) msg_ack.max_flood_attempts=int(cmds[2])
case "max_attempts": case "max_attempts":
@ -1982,21 +1970,7 @@ async def next_cmd(mc, cmds, json_output=False):
argnum = 1 argnum = 1
match cmds[1]: match cmds[1]:
case "help": case "help":
print("""Gets parameters from node get_help_for("get")
name : node name
bat : battery level in mV
fstats : fs statistics
coords : adv coordinates
lat : latitude
lon : longitude
radio : radio parameters
tx : tx power
print_snr : snr display in messages
print_adverts : display adverts as they come
print_new_contacts : display new pending contacts when available
print_path_updates : display path updates as they come
custom : all custom variables in json format
each custom var can also be get/set directly""")
case "max_flood_attempts": case "max_flood_attempts":
if json_output : if json_output :
print(json.dumps({"max_flood_attempts" : msg_ack.max_flood_attempts})) print(json.dumps({"max_flood_attempts" : msg_ack.max_flood_attempts}))
@ -3107,8 +3081,8 @@ def command_help():
reboot : reboots node reboot : reboots node
sleep <secs> : sleeps for a given amount of secs s sleep <secs> : sleeps for a given amount of secs s
wait_key : wait until user presses <Enter> wk wait_key : wait until user presses <Enter> wk
apply_to <scope> <cmds>: sends cmds to contacts matching scope at apply_to <f> <cmds> : sends cmds to contacts matching f at
Messenging Messaging
msg <name> <msg> : send message to node by name m { msg <name> <msg> : send message to node by name m {
wait_ack : wait an ack wa } wait_ack : wait an ack wa }
chan <nb> <msg> : send message to channel number <nb> ch chan <nb> <msg> : send message to channel number <nb> ch
@ -3121,6 +3095,7 @@ def command_help():
get_channel <n> : get info for channel (by number or name) get_channel <n> : get info for channel (by number or name)
set_channel n nm k : set channel info (nb, name, key) set_channel n nm k : set channel info (nb, name, key)
remove_channel <n> : remove channel (by number or name) remove_channel <n> : remove channel (by number or name)
scope <s> : sets scope for flood messages
Management Management
advert : sends advert a advert : sends advert a
floodadv : flood advert floodadv : flood advert
@ -3172,8 +3147,6 @@ def usage () :
-D : debug -D : debug
-S : scan for devices and show a selector -S : scan for devices and show a selector
-l : list available ble/serial devices and exit -l : list available ble/serial devices and exit
-C : toggles classic mode for prompt
-c <on/off> : disables most of color output if off
-T <timeout> : timeout for the ble scan (-S and -l) default 2s -T <timeout> : timeout for the ble scan (-S and -l) default 2s
-a <address> : specifies device address (can be a name) -a <address> : specifies device address (can be a name)
-d <name> : filter meshcore devices with name or address -d <name> : filter meshcore devices with name or address
@ -3182,14 +3155,16 @@ def usage () :
-p <port> : specifies tcp port (default 5000) -p <port> : specifies tcp port (default 5000)
-s <port> : use serial port <port> -s <port> : use serial port <port>
-b <baudrate> : specify baudrate -b <baudrate> : specify baudrate
-C : toggles classic mode for prompt
-c <on/off> : disables most of color output if off
Available Commands and shorcuts (can be chained) :""") Available Commands and shorcuts (can be chained) :""")
command_help() command_help()
def get_help_for (cmdname, context="line") : def get_help_for (cmdname, context="line") :
if cmdname == "apply_to" or cmdname == "at" : if cmdname == "apply_to" or cmdname == "at" :
print("""apply_to <scope> <cmd> : applies cmd to contacts matching scope print("""apply_to <f> <cmd> : applies cmd to contacts matching filter <f>
Scope acts like a filter with comma separated fields : Filter is constructed with comma separated fields :
- u, matches modification time < or > than a timestamp - u, matches modification time < or > than a timestamp
(can also be days hours or minutes ago if followed by d,h or m) (can also be days hours or minutes ago if followed by d,h or m)
- t, matches the type (1: client, 2: repeater, 3: room, 4: sensor) - t, matches the type (1: client, 2: repeater, 3: room, 4: sensor)
@ -3220,6 +3195,68 @@ def get_help_for (cmdname, context="line") :
nd can be used with no filter parameter ... !!! BEWARE WITH CHAINING !!! nd can be used with no filter parameter ... !!! BEWARE WITH CHAINING !!!
""") """)
elif cmdname == "get" :
print("""Gets parameters from node
Please see also help for set command, which is more up to date ...
name : node name
bat : battery level in mV
fstats : fs statistics
coords : adv coordinates
lat : latitude
lon : longitude
radio : radio parameters
tx : tx power
print_snr : snr display in messages
print_adverts : display adverts as they come
print_new_contacts : display new pending contacts when available
print_path_updates : display path updates as they come
custom : all custom variables in json format
each custom var can also be get/set directly""")
elif cmdname == "set" :
print("""Available parameters :
device:
pin <pin> : ble pin
radio <freq,bw,sf,cr> : radio params
tuning <rx_dly,af> : tuning params
tx <dbm> : tx power
name <name> : node name
lat <lat> : latitude
lon <lon> : longitude
coords <lat,lon> : coordinates
auto_update_contacts <> : automatically updates contact list
multi_ack <on/off> : multi-acks feature
telemetry_mode_base <mode> : set basic telemetry mode all/selected/off
telemetry_mode_loc <mode> : set location telemetry mode all/selected/off
telemetry_mode_env <mode> : set env telemetry mode all/selected/off
advert_loc_policy <policy> : "share" means loc will be shared in adv
display:
print_snr <on/off> : toggle snr display in messages
print_adverts <on/off> : display adverts as they come
print_new_contacts <on/off> : display new pending contacts when available
print_path_updates <on/off> : display path updates as they come
json_log_rx <on/off> : logs packets incoming to device as json
channel_echoes <on/off> : print repeats for channel data
echo_unk_channels <on/off> : also dump unk channels (encrypted)
color <on/off> : color off should remove ANSI codes from output
prompt:
classic_prompt <on/off> : activates less fancier prompt
arrow_head <string> : change arrow head in prompt
slash_start <string> : idem for slash start
slash_end <string> : slash end
invert_slash <on/off> : apply color inversion to slash """)
elif cmdname == "scope":
print("""scope <scope> : changes flood scope of the node
The scope command can be used from command line or interactive mode to set the region in which flood packets will be transmitted.
Managing Flood Scope in interactive mode
Flood scope has recently been introduced in meshcore (from v1.10.0). It limits the scope of packets to regions, using transport codes in the frame.
When entering chat mode, scope will be reset to *, meaning classic flood.
You can switch scope using the scope command, or postfixing the to command with %<scope>.
Scope can also be applied to a command using % before the scope name. For instance login%#Morbihan will limit diffusion of the login command (which is usually sent flood to get the path to a repeater) to the #Morbihan region.""")
else: else:
print(f"Sorry, no help yet for {cmdname}") print(f"Sorry, no help yet for {cmdname}")