95 lines
3.7 KiB
Markdown
95 lines
3.7 KiB
Markdown
# SovereignRelay
|
|
|
|
SovereignRelay is an off-grid resilient communication bridge built with NixOS. It connects local Meshtastic LoRa mesh networks to the federated internet via XMPP.
|
|
|
|
If the internet goes down, locals can communicate over the Meshtastic LoRa mesh. When the internet is up, a NixOS bridge flawlessly forwards local mesh messages to a federated XMPP Multi-User Chat (MUC) and vice versa, keeping the off-grid community connected to the broader world.
|
|
|
|
## Architecture
|
|
|
|
* **The Edge:** Local users connected to Meshtastic LoRa radios (e.g., LILYGO T-Beams or RAK WisBlocks).
|
|
* **The Bridge Hardware:** A machine (like a laptop or Raspberry Pi) running NixOS. A Meshtastic radio connects to it via USB (Serial).
|
|
* **The Bridge Software:** A Python daemon that actively listens to the Meshtastic serial stream and an XMPP connection.
|
|
* **The Federated Layer:** XMPP server facilitating connections globally.
|
|
|
|
## Prerequisites
|
|
- A local NixOS installation.
|
|
- A Meshtastic device connected via USB to the NixOS machine.
|
|
- An XMPP account that can join MUCs.
|
|
|
|
## Usage
|
|
|
|
### Developing
|
|
|
|
You can drop into a Nix shell with all the required python dependencies:
|
|
|
|
```bash
|
|
nix-shell
|
|
```
|
|
|
|
From here you can run the bridge directly:
|
|
```bash
|
|
sovereign-bridge -j "your_jid@xmpp.org" -p "your_password" -r "your_room@conference.xmpp.org" -n "meshbridge"
|
|
```
|
|
|
|
### NixOS Module (Systemd Service)
|
|
|
|
SovereignRelay provides a NixOS module to seamlessly integrate the bridge as a declarative `systemd` service that will persist, automatically start on boot, and autorestart on failure.
|
|
|
|
Clone this repository to your NixOS machine:
|
|
|
|
```bash
|
|
git clone https://github.com/jshiffer/lora-xmpp-bridge.git /path/to/lora-xmpp-bridge
|
|
```
|
|
|
|
Then in your NixOS configuration (e.g., `/etc/nixos/configuration.nix`), import the `module.nix` file:
|
|
|
|
```nix
|
|
{
|
|
imports = [
|
|
/path/to/lora-xmpp-bridge/module.nix
|
|
];
|
|
|
|
services.sovereign-bridge = {
|
|
enable = true;
|
|
jid = "your_jid@xmpp.org";
|
|
passwordFile = "/run/secrets/xmpp_password";
|
|
room = "your_room@conference.xmpp.org";
|
|
nick = "meshbridge";
|
|
};
|
|
}
|
|
```
|
|
|
|
#### Managing the XMPP Password
|
|
|
|
The `passwordFile` option ensures the XMPP password isn't leaked into the world-readable Nix store or process arguments. The daemon reads the file directly.
|
|
|
|
For a rapid 24-hour hackathon, you can simply create this file manually on the target machine:
|
|
|
|
```bash
|
|
sudo mkdir -p /run/secrets
|
|
echo "my_super_secret_password" | sudo tee /run/secrets/xmpp_password
|
|
sudo chown root:root /run/secrets/xmpp_password
|
|
sudo chmod 600 /run/secrets/xmpp_password
|
|
```
|
|
|
|
*(For a production system, you would use a secret management tool like `sops-nix` or `agenix` to declaratively deploy this file).*
|
|
|
|
#### Reproducing from a Fresh NixOS Install
|
|
|
|
To deploy this on a fresh NixOS system for the hackathon without experimental features:
|
|
|
|
1. Connect your Meshtastic node via USB.
|
|
2. If your fresh install doesn't have `git`, you can easily drop into a temporary shell that has it:
|
|
```bash
|
|
nix-shell -p git
|
|
```
|
|
3. Clone this repository to the machine (we recommend placing it near your config):
|
|
```bash
|
|
sudo git clone https://github.com/jshiffer/lora-xmpp-bridge.git /etc/nixos/lora-xmpp-bridge
|
|
```
|
|
4. Edit your `/etc/nixos/configuration.nix` to include the module and configuration block as shown above.
|
|
5. Create the password file: `echo "yourpassword" | sudo tee /run/secrets/xmpp_password && sudo chmod 600 /run/secrets/xmpp_password`.
|
|
6. **Protip for Raspberry Pi 3B+:** add 1GB of swap to prevent OOM during builds: `sudo fallocate -l 1G /swapfile && sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile`.
|
|
7. Apply the configuration: `sudo nixos-rebuild switch`.
|
|
8. Verify it's running: `systemctl status sovereign-bridge.service`.
|