From fb1381ade022c317ce5c333e0143bb87222bb483 Mon Sep 17 00:00:00 2001 From: rcarteraz Date: Mon, 11 Mar 2024 14:16:40 -0700 Subject: [PATCH 01/10] initial draft linux-native-hardware --- .../linux-native-hardware.mdx | 117 ++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx diff --git a/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx b/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx new file mode 100644 index 00000000..4809a691 --- /dev/null +++ b/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx @@ -0,0 +1,117 @@ +--- +id: linux-native-hardware +title: Meshtastic on Linux-Native Devices +sidebar_label: Linux Native Devices +sidebar_position: 11 +--- + +This guide 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 +- Ubuntu 22.04 X86_64 with a CH341-SX1262 DIY dongle +- Debian GNU/Linux trixie/sid riscv64 on Cvitek CV180X ASIC, C906 (Milk-V Duo), on the SPI bus + +### Hardware Compatibility +- Tested radios include Waveshare SX126X, 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. +- UART HATs and SX1302/SX1303 chip-based HATs are not supported. + +### 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. + +```shell +sudo apt install libgpiod-dev libyaml-cpp-dev +``` +- And optionally for web server support +```shell +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. +```shell +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`: + +```plaintext +dtparam=spi=on +dtoverlay=spi0-0cs +``` + +- I2C support is enabled with: + +```plaintext +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. + +### 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 +``` + +### GPS Support + +- Enabling UART for GPS hats on Pi5 requires modifications in `/boot/firmware/config.txt`: + +```plaintext +enable_uart=1 +dtoverlay=uart0 +``` + +The correct port for UART GPS after a reboot is `/dev/ttyAMA0`. + +### 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. + +```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. + +## CLI Configuration + +Interaction with Meshtastic can be conducted via the command line: + +```shell +meshtastic --host localhost ... +``` From 33f958ff4bce529b0c4f7e1139962f0558edc545 Mon Sep 17 00:00:00 2001 From: rcarteraz Date: Mon, 11 Mar 2024 14:34:54 -0700 Subject: [PATCH 02/10] footnote ch341 --- .../linux-native-hardware/linux-native-hardware.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 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 4809a691..88fb414d 100644 --- a/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx +++ b/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx @@ -12,9 +12,11 @@ This guide outlines the setup of Meshtastic on Linux-native devices, utilizing p 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 -- Ubuntu 22.04 X86_64 with a CH341-SX1262 DIY dongle -- Debian GNU/Linux trixie/sid riscv64 on Cvitek CV180X ASIC, C906 (Milk-V Duo), on the SPI bus +- Raspberry Pi zero, zero 2 , 3,4, Pi 400, and Pi 5. +- Ubuntu 22.04 X86_64 with a CH341-SX1262 DIY dongle.[^1] +- Debian GNU/Linux trixie/sid riscv64 on Cvitek CV180X ASIC, C906 (Milk-V Duo), on the SPI bus. + +[^1]: **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. ### Hardware Compatibility - Tested radios include Waveshare SX126X, Adafruit RFM9x, and Elecrow Lora RFM95 IOT. @@ -114,4 +116,4 @@ Interaction with Meshtastic can be conducted via the command line: ```shell meshtastic --host localhost ... -``` +``` \ No newline at end of file From 5b4084f08aadbc808d69e156067d047b2f9c33db Mon Sep 17 00:00:00 2001 From: rcarteraz Date: Fri, 15 Mar 2024 09:28:11 -0700 Subject: [PATCH 03/10] comment example --- .../linux-native-hardware/linux-native-hardware.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) 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 88fb414d..3159ff4a 100644 --- a/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx +++ b/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx @@ -69,6 +69,17 @@ dtparam=i2c_arm=on - 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 +``` ### Web Server - Meshtasticd has web server support starting with release 2.3.0 To enable this: From 489052d2931d9c758d18751a733b369ec22c6ca4 Mon Sep 17 00:00:00 2001 From: rcarteraz Date: Fri, 15 Mar 2024 09:42:29 -0700 Subject: [PATCH 04/10] spacing --- .../devices/linux-native-hardware/linux-native-hardware.mdx | 1 + 1 file changed, 1 insertion(+) 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 3159ff4a..3833bd8e 100644 --- a/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx +++ b/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx @@ -80,6 +80,7 @@ IRQ: 16 Busy: 20 Reset: 18 ``` + ### Web Server - Meshtasticd has web server support starting with release 2.3.0 To enable this: From 70907371c0f057a0a188fae2a78a2cad23f27655 Mon Sep 17 00:00:00 2001 From: rcarteraz Date: Mon, 11 Mar 2024 14:16:40 -0700 Subject: [PATCH 05/10] initial draft linux-native-hardware --- .../linux-native-hardware.mdx | 117 ++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx diff --git a/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx b/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx new file mode 100644 index 00000000..4809a691 --- /dev/null +++ b/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx @@ -0,0 +1,117 @@ +--- +id: linux-native-hardware +title: Meshtastic on Linux-Native Devices +sidebar_label: Linux Native Devices +sidebar_position: 11 +--- + +This guide 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 +- Ubuntu 22.04 X86_64 with a CH341-SX1262 DIY dongle +- Debian GNU/Linux trixie/sid riscv64 on Cvitek CV180X ASIC, C906 (Milk-V Duo), on the SPI bus + +### Hardware Compatibility +- Tested radios include Waveshare SX126X, 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. +- UART HATs and SX1302/SX1303 chip-based HATs are not supported. + +### 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. + +```shell +sudo apt install libgpiod-dev libyaml-cpp-dev +``` +- And optionally for web server support +```shell +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. +```shell +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`: + +```plaintext +dtparam=spi=on +dtoverlay=spi0-0cs +``` + +- I2C support is enabled with: + +```plaintext +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. + +### 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 +``` + +### GPS Support + +- Enabling UART for GPS hats on Pi5 requires modifications in `/boot/firmware/config.txt`: + +```plaintext +enable_uart=1 +dtoverlay=uart0 +``` + +The correct port for UART GPS after a reboot is `/dev/ttyAMA0`. + +### 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. + +```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. + +## CLI Configuration + +Interaction with Meshtastic can be conducted via the command line: + +```shell +meshtastic --host localhost ... +``` From 389ac4d11f71e2e0f7aabd08ce58aa1d5f79c79d Mon Sep 17 00:00:00 2001 From: rcarteraz Date: Mon, 11 Mar 2024 14:34:54 -0700 Subject: [PATCH 06/10] footnote ch341 --- .../linux-native-hardware/linux-native-hardware.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 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 4809a691..88fb414d 100644 --- a/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx +++ b/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx @@ -12,9 +12,11 @@ This guide outlines the setup of Meshtastic on Linux-native devices, utilizing p 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 -- Ubuntu 22.04 X86_64 with a CH341-SX1262 DIY dongle -- Debian GNU/Linux trixie/sid riscv64 on Cvitek CV180X ASIC, C906 (Milk-V Duo), on the SPI bus +- Raspberry Pi zero, zero 2 , 3,4, Pi 400, and Pi 5. +- Ubuntu 22.04 X86_64 with a CH341-SX1262 DIY dongle.[^1] +- Debian GNU/Linux trixie/sid riscv64 on Cvitek CV180X ASIC, C906 (Milk-V Duo), on the SPI bus. + +[^1]: **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. ### Hardware Compatibility - Tested radios include Waveshare SX126X, Adafruit RFM9x, and Elecrow Lora RFM95 IOT. @@ -114,4 +116,4 @@ Interaction with Meshtastic can be conducted via the command line: ```shell meshtastic --host localhost ... -``` +``` \ No newline at end of file From 2f3039f09aca4fc5d5abf8bf626050dcdb738e7b Mon Sep 17 00:00:00 2001 From: rcarteraz Date: Fri, 15 Mar 2024 09:28:11 -0700 Subject: [PATCH 07/10] comment example --- .../linux-native-hardware/linux-native-hardware.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) 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 88fb414d..3159ff4a 100644 --- a/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx +++ b/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx @@ -69,6 +69,17 @@ dtparam=i2c_arm=on - 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 +``` ### Web Server - Meshtasticd has web server support starting with release 2.3.0 To enable this: From 64b68a2d922bff96fd2b99912fa5d56ce643dda8 Mon Sep 17 00:00:00 2001 From: rcarteraz Date: Fri, 15 Mar 2024 09:42:29 -0700 Subject: [PATCH 08/10] spacing --- .../devices/linux-native-hardware/linux-native-hardware.mdx | 1 + 1 file changed, 1 insertion(+) 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 3159ff4a..3833bd8e 100644 --- a/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx +++ b/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx @@ -80,6 +80,7 @@ IRQ: 16 Busy: 20 Reset: 18 ``` + ### Web Server - Meshtasticd has web server support starting with release 2.3.0 To enable this: From b05c4154d173e163efd3023ac8c3f6d04b5df207 Mon Sep 17 00:00:00 2001 From: rcarteraz Date: Sun, 17 Mar 2024 09:48:18 -0700 Subject: [PATCH 09/10] add footnote regarding pi zero --- .../linux-native-hardware/linux-native-hardware.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 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 3833bd8e..3b7536ce 100644 --- a/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx +++ b/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx @@ -12,11 +12,12 @@ This guide outlines the setup of Meshtastic on Linux-native devices, utilizing p 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. -- Ubuntu 22.04 X86_64 with a CH341-SX1262 DIY dongle.[^1] +- 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. -[^1]: **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. +[^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. ### Hardware Compatibility - Tested radios include Waveshare SX126X, Adafruit RFM9x, and Elecrow Lora RFM95 IOT. From a3293a20c3710035a76fc0a4144202eeb0ea9c4a Mon Sep 17 00:00:00 2001 From: rcarteraz Date: Sun, 24 Mar 2024 14:21:28 -0700 Subject: [PATCH 10/10] changes based on feedback --- .../linux-native-hardware/linux-native-hardware.mdx | 10 +++++++--- 1 file changed, 7 insertions(+), 3 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 3b7536ce..e6252676 100644 --- a/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx +++ b/docs/hardware/devices/linux-native-hardware/linux-native-hardware.mdx @@ -35,7 +35,7 @@ Before proceeding with the setup, ensure the device meets the following requirem - Necessary system libraries should be installed before building or installing Meshtastic. ```shell -sudo apt install libgpiod-dev libyaml-cpp-dev +sudo apt install libgpiod-dev libyaml-cpp-dev libbluetooth-dev ``` - And optionally for web server support ```shell @@ -94,14 +94,18 @@ Webserver: ### GPS Support -- Enabling UART for GPS hats on Pi5 requires modifications in `/boot/firmware/config.txt`: +Enabling UART for GPS hats requires 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 after a reboot is `/dev/ttyAMA0`. +- 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