Skip to main content

Meshtastic Python CLI 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
meshtastic -h

--export-config

Export the configuration of the device. (to be consumed by the '--configure' command).

To create to a file with the connected device's configuration, this command's output must be piped to a yaml file.

Usage
meshtastic --export-config > example_config.yaml
meshtastic --export-config

--configure

Configure radio using a yaml file.

Usage
meshtastic --configure example_config.yaml

--port PORT

The port the Meshtastic device is connected to, i.e. /dev/ttyUSB0, /dev/cu.wchusbserial, COM4 etc. 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
meshtastic --port /dev/ttyUSB0 --info
meshtastic --port COM4 --info

--host HOST

The hostname/ipaddr of the device to connect to (over TCP).

Usage
meshtastic --host HOST

--seriallog SERIALLOG

Logs device serial output to either 'stdout', 'none' or a filename to append to.

Usage
meshtastic --port /dev/ttyUSB0 --seriallog

--info

Read and display the radio config information.

Usage
meshtastic --port /dev/ttyUSB0 --info

--set-canned-message

Set the canned message plugin messages separated by pipes | (up to 200 characters).

Usage
meshtastic --set-canned-message "I need an alpinist!|Call Me|Roger Roger|Keep Calm|On my way"

--get-canned-message

Show the canned message plugin message.

Usage
meshtastic --get-canned-message

--set-ringtone RINGTONE

Set the Notification Ringtone (up to 230 characters).

Usage
meshtastic --set-ringtone "LeisureSuit:d=16,o=6,b=56:f.5,f#.5,g.5,g#5,32a#5,f5,g#.5,a#.5,32f5,g#5,32a#5,g#5,8c#.,a#5,32c#,a5,a#.5,c#.,32a5,a#5,32c#,d#,8e,c#.,f.,f.,f.,f.,f,32e,d#,8d,a#.5,e,32f,e,32f,c#,d#.,c#"

--get-ringtone

Show the stored ringtone.

Usage
meshtastic --get-ringtone

--nodes

Prints a node list in a pretty, formatted table.

Usage
meshtastic --nodes

--qr

Displays the QR code that corresponds to the current channel.

Usage
meshtastic --qr

--get [config_section]

Gets a preferences field.

Configuration values are described in: Configuration.

Usage
meshtastic --get lora
meshtastic --get lora.region

--set [config_section].[option]  [value]

Sets a preferences field.

Configuration values are described in: Configuration.

Usage
meshtastic --set lora.region Unset

--seturl SETURL

Set a channel URL.

Usage
meshtastic --seturl https://www.meshtastic.org/c/GAMiIE67C6zsNmlWQ-KE1tKt0fRKFciHka-DShI6G7ElvGOiKgZzaGFyZWQ=

--ch-index CH_INDEX

Set the specified channel index.

Usage
meshtastic --ch-index 1 --ch-disable

--ch-add CH_ADD

Add a secondary channel, you must specify a channel name.

Usage
meshtastic --ch-add testing-channel

--ch-del

Delete the ch-index channel.

Usage
meshtastic --ch-index 1 --ch-del

--ch-enable

Enable the specified channel.

Usage
meshtastic --ch-index 1 --ch-enable

--ch-disable

Disable the specified channel.

Usage
meshtastic --ch-index 1 --ch-disable

--ch-set CH_SET CH_SET

Set a channel parameter.

Usage
meshtastic --ch-set id 1234 --ch-index 0

--ch-vlongslow

Change modem preset to VERY_LONG_SLOW.

Usage
meshtastic --ch-vlongslow

--ch-longslow

Change modem preset to LONG_SLOW.

Usage
meshtastic --ch-longslow

--ch-longfast

Change modem preset to (the default) LONG_FAST.

Usage
meshtastic --ch-longfast

--ch-medslow

Change modem preset to MEDIUM_SLOW.

Usage
meshtastic --ch-medslow

--ch-medfast

Change modem preset to MEDIUM_FAST.

Usage
meshtastic --ch-medfast

