From 32226b3bef5f9e4a37b3dfdd180d515ef275f011 Mon Sep 17 00:00:00 2001 From: Florent Date: Fri, 18 Apr 2025 08:42:06 +0200 Subject: [PATCH] updated readme --- README.md | 242 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 150 insertions(+), 92 deletions(-) diff --git a/README.md b/README.md index 17fd246..bcd65fb 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,7 @@ Arguments mostly deals with ble connection 
     -h : prints this help                                                                      
+    -j : json output
     -a <address>    : specifies device address (can be a name)
     -d <name>       : filter meshcore devices with name or address
     -t <hostname>   : connects via tcp/ip
@@ -38,116 +39,173 @@ Arguments mostly deals with ble connection
 
 ### Available Commands 
 
-Commands are given after arguments, they can be chained and some have shortcuts.
+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.
 
  
-    infos                  : print informations about the node      i 
-    reboot                 : reboots node                             
-    send <key> <msg>       : sends msg to node using pubkey[0:6]
-    sendto <name> <msg>    : sends msg to node with given name        
-    msg <name> <msg>       : same as sendto                         m 
-    wait_ack               : wait an ack for last sent msg          wa
-    recv                   : reads next msg                         r 
+   General commands
+    chat                   : enter the chat (interactive) mode
+    chat_to <ct>           : enter chat with contact                to
+    infos                  : print informations about the node      i
+    card                   : export this node URI                   e
+    ver                    : firmware version                       v
+    reboot                 : reboots node
+    sleep <secs>           : sleeps for a given amount of secs      s
+  Messenging
+    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                 : send message to public channel (0)     dch
+    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
-    advert                 : sends advert                           a 
-    contacts               : gets contact list                      lc
+  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
+    clock                  : get current time
+    clock sync             : sync device clock                      st
+    cli                    : send a cmd to node's cli (if avail)    @
+  Contacts
+    contacts / list        : gets contact list                      lc
     share_contact <ct>     : share a contact with others            sc
-    remove_contact <ct>    : removes a contact from this node         
+    export_contact <ct>    : get a contact's URI                    ec
+    remove_contact <ct>    : removes a contact from this node
     reset_path <ct>        : resets path to a contact to flood      rp
-    change_path <ct> <path>: change the path to a contact           cp
-    get_time               : gets current time                        
-    set_time <epoch>       : sets time to given epoch                 
-    sync_time              : sync time with system                    
-    set_name <name>        : sets node name                           
-    get_bat                : gets battery level                     b 
-    login <name> <pwd>     : log into a node (rep) with given pwd   l 
-    wait_login             : wait for login (timeouts after 5sec)   wl
-    cmd <name> <cmd>       : sends a command to a repeater (no ack) c 
+    change_path <ct> <pth> : change the path to a contact           cp
+  Repeaters
+    login <name> <pwd>     : log into a node (rep) with given pwd   l  [[ 
+    wait_login             : wait for login (timeouts after 5sec)   wl ]]
+    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
     wait_status            : wait and print reply                   ws
-    sleep <secs>           : sleeps for a given amount of secs      s
 

 
 ### Examples
 
 
-# gets info from first MC device it finds (was -s but now used for serial port)
-$ meshcli -d "" infos
-Scanning for devices
-Found device : F0:F5:BD:4F:9B:AD: MeshCore
-Connexion started
-{'adv_type': 1, 'public_key': '54c11cff0c2a861cfc5b0bd6e4b81cd5e6ca85e058bf53932d86c87dc7a20011', 'device_loc': '000000000000000000000000', 'radio_freq': 867500, 'radio_bw': 250000, 'radio_sf': 10, 'radio_cr': 5, 'name': 'toto'}
-cmd ['infos'] processed ...
-
-$ meshcli -a F0:F5:BD:4F:9B:AD get_time
-Connexion started
-Current time : 2024-05-15 12:52:53 (1715770373)
-cmd ['get_time'] processed ...
-
-$ date
-Tue Feb  4 12:55:05 CET 2025
-
-$ meshcli -a F0:F5:BD:4F:9B:AD sync_time get_time
-Connexion started
-True
-cmd ['sync_time'] processed ...
-Current time : 2025-02-04 12:55:24 (1738670124)
-cmd ['get_time'] processed ...
-
-$ meshcli -a F0:F5:BD:4F:9B:AD contacts
-Connexion started
-{}
-cmd ['contacts'] processed ...
-
-$ meshcli -a F0:F5:BD:4F:9B:AD sleep 10 contacts
-Connexion started
-Advertisment received
-cmd ['sleep', '10'] processed ...
+# gets info from first ble MC device it finds (was -s but now used for serial port)
+$ meshcore-cli -d "" infos
+INFO:meshcore:Scanning for devices
+INFO:meshcore:Found device : C2:2B:A1:D5:3E:B6: MeshCore-t114_fdl
+INFO:meshcore:BLE Connection started
 {
-    "flo2": {
-        "public_key": "d6e43f8e9ef26b801d6f5fee39f55ad6dfabfc939c84987256532d8b94aa25dd",
-        "type": 1,
-        "flags": 0,
-        "out_path_len": 255,
-        "out_path": "",
-        "adv_name": "flo2",
-        "last_advert": 1738670344,
-        "adv_lat": 0,
-        "adv_lon": 0,
-        "lastmod": 1738670354
-    }
+    "adv_type": 1,
+    "tx_power": 22,
+    "max_tx_power": 22,
+    "public_key": "993acd42fc779962c68c627829b32b111fa27a67d86b75c17460ff48c3102db4",
+    "adv_lat": 47.794,
+    "adv_lon": -3.428,
+    "radio_freq": 869.525,
+    "radio_bw": 250.0,
+    "radio_sf": 11,
+    "radio_cr": 5,
+    "name": "t114_fdl"
 }
