Skip to main content

Meshtastic on Linux-Native Devices

This page outlines the setup of Meshtastic on Linux-native devices, utilizing portduino to run the Meshtastic firmware under Linux.

Prerequisites and Hardware Compatibility​

Before proceeding with the setup, ensure the device meets the following requirements:

Tested Devices​

  • Raspberry Pi zero, zero 2 , 3,4, Pi 400, and Pi 5.1
  • Ubuntu 22.04 X86_64 with a CH341-SX1262 DIY dongle.2
  • Debian GNU/Linux trixie/sid riscv64 on Cvitek CV180X ASIC, C906 (Milk-V Duo), on the SPI bus.

Hardware Compatibility​

Warning

UART HATs and SX1302/SX1303 chip-based HATs are not supported. Only hats that use a SPI radio can work with Meshtastic.

  • Tested radios include the Waveshare SX126X (SPI version), Adafruit RFM9x, and Elecrow Lora RFM95 IOT.
  • Support for I2C displays, SPI displays, and keyboard input has been confirmed. It is necessary to be aware of potential pin conflicts when stacking hats.

System Requirements​

  • The Meshtastic binary, meshtasticd, necessitates root access or a user with permissions to access GPIO, SPI, and other interfaces.
  • A Linux distribution compatible with the Meshtastic installation package, which is compiled for Debian Bookworm and not compatible with Bullseye.

Installation​

Installing Meshtasticd​

  • Necessary system libraries should be installed before building or installing Meshtastic.
sudo apt install libgpiod-dev libyaml-cpp-dev libbluetooth-dev
  • And optionally for web server support
sudo apt install openssl libssl-dev libulfius-dev liborcania-dev
  • The .deb Package is available as part of the release, installing the binary, a systemd service, and a config file. It is compiled for Debian Bookworm and incompatible with Bullseye.
sudo apt install ./meshtasticd_{version}arm64.deb

Configuration​

Hardware Interfaces​

For devices requiring SPI or I2C:

  • SPI support can be enabled in /boot/config.txt or /boot/firmware/config.txt:
dtparam=spi=on
dtoverlay=spi0-0cs
  • I2C support is enabled with:
dtparam=i2c_arm=on

Meshtasticd Configuration​

  • The meshtasticd configuration is at /etc/meshtasticd/config.yaml by default. If a config.yaml is found in the current directory, that takes precedence. And a config file specified with the -c/--config option has the highest precedence.

To enable a LoRa radio connected to your device, uncomment the appropriate lines in the config file, including the Module line. As an example, the Waveshare SX126X module would have a Lora section that looks like this:

Lora:
  Module: sx1262 # Waveshare SX126X XXXM
  DIO2_AS_RF_SWITCH: true
  CS: 21
  IRQ: 16
  Busy: 20
  Reset: 18
info

The config.yaml file is sensitive to spacing, so ensure that the indentation and spacing are correct.

Web Server​

  • Meshtasticd has web server support starting with release 2.3.0 To enable this:
Webserver:
  Port: 443 # Port for Webserver & Webservices
  RootPath: /usr/share/doc/meshtasticd/web # Root Dir of WebServer

GPS Support​

Enabling UART for GPS hats requires modifications in /boot/firmware/config.txt:

# Needed for all Pi device.
enable_uart=1

# Needed for the Pi 5 only.
dtoverlay=uart0
  • The correct port for UART GPS on the Pi 5 after a reboot is /dev/ttyAMA0.
  • The correct port for UART GPS on earlier Pi versions after a reboot is /dev/ttyS0.

Persistence​

  • The persistent .proto db files of the portduino version of meshtasticd are stored under: /root/.portduino/default/prefs/.

Advanced Setup and Troubleshooting​

  • Installation of drivers for CH341 is required for Ubuntu 22.04 and other systems for SPI/I2C/GPIO support.
git clone https://github.com/frank-zago/ch341-i2c-spi-gpio.git
cd ch341-i2c-spi-gpio
make
sudo insmod ch341-core.ko
sudo insmod gpio-ch341.ko
sudo insmod i2c-ch341.ko
sudo insmod spi-ch341.ko
  • Devices with kernels older than 5.16 may need to blacklist ch341, while kernels 6.0 and newer are observed to work more reliably.

CLI Configuration​

Interaction with Meshtastic can be conducted via the command line:

meshtastic --host localhost ...

Footnotes​

  1. While the Raspberry Pi Zero has been tested with meshtasticd, building as a native ARM32 binary has proven challenging. As a workaround, consider building on a Raspberry Pi 4 or 5 with a 32-bit OS and copying the output file to the Pi Zero. ↩

  2. Limited Functionality with CH341-SX1262 Device: Please be aware that the CH341-SX1262 device is currently experiencing partial functionality issues. For reasons yet to be determined, this device struggles with sending packets larger than a few bytes. ↩