From ae30ef71afffda070eafc74cc9499f66ec174a9c Mon Sep 17 00:00:00 2001 From: Florent Date: Tue, 11 Nov 2025 10:38:54 +0100 Subject: [PATCH] update help and readme --- README.md | 132 +++++++++++++++++++++---------- src/meshcore_cli/meshcore_cli.py | 105 ++++++++++++++++-------- 2 files changed, 162 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index 0fe4fc4..9eafe36 100644 --- a/README.md +++ b/README.md @@ -40,22 +40,25 @@ Init files can also be defined for a given device, meshcore-cli will look for `& ### Arguments -Arguments mostly deals with ble connection +Arguments mostly deals with connection to the node 
     -h : prints this help
     -v : prints version
     -j : json output (disables init file)
     -D : debug
-    -S : performs a ble scan and ask for device
-    -l : list available ble devices and exit
-    -T <timeout>    : timeout for the ble scan (-S and -l) default 2s
-    -a <address>    : specifies device address (can be a name)
-    -d <name>       : filter meshcore devices with name or address
-    -t <hostname>   : connects via tcp/ip
-    -p <port>       : specifies tcp port (default 5000)
-    -s <port>       : use serial port <port>
-    -b <baudrate>   : specify baudrate
+    -S : scan for devices and show a selector
+    -l : list available ble/serial devices and exit
+    -T <timeout>    : timeout for the ble scan (-S and -l) default 2s
+    -a <address>    : specifies device address (can be a name)
+    -d <name>       : filter meshcore devices with name or address
+    -P              : forces pairing via the OS
+    -t <hostname>   : connects via tcp/ip
+    -p <port>       : specifies tcp port (default 5000)
+    -s <port>       : use serial port <port>
+    -b <baudrate>   : specify baudrate
+    -C              : toggles classic mode for prompt
+    -c <on/off>     : disables most of color output if off
### 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. 
+    ?<cmd> may give you some more help about cmd
   General commands
     chat                   : enter the chat (interactive) mode
-    chat_to <ct>           : enter chat with contact                to
-    script <filename>      : execute commands in filename
+    chat_to <ct>           : enter chat with contact                to
+    script <filename>      : execute commands in filename
     infos                  : print informations about the node      i
     self_telemetry         : print own telemtry                     t
     card                   : export this node URI                   e
     ver                    : firmware version                       v
     reboot                 : reboots node
-    sleep <secs>           : sleeps for a given amount of secs      s
-    wait_key               : wait until user presses <Enter>        wk
-  Messenging
-    msg <name> <msg>       : send message to node by name           m  {
+    sleep <secs>           : sleeps for a given amount of secs      s
+    wait_key               : wait until user presses <Enter>        wk
+    apply_to <f> <cmds>    : sends cmds to contacts matching f      at
+  Messaging
+    msg <name> <msg>       : send message to node by name           m  {
     wait_ack               : wait an ack                            wa }
-    chan <nb> <msg>        : send message to channel number <nb>    ch
-    public <msg>           : send message to public channel (0)     dch
+    chan <nb> <msg>        : send message to channel number <nb>    ch
+    public <msg>           : send message to public channel (0)     dch
     recv                   : reads next msg                         r
     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
-    get_channel <n>        : get info for channel n
+    get_channels           : prints all channel info
+    get_channel <n>        : get info for channel (by number or name)
     set_channel n nm k     : set channel info (nb, name, key)
+    remove_channel <n>     : remove channel (by number or name)
+    scope <s>              : sets node's flood scope
   Management
     advert                 : sends advert                           a
     floodadv               : flood advert
-    get <param>            : gets a param, "get help" for more
-    set <param> <value>    : sets a param, "set help" for more
-    time <epoch>           : sets time to given epoch
+    get <param>            : gets a param, \"get help\" for more
+    set <param> <value>    : sets a param, \"set help\" for more
+    time <epoch>           : sets time to given epoch
     clock                  : get current time
     clock sync             : sync device clock                      st
+    node_discover <filter> : discovers nodes based on their type    nd
   Contacts
     contacts / list        : gets contact list                      lc
-    contact_info <ct>      : prints information for contact ct      ci
-    contact_timeout <ct> v : sets temp default timeout for contact
-    share_contact <ct>     : share a contact with others            sc
-    export_contact <ct>    : get a contact's URI                    ec
-    import_contact <URI>   : import a contact from its URI          ic
-    remove_contact <ct>    : removes a contact from this node
-    path <ct>              : diplays path for a contact
-    reset_path <ct>        : resets path to a contact to flood      rp
-    change_path <ct> <pth> : change the path to a contact           cp
-    change_flags <ct> <f>  : change contact flags (tel_l|tel_a|star)cf
-    req_telemetry <ct>     : prints telemetry data as json          rt
-    req_mma <ct>           : requests min/max/avg for a sensor      rm
-    req_acl <ct>           : requests access control list for sensor
+    reload_contacts        : force reloading all contacts           rc
+    contact_info <ct>      : prints information for contact ct      ci
+    contact_timeout <ct> v : sets temp default timeout for contact
+    share_contact <ct>     : share a contact with others            sc
+    export_contact <ct>    : get a contact's URI                    ec
+    import_contact <URI>   : import a contact from its URI          ic
+    remove_contact <ct>    : removes a contact from this node
+    path <ct>              : diplays path for a contact
+    disc_path <ct>         : discover new path and display          dp
+    reset_path <ct>        : resets path to a contact to flood      rp
+    change_path <ct> <pth> : change the path to a contact           cp
+    change_flags <ct> <f>  : change contact flags (tel_l|tel_a|star)cf
+    req_telemetry <ct>     : prints telemetry data as json          rt
+    req_mma <ct>           : requests min/max/avg for a sensor      rm
+    req_acl <ct>           : requests access control list for sensor
     pending_contacts       : show pending contacts
-    add_pending <key>      : manually add pending contact from key
-    flush_pending          : flush pending contact clist
+    add_pending <pending>  : manually add pending contact
+    flush_pending          : flush pending contact list
   Repeaters
-    login <name> <pwd>     : log into a node (rep) with given pwd   l
-    logout <name>          : log out of a repeater
-    cmd <name> <cmd>       : sends a command to a repeater (no ack) c  [
+    login <name> <pwd>     : log into a node (rep) with given pwd   l
+    logout <name>          : log out of a repeater
+    cmd <name> <cmd>       : sends a command to a repeater (no ack) c  [
     wmt8                   : wait for a msg (reply) with a timeout     ]
-    req_status <name>      : requests status from a node            rs
+    req_status <name>      : requests status from a node            rs
+    req_neighbours <name>  : requests for neighbours in binary form rn
+    trace <path>           : run a trace, path is comma separated
### 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. +#### 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 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 ` : applies cmd to contacts matching filter `` 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 
diff --git a/src/meshcore_cli/meshcore_cli.py b/src/meshcore_cli/meshcore_cli.py
index f675a56..02b6fc8 100644
--- a/src/meshcore_cli/meshcore_cli.py
+++ b/src/meshcore_cli/meshcore_cli.py
@@ -1746,19 +1746,7 @@ async def next_cmd(mc, cmds, json_output=False):
                 match cmds[1]:
                     case "help" :
                         argnum = 1