-cmd ['contacts'] processed ...
 
-$ meshcli -a F0:F5:BD:4F:9B:AD sendto flo2 "Hello flo2" sleep 10
-Connexion started
-{'type': 1, 'expected_ack': b'9\x05\x0c\x12', 'suggested_timeout': 3260}
-cmd ['sendto', 'flo2', 'Hello flo2'] processed ...
-Code path update
-Received ACK
-Msgs are waiting
-cmd ['sleep', '10'] processed ...
+# getting time
+$ meshcli -a C2:2B:A1:D5:3E:B6 clock
+INFO:meshcore:BLE Connection started
+Current time : 2025-04-18 08:19:26 (1744957166)
 
-$ meshcli -a F0:F5:BD:4F:9B:AD recv
-Connexion started
-{'type': 'PRIV', 'pubkey_prefix': 'd6e43f8e9ef2', 'path_len': 255, 'txt_type': 0, 'sender_timestamp': 1738670421, 'text': 'hi'}
-cmd ['recv'] processed ...
+# If you're familiar with meshcli, you should have noted that 
+# now output is not json only, to get json output, use -j 
+# or prefix your commands with a dot
+$ meshcli -a C2:2B:A1:D5:3E:B6 .clock
+INFO:meshcore:BLE Connection started
+{
+    "time": 1744957249
+}
 
-# logs into a repeater (HomeRep) and check time
-$ meshcli -d t1000 login HomeRep password
-Scanning for devices
-Found device : FB:F2:5C:40:4F:77: MeshCore-t1000
-Connexion started
-{'type': 0, 'expected_ack': b'\x82yU\x02', 'suggested_timeout': 4446}
-cmd ['login', 'HomeRep', 'password'] processed ...
+# Using -j, meshcli will return a json array of replies ...
+$ meshcli -j -a C2:2B:A1:D5:3E:B6 clock
+[
+{
+    "time": 1744957261
+}
+]
 
-$ meshcli cmd HomeRep clock wait_msg
-Connexion started
-{'type': 0, 'expected_ack': b'\x00\x00\x00\x00', 'suggested_timeout': 2724}
-cmd ['cmd', 'HomeRep', 'clock'] processed ...
-Msgs are waiting
-{'type': 'PRIV', 'pubkey_prefix': '827955027cad', 'path_len': 255, 'txt_type': 1, 'sender_timestamp': 1741030036, 'text': '19:27 - 3/3/2025 UTC'}
-cmd ['wait_msg'] processed ...
+# 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)
+$ meshcli reboot
+INFO:meshcore:BLE Connection started
+$ meshcli -j clock clock sync clock | jq
+[
+  {
+    "time": 1715770360
+  },
+  {},
+  {
+    "time": 1744957460
+  }
+]
+# Now check if time is ok with human output (I don't read epoch time yet)
+$ meshcli clock
+INFO:meshcore:BLE Connection started
+Current time : 2025-04-18 08:26:25 (1744957585)
+
+# Now you'll probably want to send some messages ... 
+# For that, there is the msg command, wait_ack
+$ meshcli msg Techo_fdl "Hello T-Echo" wa
+INFO:meshcore:BLE Connection started
+Msg acked
+
+# I can check the message on the techo
+$ meshcli -d Techo sm
+INFO:meshcore:Scanning for devices
+INFO:meshcore:Found device : DE:B6:D0:68:D5:62: MeshCore-Techo_fdl
+INFO:meshcore:BLE Connection started
+t114_fdl(0): Hello T-Echo
+
+# And reply using json output for more verbosity
+[
+  {
+    "type": 0,
+    "expected_ack": "83059275",
+    "suggested_timeout": 4446
+  },
+  {
+    "code": "83059275"
+  }
+]
+
+# But this could have been done easier using the chat mode
+# Here from the techo side. Note that un-acked messages will be
+# signaled with an ! at the start of the prompt
+$ meshcli chat
+INFO:meshcore:BLE Connection started
+Interactive mode, most commands from terminal chat should work.
+Use "to" to selects contact, "list" to list contacts, "send" to send a message ...
+Line starting with "$" or "." will issue a meshcli command.
+"quit" or "q" will end interactive mode
+ t114_fdl(D): Hello T-Echo
+EnsibsRoom> Hi
+!EnsibsRoom> to t114_fdl
+t114_fdl> Hi
+ t114_fdl(D): It took you long to reply ...
+t114_fdl> I forgot to set the recipient with the to command
+ t114_fdl(D): It happens ...
+t114_fdl> 
+
+# Loging into repeaters and sending commands is also possible
+# directly from the chat, because we can use meshcli commands ;)
+$ meshcli chat (pending msgs are shown at connexion ...)
+INFO:meshcore:BLE Connection started
+Interactive mode, most commands from terminal chat should work.
+Use "to" to selects contact, "list" to list contacts, "send" to send a message ...
+Line starting with "$" or "." will issue a meshcli command.
+"quit" or "q" will end interactive mode
+ Techo_fdl(0): Cool to receive some msgs from you
+ Techo_fdl(D): Hi
+ Techo_fdl(D): I forgot to set the recipient with the to command
+FdlRoom> $login FdlRoom password wl
+Login success
+FdlRoom> $cmd FdlRoom clock
+ FdlRoom(0): 06:40 - 18/4/2025 UTC
+FdlRoom>
 

 
+
+