meshcore-cli 1.2.14__py3-none-any.whl → 1.3.1__py3-none-any.whl

meshcore_cli/meshcore_cli.py

@@ -32,7 +32,7 @@ import re
 from meshcore import MeshCore, EventType, logger
 
 # Version
-VERSION = "v1.2.14"
+VERSION = "v1.3.1"
 
 # default ble address is stored in a config file
 MCCLI_CONFIG_DIR = str(Path.home()) + "/.config/meshcore/"
@@ -40,6 +40,10 @@ MCCLI_ADDRESS = MCCLI_CONFIG_DIR + "default_address"
 MCCLI_HISTORY_FILE = MCCLI_CONFIG_DIR + "history"
 MCCLI_INIT_SCRIPT = MCCLI_CONFIG_DIR + "init"
 
+PAYLOAD_TYPENAMES = ["REQ", "RESPONSE", "TEXT_MSG", "ACK", "ADVERT", "GRP_TXT", "GRP_DATA", "ANON_REQ", "PATH", "TRACE", "MULTIPART", "CONTROL"]
+ROUTE_TYPENAMES = ["TC_FLOOD", "FLOOD", "DIRECT", "TC_DIRECT"]
+CONTACT_TYPENAMES = ["NONE","CLI","REP","ROOM","SENS"]
+
 # Fallback address if config file not found
 # if None or "" then a scan is performed
 ADDRESS = ""
@@ -205,27 +209,57 @@ process_event_message.last_node=None
 
 async def handle_log_rx(event):
     mc = handle_log_rx.mc
-    if handle_log_rx.json_log_rx: # json mode ... raw dump
-        msg = json.dumps(event.payload)
-        if handle_message.above:
-            print_above(msg)
-        else :
-            print(msg)
-        return
 
     pkt = bytes().fromhex(event.payload["payload"])
     pbuf = io.BytesIO(pkt)
     header = pbuf.read(1)[0]
+    route_type = header & 0x03
+    payload_type = (header & 0x3c) >> 2
+    payload_ver = (header & 0xc0) >> 6
+
+    transport_code = None
+    if route_type == 0x00 or route_type == 0x03: # has transport code
+        transport_code = pbuf.read(4)    # discard transport code
+
+    path_len = pbuf.read(1)[0]
+    path = pbuf.read(path_len).hex() # Beware of traces where pathes are mixed
+
+    try :
+        route_typename = ROUTE_TYPENAMES[route_type]
+    except IndexError:
+        logger.debug(f"Unknown route type {route_type}") 
+        route_typename = "UNK"
+
+    try :
+        payload_typename = PAYLOAD_TYPENAMES[payload_type]
+    except IndexError:
+        logger.debug(f"Unknown payload type {payload_type}")
+        payload_typename = "UNK"
+
+    pkt_payload = pbuf.read()
+
+    event.payload["header"] = header
+    event.payload["route_type"] = route_type
+    event.payload["route_typename"] = route_typename
+    event.payload["payload_type"] = payload_type
+    event.payload["payload_typename"]= payload_typename
 
-    if header & ~1 == 0x14: # flood msg / channel
+    event.payload["payload_ver"] = payload_ver
+
+    if not transport_code is None:
+        event.payload["transport_code"] = transport_code.hex()
+
+    event.payload["path_len"] = path_len 
+    event.payload["path"] = path
+
+    event.payload["pkt_payload"] = pkt_payload.hex()
+
+    if payload_type == 0x05: # flood msg / channel
         if handle_log_rx.channel_echoes:
-            if header & 1 == 0: # has transport code
-                pbuf.read(4)    # discard transport code
-            path_len = pbuf.read(1)[0]
-            path = pbuf.read(path_len).hex()
-            chan_hash = pbuf.read(1).hex()
-            cipher_mac = pbuf.read(2)
-            msg = pbuf.read() # until the end of buffer
+            pk_buf = io.BytesIO(pkt_payload)
+            chan_hash = pk_buf.read(1).hex()
+            cipher_mac = pk_buf.read(2)
+            msg = pk_buf.read() # until the end of buffer
 
             channel = None
             for c in await get_channels(mc):
@@ -258,6 +292,14 @@ async def handle_log_rx(event):
                 else:
                     print(txt)
 
