Skip to main content

Python API & client shell for talking to Meshtastic devices

Project description

Meshtastic-python

A python client for using Meshtastic devices. This small library (and example application) provides an easy API for sending and receiving messages over mesh radios. It also provides access to any of the operations/data available in the device user interface or the Android application. Events are delivered using a publish-subscribe model, and you can subscribe to only the message types you are interested in.

Full documentation including examples here.

Installation is easily done through the Python package installer pip (note, you must use pip version 20 or later):

  • check that your computer has the required serial drivers installed, if not download them from here.
  • check that your computer has Python 3 installed.
  • check that your computer has "pip3" installed, if not follow this guide.
  • 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
interface.sendText("hello mesh") # or sendData to send binary data, see documentations for other options.
interface.close()

For the rough notes/implementation plan see TODO.

Command line tool

This pip package will also install 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. The source code for this tool is also a good example of a 'complete' application that uses the meshtastic python API.

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.

To display a (partial) list of the available commands:

meshtastic -h

Changing device 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 protcol from your phone will reset this timer)

meshtastic --set wait_bluetooth_secs 28800
Connected to radio...
Setting preference wait_bluetooth_secs to 28800
Writing modified preferences to device...

Or to set a node at a fixed position and never power up the GPS.

meshtastic --setlat 25.2 --setlon -16.8 --setalt 120

Or to configure an ESP32 based board to join a wifi network as a station (wifi support in the device code is coming soon):

meshtastic --set wifi_ap_mode false --setstr wifi_ssid mywifissid --setstr wifi_password mywifipsw

Or to configure an ESP32 to run as a Wifi access point:

meshtastic --set wifi_ap_mode true --setstr wifi_ssid mywifissid --setstr wifi_password mywifipsw

For a full list of preferences which can be set (and their documentation) see here.

Changing channel settings

The channel settings can be changed similiarly. Either by using a standard (sharable) meshtastic URL or you can set partiular channel parameters (for advanced users).

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

This will change some channel params and then show device info (which will include the current channel URL)

You can even set the channel preshared key to a particular AES128 or AES256 sequence.

meshtastic --setchan psk 0x1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b1a1a1a1a2b2b2b2b --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 USB serial port. Typically this is fixed by the following.

sudo usermod -a -G dialout <username>

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

Afterwards you can use the meshatstic python client again on MacOS.

A note to developers of this lib

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 pandoc webencodings pyparsing twine autopep8

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

meshtastic-1.2.8.tar.gz (44.4 kB view details)

Uploaded Source

Built Distribution

meshtastic-1.2.8-py3-none-any.whl (53.8 kB view details)

Uploaded Python 3

File details

Details for the file meshtastic-1.2.8.tar.gz.

File metadata

  • Download URL: meshtastic-1.2.8.tar.gz
  • Upload date:
  • Size: 44.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.25.1 setuptools/53.0.0 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.6

File hashes

Hashes for meshtastic-1.2.8.tar.gz
Algorithm Hash digest
SHA256 b8d3adfb9e1dabbc0ddfbe98c34e7aeb94ca513bf7f43206c58025c60d8128d0
MD5 d686f5a55bb1c8b1e4d58d23d7929a3e
BLAKE2b-256 2016ef4aade0a90cc8488403793c4de0fc056cd3f83ec390bd9a4407a52a5e9a

See more details on using hashes here.

File details

Details for the file meshtastic-1.2.8-py3-none-any.whl.

File metadata

  • Download URL: meshtastic-1.2.8-py3-none-any.whl
  • Upload date:
  • Size: 53.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.25.1 setuptools/53.0.0 requests-toolbelt/0.9.1 tqdm/4.51.0 CPython/3.8.6

File hashes

Hashes for meshtastic-1.2.8-py3-none-any.whl
Algorithm Hash digest
SHA256 7ead3b3370ac58aee4d83d9fe1e77a445a2275c37407e2b921d4ca74af206a32
MD5 2459e43b3d5d230099b22212625f3477
BLAKE2b-256 588cd1cd93630d4fb7f7b81167e52d5e9bf68135ee83543dcb913873d3958785

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page