---
id: linux-native-hardware
title: Meshtastic on Linux-Native Devices
sidebar_label: Linux Native Devices
sidebar_position: 11
description: Set up and configure Meshtastic on Linux-native devices using the meshtasticd binary.
---

<!-- markdownlint-disable code-block-style -->

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";
import { Icon } from "@iconify/react";

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

#### SPI

- Raspberry Pi: Zero, Zero 2, 3, 4, Pi 400, and Pi 5 on Raspbian `bookworm`.
- Luckfox Pico: [femtofox](https://github.com/noon92/femtofox/tree/main) on Ubuntu 22.04 `jammy`.

#### USB (CH341)

- Debian 12 (`bookworm`) with MeshStick.
- Ubuntu LTS (`24.04`, `22.04`) with MeshStick.
- Fedora `41` with MeshStick.
- meshtasticd Docker container with MeshStick passed-through.

### Hardware Compatibility

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

- Tested Raspberry Pi LoRa hats include the [MeshAdv-Pi v1.1](https://github.com/chrismyers2000/MeshAdv-Pi-Hat), 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 packages.

## Installation

### Installing Meshtasticd

<!-- markdownlint-disable no-inline-html -->

<Tabs groupId="operating-systems" queryString="os">
  <TabItem value="debian" label={<><Icon icon="mdi:debian" height="1.5rem" /> Debian</>} default>
    Debian packages are provided via [OpenSUSE Build Service](https://build.opensuse.org/project/show/network:meshtastic).

    Supported: `bookworm`

    **Install - Debian 12 (`bookworm`):**
    ```shell
    ```

    <details>
      <summary>Experimental builds</summary>

      These builds are provided without support, please **do not file issues** relating to Experimental builds.

      Experimental Support: `trixie` (testing), `sid` (unstable)

      **Install - Debian 13 (`trixie`):**
      ```shell
      ```

      **Install - Debian unstable (`sid`):**
      ```shell
      ```
    </details>

  </TabItem>
  <TabItem value="raspbian" label={<><Icon icon="cib:raspberry-pi" height="1.5rem" /> Raspbian</>}>
    Raspbian (Raspberry Pi OS) packages are provided via [OpenSUSE Build Service](https://build.opensuse.org/project/show/network:meshtastic).

    Supported: `bookworm`

    **Install - Raspbian 12 (`bookworm`):**
    ```shell
    ```

  </TabItem>
  <TabItem value="ubuntu" label={<><Icon icon="mdi:ubuntu" height="1.5rem" /> Ubuntu</>}>
    Ubuntu packages are provided via [Canonical Launchpad](https://launchpad.net/~meshtastic).

    Supported: `oracular` (24.10), `noble` (24.04 LTS), `jammy` (22.04 LTS)

    **Install:**
    ```shell
    # Install requirements for add-apt-repository
    sudo apt install software-properties-common
    # Add Meshtastic repo
    sudo add-apt-repository ppa:meshtastic/beta
    # Install meshtasticd
    sudo apt install meshtasticd
    ```

    <details>
      <summary>Experimental builds</summary>

      These builds are provided without support, please **do not file issues** relating to Experimental builds.

      Experimental Support: `plucky` (25.04)

      **Install:**
      > Install via the instructions above.
    </details>

  </TabItem>
  <TabItem value="fedora" label={<><Icon icon="mdi:fedora" height="1.5rem" /> Fedora</>}>
    Fedora packages are provided via Fedora COPR.

    Supported[^1]: `41`, `40`

    **Install:**
    ```shell
    # Add Meshtastic COPR repo
    sudo dnf copr enable <insert_copr_here>
    # Install meshtasticd
    sudo dnf install meshtasticd
    ```

    <details>
      <summary>Experimental builds</summary>

      These builds are provided without support, please **do not file issues** relating to Experimental builds.

      Experimental Support: `rawhide`

      **Install - `rawhide`:**
      > Install via the instructions above.
    </details>

  </TabItem>

  <TabItem value="docker" label={<><Icon icon="mdi:docker" height="1.5rem" /> Docker</>}>
    Docker containers are provided via [DockerHub](https://hub.docker.com/r/meshtastic/meshtasticd).

    **Pull:**
    ```shell
    docker pull meshtastic/meshtasticd
    ```

  </TabItem>
</Tabs>
<!-- markdownlint-enable no-inline-html -->

## Configuration

### Hardware Interfaces

For devices requiring SPI or I2C:

- This can be done by running the below commands on a Raspberry Pi (2-5)

```shell
sudo raspi-config nonint set_config_var dtparam=spi on /boot/firmware/config.txt # Enable SPI
sudo raspi-config nonint set_config_var dtparam=i2c_arm on /boot/firmware/config.txt # Enable i2c_arm

# Ensure dtoverlay=spi0-0cs is set in /boot/firmware/config.txt without altering dtoverlay=vc4-kms-v3d or dtparam=uart0
sudo sed -i -e '/^\s*#\?\s*dtoverlay\s*=\s*vc4-kms-v3d/! s/^\s*#\?\s*(dtoverlay|dtparam\s*=\s*uart0)\s*=.*/dtoverlay=spi0-0cs/' /boot/firmware/config.txt

# Insert dtoverlay=spi0-0cs after dtparam=spi=on if not already present
if ! sudo grep -q '^\s*dtoverlay=spi0-0cs' /boot/firmware/config.txt; then
    sudo sed -i '/^\s*dtparam=spi=on/a dtoverlay=spi0-0cs' /boot/firmware/config.txt
fi
```

- Or this can be accomplished by manually enabling SPI support in `/boot/firmware/config.txt`:

```plaintext
dtparam=spi=on
dtoverlay=spi0-0cs
```

- I2C support is enabled with:

```plaintext
dtparam=i2c_arm=on
```

### GPS Support

- You can enable UART by running the below commands (which additionally will disable serial console tty)

```shell
sudo raspi-config nonint do_serial_hw 0 # Enable Serial Port (enable_uart=1)
sudo raspi-config nonint do_serial_cons 1 # Disable Serial Console
```

- Or you can manually enable UART for GPS hats by making modifications in `/boot/firmware/config.txt`:

```plaintext
# 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`.
- You may need to disable the serial console on a Pi and then reboot

```shell
sudo raspi-config nonint do_serial_cons 1 # Disable Serial Console
```

### 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:

```yaml
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`.[^1]

[^1]: Fedora packages do not currently include **web server** support.

To enable this:

```yaml
Webserver:
  Port: 443 # Port for Webserver & Webservices
  RootPath: /usr/share/meshtasticd/web # Root Dir of WebServer
```

### Bluetooth Support

Bluetooth is currently unsupported and not functional on Linux Native devices. This may change in the future.

### Persistence

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

### Advanced Setup and Troubleshooting

#### Enabling the systemd service

To configure the device to start and stop meshtasticd as as service using systemctl you can setup the service unit using the instructions below.

<!-- markdownlint-disable no-inline-html -->

<details>
  <summary>Create the systemd service (only for manual installs)</summary>

The `meshtasticd` systemd service is automatically installed when using the official Meshtastic packages.
These instructions are only needed when installing manually.

Create the service unit file:

Create a new file in the /etc/systemd/system/ directory with a name like meshtasticd.service.

```shell
sudo nano /etc/systemd/system/meshtasticd.service
```

Add the following content to the file:

```plaintext
[Unit]
Description=Meshtastic Daemon
After=network.target

[Service]
ExecStart=/usr/sbin/meshtasticd
Restart=always
User=root
Group=root
Type=simple

[Install]
WantedBy=multi-user.target
```

Reload systemd to recognize the new service:

```shell
sudo systemctl daemon-reload
```

</details>
<!-- markdownlint-enable no-inline-html -->

Enable the service to start on boot:

```shell
sudo systemctl enable meshtasticd
```

##### Starting and Stopping the Service

Start the service:

```shell
sudo systemctl start meshtasticd
```

Check the status of the service:

```shell
sudo systemctl status meshtasticd
```

This will give you a detailed view of the service status and any potential errors.

Stop the service:

```shell
sudo systemctl stop meshtasticd
```

By following these steps, you set up a systemd service for meshtasticd that will start automatically at boot and restart if it crashes. You can manage it using the standard systemctl commands (start, stop, restart, status, etc.).

#### View Logs of Meshtastic

To view the log output of the meshtasticd service, use the below command to read them out of the system journal.

```shell
journalctl -u meshtasticd -b
```

#### Avahi setup

This will allow the Android client to auto-discover your Linux Native device.

- Install avahi-daemon (debian/ubuntu)

```shell
sudo apt install avahi-daemon
```

- Configure Avahi to advertise the node

Create the service file:

```shell
sudo nano /etc/avahi/services/meshtastic.service
```

And paste the following:

```xml
<?xml version="1.0" standalone="no"?><!--*-nxml-*-->
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
    <name>Meshtastic</name>
    <service protocol="ipv4">
        <type>_meshtastic._tcp</type>
        <port>4403</port>
    </service>
</service-group>
```

Then save and exit.

## CLI Configuration

Interaction with Meshtastic can be conducted via the command line:

```plaintext
meshtastic --host localhost ...
```

See:

- [CLI Installation](/docs/software/python/cli/installation/)
- [CLI Usage](/docs/software/python/cli/usage/)