+    if handle_log_rx.json_log_rx: # json mode ... raw dump
+        msg = json.dumps(event.payload)
+        if handle_message.above:
+            print_above(msg)
+        else :
+            print(msg)
+
+
 handle_log_rx.json_log_rx = False
 handle_log_rx.channel_echoes = False
 handle_log_rx.mc = None
@@ -390,7 +432,7 @@ class MyNestedCompleter(NestedCompleter):
                 opts = self.options.keys()
             completer = WordCompleter(
                 opts, ignore_case=self.ignore_case,
-                pattern=re.compile(r"([a-zA-Z0-9_\\/\#]+|[^a-zA-Z0-9_\s\#]+)"))
+                pattern=re.compile(r"([a-zA-Z0-9_\\/\#\?]+|[^a-zA-Z0-9_\s\#\?]+)"))
             yield from completer.get_completions(document, complete_event)
         else: # normal behavior for remainder
             yield from super().get_completions(document, complete_event)
@@ -541,11 +583,21 @@ def make_completion_dict(contacts, pending={}, to=None, channels=None):
             "flood_after":None,
             "custom":None,
         },
+        "?get":None,
+        "?set":None,
+        "?scope":None,
+        "?contact_info":None,
+        "?apply_to":None,
+        "?at":None,
+        "?node_discover":None,
+        "?nd":None,
     }
 
     contact_completion_list = {
         "contact_info": None,
         "contact_name": None,
+        "contact_key": None,
+        "contact_type": None,
         "contact_lastmod": None,
         "export_contact" : None,
         "share_contact" : None,
@@ -708,7 +760,7 @@ make_completion_dict.custom_vars = {}
 async def interactive_loop(mc, to=None) :
     print("""Interactive mode, most commands from terminal chat should work.
 Use \"to\" to select recipient, use Tab to complete name ...
-Line starting with \"$\" or \".\" will issue a meshcli command.
+Some cmds have an help accessible with ?<cmd>. Do ?[Tab] to get a list.
 \"quit\", \"q\", CTRL+D will end interactive mode""")
 
     contact = to
@@ -1061,6 +1113,26 @@ async def process_contact_chat_line(mc, contact, line):
         await process_cmds(mc, args)
         return True
 
+    if line.startswith("contact_key") or line.startswith("ck"):
+        print(contact['public_key'],end="")
+        if " " in line:
+            print(" ", end="", flush=True)
+            secline = line.split(" ", 1)[1]
+            await process_contact_chat_line(mc, contact, secline)
+        else:
+            print("")
+        return True
+
+    if line.startswith("contact_type") or line.startswith("ct"):
+        print(f"{CONTACT_TYPENAMES[contact['type']]:4}",end="")
+        if " " in line:
+            print(" ", end="", flush=True)
+            secline = line.split(" ", 1)[1]
+            await process_contact_chat_line(mc, contact, secline)
+        else:
+            print("")
+        return True
+
     if line.startswith("contact_name") or line.startswith("cn"):
         print(contact['adv_name'],end="")
         if " " in line:
@@ -1071,6 +1143,44 @@ async def process_contact_chat_line(mc, contact, line):
             print("")
         return True
 
+    if line.startswith("path") :
+        if contact['out_path_len'] == -1:
+            print("Flood", end="")
+        elif contact['out_path_len'] == 0:
+            print("0 hop", end="")
+        else:
+            print(contact['out_path'],end="")
+        if " " in line:
+            print(" ", end="", flush=True)
+            secline = line.split(" ", 1)[1]
+            await process_contact_chat_line(mc, contact, secline)
+        else:
+            print("")
+        return True
+
+    if line.startswith("sleep") or line.startswith("s"):
+        try:
+            sleeptime = int(line.split(" ",2)[1])
+            cmd_pos = 2
+        except IndexError: # nothing arg after sleep
+            sleeptime = 1
+            cmd_pos = 0
+        except ValueError:
+            sleeptime = 1
+            cmd_pos = 1
+
+        try:
+            if cmd_pos > 0:
+                secline = line.split(" ",cmd_pos)[cmd_pos]
+                await process_contact_chat_line(mc, contact, secline)
+        except IndexError:
+            pass
+
+        # will sleep after executed command if there is a command
+        await asyncio.sleep(sleeptime)
+
+        return True
+
     if line == "contact_lastmod":
         timestamp = contact["lastmod"]
         print(f"{contact['adv_name']} updated"
@@ -1079,20 +1189,24 @@ async def process_contact_chat_line(mc, contact, line):
         return True
 
     # commands that take contact as second arg will be sent to recipient
-    if line == "sc" or line == "share_contact" or\
-            line == "ec" or line == "export_contact" or\
-            line == "uc" or line == "upload_contact" or\
-            line == "rp" or line == "reset_path" or\
-            line == "dp" or line == "disc_path" or\
-            line == "contact_info" or line == "ci" or\
-            line == "req_status" or line == "rs" or\
-            line == "req_neighbours" or line == "rn" or\
-            line == "req_telemetry" or line == "rt" or\
-            line == "req_acl" or\
-            line == "path" or\
-            line == "logout" :
-        args = [line, contact['adv_name']]
+    # and can be chained ...
+    if line.startswith("sc") or line.startswith("share_contact") or\
+            line.startswith("ec") or line.startswith("export_contact") or\
+            line.startswith("uc") or line.startswith("upload_contact") or\
+            line.startswith("rp") or line.startswith("reset_path") or\
+            line.startswith("dp") or line.startswith("disc_path") or\
+            line.startswith("contact_info") or line.startswith("ci") or\
+            line.startswith("req_status") or line.startswith("rs") or\
+            line.startswith("req_neighbours") or line.startswith("rn") or\
+            line.startswith("req_telemetry") or line.startswith("rt") or\
+            line.startswith("req_acl") or\
+            line.startswith("path") or\
+            line.startswith("logout") :
+        args = [line.split()[0], contact['adv_name']]
         await process_cmds(mc, args)
+        if " " in line:
+            secline = line.split(" ", 1)[1]
+            await process_contact_chat_line(mc, contact, secline)
         return True
 
     # special case for rp that can be chained from cmdline
@@ -1242,12 +1356,13 @@ async def process_contact_chat_line(mc, contact, line):
 
     return False
 
-async def apply_command_to_contacts(mc, contact_filter, line):
+async def apply_command_to_contacts(mc, contact_filter, line, json_output=False):
     upd_before = None
     upd_after = None
     contact_type = None
     min_hops = None
     max_hops = None
+    count = 0
 
     await mc.ensure_contacts()
 
@@ -1302,6 +1417,9 @@ async def apply_command_to_contacts(mc, contact_filter, line):
                 (upd_after is None or contact["lastmod"] > upd_after) and\
                 (min_hops is None or contact["out_path_len"] >= min_hops) and\
                 (max_hops is None or contact["out_path_len"] <= max_hops):
+
+            count = count + 1
+
             if await process_contact_chat_line(mc, contact, line):
                 pass
 
@@ -1326,6 +1444,9 @@ async def apply_command_to_contacts(mc, contact_filter, line):
             else:
                 logger.error(f"Can't send {line} to {contact['adv_name']}")
 
+    if not json_output:
+        print(f"> {count} matches in contacts")
+
 async def send_cmd (mc, contact, cmd) :
     res = await mc.commands.send_cmd(contact, cmd)
     if not res is None and not res.type == EventType.ERROR:
@@ -1716,26 +1837,14 @@ async def next_cmd(mc, cmds, json_output=False):
 
             case "apply_to"|"at":
                 argnum = 2
-                await apply_command_to_contacts(mc, cmds[1], cmds[2])
+                await apply_command_to_contacts(mc, cmds[1], cmds[2], json_output=json_output)
 
             case "set":
                 argnum = 2
                 match cmds[1]:
                     case "help" :
                         argnum = 1
-                        print("""Available parameters :
-    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""")
+                        get_help_for("set")
                     case "max_flood_attempts":
                         msg_ack.max_flood_attempts=int(cmds[2])
                     case "max_attempts":
@@ -1959,21 +2068,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}))
@@ -2340,6 +2435,7 @@ async def next_cmd(mc, cmds, json_output=False):
                         else :
                             color = process_event_message.color
                             classic = interactive_loop.classic or not color
