# rMesh Gateway Setup Guide

Dual-stack mesh networking: **MeshCore** for LoRa mesh, **Reticulum** for Internet backbone.

This guide covers:
- Setting up a MeshCore Companion node as your primary LoRa gateway (Part 1-3)
- Optionally adding an RNode for Reticulum Internet bridging (Part 4-5)
- Radio parameters and network architecture (Part 6-7)

---

## Architecture

```
[MeshCore Nodes] <--868MHz--> [Companion WiFi] <--TCP:5000--> [rmesh-reticulum] <--TCP:4242--> [Reticulum Internet backbone]
```

MeshCore handles the LoRa mesh (structured routing, 64 hops, efficient spectrum use).
Reticulum bridges separate LoRa islands over the Internet.

---

## Part 0: MeshCore Companion WiFi Setup (Primary Gateway)

This is the recommended primary gateway. A MeshCore Companion node with WiFi
firmware creates a TCP server that rMesh connects to directly.

### Flash MeshCore Companion WiFi firmware

1. Open **https://meshcore.io/flasher** in Chrome.
2. Connect a Heltec V3 or T-Beam via USB.
3. Select your device, then **Companion** firmware.
4. Enable WiFi in the configuration (set your SSID + password).
5. Flash. The device creates a TCP server on port 5000.

### Find the device IP

After flashing, the device connects to your WiFi. Find its IP via your router's
DHCP client list, or use:
```bash
# If mDNS is available
ping meshcore.local
```

### Enable in rMesh

Edit `/opt/apps/rmesh-reticulum/.env`:
```
MESHCORE_ENABLED=true
MESHCORE_HOST=192.168.1.xxx    # Your companion's IP
MESHCORE_PORT=5000
```

Restart:
```bash
cd /opt/apps/rmesh-reticulum
docker compose up -d
```

Check logs:
```bash
docker logs rmesh-reticulum --tail 20
```

You should see: `MeshCore bridge ready — device: YourNodeName`

### Alternative: USB Serial

If the companion is plugged directly into the server:
```
MESHCORE_ENABLED=true
MESHCORE_SERIAL=/dev/ttyUSB0
```
And add to docker-compose.yml:
```yaml
devices:
  - /dev/ttyUSB0:/dev/ttyUSB0
```

---

## Part 0.5: MeshCore Repeaters and Room Servers

### Flash a Repeater (autonomous relay)

1. Same web flasher, select **Repeater** instead of Companion.
2. Repeaters are autonomous — no phone or server connection needed.
3. They learn routes and relay traffic between companions.
4. Deploy on rooftops/high points with the solar kit from the BOM.

### Flash a Room Server (BBS)

1. Web flasher, select **Room Server**.
2. Room Servers store posts/messages for the community.
3. Users connect to Room Servers through the mesh via their Companion.

---

## Part 1: RNode for Reticulum Internet Backbone (Optional)

If you want to bridge separate MeshCore mesh islands over the Internet,
add an RNode running Reticulum as a second radio interface.

> **Note:** RNode and MeshCore are different protocols on different radios.
> They don't interfere — use separate Heltec V3 boards for each.

## Overview (RNode section)

```
[LoRa mesh nodes] <--868 MHz--> [RNode (Heltec V3)] <--USB--> [Server] <--Docker--> [rmesh-reticulum]
```

The RNode acts as a radio modem. It converts LoRa radio traffic into serial data
that Reticulum can process. Reticulum running inside the `rmesh-reticulum` container
bridges the radio network with the TCP/IP network.

---

## Part 1: Flash RNode Firmware onto Heltec V3

### Prerequisites

On any Linux/macOS machine with USB:

```bash
# Install Reticulum (includes rnodeconf tool)
pip install rns --upgrade

# Linux only: add your user to the serial port group
sudo usermod -a -G dialout $USER
# Log out and back in for this to take effect
```

The Heltec V3 uses a CH9102 USB chip. Modern Linux kernels include the driver
(`ch341` module). No extra drivers needed on Linux. On macOS/Windows, install the
CH340/CH9102 driver from the manufacturer.

### Flash the firmware

1. Connect the Heltec V3 via USB-C (use a **data** cable, not charge-only).

2. Run the autoinstaller:
   ```bash
   rnodeconf --autoinstall
   ```

