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 --globalPython 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 reticulumThe 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 -iNaming
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/rrcdThen we can install rrcd from source.
cd /etc/rrcd
git clone https://github.com/kc1awv/rrcd
pipx install --global ./rrcdWe need to run rrcd directly to initialise the configuration while specifying the correct configuration directory.
RRCD_HOME=/etc/rrcd sudo -su reticulum rrcdWe 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.tomlFeel 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.targetThen enable the service and ensure it’s up and running.
systemctl daemon-reload
systemctl enable --now rrcd
systemctl status rrcd
journalctl -fu rrcdYou 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 -pTCP
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 --globalCreate a system configuration location.
mkdir /etc/reticulum
chown reticulum:reticulum /etc/reticulumWe 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 = 24242Then 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.targetThen enable the service and ensure it’s up and running.
systemctl daemon-reload
systemctl enable --now rnsd
systemctl status rnsd
tail -f /etc/reticulum/logfilePNode
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 --globalWe need to “inject” this Python package into the rnsd virtual environment so the packages can interoperate.
pipx inject rns lxmf --globalCreate a system configuration location.
mkdir /etc/lxmd
chown reticulum:reticulum /etc/lxmdAnd 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 = 4Then 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.targetThen enable the service and ensure it’s up and running.
systemctl daemon-reload
systemctl enable --now lxmd
systemctl status lxmd
tail -f /etc/lxmd/logfileLoRa
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 rebootWe need to see the LoRa device when it connects to identify it.
sudo dmesg -wPlug 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.rulesAnd 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_XXXXRNode
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 --autoinstallIf 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 = 22RTNode
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
Detectand select your LoRa device. - Choose the
Full Installoption 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 theSSIDandPasswordof 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 backbonefrom our list of backbones. - Enable the
Local TCP Server. - Enable
Bluetooth. - Enable
Diagnostics (rnprobe). - Configure the
LoRa Radiosettings 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_XXXSniffing packets
pipx install loramonUsing 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-captureSignal 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 --globalRotating 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 logrotateUsing 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 -vvvvAnd in another terminal, git clone the Reticulum repository.
git clone rns://7649a50d84610232d1416b41d2896aff/reticulum/reticulumInstall 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 verifyYou can use pipx to directly install this file.