+                            print(" ", end="")
                             for t in ev.payload["path"]:
                                 if classic :
                                     print("→",end="")
@@ -2493,18 +2589,14 @@ async def next_cmd(mc, cmds, json_output=False):
                         await mc.ensure_contacts()
                         print(f"Discovered {len(dn)} nodes:")
                         for n in dn:
-                            name = f"{n['pubkey'][0:2]} {mc.get_contact_by_key_prefix(n['pubkey'])['adv_name']}"
-                            if name is None:
+                            try :
+                                name = f"{n['pubkey'][0:2]} {mc.get_contact_by_key_prefix(n['pubkey'])['adv_name']}"
+                            except TypeError:
                                 name = n["pubkey"][0:16]
-                            type = f"t:{n['node_type']}"
-                            if n['node_type'] == 1:
-                                type = "CLI"
-                            elif n['node_type'] == 2:
-                                type = "REP"
-                            elif n['node_type'] == 3:
-                                type = "ROOM"
-                            elif n['node_type'] == 4:
-                                type = "SENS"
+                            if n['node_type'] >= len(CONTACT_TYPENAMES):
+                                type = f"t:{n['node_type']}"
+                            else:
+                                type = CONTACT_TYPENAMES[n['node_type']]
 
                             print(f" {name:16} {type:>4} SNR: {n['SNR_in']:6,.2f}->{n['SNR']:6,.2f} RSSI: ->{n['RSSI']:4}")
 