3. When prompted:
   - Device type: **Heltec LoRa32 v3**
   - Frequency band: **868/915/923 MHz** (the SX1262 variant)

4. The tool downloads and flashes the firmware. Takes about 1-2 minutes.

### Alternative: Browser-based flasher

Open **https://liamcottle.github.io/rnode-flasher/** in Chrome/Edge.
Select Heltec LoRa32 V3, 868 MHz. Click flash. Uses WebSerial API.

### Verify the flash

```bash
rnodeconf -i /dev/ttyUSB0
```

You should see: firmware version, device signature, hardware platform, and
frequency range. The status LED will flash every ~2 seconds when idle.

> **Tip:** Find the stable device path for later use:
> ```bash
> ls -la /dev/serial/by-id/
> ```
> Use this path instead of `/dev/ttyUSB0` to avoid port renumbering.

---

## Part 2: Connect RNode to the Server

### Option A: Direct USB to server (simplest)

If the Heltec V3 is plugged directly into the Netcup server (or a USB-over-IP
adapter), the device appears as `/dev/ttyUSB0` or `/dev/ttyACM0` on the host.

### Option B: Via Raspberry Pi bridge (remote location)

If the RNode is at a different location from the server:

1. Plug RNode into a Raspberry Pi via USB.
2. Install Reticulum on the Pi: `pip install rns`
3. Configure the Pi's Reticulum with:
   - An `RNodeInterface` for the radio
   - A `TCPClientInterface` pointing to your server's IP on port 4242
4. The Pi bridges radio traffic to the server over the internet.

Pi config (`~/.reticulum/config`):
```ini
[reticulum]
  enable_transport = True

[interfaces]
  [[RNode LoRa]]
    type = RNodeInterface
    enabled = yes
    port = /dev/ttyUSB0
    frequency = 867200000
    bandwidth = 125000
    txpower = 7
    spreadingfactor = 8
    codingrate = 5

  [[TCP to Server]]
    type = TCPClientInterface
    enabled = yes
    target_host = YOUR_SERVER_IP
    target_port = 4242
```

### Option C: RNode over WiFi/Bluetooth

RNode supports network connections. After flashing, configure the RNode's WiFi:
```bash
rnodeconf /dev/ttyUSB0 --wifi-ssid "YourNetwork" --wifi-pass "YourPassword"
```

Then in Reticulum config, use TCP instead of serial:
```ini
[[RNode LoRa]]
  type = RNodeInterface
  enabled = yes
  port = tcp://rnode-ip-address:0
```

---

## Part 3: Enable RNode in rmesh-reticulum Container

### Step 1: Pass the USB device into Docker

Edit `/opt/apps/rmesh-reticulum/docker-compose.yml`:

```yaml
services:
  rmesh-reticulum:
    # ... existing config ...
    devices:
      - /dev/ttyUSB0:/dev/ttyUSB0
    # You may also need:
    # privileged: true
    # Or more targeted:
    # cap_add:
    #   - SYS_RAWIO
```

> Use the stable path from `/dev/serial/by-id/` instead of `/dev/ttyUSB0` to
> avoid issues if multiple USB devices are connected.

### Step 2: Update the Reticulum config

Edit `/opt/apps/rmesh-reticulum/config/reticulum.conf` — uncomment and configure
the RNode interface:

```ini
[interfaces]
  [[Default Interface]]
    type = TCPServerInterface
    interface_enabled = True
    listen_ip = 0.0.0.0
    listen_port = 4242

  [[RNode LoRa]]
    type = RNodeInterface
    interface_enabled = True
    port = /dev/ttyUSB0
    frequency = 867200000
    bandwidth = 125000
    txpower = 7
    spreadingfactor = 8
    codingrate = 5
```

### Step 3: Rebuild and restart

```bash
cd /opt/apps/rmesh-reticulum

# If this is first time changing the config after initial deploy,
# clear the persisted config so entrypoint.sh copies the new one:
docker compose down
docker volume rm rmesh-reticulum_reticulum_data  # WARNING: resets identity
# Or exec into container and update config in-place:
docker exec rmesh-reticulum cp /app/config/reticulum.conf /data/reticulum/config

docker compose up -d
```

### Step 4: Verify

```bash
docker logs rmesh-reticulum --tail 20
```

You should see the RNode interface initializing alongside the TCP interface.
Check the bridge API:

```bash
curl -H "X-Bridge-API-Key: YOUR_KEY" http://localhost:8000/api/status
```

