Merge pull request #101 from srichs/correct-readme

Updated README and python-cmd-guide
2026-01-05 22:37:57 -05:00 · 2021-08-15 14:11:00 -07:00
parent 8649bc3655 223c67d2b4
commit a65d502f14
2 changed files with 406 additions and 6 deletions
--- a/README.md
+++ b/README.md
@@ -11,15 +11,19 @@ Installation is easily done through the Python package installer pip (note, you
 - check that your computer has Python 3 installed.
 - check that your computer has "pip3" installed, if not follow [this guide](https://www.makeuseof.com/tag/install-pip-for-python/).
 - check that pytap2 is installed by pip3. If not, install it:
+
 ```
 sudo pip3 install --upgrade pytap2
 ```
+
 - install meshtastic:
+
 ```
 sudo pip3 install --upgrade meshtastic
 ```

 An example using Python 3 code to send a message to the mesh:
+
 ```
 import meshtastic
 interface = meshtastic.SerialInterface() # By default will try to find a meshtastic device, otherwise provide a device path like /dev/ttyUSB0
@@ -36,6 +40,7 @@ This pip package will also install a "meshtastic" command line executable, which
 NOTE: This command is not run inside of python, you run it from your operating system shell prompt directly.  If when you type "meshtastic" it doesn't find the command and you are using Windows: Check that the python "scripts" directory [is in your path](https://datatofish.com/add-python-to-windows-path/).

 To display a (partial) list of the available commands:
+
 ```
 meshtastic -h
 ```
@@ -79,7 +84,7 @@ The channel settings can be changed similiarly.  Either by using a standard (sha
 The URL is constructed automatically based off of the current channel settings. So if you want to customize a channel you could do something like:

 ```
-meshtastic --setchan name mychan --setchan channel_num 4 --info
+meshtastic --ch-set name mychan --ch-set channel_num 4 --info
 ```

 This will change some channel params and then show device info (which will include the current channel URL)
@@ -87,14 +92,20 @@ This will change some channel params and then show device info (which will inclu
 You can even set the channel preshared key to a particular AES128 or AES256 sequence.

 ```
-meshtastic --setchan psk 0x1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b --info
+meshtastic --ch-set psk 0x1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b --info
 ```

-Use "--setchan psk none" to turn off encryption.  
+Use "--ch-set psk none" to turn off encryption.  

-Use "--setchan psk random" will assign a new (high quality) random AES256 key to the primary channel (similar to what the Android app does when making new channels).
+Use "--ch-set psk random" will assign a new (high quality) random AES256 key to the primary channel (similar to what the Android app does when making new channels).

-Use "--setchan psk default" to restore the standard 'default' (minimally secure, because it is in the source code for anyone to read) AES128 key.
+Use "--ch-set psk default" to restore the standard 'default' (minimally secure, because it is in the source code for anyone to read) AES128 key.
+
+All "ch-set" commands will default to the primary channel at index 0, but can be applied to other channels with the "ch-index" parameter:
+
+```
+meshtastic --ch-index 1 --ch-set name mychan --ch-set channel_num 4 --info
+```

 ## Ham radio support

@@ -114,6 +125,7 @@ This is a collection of common questions and answers from our friendly forum.
 ### [Permission denied: ‘/dev/ttyUSB0’](https://meshtastic.discourse.group/t/question-on-permission-denied-dev-ttyusb0/590/3?u=geeksville)

 This indicates an OS permission problem for access by your user to the USB serial port.  Typically this is fixed by the following.
+
 ```
 sudo usermod -a -G dialout <username>
 ```
@@ -133,6 +145,7 @@ Afterwards you can use the meshatstic python client again on MacOS.
 We use the visual-studio-code default python formatting conventions (autopep8).  So if you use that IDE you should be able to use "Format Document" and not generate unrelated diffs.  If you use some other editor, please don't change formatting on lines you haven't changed.

 If you need to build a new release you'll need:
+
 ```
 apt install pandoc
 sudo pip3 install markdown pdoc3 webencodings pyparsing twine autopep8
--- a/docs/python-cmd-guide.md
+++ b/docs/python-cmd-guide.md
@@ -1,2 +1,389 @@
-# Python API commands guide
+# Python API Commands Guide

+The python pip package installs a "meshtastic" command line executable, which displays packets sent over the network as JSON and lets you see serial debugging information from the meshtastic devices. This command is not run inside of python, you run it from your operating system shell prompt directly. If when you type "meshtastic" it doesn't find the command and you are using Windows: Check that the python "scripts" directory is in your path.
+
+## Optional Arguments
+
+### -h or --help
+
+Shows a help message that describes the arguments.
+
+**Usage**
+
+``` shell
+meshtastic -h
+```
+
+### --port PORT
+
+The port the Meshtastic device is connected to, i.e. /dev/ttyUSB0 or COM4. if unspecified, meshtastic will try to find it. Important to use when multiple devices are connected to ensure you call the command for the correct device.
+
+**Usage**
+
+``` shell
+meshtastic --port /dev/ttyUSB0 --info
+meshtastic --port COM4 --info
+```
+
+### --host HOST
+
+The hostname/ipaddr of the device to connect to (over TCP).
+
+**Usage**
+
+``` shell
+meshtastic --host HOST
+```
+
+### --seriallog SERIALLOG
+
+Logs device serial output to either 'stdout', 'none' or a filename to append to.
+
+**Usage**
+
+``` shell
+meshtastic --port /dev/ttyUSB0 --seriallog
+```
+
+### --info
+
+Read and display the radio config information.
+
+**Usage**
+
+``` shell
+meshtastic --port /dev/ttyUSB0 --info
+```
+
+### --nodes
+
+Prints a node list in a pretty, formatted table.
+
+**Usage**
+
+``` shell
+meshtastic --nodes
+```
+
+### --qr
+
+Displays the QR code that corresponds to the current channel.
+
+**Usage**
+
+``` shell
+meshtastic --qr
+```
+
+### --get GET
+
+Gets a preferences field.
+
+**Usage**
+
+``` shell
+meshtastic --get modem_config
+```
+
+### --set SET SET
+
+Sets a preferences field.
+
+**Usage**
+
+``` shell
+meshtastic --set region Unset
+```
+
+### --seturl SETURL
+
+Set a channel URL.
+
+**Usage**
+
+``` shell
+meshtastic --seturl https://www.meshtastic.org/c/GAMiIE67C6zsNmlWQ-KE1tKt0fRKFciHka-DShI6G7ElvGOiKgZzaGFyZWQ=
+```
+
+### --ch-index CH_INDEX
+
+Set the specified channel index
+
+**Usage**
+
+``` shell
+meshtastic --ch-index 1 --ch-disable
+```
+
+### --ch-add CH_ADD
+
+Add a secondary channel, you must specify a channel name.
+
+**Usage**
+
+``` shell
+meshtastic --ch-add testing-channel
+```
+### --ch-del
+
+Delete the ch-index channel.
+
+**Usage**
+
+``` shell
+meshtastic --ch-index 1 --ch-del
+```
+
+### --ch-enable
+
+Enable the specified channel.
+
+**Usage**
+
+``` shell
+meshtastic --ch-index 1 --ch-enable
+```
+
+### --ch-disable
+
+Disable the specified channel.
+
+**Usage**
+
+``` shell
+meshtastic --ch-index 1 --ch-disable
+```
+
+### --ch-set CH_SET CH_SET
+
+Set a channel parameter.
+
+**Usage**
+
+``` shell
+meshtastic --ch-set id 1234
+```
+
+### --ch-longslow
+
+Change to the standard long-range (but slow) channel.
+
+**Usage**
+
+``` shell
+meshtastic --ch-longslow
+```
+
+### --ch-shortfast
+
+Change to the standard fast (but short range) channel.
+
+**Usage**
+
+``` shell
+meshtastic --ch-shortfast
+```
+
+### --set-owner SET_OWNER
+
+Set device owner name.
+
+**Usage**
+
+``` shell
+meshtastic --dest \!28979058 --set-owner "MeshyJohn"
+```
+
+### --set-ham SET_HAM
+
+Set licensed HAM ID and turn off encryption.
+
+**Usage**
+
+``` shell
+meshtastic --set-ham KI1345
+```
+
+### --dest DEST
+
+The destination node id for any sent commands
+
+**Usage**
+
+``` shell
+meshtastic --dest \!28979058 --set-owner "MeshyJohn"
+```
+
+### --sendtext SENDTEXT
+
+Send a text message.
+
+**Usage**
+
+``` shell
+meshtastic --sendtext "Hello Mesh!"
+```
+
+### --sendping
+
+Send a ping message (which requests a reply).
+
+**Usage**
+
+``` shell
+meshtastic --sendping
+```
+
+### --reboot
+
+Tell the destination node to reboot.
+
+**Usage**
+
+``` shell
+meshtastic --dest \!28979058 --reboot
+```
+
+### --reply
+
+Reply to received messages.
+
+**Usage**
+
+``` shell
+meshtastic --reply 
+```
+
+### --gpio-wrb GPIO_WRB GPIO_WRB
+
+Set a particular GPIO # to 1 or 0.
+
+**Usage**
+
+``` shell
+meshtastic --port /dev/ttyUSB0 --gpio-wrb 4 1 --dest \!28979058
+```
+
+### --gpio-rd GPIO_RD
+
+Read from a GPIO mask.
+
+**Usage**
+
+``` shell
+meshtastic --port /dev/ttyUSB0 --gpio-rd 0x10 --dest \!28979058 
+```
+
+### --gpio-watch GPIO_WATCH
+
+Start watching a GPIO mask for changes.
+
+**Usage**
+
+``` shell
+meshtastic --port /dev/ttyUSB0 --gpio-watch 0x10 --dest \!28979058
+```
+
+### --no-time
+
+Suppress sending the current time to the mesh.
+
+**Usage**
+
+``` shell
+meshtastic --port /dev/ttyUSB0 --no-time
+```
+
+### --setalt SETALT
+
+Set device altitude (allows use without GPS).
+
+**Usage**
+
+``` shell
+meshtastic --setalt 120
+```
+
+### --setlat SETLAT
+
+Set device latitude (allows use without GPS).
+
+**Usage**
+
+``` shell
+meshtastic --setlat 25.2
+```
+
+### --setlon SETLON
+
+Set device longitude (allows use without GPS).
+
+**Usage**
+
+``` shell
+meshtastic --setlon -16.8
+```
+
+### --debug
+
+Show API library debug log messages.
+
+**Usage**
+
+``` shell
+meshtastic --debug --info
+```
+
+### --test
+
+Run stress test against all connected Meshtastic devices.
+
+**Usage**
+
+``` shell
+meshtastic --test
+```
+
+### --ble BLE
+
+BLE mac address to connect to (BLE is not yet supported for this tool).
+
+**Usage**
+
+``` shell
+meshtastic --ble "83:38:92:32:37:48"
+```
+
+### --noproto
+
+Don't start the API, just function as a dumb serial terminal.
+
+**Usage**
+
+``` shell
+meshtastic --noproto
+```
+
+### --version
+
+Show program's version number and exit.
+
+**Usage**
+
+``` shell
+meshtastic --version
+```
+
+## Deprecated Arguments
+
+### --setchan
+
+Deprecated - use "--ch-set param value" instead.
+
+### --set-router
+
+Deprecated - use "--set is_router true" instead.
+
+### --unset-router
+
+Deprecated - use "--set is_router false" instead.