@@ -2522,7 +2614,7 @@ async def next_cmd(mc, cmds, json_output=False):
                 else :
                     print(json.dumps({
                         "name": contact["adv_name"],
-                        "pubkey_pre": contact["public_key"][0:12],
+                        "pubkey_pre": contact["public_key"][0:16],
                         "lpp": res,
                     }, indent = 4))
 
@@ -2610,15 +2702,30 @@ async def next_cmd(mc, cmds, json_output=False):
                     if json_output:
                         print(json.dumps(res, indent=4))
                     else:
+                        width = os.get_terminal_size().columns
                         print(f"Got {res['results_count']} neighbours out of {res['neighbours_count']} from {contact['adv_name']}:")
                         for n in res['neighbours']:
                             ct = mc.get_contact_by_key_prefix(n["pubkey"])
-                            if ct :
+                            if ct and width > 60 :
                                 name = f"[{n['pubkey'][0:8]}] {ct['adv_name']}"
+                                name = f"{name:30}"
+                            elif ct :
+                                name = f"{ct['adv_name']}"
+                                name = f"{name:20}"
                             else:
                                 name = f"[{n['pubkey']}]"
 
-                            print(f" {name:30} last viewed {n['secs_ago']} sec ago at {n['snr']} ")
+                            t_s = n['secs_ago']
+                            time_ago = f"{t_s}s"
+                            if t_s / 86400 >= 1 : # result in days
+                                time_ago = f"{int(t_s/86400)}d ago{f' ({time_ago})' if width > 62 else ''}"
+                            elif t_s / 3600 >= 1 : # result in days
+                                time_ago = f"{int(t_s/3600)}h ago{f' ({time_ago})' if width > 62 else ''}"
+                            elif t_s / 60 >= 1 : # result in min
+                                time_ago = f"{int(t_s/60)}m ago{f' ({time_ago})' if width > 62 else ''}"
+
+
+                            print(f" {name} {time_ago}, {n['snr']}dB{' SNR' if width > 66 else ''}")
 
             case "req_binary" :
                 argnum = 2
@@ -2641,7 +2748,13 @@ async def next_cmd(mc, cmds, json_output=False):
                     print(json.dumps(res, indent=4))
                 else :
                     for c in res.items():
-                        print(c[1]["adv_name"])
+                        if c[1]['out_path_len'] == -1:
+                            path_str = "Flood"
+                        elif c[1]['out_path_len'] == 0:
+                            path_str = "0 hop"
+                        else:
+                            path_str = f"{c[1]['out_path']}"
+                        print(f"{c[1]['adv_name']:30} {CONTACT_TYPENAMES[c[1]['type']]:4}  {c[1]['public_key'][:12]}  {path_str}")
                     print(f"> {len(mc.contacts)} contacts in device")
 
             case "reload_contacts" | "rc":
@@ -2709,7 +2822,7 @@ async def next_cmd(mc, cmds, json_output=False):
                         if (path_len == 0) :
                             print("0 hop")
                         elif (path_len == -1) :
