mirror of
https://github.com/meshtastic/meshtastic.git
synced 2025-03-05 21:00:08 -08:00
Linux docs overhaul
This commit is contained in:
parent
c33215a36e
commit
76eb4cd131
|
@ -5,8 +5,11 @@ sidebar_label: Linux Native Devices
|
||||||
sidebar_position: 11
|
sidebar_position: 11
|
||||||
description: Set up and configure Meshtastic on Linux-native devices using the meshtasticd binary.
|
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.
|
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:
|
Before proceeding with the setup, ensure the device meets the following requirements:
|
||||||
|
|
||||||
### Tested Devices
|
### Tested Devices
|
||||||
- Raspberry Pi zero, zero 2 , 3,4, Pi 400, and Pi 5.[^1]
|
#### SPI
|
||||||
- Ubuntu 22.04 X86_64 with a CH341-SX1262 DIY dongle.[^2]
|
- Raspberry Pi: Zero, Zero 2, 3, 4, Pi 400, and Pi 5 on Raspbian `bookworm`.
|
||||||
- Debian GNU/Linux trixie/sid riscv64 on Cvitek CV180X ASIC, C906 (Milk-V Duo), on the SPI bus.
|
- 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.
|
#### USB (CH341)
|
||||||
[^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.
|
- 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
|
### Hardware Compatibility
|
||||||
|
|
||||||
|
@ -28,25 +34,115 @@ Before proceeding with the setup, ensure the device meets the following requirem
|
||||||
UART HATs and SX1302/SX1303 chip-based HATs are not supported. Only hats that use a SPI radio can work with Meshtastic.
|
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.
|
- 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.
|
- 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
|
### System Requirements
|
||||||
- The Meshtastic binary, `meshtasticd`, necessitates root access or a user with permissions to access GPIO, SPI, and other interfaces.
|
- 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
|
## Installation
|
||||||
|
|
||||||
### Installing Meshtasticd
|
### 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.
|
**Install - Debian 12 (`bookworm`):**
|
||||||
```shell
|
```shell
|
||||||
wget https://github.com/meshtastic/firmware/releases/download/v{version}/meshtasticd_{version}_arm64.deb
|
|
||||||
sudo apt install ./meshtasticd_{version}arm64.deb
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<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
|
## Configuration
|
||||||
|
|
||||||
### Hardware Interfaces
|
### Hardware Interfaces
|
||||||
|
@ -81,37 +177,6 @@ dtoverlay=spi0-0cs
|
||||||
dtparam=i2c_arm=on
|
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
|
### GPS Support
|
||||||
|
|
||||||
- You can enable UART by running the below commands (which additionally will disable serial console tty)
|
- You can enable UART by running the below commands (which additionally will disable serial console tty)
|
||||||
|
@ -138,16 +203,56 @@ dtoverlay=uart0
|
||||||
sudo raspi-config nonint do_serial_cons 1 # Disable Serial Console
|
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
|
### Persistence
|
||||||
|
|
||||||
- The persistent .proto db files of the portduino version of meshtasticd are stored under: `/root/.portduino/default/prefs/`.
|
- The persistent .proto db files of the portduino version of meshtasticd are stored under: `/root/.portduino/default/prefs/`.
|
||||||
|
|
||||||
### Advanced Setup and Troubleshooting
|
### 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.
|
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 the service unit file:
|
||||||
|
|
||||||
Create a new file in the /etc/systemd/system/ directory with a name like meshtasticd.service.
|
Create a new file in the /etc/systemd/system/ directory with a name like meshtasticd.service.
|
||||||
|
@ -176,6 +281,8 @@ Reload systemd to recognize the new service:
|
||||||
```shell
|
```shell
|
||||||
sudo systemctl daemon-reload
|
sudo systemctl daemon-reload
|
||||||
```
|
```
|
||||||
|
</details>
|
||||||
|
<!-- markdownlint-enable no-inline-html -->
|
||||||
|
|
||||||
Enable the service to start on boot:
|
Enable the service to start on boot:
|
||||||
```shell
|
```shell
|
||||||
|
@ -193,39 +300,22 @@ Check the status of the service:
|
||||||
```shell
|
```shell
|
||||||
sudo systemctl status meshtasticd
|
sudo systemctl status meshtasticd
|
||||||
```
|
```
|
||||||
|
This will give you a detailed view of the service status and any potential errors.
|
||||||
|
|
||||||
Stop the service:
|
Stop the service:
|
||||||
```shell
|
```shell
|
||||||
sudo systemctl stop meshtasticd
|
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.).
|
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 Mesthastic
|
#### 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.
|
To view the log output of the meshtasticd service, use the below command to read them out of the system journal.
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
journalctl -u meshtasticd -b
|
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
|
#### Avahi setup
|
||||||
This will allow the Android client to auto-discover your Linux Native device.
|
This will allow the Android client to auto-discover your Linux Native device.
|
||||||
|
|
||||||
|
@ -260,6 +350,9 @@ Then save and exit.
|
||||||
|
|
||||||
Interaction with Meshtastic can be conducted via the command line:
|
Interaction with Meshtastic can be conducted via the command line:
|
||||||
|
|
||||||
```shell
|
```plaintext
|
||||||
meshtastic --host localhost ...
|
meshtastic --host localhost ...
|
||||||
```
|
```
|
||||||
|
See:
|
||||||
|
- [CLI Installation](/docs/software/python/cli/installation/)
|
||||||
|
- [CLI Usage](/docs/software/python/cli/usage/)
|
||||||
|
|
|
@ -22,6 +22,7 @@
|
||||||
"@docusaurus/theme-mermaid": "3.6.1",
|
"@docusaurus/theme-mermaid": "3.6.1",
|
||||||
"@giscus/react": "^3.0.0",
|
"@giscus/react": "^3.0.0",
|
||||||
"@heroicons/react": "^2.1.1",
|
"@heroicons/react": "^2.1.1",
|
||||||
|
"@iconify/react": "^5.2.0",
|
||||||
"@mdx-js/react": "^3.0.1",
|
"@mdx-js/react": "^3.0.1",
|
||||||
"@meshtastic/js": "2.3.7-5",
|
"@meshtastic/js": "2.3.7-5",
|
||||||
"autoprefixer": "^10.4.17",
|
"autoprefixer": "^10.4.17",
|
||||||
|
|
Loading…
Reference in a new issue