Reticulum Community Hub (RCH)

Reticulum Community Hub (RCH) is a shared coordination point for mesh networks. It allows people and groups to exchange messages, share situational updates, and distribute files in a structured and reliable way, even across intermittent or low-connectivity environments, while remaining independent from centralized internet services.

Why?

"RCH begins from a simple refusal: When this illusion breaks, highly optimized global systems fail first."

Read our full manifesto: docs/Manifesto_Reticulum_Community_Hub.md

What it does

• One-to-many and topic-scoped message fan-out over LXMF.
• Canonical TopicID normalization plus validated delivery metadata for hub-originated message sends.
• Telemetry collection and on-demand telemetry responses.
• File and image attachment storage with retrieval and deletion by ID.
• Topic pages can associate existing asset-library files and images without duplicating stored attachments.
• sci-fi themed admin UI.
• Operator-managed map markers backed by Reticulum object identities and telemetry updates.
• TAK bridge for chat and location updates (Optional).
• Capability announces embedded in Reticulum announces for feature discovery.
• RNS 1.1.7 and LXMF 0.9.5 support, including announce-slot compatibility with LXMF functionality signaling.

What it looks like

Quickstart (from source)

1. Clone and enter the repo.

   git clone https://github.com/FreeTAKTeam/Reticulum-Community-Hub.git
   cd Reticulum-Community-Hub

2. Create and activate a virtual environment.

   python -m venv .venv
   # Linux/macOS
   source .venv/bin/activate
   # Windows (PowerShell)
   .venv\Scripts\Activate.ps1

3. Install dependencies.

   python -m pip install --upgrade pip
   python -m pip install -e .

4. Prepare a storage directory and config.
   • Start once with your chosen --storage_dir; if config.ini or lxmf-router.ini is missing, RCH writes packaged defaults for both files.
   • You can also copy the shipped template from reticulum_telemetry_hub/config/default_config.ini.
   • The shipped LXMF router template also lives at reticulum_telemetry_hub/config/default_lxmf_router_config.ini.
   • Adjust paths in the [hub], [files], and [images] sections as needed.
   • config.ini [propagation] and [lxmf] values override matching keys from lxmf-router.ini.
5. Start the hub.

   python -m reticulum_telemetry_hub.reticulum_server \
       --storage_dir ./RCH_Store \
       --display_name "RCH"

   Or start the hub + northbound API with the new entrypoint:

   rch start --data-dir ./RCH_Store --port 8000 --log-level info

For configuration, services, and client usage details, see docs/userManual.md.

Transport runtime notes

• RCH 2.9.2 targets RNS 1.2.0 and LXMF 0.9.6.
• Upgrade note: RNS 1.2.0 adds upstream Git-over-Reticulum support, the rnsh utility, and transport/runtime cleanup; LXMF remains at 0.9.6.
• Capability announces now preserve upstream announce extension slots, so RCH can append its own capability payload without overwriting LXMF functionality signaling when peers start advertising it.
• Compatibility warning: the 2.9.2 announce capability layout is not backward-compatible with older RCH nodes that only read slot 2 for the RCH capability payload. Mixed-version deployments can lose capability discovery until all participating RCH nodes are upgraded.
• RCH still keeps two local LXMF runtime guards for LXMPeer.offer_response() integer error responses and zero-duration stamp-speed calculation because those failure paths remain present in upstream LXMF 0.9.6.

Install from PyPI

1. Create and activate a virtual environment.

   python -m venv .venv
   # Linux/macOS
   source .venv/bin/activate
   # Windows (PowerShell)
   .venv\Scripts\Activate.ps1

2. Install the package.

   python -m pip install --upgrade pip
   python -m pip install ReticulumCommunityHub

3. Start the hub (point at your storage directory).

   python -m reticulum_telemetry_hub.reticulum_server --storage_dir /path/to/RCH_Store

Northbound API and admin UI

The northbound FastAPI service exposes REST + WebSocket endpoints used by the admin UI.

• Run the hub + API together (recommended for chat/message sending):

  rch start --data-dir ./RCH_Store --port 8000 --api-host 0.0.0.0 --log-level info

  By default, the gateway binds to 0.0.0.0 (all interfaces).

• Check or stop the backend:

  rch status --data-dir ./RCH_Store
  rch stop --data-dir ./RCH_Store

• Run only the API server (read-only unless you provide a message dispatcher):

  uvicorn reticulum_telemetry_hub.northbound.app:app --host 0.0.0.0 --port 8000

• Remote clients must authenticate. Set RTH_API_KEY and send it as X-API-Key or a Bearer token (RCH_API_KEY remains a backward-compatible alias).

• Loopback/local requests from the same machine are allowed without API credentials.

• Marker identity encryption is derived from the hub identity (no extra key configuration required).

• Northbound message dispatch applies exactly one routing mode per send: broadcast, topic fan-out, or targeted destination.

• Hub-originated outbound chat attaches an RTHDelivery envelope carrying Message-ID, Content-Type, Schema-Version, TTL, Priority, Sender, Born, and optional Created-At, and persists retry/ack state in chat history metadata.

