Getting Started with Reticulum: From Mac to Raspberry Pi

A beginner-friendly walkthrough for setting up your first Reticulum mesh node — including common issues and exactly how to fix them.

What is Reticulum?

Reticulum is an open-source, decentralised networking stack that treats LoRa, WiFi, Ethernet, and serial connections as interchangeable interfaces. It encrypts everything by default, has no central servers, and routes messages automatically across whatever hardware is available. Think of it as a mesh network you fully own and control.

This guide covers two stages:

1. Flashing an RNode on your Mac — turning a LilyGo LoRa32 into a Reticulum radio interface

2. Setting up a Raspberry Pi relay — an always-on home node running Reticulum and MeshChat

What You'll Need

• LilyGo LoRa32 v2.1 (868/915 MHz) — your RNode hardware

• Mac running macOS (this guide was written on Sequoia 15.x)

• Raspberry Pi 3 B+ or newer with a 16GB+ microSD card

• A known-good USB-C data cable — not a charge-only cable (this is the most common silent failure)

• Chrome browser — required for the web flasher

Part 1: Flashing the RNode on Your Mac

Step 1 — Install the CP210x USB Driver

The LilyGo uses a Silicon Labs CP210x chip for USB communication. macOS doesn't include this driver by default.

Go to: silabs.com/developers/usb-to-uart-bridge-vcp-drivers

Download and install the Mac driver, then restart your Mac.

macOS Sequoia extra step: After installing, go to: System Settings → General → Login Items & Extensions → Driver Extensions

Make sure the Silicon Labs driver is toggled on. Without this step the driver installs but doesn't activate.

Step 2 — Verify Your Mac Can See the Board

Plug the LilyGo in via USB, open Terminal and run:

You should see something like /dev/tty.usbserial-XXXXXXXX in the list. If you don't see it:

• Try a different cable — charge-only cables are the most common cause. The OLED screen will light up (it gets power) but the board won't appear in the device list

• Check System Report → USB to see if the device appears at all when plugged in

• If it shows as an unknown device, the driver isn't loading — revisit Step 1

Step 3 — Flash the RNode Firmware

Open Chrome and go to: liamcottle.github.io/rnode-flasher

Select:

• Product: LilyGO LoRa32 v2.1

• Model: 868/915/923 MHz

Click Download Firmware to download rnode_firmware_lora32v21.zip, then click Choose File and select the zip.

Click Flash Now and select your serial port when prompted.

If you get a timeout error, the board needs to be put into download mode. If your BOOT button is intact, hold it while clicking Flash Now. If not, you can use rnodeconf from the command line instead (see below).

Step 4 — Flash via Command Line (if web flasher times out)

Install Reticulum tools:

Then run the auto-installer with a lower baud rate (required on some boards):

Follow the prompts — select 868/915/923 MHz when asked about frequency band. The installer will download and flash the firmware automatically.

When complete, the OLED should show RNode status information.

Part 2: Running MeshChat on Your Mac

MeshChat is a web-based Reticulum messaging client. It runs as a local server and opens in your browser.

Step 1 — Install Dependencies

Step 2 — Clone and Build MeshChat

If the build fails with a cx_Freeze error, you can bypass it by running directly from source — the build step is only needed for creating a standalone app, not for running it directly.

Step 3 — Run MeshChat

Open http://127.0.0.1:8000 in Chrome. You should see the MeshChat interface with the Network Visualiser showing other Reticulum nodes on the internet backbone.

Part 3: Setting Up the Raspberry Pi Relay

The Pi acts as an always-on Reticulum transport node — bridging your local LoRa network to the internet and relaying messages when you're not home.

Step 1 — Flash the SD Card

Download Raspberry Pi Imager from raspberrypi.com/software.

Select:

• Device: your Pi model

• OS: Raspberry Pi OS Lite (64-bit) — the 64-bit version is required to avoid Python dependency issues

• Storage: your SD card

Before writing, go through the customisation settings and set:

• A hostname (used to connect via SSH)

• A username and password

• Your WiFi network name and password

• Enable SSH under Remote Access

• Country code under Localisation — important for WiFi to work correctly

Write the image and insert the card into your Pi.

Step 2 — Connect to the Pi