--ch-shortslow

Change modem preset to SHORT_SLOW.

Usage
meshtastic --ch-shortslow

--ch-shortfast

Change modem preset to SHORT_FAST.

Usage
meshtastic --ch-shortfast

--set-owner SET_OWNER

Set device owner name.

Usage
meshtastic --set-owner "MeshyJohn"

--set-owner-short SET_OWNER_SHORT

Set device owner short name (4 characters max).

Usage
meshtastic --set-owner-short "MJ"

--set-ham SET_HAM

Set licensed Ham ID and turn off encryption.

Usage
meshtastic --set-ham KI1345

--dest DEST

The destination node id for any sent commands. Used for Remote Node Administration

Usage
meshtastic --dest '!28979058' --set-owner "MeshyJohn"

--sendtext SENDTEXT

Send a text message. Can specify a channel index ('--ch-index') or a destination ('--dest').

Usage
meshtastic --sendtext "Hello Mesh!"

--sendping

Send a ping message (which requests a reply).

Usage
meshtastic --sendping

--traceroute TRACEROUTE

Traceroute from connected node to a destination. You need pass the destination ID as an argument. Only nodes that have the encryption key can be traced.

Usage
meshtastic --traceroute '!ba4bf9d0'

--request-telemetry

Request telemetry from a node. You need to pass the destination ID as an argument with '--dest'. For repeaters, the nodeNum is required.

Usage
meshtastic --request-telemetry --dest '!ba4bf9d0'
meshtastic --request-telemetry --dest 1828779180

--ack

Used in combination with --sendtext to wait for an acknowledgment.

Usage
meshtastic --sendtext "Hello Mesh!" --ack

--reboot

Tell the node to reboot.

Usage
meshtastic --reboot

--shutdown

Tell the node to shutdown.

Usage
meshtastic --shutdown

--factory-reset

Tell the node to install the default config.

Usage
meshtastic --factory-reset

--reset-nodedb

Tell the node to clear its list of nodes.

Usage
meshtastic --reset-nodedb

--reply

Reply to received messages.

Usage
meshtastic --reply

--gpio-wrb GPIO_WRB GPIO_WRB

Set a particular GPIO # to 1 or 0.

Usage
meshtastic --port /dev/ttyUSB0 --gpio-wrb 4 1 --dest '!28979058'

--gpio-rd GPIO_RD

Read from a GPIO mask.

Usage
meshtastic --port /dev/ttyUSB0 --gpio-rd 0x10 --dest '!28979058'

--gpio-watch GPIO_WATCH

Start watching a GPIO mask for changes.

Usage
meshtastic --port /dev/ttyUSB0 --gpio-watch 0x10 --dest '!28979058'

--no-time

Suppress sending the current time to the mesh.

Usage
meshtastic --port /dev/ttyUSB0 --no-time

--setalt SETALT

Set device altitude (allows use without GPS).

Usage
meshtastic --setalt 120

--setlat SETLAT

Set device latitude (allows use without GPS).

Usage
meshtastic --setlat 25.2

--setlon SETLON

Set device longitude (allows use without GPS).

Usage
meshtastic --setlon -16.8

--debug

Show API library debug log messages.

Usage
meshtastic --debug --info

--test

Run stress test against all connected Meshtastic devices.

Usage
meshtastic --test

--ble BLE

Connect to a Meshtastic device using its BLE address or name. This option allows for wireless communication with the device, similar to how the --host option is used for TCP connections.

Usage
meshtastic --ble "device_name_or_address" --info

--ble-scan

Scan for available Meshtastic devices using BLE. This command lists discoverable devices, providing a convenient method to identify devices for connection via BLE.

Usage
meshtastic --ble-scan

--noproto

Don't start the API, just function as a dumb serial terminal. Probably not very helpful from the command line. Used more for testing/internal needs.

Usage
meshtastic --noproto

--version

Show program's version number and exit.

Usage
meshtastic --version

--support

Print out info that would be helpful supporting any issues.

Usage
meshtastic --support