meshcore-cli/README.md

mccli

mccli.py : CLI interface to MeschCore BLE companion app

Usage

$ mccli.py <args> <commands>

Arguments

Arguments mostly deals with ble connection

    -h : prints this help                                                                      
    -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

Available Commands

Commands are given after arguments, they can be chained and some have shortcuts.

    infos                   i : print informations about the node
    reboot                    : reboots node
    send <key> <msg>          : sends msg to node with pubkey starting by key
    sendto <name> <msg>       : sends msg to node with given name
    msg <name> <msg>        m : same as sendto
    wait_ack                wa: wait an ack for last sent msg
    recv                    r : reads next msg
    sync_msgs               sm: gets all unread msgs from the node
    wait_msg                wm: wait for a message and read it
    advert                  a : sends advert
    contacts                lc: gets contact list
    share_contact <ct>      sc: share a contact with others
    remove_contact <ct>       : removes a contact from this node
    reset_path <ct>         rp: resets path to a contact to flood
    change_path <ct> <path> cp: change the path to a contact
    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                 b : gets battery level
    login <name> <pwd>      l : log into a node (repeater) with given pwd
    wait_login              wl: wait for login (timeouts after 5sec)
    cmd <name> <cmd>        c : sends a command to a repeater (no ack)
    req_status <name>       rs: requests status from a node
    wait_status             ws: wait and print reply
    sleep <secs>            s : sleeps for a given amount of secs

Examples

# gets info from first MC device it finds (was -s but now used for serial port)
$ ./mccli.py -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 ...

$ ./mccli.py -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

$ ./mccli.py -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 ...

$ ./mccli.py -a F0:F5:BD:4F:9B:AD contacts
Connexion started
{}
cmd ['contacts'] processed ...

$ ./mccli.py -a F0:F5:BD:4F:9B:AD sleep 10 contacts
Connexion started
Advertisment received
cmd ['sleep', '10'] processed ...
{
    "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
    }
}
cmd ['contacts'] processed ...

$ ./mccli.py -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 ...

$ ./mccli.py -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 ...

# logs into a repeater (HomeRep) and check time
$ ./mccli.py -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 ...

$ ./mccli.py 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 ...