-                            print("Path not set")
+                            print("Flood")
                         else:
                             print(path)
 
@@ -2736,6 +2849,8 @@ async def next_cmd(mc, cmds, json_output=False):
                         print(f"Unknown contact {cmds[1]}")
                 else:
                     path = cmds[2].replace(",","") # we'll accept path with ,
+                    if path == "0":
+                        path = ""
                     try:
                         res = await mc.commands.change_contact_path(contact, path)
                         logger.debug(res)
@@ -3068,8 +3183,8 @@ def command_help():
     reboot                 : reboots node
     sleep <secs>           : sleeps for a given amount of secs      s
     wait_key               : wait until user presses <Enter>        wk
-    apply_to <scope> <cmds>: sends cmds to contacts matching scope  at
-  Messenging
+    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
@@ -3082,6 +3197,7 @@ def command_help():
     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 scope for flood messages
   Management
     advert                 : sends advert                           a
     floodadv               : flood advert
@@ -3133,8 +3249,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 <on/off>     : disables most of color output if off
     -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
@@ -3143,14 +3257,16 @@ def usage () :
     -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 and shorcuts (can be chained) :""")
     command_help()
 
 def get_help_for (cmdname, context="line") :
     if cmdname == "apply_to" or cmdname == "at" :
-        print("""apply_to <scope> <cmd> : applies cmd to contacts matching scope
-    Scope acts like a filter with comma separated fields :
+        print("""apply_to <f> <cmd> : applies cmd to contacts matching filter <f>
+    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)
@@ -3158,7 +3274,7 @@ def get_help_for (cmdname, context="line") :
      - d, direct, similar to h>-1
      - f, flood, similar to h<0 or h=-1
 
-    Note: Some commands like contact_name (aka cn), reset_path (aka rp), forget_password (aka fp) can be chained.
+    Note: Some commands like contact_name (aka cn), contact_key (aka ck), contact_type (aka ct), reset_path (aka rp), forget_password (aka fp) can be chained. There is also a sleep command taking an optional event. 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
@@ -3169,7 +3285,7 @@ def get_help_for (cmdname, context="line") :
         at t=2 rp login
 """)
 
-    if cmdname == "node_discover" or cmdname == "nd" :
+    elif cmdname == "node_discover" or cmdname == "nd" :
         print("""node_discover <filter> : discovers 0-hop nodes and displays signal info
 
     filter can be "all" for all types or nodes or a comma separated list consisting of :
@@ -3181,6 +3297,80 @@ 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 <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.
+""")
+
+    elif cmdname == "contact_info":
+        print("""contact_info <ct> : displays contact info
+
+    in interactive mode, there are some lighter commands that can be chained to give more compact information
+        - contact_name (cn)
+        - contact_key (ck)
+        - contact_type (ct)
+""")
+
     else:
         print(f"Sorry, no help yet for {cmdname}")
 

{meshcore_cli-1.2.14.dist-info → meshcore_cli-1.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meshcore-cli
-Version: 1.2.14
+Version: 1.3.1
 Summary: Command line interface to meshcore companion radios
 Project-URL: Homepage, https://github.com/fdlamotte/meshcore-cli
 Project-URL: Issues, https://github.com/fdlamotte/meshcore-cli/issues
@@ -58,22 +58,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
 
 <pre>
     -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 &lt;timeout>    : timeout for the ble scan (-S and -l) default 2s
-    -a &lt;address>    : specifies device address (can be a name)
-    -d &lt;name>       : filter meshcore devices with name or address
-    -t &lt;hostname>   : connects via tcp/ip
-    -p &lt;port>       : specifies tcp port (default 5000)
-    -s &lt;port>       : use serial port &lt;port>
-    -b &lt;baudrate>   : specify baudrate
+    -S : scan for devices and show a selector
+    -l : list available ble/serial devices and exit
+    -T &lt;timeout&gt;    : timeout for the ble scan (-S and -l) default 2s
+    -a &lt;address&gt;    : specifies device address (can be a name)
+    -d &lt;name&gt;       : filter meshcore devices with name or address
+    -P              : forces pairing via the OS
+    -t &lt;hostname&gt;   : connects via tcp/ip
+    -p &lt;port&gt;       : specifies tcp port (default 5000)
+    -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>
 
 ### Available Commands
@@ -81,60 +84,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.
 
 <pre>
+    ?&lt;cmd&gt; may give you some more help about cmd
   General commands
     chat                   : enter the chat (interactive) mode
-    chat_to &lt;ct>           : enter chat with contact                to
-    script &lt;filename>      : execute commands in filename
+    chat_to &lt;ct&gt;           : enter chat with contact                to
+    script &lt;filename&gt;      : 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 &lt;secs>           : sleeps for a given amount of secs      s
-    wait_key               : wait until user presses &lt;Enter>        wk
-  Messenging
-    msg &lt;name> &lt;msg>       : send message to node by name           m  {
+    sleep &lt;secs&gt;           : sleeps for a given amount of secs      s
+    wait_key               : wait until user presses &lt;Enter&gt;        wk
+    apply_to &lt;f&gt; &lt;cmds&gt;    : sends cmds to contacts matching f      at
+  Messaging
+    msg &lt;name&gt; &lt;msg&gt;       : send message to node by name           m  {
     wait_ack               : wait an ack                            wa }
-    chan &lt;nb> &lt;msg>        : send message to channel number &lt;nb>    ch
-    public &lt;msg>           : send message to public channel (0)     dch
+    chan &lt;nb&gt; &lt;msg&gt;        : send message to channel number &lt;nb&gt;    ch
+    public &lt;msg&gt;           : 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 &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)
+    remove_channel &lt;n&gt;     : remove channel (by number or name)
+    scope &lt;s&gt;              : sets node's flood scope
   Management
     advert                 : sends advert                           a
     floodadv               : flood advert
-    get &lt;param>            : gets a param, "get help" for more
-    set &lt;param> &lt;value>    : sets a param, "set help" for more
-    time &lt;epoch>           : sets time to given epoch
+    get &lt;param&gt;            : gets a param, \"get help\" for more
+    set &lt;param&gt; &lt;value&gt;    : sets a param, \"set help\" for more
+    time &lt;epoch&gt;           : sets time to given epoch
     clock                  : get current time
     clock sync             : sync device clock                      st
+    node_discover &lt;filter&gt; : discovers nodes based on their type    nd
   Contacts
     contacts / list        : gets contact list                      lc
-    contact_info &lt;ct>      : prints information for contact ct      ci
-    contact_timeout &lt;ct> v : sets temp default timeout for contact
-    share_contact &lt;ct>     : share a contact with others            sc
-    export_contact &lt;ct>    : get a contact's URI                    ec
-    import_contact &lt;URI>   : import a contact from its URI          ic
-    remove_contact &lt;ct>    : removes a contact from this node
-    path &lt;ct>              : diplays path for a contact
-    reset_path &lt;ct>        : resets path to a contact to flood      rp
-    change_path &lt;ct> &lt;pth> : change the path to a contact           cp
-    change_flags &lt;ct> &lt;f>  : change contact flags (tel_l|tel_a|star)cf
-    req_telemetry &lt;ct>     : prints telemetry data as json          rt
-    req_mma &lt;ct>           : requests min/max/avg for a sensor      rm
-    req_acl &lt;ct>           : requests access control list for sensor
+    reload_contacts        : force reloading all contacts           rc
+    contact_info &lt;ct&gt;      : prints information for contact ct      ci
+    contact_timeout &lt;ct&gt; v : sets temp default timeout for contact
+    share_contact &lt;ct&gt;     : share a contact with others            sc
+    export_contact &lt;ct&gt;    : get a contact's URI                    ec
+    import_contact &lt;URI&gt;   : import a contact from its URI          ic
+    remove_contact &lt;ct&gt;    : removes a contact from this node
+    path &lt;ct&gt;              : diplays path for a contact
+    disc_path &lt;ct&gt;         : discover new path and display          dp
+    reset_path &lt;ct&gt;        : resets path to a contact to flood      rp
+    change_path &lt;ct&gt; &lt;pth&gt; : change the path to a contact           cp
+    change_flags &lt;ct&gt; &lt;f&gt;  : change contact flags (tel_l|tel_a|star)cf
+    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
-    add_pending &lt;key>      : manually add pending contact from key
-    flush_pending          : flush pending contact clist
+    add_pending &lt;pending&gt;  : manually add pending contact
+    flush_pending          : flush pending contact list
   Repeaters
-    login &lt;name> &lt;pwd>     : log into a node (rep) with given pwd   l
-    logout &lt;name>          : log out of a repeater
-    cmd &lt;name> &lt;cmd>       : sends a command to a repeater (no ack) c  [
+    login &lt;name&gt; &lt;pwd&gt;     : log into a node (rep) with given pwd   l
+    logout &lt;name&gt;          : log out of a repeater
+    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     ]
-    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>
 
 ### Interactive Mode
@@ -147,14 +160,70 @@ You'll get a prompt with the name of your node. From here you can type meshcore-
 
 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 <dest>` : will enter dest (node or channel)
 - `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.
+When you are in 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 (autocompletion 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.
+The `/` character is used to bypass the node you have currently selected using `to`:
+- `/<cmd>` issues cmd command on the root
+- `/<node>/<cmd>` will send cmd to selected node
+- `/<dest> <msg>` will send msg to dest (channel or node)
+
+#### 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.
+
+#### Channel echoes
+
+It's sometimes interesting to know the path taken by a message received from a channel or which repeaters have repeated a sent message.
+
+The app give you the information by listening `rx_log` from the device, when obtained the information is attached to the message and can be read.
+
+In meshcore-cli I went lower-level by implementing channel echoes. When activated (with `/set channel_echoes on`), all the channel messages will be printed on the terminal along with the SNR and path taken. When sending a message, you'll have all the repeats from 0-hop repeaters as echoes, and when a message is received, you should see information about the received message, but also all the instances of the same message that might have reached you from another path.
+
+In the example below, a msg has been sent between two repeaters, 21 and 25. 25 repeated the message and 21 the repeat and both echoes came back to the node with different SNRs.
+
+```
+f1down/#fdl|*> 8
+#fdl f1down: 8                                                 [25] -4.75-112
+#fdl f1down: 8                                               [2521]  1.00-109
+```
+
+### 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
 

meshcore_cli-1.3.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+meshcore_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+meshcore_cli/__main__.py,sha256=PfYgibmu2LEtC-OV7L1UgmvV3swJ5rQ4bbXHlwUFlgE,83
+meshcore_cli/meshcore_cli.py,sha256=ZuBGD-H_nXLmHSP3ffat8ZtKNfieKbLmL3TQgv8B4_I,149253
+meshcore_cli-1.3.1.dist-info/METADATA,sha256=k3NMG9h1qPemlm8if4A_7JD7yH6Wi8wzhABH_0ijtJo,15873
+meshcore_cli-1.3.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+meshcore_cli-1.3.1.dist-info/entry_points.txt,sha256=77V29Pyth11GteDk7tneBN3MMk8JI7bTlS-BGSmxCmI,103
+meshcore_cli-1.3.1.dist-info/licenses/LICENSE,sha256=F9s987VtS0AKxW7LdB2EkLMkrdeERI7ICdLJR60A9M4,1066
+meshcore_cli-1.3.1.dist-info/RECORD,,

meshcore_cli-1.2.14.dist-info/RECORD

@@ -1,8 +0,0 @@
-meshcore_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-meshcore_cli/__main__.py,sha256=PfYgibmu2LEtC-OV7L1UgmvV3swJ5rQ4bbXHlwUFlgE,83
-meshcore_cli/meshcore_cli.py,sha256=NbE3xX0GE3dtq0WnlBdF79iwyeGnxHerFGGoQNLeDSc,141395
-meshcore_cli-1.2.14.dist-info/METADATA,sha256=DDHsEo0JnY32-PX5_tr3qUYagxHJfJ9eSqYn5FJkrdw,11658
-meshcore_cli-1.2.14.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-meshcore_cli-1.2.14.dist-info/entry_points.txt,sha256=77V29Pyth11GteDk7tneBN3MMk8JI7bTlS-BGSmxCmI,103
-meshcore_cli-1.2.14.dist-info/licenses/LICENSE,sha256=F9s987VtS0AKxW7LdB2EkLMkrdeERI7ICdLJR60A9M4,1066
-meshcore_cli-1.2.14.dist-info/RECORD,,