From 76eb4cd131f2be98ecbedd505e6797a2b345633c Mon Sep 17 00:00:00 2001 From: vidplace7 Date: Thu, 9 Jan 2025 19:59:33 -0500 Subject: [PATCH] Linux docs overhaul --- .../linux-native-hardware.mdx | 273 ++++++++++++------ package.json | 1 + 2 files changed, 184 insertions(+), 90 deletions(-) diff --git a/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx b/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx index 2ecd55ec..41a1accd 100644 --- a/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx +++ b/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx @@ -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. --- + -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 @@ -28,24 +34,114 @@ 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. ::: -- 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 + + + Debian} default> + Debian packages are provided via [OpenSUSE Build Service](https://build.opensuse.org/project/show/network:meshtastic). - + 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 + ``` + +
+ Experimental builds + + 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 + ``` +
+ + 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 + ``` + + + 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 + ``` + +
+ Experimental builds + + 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. +
+ + Fedora}> + Fedora packages are provided via Fedora COPR. + + Supported[^1]: `41`, `40` + + **Install:** + ```shell + # Add Meshtastic COPR repo + sudo dnf copr enable + # Install meshtasticd + sudo dnf install meshtasticd + ``` + +
+ Experimental builds + + 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. +
+ + + Docker}> + Docker containers are provided via [DockerHub](https://hub.docker.com/r/meshtastic/meshtasticd). + + **Pull:** + ```shell + docker pull meshtastic/meshtasticd + ``` + + + ## Configuration @@ -81,37 +177,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) @@ -138,44 +203,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: + +
+ Create the systemd service (only for manual installs) -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 + ``` +
+ Enable the service to start on boot: ```shell @@ -193,39 +300,22 @@ 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 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. ```shell 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. @@ -260,6 +350,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/) diff --git a/package.json b/package.json index bc91391f..3f49e3f1 100644 --- a/package.json +++ b/package.json @@ -22,6 +22,7 @@ "@docusaurus/theme-mermaid": "3.6.1", "@giscus/react": "^3.0.0", "@heroicons/react": "^2.1.1", + "@iconify/react": "^5.2.0", "@mdx-js/react": "^3.0.1", "@meshtastic/js": "2.3.7-5", "autoprefixer": "^10.4.17",