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.
For a more complete list of options, run:
meshtastic --help
Connection Arguments
--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.
This argument can also be specified as --serial or -s.
meshtastic --port /dev/ttyUSB0 --info
meshtastic --port COM4 --info
meshtastic -s --info
--host HOST
The hostname/ipaddr of the device to connect to (over TCP). If a host is not provided, the CLI will try to connect to localhost.
This argument can also be specified as --tcp or -t.
meshtastic --host meshtastic.local --info
meshtastic --host --info
--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. If an address is not provided, meshtastic will try to find a compatible device that's paired.
This argument can also be specified as -b.
meshtastic --ble "device_name_or_address" --info
meshtastic -b --info
Help & Support Arguments
-h or --help
Shows a help message that describes the arguments.
meshtastic -h
--version
Show program's version number and exit.
meshtastic --version
--support
Print out info that would be helpful supporting any issues.
meshtastic --support
Optional Arguments
--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.
meshtastic --export-config > example_config.yaml
--configure
Configure radio using a yaml file.
meshtastic --configure example_config.yaml
--seriallog SERIALLOG
Logs device serial output to either 'stdout', 'none' or a filename to append to. Defaults to 'stdout' if no filename is specified.
meshtastic --port /dev/ttyUSB0 --seriallog
meshtastic -t meshtastic.local --seriallog log.txt
--info
Read and display the radio config information.
meshtastic --port /dev/ttyUSB0 --info
--set-canned-message
Set the canned message plugin messages separated by pipes | (up to 200 characters).
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.
meshtastic --get-canned-message
--set-ringtone RINGTONE
Set the Notification Ringtone (up to 230 characters).
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.
meshtastic --get-ringtone
--nodes
Prints a node list in a pretty, formatted table.
meshtastic --nodes
--qr1
Displays the URL and QR code that corresponds to the current primary channel.
meshtastic --qr
--qr-all
Displays the URL and QR code that corresponds to all configured channels on the node.
meshtastic --qr-all
--get [config_section]
Gets a preferences field.
Configuration values are described in: Configuration.
meshtastic --get lora
meshtastic --get lora.region
To see all valid values, pass an invalid value, such as 0:
meshtastic --get 0
--set [config_section].[option] [value]
Sets a preferences field.
Configuration values are described in: Configuration.
meshtastic --set lora.region Unset
--seturl SETURL
Set the channel URL, which contains LoRa configuration plus the configuration of channels. Replaces your current configuration and channels completely.
meshtastic --seturl https://www.meshtastic.org/c/GAMiIE67C6zsNmlWQ-KE1tKt0fRKFciHka-DShI6G7ElvGOiKgZzaGFyZWQ=
--pos-fields POS_FIELDS
Configure position fields to send with positions; can pass multiple values. With 0 values, list current settings.
meshtastic --pos-fields
meshtastic --pos-fields ALTITUDE HEADING SPEED
--ch-index CH_INDEX
Act on the specified channel index. Applies to options that configure channels (such as --ch-set and --ch-del) as well as options that send messages to the mesh (such as --sendtext and --traceroute).
meshtastic --ch-index 1 --ch-disable
--ch-add CH_ADD
Add a secondary channel, you must specify a channel name.
Incompatible with --ch-index. If you pass --ch-add, any subsequent --ch-set and other commands that use a channel will use the index of the newly-added channel.
meshtastic --ch-add testing-channel
--ch-del
Delete the channel specified by --ch-index.
meshtastic --ch-index 1 --ch-del
--ch-enable (deprecated)
This option is deprecated. Using --ch-add is preferred in order to ensure there are no gaps in the channel list.
Enable the channel specified by --ch-index.
meshtastic --ch-index 1 --ch-enable
--ch-disable (deprecated)
This option is deprecated. Using --ch-del is preferred in order to ensure there are no gaps in the channel list.
Disable the channel specified by --ch-index.
meshtastic --ch-index 1 --ch-disable
--ch-set CH_SET CH_SET
Set a channel parameter on the channel specified by --ch-index.
meshtastic --ch-set id 1234 --ch-index 0
--ch-vlongslow
Change modem preset to VERY_LONG_SLOW.
meshtastic --ch-vlongslow
--ch-longslow
Change modem preset to LONG_SLOW.
meshtastic --ch-longslow
--ch-longfast
Change modem preset to (the default) LONG_FAST.
meshtastic --ch-longfast
--ch-medslow
Change modem preset to MEDIUM_SLOW.
meshtastic --ch-medslow
--ch-medfast
Change modem preset to MEDIUM_FAST.
meshtastic --ch-medfast
--ch-shortslow
Change modem preset to SHORT_SLOW.
meshtastic --ch-shortslow
--ch-shortfast
Change modem preset to SHORT_FAST.
meshtastic --ch-shortfast
--set-owner SET_OWNER
Set device owner name, sometimes called the long name.
meshtastic --set-owner "MeshyJohn"
--set-owner-short SET_OWNER_SHORT
Set device owner short name (4 characters max).
meshtastic --set-owner-short "MJ"
--set-ham SET_HAM
Set licensed Ham ID (by setting the owner name) and turn off encryption on the primary channel.
To disable Ham mode, use --set-owner and --set-owner-short to reset the owner names, and use --seturl or --ch-set commands to configure channels with the name and encryption you wish them to have. Or, use --factory-reset to reset to default settings.
meshtastic --set-ham KI1345
--dest DEST
The destination node id for any sent commands, if not passed to a command another way. Used for Remote Node Administration.
On many shells, exclamation points trigger special behavior unless enclosed in single quotes.
meshtastic --dest '!28979058' --set-owner "MeshyJohn"
--sendtext SENDTEXT
Send a text message. Can specify a channel index (--ch-index) and/or a destination (--dest).
meshtastic --sendtext 'Hello Mesh!'
meshtastic --ch-index 1 --sendtext 'Hello secondary channel!'
--traceroute TRACEROUTE
Traceroute from connected node to a destination. You need pass the destination ID as an argument, and may pass --ch-index to specify a channel. The node you are tracing must have the same channel configured, and only nodes that share the channel will identify themselves within the response. With recent enough firmware, other nodes may be included as !ffffffff but not with their actual ID.
meshtastic --traceroute '!ba4bf9d0'
--request-telemetry
Request telemetry from a node. You need to pass the destination ID as an argument with --dest. For repeaters, using the node's decimal ID may be more effective, but a hexadecimal ID should work as well.
meshtastic --request-telemetry --dest '!ba4bf9d0'
meshtastic --request-telemetry --dest 1828779180
--request-position
Request position from a node. You need to pass the destination ID as an argument with --dest.
meshtastic --request-position --dest '!ba4bf9d0' --ch-index 1
--ack
Used in combination with --sendtext and other commands to wait for an acknowledgment. Not all commands will be able to return an acknowledgment. Best used for commands that specify a single destination node.
meshtastic --sendtext 'Hello Mesh!' --dest '!28979058' --ack
--reboot
Tell the node to reboot.
meshtastic --reboot
--shutdown
Tell the node to shutdown.
meshtastic --shutdown
--factory-reset
Tell the node to install the default config.
meshtastic --factory-reset
--reset-nodedb
Tell the node to clear its list of nodes.
meshtastic --reset-nodedb
--remove-node NODE
Tell the node to remove the specified node from the NodeDB.
meshtastic --remove-node '!48759737'
--reply
Listen for messages. When one is received, send a message to the primary channel repeating the message along with some information.
meshtastic --reply
--no-time
Suppress sending the current time to the mesh on startup. May improve reliability and startup time.
meshtastic --port /dev/ttyUSB0 --no-time
--no-nodes
Instruct the node to not send nodeinfo from the NodeDB on startup. Requires firmware of sufficient version. Commands that use node information may behave unpredictably, since that information will not be populated, but this can improve efficiency for commands that don't.
meshtastic --no-nodes --no-time --sendtext "Firing off a quick message"
--wait-to-disconnect WAIT_TO_DISCONNECT
After performing whatever actions are specified by other options, wait before disconnecting from the device. Some devices will reboot when the serial connection disconnects, so adding a wait time may improve reliability. Defaults to 5 seconds if not provided.
meshtastic --set lora.channel_num 20 --wait-to-disconnect 10
--setalt SETALT
Set device altitude (allows use without GPS), and enables fixed position mode.
Can only be used on locally-connected nodes and not along with --dest.
meshtastic --setalt 120
--setlat SETLAT
Set device latitude (allows use without GPS), and enables fixed position mode.
Can only be used on locally-connected nodes and not along with --dest.
meshtastic --setlat 25.2
--setlon SETLON
Set device longitude (allows use without GPS), and enables fixed position mode.
Can only be used on locally-connected nodes and not along with --dest.
meshtastic --setlon -16.8
--remove-position
Clear the node's currently set fixed position and disable fixed position mode.
Can only be used on locally-connected nodes and not along with --dest.
meshtastic --remove-position
--debug
Show API library debug log messages.
meshtastic --debug --info
--listen
Stay open and listen to the stream of protocol buffer messages. This option enables --debug even if it is not provided alongside this argument.
meshtastic --listen
--test
Run stress test against all connected Meshtastic devices.
meshtastic --test
--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.
meshtastic --ble-scan
--noproto
Don't start the API, just function as a dumb serial terminal. Useful for debugging because it doesn't count as a client. Depends on a physically cabled serial connection. It will connect but not display information over a network (--host) or Bluetooth (--ble) connection.
meshtastic --noproto
Remote Hardware arguments
--gpio-wrb GPIO_WRB GPIO_WRB
Set a particular GPIO # to 1 or 0.
meshtastic --port /dev/ttyUSB0 --gpio-wrb 4 1 --dest '!28979058'
--gpio-rd GPIO_RD
Read from a GPIO mask.
meshtastic --port /dev/ttyUSB0 --gpio-rd 0x10 --dest '!28979058'
--gpio-watch GPIO_WATCH
Start watching a GPIO mask for changes.
meshtastic --port /dev/ttyUSB0 --gpio-watch 0x10 --dest '!28979058'
Tunnel arguments
--tunnel
Linux only, very experimental. Low bandwidth and low reliability.
Create a TUN tunnel device for forwarding IP packets over the mesh.
--subnet TUNNEL_NET
Set the subnet for the local end of the tunnel established using --tunnel.
Footnotes
-
The Meshtastic QR code (or Channel URL) allows users to quickly share channel and LoRa settings, making it easy to configure multiple nodes with matching settings for communication. Scanning a QR code applies all included channel settings and LoRa configuration settings, so be sure to review what these settings include before proceeding. Only scan QR codes from trusted sources.
For more details, see:
↩