• The hub now uses a propagation-first outbound policy: broadcast/topic fan-out sends are queued as propagated immediately, while targeted sends get one direct attempt only when the recipient has fresh presence evidence from current runtime activity or an announce seen within the last hour.

• The admin UI sidebar can be collapsed and pinned (stored per-browser).

• Telemetry map markers render MDI icons when telemetry payloads include telemetry_type, symbol, category, or type.

• The WebMap shows a live latitude/longitude readout for the map cursor.

• Marker symbols load from rch-symbols.yaml (override with RTH_SYMBOL_REGISTRY_PATH).

• /api/v1/app/info includes the hub Reticulum destination (reticulum_destination) for display on the About page.

• File/image attachments support delete operations that remove both metadata and on-disk content (DELETE /File/{id}, DELETE /Image/{id}).

• Existing file/image asset-library records can be linked or unlinked from topics, and the Topics page lists the files and images currently associated with each topic.

• The UI lives in ui/:

  cd ui
  npm install
  npm run dev

  The UI uses Vite 6 (installed via npm install).

  Set VITE_RCH_BASE_URL and VITE_RTH_WS_BASE_URL when the UI should target a different hub. For a remote-friendly combined launcher, run ./run_server_ui_remote.sh.

Remote access (LAN/WAN)

For full setup examples, see docs/remoteAccess.md.

1. Set an API key on the host that runs RCH:

   # Linux/macOS
   export RTH_API_KEY="change-this"
   # Windows PowerShell
   $env:RTH_API_KEY = "change-this"

2. Start the gateway on a reachable interface and port:

   rch start --data-dir ./RCH_Store --api-host 0.0.0.0 --port 8000

3. Allow inbound TCP traffic on that port in the host firewall.
4. From another machine, point the UI/API to the hub host IP:
   • REST base URL: http://<hub-ip>:8000
   • WebSocket base URL: ws://<hub-ip>:8000
5. Authenticate remote requests with either:
   • X-API-Key: <your-key>
   • Authorization: Bearer <your-key>

Electron desktop packaging (Windows + Raspberry Pi OS)

The electron/ folder contains a minimal desktop wrapper that bundles the UI and loads the hub API from 127.0.0.1.

1. Install Electron dependencies:

   cd electron
   npm install

2. Run the Electron shell in dev mode (starts the Vite dev server):

   npm run dev

3. Build installers:

   npm run dist

4. Build Windows installer + portable EXE:

   npm run dist -- --win

Electron packaging expects a bundled backend executable. Install PyInstaller and build it before packaging:

python -m pip install -e .
python -m pip install pyinstaller
cd electron
npm run build:backend

Before each Electron build, the desktop app version is synchronized from pyproject.toml automatically.

Windows artifact naming:

• Installer: RCH_win Install_<version>.exe
• Portable: RCH_win Portable_<version>.exe

For Raspberry Pi OS, build on Linux and target the desired architecture:

npm run dist -- --linux --armv7l
npm run dist -- --linux --arm64

Packaged builds default to http://127.0.0.1:8000 for the API when loaded from file://. Override in the Connect page or set VITE_RTH_BASE_URL / VITE_RTH_WS_BASE_URL at build time.

Packaged desktop builds also launch the bundled backend automatically. Set RCH_BACKEND_MANAGED=false to disable autostart, or override with RCH_DATA_DIR, RCH_BACKEND_PORT, and RCH_LOG_LEVEL.

Marker management endpoints (used by the WebMap UI):

• GET /api/markers (list stored markers)
• GET /api/markers/symbols (list available marker symbols)
• POST /api/markers (create marker with type/symbol/lat/lon, optional name/category/notes/ttl_seconds)
• PATCH /api/markers/{object_destination_hash}/position (update marker coordinates)

Documentation

• docs/README.md (documentation map)
• docs/userManual.md (user and operator guide)
• docs/architecture/architecture.md (system overview and references)
• docs/southbound.md (LXMF southbound transport and RTHDelivery contract)
• API/ReticulumCommunityHub-OAS.yaml (REST/OpenAPI reference)

Contributing

We welcome and encourage contributions. Please include appropriate tests and follow the project coding standards.

Linting

RCH uses Ruff for linting with a 120-character line length and ignores E203 to align with Black-style slicing.

• With Poetry (installs dev dependencies, including Ruff):

  poetry install --with dev
  poetry run ruff check .

• With a plain virtual environment:

  python -m pip install ruff
  ruff check .

License

This project is licensed under the Eclipse Public License (EPL). For more details, refer to the LICENSE file in the repository.

Support

For issues or support, open a GitHub issue

Support Reticulum

You can help support the continued development of open, free and private communications systems by donating via one of the following channels to Mark, the original Reticulum author:

• Monero: 84FpY1QbxHcgdseePYNmhTHcrgMX4nFfBYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD19b3B8NiLCGVxzKV17UMmmeEsCrPyA5w
• Ethereum: 0xFDabC71AC4c0C78C95aDDDe3B4FA19d6273c5E73
• Bitcoin: 35G9uWVzrpJJibzUwpNUQGQNFzLirhrYAH
• Ko-Fi: https://ko-fi.com/markqvist