-                        print("""Available parameters :
-    pin                    : ble pin
-    radio        : radio params
-    tuning           : tuning params
-    tx                     : tx power
-    name                  : node name
-    lat                    : latitude
-    lon                    : longitude
-    coords             : coordinates
-    print_snr           : toggle 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""")
+                        get_help_for("set")
                     case "max_flood_attempts":
                         msg_ack.max_flood_attempts=int(cmds[2])
                     case "max_attempts":
@@ -1982,21 +1970,7 @@ async def next_cmd(mc, cmds, json_output=False):
                 argnum = 1
                 match cmds[1]:
                     case "help":
-                        print("""Gets parameters from node
-    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""")
+                        get_help_for("get")
                     case "max_flood_attempts":
                         if json_output :
                             print(json.dumps({"max_flood_attempts" : msg_ack.max_flood_attempts}))
@@ -3107,8 +3081,8 @@ def command_help():
     reboot                 : reboots node
     sleep            : sleeps for a given amount of secs      s
     wait_key               : wait until user presses         wk
-    apply_to  : sends cmds to contacts matching scope  at
-  Messenging
+    apply_to      : sends cmds to contacts matching f      at
+  Messaging
     msg         : send message to node by name           m  {
     wait_ack               : wait an ack                            wa }
     chan          : send message to channel number     ch
@@ -3121,6 +3095,7 @@ def command_help():
     get_channel         : get info for channel (by number or name)
     set_channel n nm k     : set channel info (nb, name, key)
     remove_channel      : remove channel (by number or name)
+    scope               : sets scope for flood messages
   Management
     advert                 : sends advert                           a
     floodadv               : flood advert
@@ -3172,8 +3147,6 @@ def usage () :
     -D : debug
     -S : scan for devices and show a selector
     -l : list available ble/serial devices and exit
-    -C              : toggles classic mode for prompt
-    -c      : disables most of color output if off
     -T     : timeout for the ble scan (-S and -l) default 2s
     -a 
    : specifies device address (can be a name)
     -d        : filter meshcore devices with name or address
@@ -3182,14 +3155,16 @@ def usage () :
     -p        : specifies tcp port (default 5000)
     -s        : use serial port 
     -b    : specify baudrate
+    -C              : toggles classic mode for prompt
+    -c      : disables most of color output if off
 
  Available Commands and shorcuts (can be chained) :""")
     command_help()
 
 def get_help_for (cmdname, context="line") :
     if cmdname == "apply_to" or cmdname == "at" :
-        print("""apply_to   : applies cmd to contacts matching scope
-    Scope acts like a filter with comma separated fields :
+        print("""apply_to   : applies cmd to contacts matching filter 
+    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)
@@ -3220,6 +3195,68 @@ def get_help_for (cmdname, context="line") :
     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                    : ble pin
+    radio        : radio params
+    tuning           : tuning params
+    tx                     : tx power
+    name                  : node name
+    lat                    : latitude
+    lon                    : longitude
+    coords             : coordinates
+    auto_update_contacts <>     : automatically updates contact list
+    multi_ack           : multi-acks feature
+    telemetry_mode_base   : set basic telemetry mode all/selected/off
+    telemetry_mode_loc    : set location telemetry mode all/selected/off
+    telemetry_mode_env    : set env telemetry mode all/selected/off
+    advert_loc_policy   : "share" means loc will be shared in adv
+  display:
+    print_snr           : toggle 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
+    json_log_rx         : logs packets incoming to device as json
+    channel_echoes      : print repeats for channel data
+    echo_unk_channels   : also dump unk channels (encrypted)
+    color               : color off should remove ANSI codes from output
+  prompt:
+    classic_prompt      : activates less fancier prompt
+    arrow_head          : change arrow head in prompt
+    slash_start         : idem for slash start
+    slash_end           : slash end
+    invert_slash        : apply color inversion to slash """)
+
+    elif cmdname == "scope":
+        print("""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 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:
         print(f"Sorry, no help yet for {cmdname}")