After booting (allow 2 minutes on first boot), SSH in from your Mac:

If you get a host key warning, run:

Then try SSH again.

If the Pi doesn't appear on your network, check your router's connected devices list. Common causes: wrong WiFi password, wrong network name (case sensitive), or the country code wasn't set (prevents WiFi from working on first boot).

Step 3 — Update the Pi

Step 4 — Install Reticulum

Step 5 — Generate the Reticulum Config

Start rnsd once to create the default config file:

Wait a few seconds, then stop it:

Step 6 — Configure Reticulum

Edit the config:

Make these two changes:

Enable transport (allows the Pi to relay messages for other nodes):

Add your RNode interface in the [interfaces] section. The LilyGo will appear as /dev/ttyACM0 when plugged into the Pi:

  [[My RNode]

Save with Ctrl+X, Y, Enter.

Important: Only add one RNode interface per port. If you configure the RNode in MeshChat AND in the Reticulum config file, they'll conflict and both will fail.

Step 7 — Add Your User to the dialout Group

Linux restricts serial port access by default. Add your user to the dialout group so Reticulum can talk to the RNode:

Log out and back in for this to take effect. Verify it worked:

You should see dialout in the list.

Step 8 — Set Up rnsd as a System Service

Paste:

[Unit]
Description=Reticulum Network Stack Daemon
After=network.target

[Service]
Type=simple
User=yourusername
ExecStart=/usr/bin/python3 -m RNS.Utilities.rnsd
Restart=always
RestartSec=5

[Install]

Enable and start it:

You should see Active: active (running).

Step 9 — Install MeshChat on the Pi

The Pi 3 B+ only has 1GB RAM which can cause crashes during npm builds. Add swap first:

Add or change to:

Then:

Clone MeshChat and install dependencies:

If npm isn't available, install Node.js via NodeSource:

Build the frontend:

Alternative if the build keeps crashing — build on your Mac and copy the result to the Pi:

Step 10 — Fix a Known MeshChat Bug

There's a bug in MeshChat that causes an AttributeError when an interface has a null network_id. Fix it:

sed -i 's/interface_stats\["network_id"\] = interface_stats\["network_id"\]\.hex()/interface_stats["network_id"] = interface_stats["network_id"].hex() if interface_stats["network_id"]

Verify the fix:

You should see else None at the end of the line.

Step 11 — Set Up MeshChat as a Service

Paste:

[Unit]
Description=Reticulum MeshChat
After=rnsd.service

[Service]
Type=simple
User=yourusername
WorkingDirectory=/home/yourusername/reticulum-meshchat
ExecStart=/usr/bin/python3 meshchat.py --host 0.0.0.0
Restart=always
RestartSec=5

[Install]

Enable and start:

Step 12 — Access MeshChat from Your Network

Open a browser on any device on your home network and go to:

Verifying Everything Works

Run this on the Pi to check interface status:

A healthy setup looks like:

RNodeInterface[My RNode]

Key things to check:

• Status: Up — RNode is connected and responding

• Noise Floor around -120 dBm — clean signal, antenna is working

• Battery percentage showing — LilyGo battery is detected

Common Issues

RNode shows Disconnected in MeshChat Check that you haven't configured the RNode in both MeshChat's interface list AND in the Reticulum config file. Only configure it in one place — the config file is recommended.

Permission denied on serial port Your user isn't in the dialout group. Run sudo usermod -a -G dialout yourusername and log out/in.

dpkg interrupted errors Run sudo dpkg --configure -a to clear the interrupted state before running any apt commands.

MeshChat won't load from other devices Make sure you're running with --host 0.0.0.0 flag. Without it, MeshChat only listens on localhost.

Mac can't see the LilyGo Almost always a charge-only USB cable. Check System Report → USB — if the device doesn't appear at all when plugged in, swap the cable.

Next Steps

Once your Pi relay is running, you can extend your network by:

• Adding a second RNode (Heltec LoRa32 v3 recommended) paired to an Android phone running Sideband for portable use

• Connecting to the global Reticulum testnet via a TCP interface

• Installing Sideband on iOS via TestFlight for basic messaging over WiFi

The Reticulum manual (available at reticulum.network) covers all interface types and advanced configuration options.