Using the Meshtastic CLI
This section covers using the "meshtastic" command line executable, which displays packets sent over the network as JSON and lets you see serial debugging information from the Meshtastic devices.
The meshtastic command is not run within python but is a script run from your operating system shell prompt. When you type "meshtastic" and the prompt is unable to find the command in Windows, check that the python "scripts" directory is in your path.
Viewing Serial Output
The --noproto command in the Meshtastic Python CLICLI (Command Line Interface). A text-based interface used for interacting with software or devices like Meshtastic. is used to disable the API and function merely as a "dumb serial terminal." This mode of operation allows both the API and device functionalities to remain accessible for regular use, while simultaneously providing a window into the raw serial output. This feature can be particularly useful for debugging, development, or understanding the low-level communication between devices. Depends on a physically cabled serial connection. It will connect but not display information over a network (--host) or Bluetooth (--ble) connection.
user@host % meshtastic --noproto
# You should see results similar to this:
WARNING file:mesh_interface.py _sendToRadio line:681 Not sending packet because protocol use is disabled by noProto
Connected to radio
WARNING file:mesh_interface.py _sendPacket line:531 Not sending packet because protocol use is disabled by noProto
INFO | 18:38:04 711 [DeviceTelemetryModule] (Sending): air_util_tx=0.116361, channel_utilization=1.916667, battery_level=101, voltage=4.171000
DEBUG | 18:38:04 711 [DeviceTelemetryModule] updateTelemetry LOCAL
DEBUG | 18:38:04 711 [DeviceTelemetryModule] Node status update: 2 online, 4 total
INFO | 18:38:04 711 [DeviceTelemetryModule] Sending packet to phone
INFO | 18:38:04 711 Telling client we have new packets 28
Getting a list of User Preferences
You can get a list of user preferences by running '--get' with an invalid attribute such as 'all'.
meshtastic --get all
Changing settings
You can also use this tool to set any of the device parameters which are stored in persistent storage. For instance, here's how to set the device to keep the Bluetooth link alive for eight hours (any usage of the Bluetooth protocol from your phone will reset this timer)
# You should see a result similar to this:
mydir$ meshtastic --set power.wait_bluetooth_secs 28800
Connected to radio...
Setting power.wait_bluetooth_secs to 28800
Writing modified preferences to device...
Or to set a node at a fixed position and never power up the GPSGPS (Global Positioning System). A satellite positioning system. A node with a GPS module determines its own location and can report that position to the mesh..
meshtastic --setlat 25.2 --setlon -16.8 --setalt 120
Or to configure an ESP32ESP32A chipset of microcontroller made/designed by Espressif, used by a number of devices. Higher power usage than nRF52, but often cheaper and supports Wi-Fi if desired. based board to join a Wifi network as a station:
meshtastic --set network.wifi_ssid mywifissid --set network.wifi_psk mywifipsw --set network.wifi_enabled 1
Settings and their accepted values are listed under Configuration; field definitions are in the protobufs.
Changing channel settings
The channel settings can also be changed, either by using a standard (shareable) meshtastic URL or you can set a particular channel parameter (for advanced users).
Meshtastic encodes the radio channel and PSKPSK (Pre-Shared Key). A secret code or passphrase used in Meshtastic channels for encryption, ensuring that only devices with the matching PSK can communicate within that specific channel. in the channel's URL. All nodes must connect to the channel again by using the URL provided after a change in this section by performing the --info switch.
meshtastic --ch-set name mychan --ch-index 1 --info
You can even set the channel preshared key to a particular AES128 or AES256 sequence.
meshtastic --ch-index 1 --ch-set psk 0x1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b --info
Use --ch-set psk none --ch-index 0 to turn off encryption.
Use --ch-set psk random --ch-index 0 to 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 default --ch-index 0 to restore the standard 'default' (minimally secure, because it is in the source code for anyone to read) AES128 key.
Use --ch-set psk base64:{key} --ch-index {index} to set the PSKPSK (Pre-Shared Key). A secret code or passphrase used in Meshtastic channels for encryption, ensuring that only devices with the matching PSK can communicate within that specific channel. of a channel to a known entity
All ch-set commands need to have the ch-index parameter specified:
meshtastic --ch-index 1 --ch-set name mychan --info
Ham radio support
Meshtastic is designed to be used without a radio operator license. If you do have a license you can set your operator ID and turn off encryption with:
# You should see a result similar to this:
mydir$ meshtastic --set-ham KI1345
Connected to radio
Setting Ham ID to KI1345 and turning off encryption
Writing modified channels to device
Toggling set-ham changes your device settings in the following ways.
| Setting | set-ham Default | Normal Default |
|---|---|---|
IsLicensed | true | See User Config - IsLicensed |
LongName | Your CallSign | See User Config - LongName |
ShortName | Abrv CallSign | See User Config - ShortName |
PSK | "" | See Channel Settings - PSK |
Changing the preshared key
You can set the channel preshared key to a particular AES128 or AES256 sequence.
meshtastic --ch-set psk 0x1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b --info
Use "--ch-set pskPSK (Pre-Shared Key). A secret code or passphrase used in Meshtastic channels for encryption, ensuring that only devices with the matching PSK can communicate within that specific channel. none" to turn off encryption.
Use "--ch-set pskPSK (Pre-Shared Key). A secret code or passphrase used in Meshtastic channels for encryption, ensuring that only devices with the matching PSK can communicate within that specific channel. 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 pskPSK (Pre-Shared Key). A secret code or passphrase used in Meshtastic channels for encryption, ensuring that only devices with the matching PSK can communicate within that specific channel. 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.
Utilizing BLE via the Python CLI
The Python CLICLI (Command Line Interface). A text-based interface used for interacting with software or devices like Meshtastic. supports communicating with Meshtastic devices via Bluetooth Low Energy (BLEBLE (Bluetooth Low Energy). The default wireless connection between a node and a phone client.), in addition to the standard serial and TCPTCP (Transmission Control Protocol). One of the three ways a client reaches a node, alongside serial and Bluetooth. Clients connect over TCP on port 4403./IP connections. To use BLEBLE (Bluetooth Low Energy). The default wireless connection between a node and a phone client., you will need a Bluetooth adapter on your computer.
Scan for BLE Devices
First, you can scan for available Meshtastic devices using:
meshtastic --ble-scan
This will list all Meshtastic devices discoverable over BLEBLE (Bluetooth Low Energy). The default wireless connection between a node and a phone client. along with their addresses and names in the following format:
Found: name='Meshtastic_1234' address='AA11BB22-CC33-DD44-EE55-FF6677889900'
BLE scan finished
Available Commands
Once you have the device address or name, you can utilize it alongside your normal Python CLICLI (Command Line Interface). A text-based interface used for interacting with software or devices like Meshtastic. commands like --info, --nodes, --export-config, etc. but with the --ble option to communicate via BLEBLE (Bluetooth Low Energy). The default wireless connection between a node and a phone client. rather than serial.
You can use either the name or address to issue your commands.
meshtastic --ble <name> --info
meshtastic --ble <address> --nodes
The initial time you use the --ble option for a specific device, you will be prompted to enter the BLEBLE (Bluetooth Low Energy). The default wireless connection between a node and a phone client. PIN code (as is normal with a client). Once paired, this step won't be required unless you forget the device.
On Linux, you may need to pair the BLEBLE (Bluetooth Low Energy). The default wireless connection between a node and a phone client. device using bluetoothctl before connecting. This allows entering the required PIN for pairing.
Additional BLE Examples
Scan for devices and get info from the first one:
meshtastic --ble-scan
# Sample output:
# Found: name='Meshtastic_1234' address='AA11BB22-CC33-DD44-EE55-FF6677889900'
# Found: name='Meshtastic_5678' address='FF00DD00-AA11-BB22-CC33-DD44EE5566FF'
BLE scan finished
meshtastic --ble AA11BB22-CC33-DD44-EE55-FF6677889900 --info
Connect to a named device and read the node list:
meshtastic --ble Meshtastic_1234 --nodes
Export device config with --export-config
meshtastic --ble Meshtastic_1234 --export-config > config.yaml
Send a command to a remote device using the --dest option:
meshtastic --dest '!fe1932db4' --set device.is_managed false --ble Meshtastic_9abc
For debugging, you can enable verbose BLE logging by adding the --debug flag:
meshtastic --ble AA11BB22-CC33-DD44-EE55-FF6677889900 --debug --info
FAQ/common problems
This is a collection of common questions and answers from our friendly forum.
Permission denied: ‘/dev/ttyUSB0’
This indicates an OS permission problem for access by your user to the USBUSB (Universal Serial Bus). The wired connection used to power a device, flash firmware onto it, and communicate with it over serial. serial port. Typically this is fixed by the following.
sudo usermod -a -G dialout <username>
If adding your user to the dialout group does not work, you can use the following command to find out which group to add your user to. In this example (from Arch Linux) the group was "uucp"
❯ ls -al /dev/ttyACM0
crw-rw---- 1 root uucp 166, 0 Jul 20 21:52 /dev/ttyACM0
Mac OS Big Sur
There is a problem with Big Sur and pyserial. The workaround is to install a newer version of pyserial:
pip3 install -U --pre pyserial
[Errno -2] Name or service not known / [Errno -3] Temporary failure in name resolution
DNS failures: the --host name did not resolve (-2) or the lookup itself failed (-3). .local mDNS names often fail on Windows and in containers — use the node's IP instead, for example meshtastic --host 192.168.1.50 --info.
Warning: Error processing received packet: 'NoneType' object has no attribute 'get'
A packet the CLICLI (Command Line Interface). A text-based interface used for interacting with software or devices like Meshtastic. cannot decode, usually one encrypted with a channel key your node does not have. Non-fatal — the packet is skipped and the CLICLI (Command Line Interface). A text-based interface used for interacting with software or devices like Meshtastic. continues.