RCN - Documentation: https://rcn.varia.zone/ - Almanac: https://rcn.varia.zone/almanac/ - Clients: https://rcn.varia.zone/clients/ - Contact: https://rcn.varia.zone/contact/ - Events: https://rcn.varia.zone/events/ - Experiments: https://rcn.varia.zone/experiments/ - Gallery: https://rcn.varia.zone/gallery/ - Glossary: https://rcn.varia.zone/glossary/ - Links: https://rcn.varia.zone/links/ - Network: https://rcn.varia.zone/network/ # Conventions ## Python We use [`pipx`](https://pipx.pypa.io/stable/) as the "least complicated" Python packaging tool at this moment in time. We recommend to use the so-called "zipapp" version of `pipx`, which allows us to download a single file and run it independently of the system Python installation. ```bash sudo -i wget https://github.com/pypa/pipx/releases/download/1.17.11/pipx.pyz chmod +x pipx.pyz mv pipx.pyz /usr/bin/pipx pipx --version pipx ensurepath --global ``` Python packages will be installed into `/opt/pipx`. ## System user We create a specific system user for all server-based programs which rely on Reticulum. ```bash useradd --system -s /sbin/nologin reticulum ``` The guides below assume this is also the case on your system. ## Root permissions Unless `sudo` is specified, the commands below assume you are running the commands as the root user. ```bash sudo -i ``` ## Naming All network-facing interfaces (which end-users configure in their clients) should be named after a snack featured in your local snackbar. See [the network page](/network) for names which have already been used. Happy Snacking! # Dependencies Building a reliable community network using Reticulum is an exercise in dependency management. We need to understand and maintain an overview of all our dependencies in order to understand how resilient our network can be. This involves tracking software and hardware versions, firmwares and project developments. | Software | Purpose | Version | Check | | -------- | ------- | ------- | ----- | | [`LoraMon`](https://github.com/markqvist/LoRaMon) | Debugging LoRa | [`0.9.7`](https://pypi.org/project/loramon/#files) | `loramon --version` | [`RNode_Firmware`](https://github.com/markqvist/RNode_Firmware) | RNode firmware | [`1.86`](https://github.com/markqvist/RNode_Firmware/releases/tag/1.86) | `rnodeconf --info /dev/rnode_XXXX` | | [`RTNode-HeltecV4`](https://github.com/jrl290/RTNode-HeltecV4) ([web flasher](https://jrl290.github.io/RTNode-HeltecV4/)) | RTNode firmware | [`v1.0.51`](https://github.com/jrl290/RTNode-HeltecV4/releases/tag/v1.0.51) | `rnodeconf --info /dev/rnode_XXXX` | | [`F-Droid`](https://f-droid.org/en/) | Android app distribution | [`1.23.2`](https://f-droid.org/F-Droid.apk) | `Settings > About F-Droid`| | [`Hugo`](https://themes.gohugo.io) | This website | [`v0.167.0+extended+withdeploy`](https://github.com/gohugoio/hugo/releases/tag/v0.167.0) | `hugo version` | | [`lxmd`](https://github.com/markqvist/LXMF) | Propagation node | [`1.3.0`](https://github.com/markqvist/LXMF/releases/tag/1.3.0) | `lxmd --version` | | [`Obtainium`](https://obtainium.imranr.dev) | Android app distribution | [`v1.6.17`](https://github.com/ImranR98/Obtainium/releases/download/v1.6.17/app-release.apk) | Not available | | [`pipx`](https://pipx.pypa.io/stable/) | Python package installer | [`1.17.10`](https://github.com/pypa/pipx/releases/tag/1.17.10) | `pipx --version` | | [`Ratspeak (Android)`](https://ratspeak.org) | Android client | [`v1.0.44`](https://github.com/ratspeak/Ratspeak/releases/tag/v1.0.44) | Settings | | [`Ratspeak (iOS client)`](https://ratspeak.org) | iOS client | [Public Beta](https://testflight.apple.com/join/AzzW4Jg6) | Settings | | [`Ratspeak (Linux)`](https://ratspeak.org) | Linux client | [`v1.0.44`](https://github.com/ratspeak/Ratspeak/releases/tag/v1.0.44) | Settings | | [`Ratspeak (MacOS)`](https://ratspeak.org) | MacOS client | [`v1.0.44`](https://github.com/ratspeak/Ratspeak/releases/tag/v1.0.44) | Settings | | [`rnsd`](https://reticulum.network/manual/using.html#the-rnsd-utility) | General connectivity | [`1.6.0`](https://github.com/markqvist/Reticulum/releases/tag/1.6.0) | `rnsd --version` | | [`rrcd`](https://github.com/kc1awv/rrcd) | Group chat server | [`f6d7e9d`](https://github.com/kc1awv/rrcd/commit/f6d7e9d72bf83c70d7a9373ae8c5edaa052a7bf2) | Not available | # Services ## Relay Chat [Reticulum Relay chat](https://rrc.kc1awv.net) is a live chat system built on top of Reticulum. More information is available on [their documentation](https://rrc.kc1awv.net). Unfortunately, there is currently not support for typical group chat functionality in the [Columba](https://columba.network) client. However, for the hacker-inclined amongst us, we can still do group chats in [Nomadnet](https://github.com/markqvist/nomadnet). This page documents how to run an instance of [`rrcd`](https://github.com/kc1awv/rrcd) alongside an existing `rnsd` installation. We need to install `rrcd` [from source](https://github.com/kc1awv/rrcd) because it is not published on the PyPi package repository. There are also no published tags. We need to first create a system-wide configuration directory. ```bash mkdir /etc/rrcd chown reticulum:reticulum /etc/rrcd ``` Then we can install `rrcd` from source. ```bash cd /etc/rrcd git clone https://github.com/kc1awv/rrcd pipx install --global ./rrcd ``` We need to run `rrcd` directly to initialise the configuration while specifying the correct configuration directory. ```bash RRCD_HOME=/etc/rrcd sudo -su reticulum rrcd ``` We need to ensure the correct configuration directory is configured in the `/etc/rrcd/rrcd.toml`. ```toml [hub] configdir = "/etc/reticulum" identity_path = '/etc/rrcd/hub_identity' room_registry_path = '/etc/rrcd/rooms.toml' # ... cut for brevity ... ``` Then we can test if you `rrcd` will run correctly. ```bash sudo -su reticulum rrcd \ --configdir /etc/reticulum \ --config /etc/rrcd/rrcd.toml \ --identity /etc/rrcd/hub_identity \ --room-registry /etc/rrcd/rooms.toml ``` Feel free to configure your own default rooms in the `rooms.toml`. If all goes well, we can transfer this into a Systemd service file. ```bash $EDITOR /etc/systemd/system/rrcd.service ``` ```conf [Unit] Description=Reticulum Relay Chat After=default.target [Service] User=reticulum Type=simple Restart=always RestartSec=3 ExecStart=/usr/local/bin/rrcd --configdir /etc/reticulum --config /etc/rrcd/rrcd.toml --identity /etc/rrcd/hub_identity --room-registry /etc/rrcd/rooms.toml [Install] WantedBy=default.target ``` Then enable the service and ensure it's up and running. ```bash systemctl daemon-reload systemctl enable --now rrcd systemctl status rrcd journalctl -fu rrcd ``` You can read the logs to find out the hash destination of the hub which can be configured in Nomadnet. It's also possible to use `rnid` to view the hub identity. ```bash rnid -i /etc/rrcd/hub_identity -p ``` # TCP ## Backbone When installing [TCP backbones](https://markqvist.github.io/Reticulum/manual/interfaces.html#backbone-interface), we are typically dealing with an installation procedure on an old laptop or home desktop server. Any Linux system will do. Backbones should generally provide reliable uptime so that our "over the internet" fallback provides stable connectivity. We run both `rnsd` with transport, probe and gateway mode enabled. We run `lxmd` alongside `rnsd` to support [propagation](https://reticulum.network/manual/software.html#lxmf) (which supports "store and forward" offline messaging). See the [propagation node](/almanac#pnode) documentation for more. Install `rnsd` globally with `pipx`. ```bash pipx install rns --global ``` Create a system configuration location. ```bash mkdir /etc/reticulum chown reticulum:reticulum /etc/reticulum ``` We create a TCP backbone, running [gateway mode](https://reticulum.network/manual/interfaces.html#interfaces-modes) with [transport](https://reticulum.network/manual/networks.html#transport-nodes-and-instances) and [probing](https://reticulum.network/manual/using.html#the-rnprobe-utility) enabled. We use `24242` as our standard port. Add the following contents to `/etc/reticulum/config`. ```toml [reticulum] enable_transport = yes share_instance = yes instance_name = default respond_to_probes = yes static_transport_identity = yes [logging] loglevel = 4 [interfaces] [[YourBackboneNameHere]] type = BackboneInterface enabled = yes listen_on = 0.0.0.0 port = 24242 ``` Then we configure a Systemd service file to run the `rnsd` process. ```bash $EDITOR /etc/systemd/system/rnsd.service ``` ```conf [Unit] Description=Reticulum Network Stack Daemon After=default.target [Service] User=reticulum Type=simple Restart=always RestartSec=3 ExecStart=/usr/local/bin/rnsd --service [Install] WantedBy=default.target ``` Then enable the service and ensure it's up and running. ```bash systemctl daemon-reload systemctl enable --now rnsd systemctl status rnsd tail -f /etc/reticulum/logfile ``` ## PNode PNodes (propagation nodes) are vital for supporting delay tolerant communication. They allow peers to send messages to each other when the other is offline. This is done in a "store and forward" manner. Propagation nodes usually need to be configured manually in the users client. PNodes typically enforce limits on what kind of load they can carry due to constraints of their specific medium, e.g. the size of the messages over a LoRa connection. Install `lxmf` globally with `pipx`. ```bash pipx install rns --global ``` We need to "inject" this Python package into the `rnsd` virtual environment so the packages can interoperate. ```bash pipx inject rns lxmf --global ``` Create a system configuration location. ```bash mkdir /etc/lxmd chown reticulum:reticulum /etc/lxmd ``` And add the following contents to `/etc/lxmd/config`. ```toml [propagation] enable_node = yes node_name = "Your Propagation Node Name Here>" announce_at_start = yes autopeer = yes autopeer_maxdepth = 6 auth_required = no [lxmf] announce_at_start = no delivery_transfer_max_accepted_size = 1 propagation_message_max_accepted_size = 50000 # 5MB [logging] loglevel = 4 ``` Then we configure a Systemd service file to run the `lxmd` process. ```bash $EDITOR /etc/systemd/system/lxmd.service ``` ```conf [Unit] Description=Reticulum LXMF Daemon (lxmd) After=default.target [Service] User=reticulum Type=simple Restart=always RestartSec=3 ExecStart=/usr/local/bin/lxmd --service --propagation-node [Install] WantedBy=default.target ``` Then enable the service and ensure it's up and running. ```bash systemctl daemon-reload systemctl enable --now lxmd systemctl status lxmd tail -f /etc/lxmd/logfile ``` # LoRa ## Presets These are the LoRa settings we use. * Frequency (MHz): 867.200 (867200000) * Bandwidth: 125 kHz (125000) * Spreading Factor: SF8 * Coding Rate: 4/5 * TX Power (dBm): 28 See the [Reticulum primer](/pdf/primer.pdf) for more details on this configuration. ## Serial ports In order to interact with our LoRa device, we need to connect it to our laptop. This involves a process of the device registering itself but this registration can change over time. We need to configure our system to stabilise this registration. This is done by assigning a fixed filesystem path for the serial port based the unique identifier of the LoRa device. We need to give our own system user permissions to pole the serial ports (the interface which you use to communicate from your laptop to the LoRa device). ```bash sudo usermod -aG dialout $USER sudo reboot ``` We need to see the LoRa device when it connects to identify it. ```bash sudo dmesg -w ``` Plug the LoRa device in and out with your USB cable. You should see a `ttyXXXX` value in the logs. This gives you the `/dev/ttyXXXX` path. This value can change when the device is plugged in, so we prefer to map a stable path based on the devices serial number (which is unique). ```bash udevadm info -a -n /dev/ttyXXXX | grep ATTRS{serial} sudo $EDITOR /etc/udev/rules.d/99-rnodes.rules ``` And then put the following in `/etc/udev/rules.d/99-rnodes.rules`. ```bash SUBSYSTEM=="tty", ATTRS{serial}=="", SYMLINK+="rnode_XXXX" ``` Then reload `udev` and confirm the stable path is configured. ```bash sudo udevadm control --reload-rules sudo udevadm trigger rnodeconf --info /dev/rnode_XXXX ``` ## RNode Running a LoRa-based [RNode](https://reticulum.network/manual/hardware.html#rnode) requires connecting a Heltec v4 device (see below) via USB-C cable to a server, laptop. Unlike the [transport node](/almanac#rtnode), it is not assumed that this node will be reliably available. RNodes usually require a [propagation node](//almanac#pnode) for delay tolerant communication. ### Requirements We are using [WiFi LoRa 32 v4](https://heltec.org/project/wifi-lora-32-v4/). We are using the standard [`RNode_Firmware`](https://github.com/markqvist/RNode_Firmware). See the [serial ports](/almanac#serial-ports) documentation for how to connect your device in a stable way. ### Serial flasher It can be installed using `rnodeconf`. ``` rnodeconf --autoinstall ``` If you want to enable transport mode for your RNode, see the specific [transport node docs](//almanac#rtnode). ### Configuration Using [our presets](//almanac#presets). ```toml [[MyRnodeName]] name = MyRnodeName type = RNodeInterface enabled = true port = /dev/rnode_XXXX frequency = 867200000 bandwidth = 125000 spreadingfactor = 8 codingrate = 5 txpower = 22 ``` ## RTNode Running a LoRa-based RTNode (RNode with [transport mode](https://reticulum.network/manual/networks.html#transport-nodes-and-instances) enabled) requires connecting a Heltec v4 device (see below) via USB-C cable to a server, laptop or Raspberry Pi. Similarly to the [TCP backbone](//almanac#backbone), it is assumed that the device and server will maintain reliable uptime for general connectivity. ### Requirements We are using [WiFi LoRa 32 v4](https://heltec.org/project/wifi-lora-32-v4/). We use the [RTNode Firmware](https://jrl290.github.io/RTNode-HeltecV4/) web flasher. See the [serial ports](/almanac#serial-ports) documentation for how to connect your device in a stable way. ### Web flasher * Go to the [web flasher](https://jrl290.github.io/RTNode-HeltecV4). * Click `Detect` and select your LoRa device. * Choose the `Full Install` option with a version which matches our [dependency table](/almanac#dependencies). * Flash the firmware. ### Configuration Once the LoRa device is flashed, it will expose a WiFI access point which you can connect. It should be called something like `RTNode-Setup`. Then visit [`http://10.0.0.1`](http://10.0.0.1) in your browser and configure the transport node. It is also possible to force the device into this mode later by holding the on/off button. * Set the `Node Name` * Enable the `WiFi Network`. Please note, this should be the `SSID` and `Password` of your local WiFi access point. This allows the LoRa device to connect to the internet and provide a bridge over LoRa and TCP. * Configure a `TCP backbone` from [our list of backbones](//almanac#backbone). * Enable the `Local TCP Server`. * Enable `Bluetooth`. * Enable `Diagnostics (rnprobe)`. * Configure the `LoRa Radio` settings to match [our presets](//almanac#presets). * Enable Discovery if you want your node to show up on [`rmap.world`](https://rmap.world). ## Debugging ### Streaming the serial port To see specifically what the LoRa device is doing, connect it to your laptop and stream the serial port into your local terminal. ```bash sudo apt install -y tio tio -b 9600 /dev/rnode_XXX ``` ### Sniffing packets ```bash pipx install loramon ``` Using [our presets](//almanac#presets), you can pole the device with `loramon` in your local terminal. ```bash loramon /dev/rnode_XXXX \ --freq 867200000 \ --bw 125000 \ --sf 8 \ --cr 5 \ -C -W loramon-capture ``` ### Signal strength It is possible to run `rnprobe` using `rnprobe` directly on the command-line or with newer verions of `nomadnet`. We can then receive and view the [`RSSI` & `SNR` values](https://www.thethingsnetwork.org/docs/lorawan/rssi-and-snr/) in the probe success responses. We must run each RNode as a transport node which enables probing. The probe address is outputted when running `rnsd` directly or in the command-line before `nomadnet` opens. We usually need to close & re-open `nomadnet`. **NOTE**: make sure you also set `static_transport_identity = yes` so the value doesn't change again while you're testing. ## Resources * [Antenna Tutorial incl. cheap DIY Antenna Tester (LoRa, ESP32)](https://www.youtube.com/watch?v=J3PBL9oLPX8) * [Line of sight calculator](https://www.altimetercloud.com/tools/line_of_sight/?s=1001I) # Maintenance ## Upgrading a Python package Assuming [a similar setup](/almanac#python), all packages can be manipulated with `pipx`. ``` pipx upgrade --global ``` We assume `--global` since we typically install Python packages for the entire system. ## Upgrading all packages ``` pipx upgrade-all --global ``` ## Rotating log files We need to clean up the `rnsd` and other service log files or they will grow infinitely. `logrotate` is useful for this. ```conf /etc/reticulum/logfile { weekly missingok rotate 14 compress notifempty } /etc/lxmd/logfile { weekly missingok rotate 14 compress notifempty } ``` Ensure the service restarts successfully. ```bash sudo systemctl restart logrotate sudo systemctl status logrotate ``` # Using `rngit` It is important to run `rngit` on the command-line before running any `git clone` commands. It is advised to configure a connection to the distributed network before attempting to clone repositories. Otherwise, probably no connection can be established to the desired remote destination hash. ## Retrieving a copy of Reticulum The reference implementation of Reticulum is published on Aleph Git (a `rngit` instance) at the following destination hash: `a8d24177d946de4f1f0a0fe1af9a1338`. It can be cloned by following the tips above. In one terminal, run `rngit` with verbosity on. ```bash rngit -vvvv ``` And in another terminal, git clone the Reticulum repository. ```bash git clone rns://7649a50d84610232d1416b41d2896aff/reticulum/reticulum ``` ## Install the latest release of Reticulum You can retrieve the latest release wheel and verify it with the following commands. ``` rngit release rns://7649a50d84610232d1416b41d2896aff/reticulum/reticulum fetch "latest:rns-*.whl" rngit release rns_X.X.X.rsm verify ``` You can use `pipx` to directly install this file.