The `path_count` should increase as radio nodes announce themselves.

---

## Part 4: Radio Parameters

### Recommended EU settings (868 MHz)

| Parameter | Value | Notes |
|-----------|-------|-------|
| frequency | 867200000 | 867.2 MHz (EU general) |
| bandwidth | 125000 | 125 kHz — good range/speed balance |
| txpower | 7 | 7 dBm (~5 mW). Safe for EU with any antenna |
| spreadingfactor | 8 | SF8 — balanced range and throughput |
| codingrate | 5 | 4/5 — lowest overhead, fine for low-noise |

### Tuning for range vs speed

| Goal | SF | BW | Bitrate | Range |
|------|----|----|---------|-------|
| Maximum speed | 7 | 250000 | ~11 kbps | Shorter |
| Balanced | 8 | 125000 | ~3.1 kbps | Medium |
| Maximum range | 12 | 125000 | ~0.29 kbps | Longest |

> **All nodes on the same network must use identical radio parameters.**
> Different SF/BW/frequency = invisible to each other.

### EU duty cycle

The 868 MHz band has a **1% duty cycle** limit on most sub-bands (ETSI EN 300.220).
Reticulum handles this automatically. With SF8/125kHz, a typical message takes
~100ms on air, allowing ~36 messages per hour within duty cycle.

The sub-band 869.4-869.65 MHz allows **10% duty cycle** and **500 mW ERP** — useful
for higher-traffic gateways. Set `frequency = 869525000` to use it.

---

## Part 5: Flash MeshCore on a Second Device

For a companion device that pairs with your phone:

### Web flasher (easiest)

1. Open **https://meshcore.io/flasher** in Chrome.
2. Connect a second Heltec V3 via USB.
3. Select: **Heltec V3** → **Companion**.
4. Click flash. Done in under a minute.

### Companion apps

After flashing MeshCore Companion firmware, pair with:
- **MeshCore app** (by Liam Cottle) — Android/iOS/Web
- **Web app**: https://app.meshcore.nz

### MeshCore Repeater

To flash a dedicated relay node (e.g., the T-Beam for outdoor solar deployment):
1. Same web flasher, select **Repeater** instead of Companion.
2. Repeaters are autonomous — no phone pairing needed.
3. They learn routes and relay traffic between companions.

---

## Part 6: Network Architecture

Once you have hardware deployed:

```
                                    Internet
                                       |
                              [Netcup Server]
                              rmesh-reticulum
                              TCP:4242 + API:8000
                                   |    |
                    +--------------+    +----------------+
                    |                                    |
            [RNode Gateway]                    [Remote Reticulum
             Heltec V3 USB                      nodes via TCP]
             868 MHz LoRa
                    |
         +----------+-----------+
         |                      |
  [MeshCore Companion]   [MeshCore Repeater]
   Heltec V3 + Phone     T-Beam + Solar
                                |
                         [More nodes...]
```

The RNode gateway bridges LoRa and TCP/IP. MeshCore nodes on the same frequency
are heard by the RNode. Reticulum handles the routing and encryption.

> **Important:** MeshCore and Reticulum use different protocols at the LoRa level.
> An RNode running Reticulum firmware talks to other Reticulum/RNode devices.
> MeshCore devices talk to other MeshCore devices. To bridge between them, you'd
> need both firmwares running on separate radios, or use the experimental
> Reticulum-over-MeshCore bridge (see GitHub discussions).
>
> For a simple start: use RNode firmware on everything, and run Sideband on phones
> instead of the MeshCore app. This keeps the whole network on one protocol.

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `Permission denied: /dev/ttyUSB0` | `sudo usermod -a -G dialout $USER` then re-login |
| Device not detected | Try a different USB cable (must be data-capable) |
| `rnodeconf` can't find device | Check `ls /dev/tty*` — may be `ttyACM0` instead of `ttyUSB0` |
| RNode flashing fails | Hold BOOT button while plugging in USB, then retry |
| Container can't see device | Add `devices: ["/dev/ttyUSB0:/dev/ttyUSB0"]` to docker-compose.yml |
| No radio peers discovered | Verify all nodes use same frequency/bandwidth/SF |
| Docker volume has old config | `docker exec rmesh-reticulum cp /app/config/reticulum.conf /data/reticulum/config` then restart |