mudhorn/meshtastic
1
0
Fork 0
mirror of https://github.com/meshtastic/meshtastic.git synced 2025-03-05 21:00:08 -08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Linux docs overhaul

Browse source
This commit is contained in:
vidplace7 2025-01-09 19:59:33 -05:00
parent 5d2a5f1973
commit 0c8cbaaf78
1 changed files with 182 additions and 89 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

271
docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx
View file

@ -5,8 +5,11 @@ 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 NativeLibraries from "@site/docs/blocks/_native-libraries.mdx";
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.
@ -15,12 +18,15 @@ This page outlines the setup of Meshtastic on Linux-native devices, utilizing po
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.
#### 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`.
[^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.
#### 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
@ -29,24 +35,114 @@ Before proceeding with the setup, ensure the device meets the following requirem
- Waveshare SX1262 LoRaWAN Node Module Expansion Board for Raspberry Pi, while supported, does have known hardware limitations that may affect longer messages. Users should be mindful of this when composing messages. It is also recommended to use the CLIENT_MUTE role to avoid rebroadcasting larger messages.
:::
- Tested radios include the Waveshare SX126X (SPI version), Adafruit RFM9x, and Elecrow Lora RFM95 IOT.
- 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 package, which is compiled for Debian Bookworm and not compatible with Bullseye.
- 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).
<NativeLibraries />
Supported: `bookworm`
- The .deb Package is available as [part of the release](https://github.com/meshtastic/firmware/releases/latest), installing the binary, a systemd service, and a config file. It is compiled for Debian Bookworm and incompatible with Bullseye.
```shell
wget https://github.com/meshtastic/firmware/releases/download/v{version}/meshtasticd_{version}_arm64.deb
sudo apt install ./meshtasticd_{version}arm64.deb
```
**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
@ -82,37 +178,6 @@ dtoverlay=spi0-0cs
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:
```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 To enable this:
```plaintext
Webserver:
Port: 443 # Port for Webserver & Webservices
RootPath: /usr/share/doc/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.
### GPS Support
- You can enable UART by running the below commands (which additionally will disable serial console tty)
@ -139,44 +204,86 @@ dtoverlay=uart0
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
#### Creating and Enabling a Systemctl Script (non .deb installs)
#### 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.
Create the service unit file:
<!-- markdownlint-disable no-inline-html -->
<details>
<summary>Create the systemd service (only for manual installs)</summary>
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:
The `meshtasticd` systemd service is automatically installed when using the official Meshtastic packages.
These instructions are only needed when installing manually.
```plaintext
[Unit]
Description=Meshtastic Daemon
After=network.target
Create the service unit file:
[Service]
ExecStart=/usr/sbin/meshtasticd
Restart=always
User=root
Group=root
Type=simple
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:
[Install]
WantedBy=multi-user.target
```
```plaintext
[Unit]
Description=Meshtastic Daemon
After=network.target
Reload systemd to recognize the new service:
```shell
sudo systemctl daemon-reload
```
[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
@ -194,14 +301,13 @@ 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
```
This will give you a detailed view of the service status and any potential errors.
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
@ -211,22 +317,6 @@ To view the log output of the meshtasticd service, use the below command to read
journalctl -u meshtasticd -b
```
#### Installation of drivers
- Installation of drivers for CH341 is required for Ubuntu 22.04 and other systems for SPI/I2C/GPIO support.
```shell
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.
#### Avahi setup
This will allow the Android client to auto-discover your Linux Native device.
@ -261,6 +351,9 @@ Then save and exit.
Interaction with Meshtastic can be conducted via the command line:
```shell
```plaintext
meshtastic --host localhost ...
```
See:
- [CLI Installation](/docs/software/python/cli/installation/)
- [CLI Usage](/docs/software/python/cli/usage/)