From f332d2fc2b9930111b2ceaf4ee628bc15668738b Mon Sep 17 00:00:00 2001 From: Florent Date: Wed, 30 Apr 2025 09:19:58 +0200 Subject: [PATCH] documentation ... --- README.md | 125 ++++++++++++++++--------------- pyproject.toml | 2 +- src/meshcore_cli/meshcore_cli.py | 7 ++ 3 files changed, 73 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 4761ca8..97aefe5 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,9 @@ If you want meshcore-cli to remember last BLE device, you should have some `$HOM $ meshcli <args> <commands> -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``` @@ -35,7 +35,7 @@ If there is an initialization script file called ```init```, it will be executed Arguments mostly deals with ble connection 
-    -h : prints this help                                                                      
+    -h : prints this help
     -j : json output
     -D : print debug messages
     -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.
 
 
-   General commands
+  General commands
     chat                   : enter the chat (interactive) mode
-    chat_to <ct>           : enter chat with contact                to
-    script <file>          : executes script stored in file
+    chat_to <ct>           : enter chat with contact                to
+    script <filename>      : execute commands in filename
     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
+    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  {
+    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
+    chan <nb> <msg>        : send message to channel number     ch
+    public <msg>           : 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
+    sync_msgs              : gets all unread msgs from the node     sm
+    msgs_subscribe         : display msgs as they arrive            ms
   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
     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
-    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> <pth> : change the path to a contact           cp
+    share_contact <ct>     : share a contact with others            sc
+    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> <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  [
+    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
-    wait_status            : wait and print reply                   ws
+    req_status <name>      : requests status from a node            rs
 

 
-### 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 ` : 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
 
 
 # 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
 }
 
-# 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
-[
 {
     "time": 1744957261
 }
-]
 
 # 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
-  }
-]
+$ meshcli -j clock clock sync clock | jq -c
+{ "time": 1715770371 }
+{ "ok": "time synced" }
+{ "time": 1745996105 }
+
 # 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)
+Current time : 2025-04-30 08:56:27 (1745996187)
 
 # Now you'll probably want to send some messages ... 
 # For that, there is the msg command, wait_ack
@@ -172,33 +184,26 @@ 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"
-  }
-]
+# here I've used jq with -cs to get a compact array
+$ meshcli msg t114_fdl hello wa | jq -cs
+[{"type":0,"expected_ack":"4802ed93","suggested_timeout":2970},{"code":"4802ed93"}]
 
-# 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
-# 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
 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
+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(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(D): It happens ...
 t114_fdl> 
 
 # 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 ...
 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
+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 password
 Login success
-FdlRoom> $cmd FdlRoom clock
- FdlRoom(0): 06:40 - 18/4/2025 UTC
+FdlRoom> clock
+FdlRoom(0): 06:40 - 18/4/2025 UTC
 FdlRoom>
 

 
diff --git a/pyproject.toml b/pyproject.toml
index 14ef63d..32f2cbd 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meshcore-cli"
-version = "0.7.4"
+version = "0.7.5"
 authors = [
   { name="Florent de Lamotte", email="florent@frizoncorrea.fr" },
 ]
diff --git a/src/meshcore_cli/meshcore_cli.py b/src/meshcore_cli/meshcore_cli.py
index 105297e..248e928 100644
--- a/src/meshcore_cli/meshcore_cli.py
+++ b/src/meshcore_cli/meshcore_cli.py
@@ -21,6 +21,9 @@ from prompt_toolkit.shortcuts import radiolist_dialog
 from meshcore import TCPConnection, BLEConnection, SerialConnection
 from meshcore import MeshCore, EventType, logger
 
+# Version
+VERSION = "0.7.5"
+
 # default ble address is stored in a config file
 MCCLI_CONFIG_DIR = str(Path.home()) + "/.config/meshcore/"
 MCCLI_ADDRESS = MCCLI_CONFIG_DIR + "default_address"
@@ -1406,6 +1409,7 @@ def usage () :
 
  Arguments :
     -h : prints this help
+    -v : prints version
     -j : json output (disables init file)
     -D : debug
     -S : performs a ble scan and ask for device
@@ -1462,6 +1466,9 @@ async def main(argv):
                 return
             case "-T" :
                 timeout = float(arg)
+            case "-v":
+                print (f"meshcore cli version {VERSION}")
+                return
             case "-l" :
                 devices = await BleakScanner.discover(timeout=timeout)
                 if len(devices) == 0: