Conventions

Python

We use pipx 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.

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.

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.

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 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 Debugging LoRa 0.9.7 loramon --version
RNode_Firmware RNode firmware 1.86 rnodeconf --info /dev/rnode_XXXX
RTNode-HeltecV4 (web flasher) RTNode firmware v1.0.51 rnodeconf --info /dev/rnode_XXXX
F-Droid Android app distribution 1.23.2 Settings > About F-Droid
Hugo This website v0.167.0+extended+withdeploy hugo version
lxmd Propagation node 1.3.0 lxmd --version
Obtainium Android app distribution v1.6.17 Not available
pipx Python package installer 1.17.10 pipx --version
Ratspeak (Android) Android client v1.0.44 Settings
Ratspeak (iOS client) iOS client Public Beta Settings
Ratspeak (Linux) Linux client v1.0.44 Settings
Ratspeak (MacOS) MacOS client v1.0.44 Settings
rnsd General connectivity 1.6.0 rnsd --version
rrcd Group chat server f6d7e9d Not available

Services

Relay Chat

Reticulum Relay chat is a live chat system built on top of Reticulum. More information is available on their documentation. Unfortunately, there is currently not support for typical group chat functionality in the Columba client. However, for the hacker-inclined amongst us, we can still do group chats in Nomadnet. This page documents how to run an instance of rrcd alongside an existing rnsd installation.

We need to install rrcd from source 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.

mkdir /etc/rrcd
chown reticulum:reticulum /etc/rrcd

Then we can install rrcd from source.

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.

RRCD_HOME=/etc/rrcd sudo -su reticulum rrcd

We need to ensure the correct configuration directory is configured in the /etc/rrcd/rrcd.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.

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.

$EDITOR /etc/systemd/system/rrcd.service
[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.

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.

rnid -i /etc/rrcd/hub_identity -p

TCP

Backbone

When installing TCP backbones, 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 (which supports “store and forward” offline messaging). See the propagation node documentation for more.

Install rnsd globally with pipx.

pipx install rns --global

Create a system configuration location.

mkdir /etc/reticulum
chown reticulum:reticulum /etc/reticulum

We create a TCP backbone, running gateway mode with transport and probing enabled. We use 24242 as our standard port. Add the following contents to /etc/reticulum/config.

[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.

$EDITOR /etc/systemd/system/rnsd.service
[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.

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.

pipx install rns --global

We need to “inject” this Python package into the rnsd virtual environment so the packages can interoperate.

pipx inject rns lxmf --global

Create a system configuration location.

mkdir /etc/lxmd
chown reticulum:reticulum /etc/lxmd

And add the following contents to /etc/lxmd/config.

[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.

$EDITOR /etc/systemd/system/lxmd.service
[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.

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 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).

sudo usermod -aG dialout $USER
sudo reboot

We need to see the LoRa device when it connects to identify it.

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).

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.

SUBSYSTEM=="tty", ATTRS{serial}=="<SERIALNUMBER>", SYMLINK+="rnode_XXXX"

Then reload udev and confirm the stable path is configured.

sudo udevadm control --reload-rules
sudo udevadm trigger
rnodeconf --info /dev/rnode_XXXX

RNode

Running a LoRa-based RNode requires connecting a Heltec v4 device (see below) via USB-C cable to a server, laptop. Unlike the transport node, it is not assumed that this node will be reliably available. RNodes usually require a propagation node for delay tolerant communication.

Requirements

We are using WiFi LoRa 32 v4. We are using the standard RNode_Firmware. See the 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.

Configuration

Using our presets.

[[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 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, it is assumed that the device and server will maintain reliable uptime for general connectivity.

Requirements

We are using WiFi LoRa 32 v4. We use the RTNode Firmware web flasher. See the serial ports documentation for how to connect your device in a stable way.

Web flasher

  • Go to the web flasher.
  • Click Detect and select your LoRa device.
  • Choose the Full Install option with a version which matches our dependency table.
  • 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 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.
  • Enable the Local TCP Server.
  • Enable Bluetooth.
  • Enable Diagnostics (rnprobe).
  • Configure the LoRa Radio settings to match our presets.
  • Enable Discovery if you want your node to show up on 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.

sudo apt install -y tio
tio -b 9600 /dev/rnode_XXX

Sniffing packets

pipx install loramon

Using our presets, you can pole the device with loramon in your local terminal.

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 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

Maintenance

Upgrading a Python package

Assuming a similar setup, all packages can be manipulated with pipx.

pipx upgrade --global <package-name>

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.

/etc/reticulum/logfile {
    weekly
    missingok
    rotate 14
    compress
    notifempty
}

/etc/lxmd/logfile {
    weekly
    missingok
    rotate 14
    compress
    notifempty
}

Ensure the service restarts successfully.

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.

rngit -vvvv

And in another terminal, git clone the Reticulum repository.

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.