From e910855427ca29dc0e52a7107dafc754e27662af Mon Sep 17 00:00:00 2001 From: Assistant <12+assistant@git@zakscode.com> Date: Mon, 21 Sep 2026 14:10:55 -0400 Subject: [PATCH] docs: update README with layered architecture Co-authored-by: Zakary Timson --- README.md | 234 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 151 insertions(+), 83 deletions(-) diff --git a/README.md b/README.md index 17e4f51..74f54ec 100755 --- a/README.md +++ b/README.md @@ -1,83 +1,151 @@ -# Multipurpose Radio Server (MRS) - ---- - -###### By: Zakary Timson -###### Date: September 16, 2025 -###### Version: 1.0 - ---- - -![](https://meshtastic.org/assets/images/lora-topology-2-c80684f1eafdf2a71fbaf26e494fb26d.webp) - -> Compact communication and information exchange server on Raspberry Pi for service-denied areas. -> Ideal for disasters, unserviced environments, long-range tracking, and offline-first operations. - ---- - -## Table of Contents -- [Multipurpose Radio Server](#multipurpose-radio-server-mrs) - - [Description](#description) - - [Inspiration](#inspiration) - - [Capabilities](#capabilities) - - [Manual](#manual) - - [Setup](docs/setup.md) - - [Introduction](#introduction) - - [Connecting & Wifi](#connecting) - - [Mesh Network](#mesh-network) - - [LoRa Radio](#lora-radio) - - [FileBrowser](#filebrowser) - - [Desktop Environment](#desktop-environment) - - Services - - [AI Assistant](#ai-assistant) - - [Archive](#archive) - - [ATAK](#atak) - - [Maps](docs/maps.md) - - [Messaging](#messaging) - - [Pentesting](#pentesting) - - [SDR](#sdr) - - [SSH](#ssh) - - [VPN](#vpn) - - [Todo](#todo) - - [License](LICENSE) - ---- - -## Description - -### Inspiration -- [A.C.I.D](https://www.youtube.com/watch?v=nSrYmkGq9TM) -- [Offline internet](https://www.youtube.com/watch?v=L5RJZmuRJKA) -- [Meshtastic radios](https://morosx.com/ols/products/xtak-lora-mesh) -- [HaLow mesh network](https://www.youtube.com/watch?v=ofR7GFNZzJY) -- [Signal Intelligence](https://www.youtube.com/watch?v=Nam87B2u6bo&t=1942s) - -### Capabilities - -**Networking** -- 900 MHz **HaLow** / 2.4 GHz / 5 GHz Mesh WiFi using **B.A.T.M.A.N.** (1 km +) -- LoRa radio communication (1-100s of kms) -- Connect to AP with QR code using **dnsmasq, hostapd** -- Captive portal & device home page + settings page - -**Communication** -- Offline & federated text/voice/file chat using **Synapse** and **Element** -- Built-in LoRa **Meshtastic** node (≈2–15 km) -- GPS positioning & offline maps using **gpsd, chrony** -- Track people & logistics with **ATAK** - -**Information Archive** -- Offline AI/LLM assistant using **Ollama** and **OpenWebUI** -- Offline Wikipedia, Ghetesburg project & more using **Kiwix** -- File sharing & syncing using **FileBrowser** and **Rclone** -- Remote desktop usig **RDP** and **Apache Guacamole** - -**Recon & Security** -- WiFi & Bluetooth reconnaissance with **Bettercap, nmap, masscan** and more -- Red team operations with **aircrack, nikto, Metasploit** and more -- Radio frequency recon using **SDRAngel** -- ADS-B plane tracking with **tar1090** - -## License - -This project is licensed under the [MIT License](LICENSE). +# Multipurpose Radio Server (MRS) + +--- + +###### By: Zakary Timson +###### Date: September 2026 +###### Version: 1.0 + +--- + +> Offline-first radio and connectivity hub for service-denied or isolated environments. +> Designed for disaster response, long-range tracking, reconnaissance, and resilient communications. + +--- + +## Architecture Overview + +MRS is now structured around three modular layers: + +- **MRS (Core Layer)**: Hardware-focused connectivity and reconnaissance +- **OpenCast (Media/Control Layer)**: Screen casting, control panel, remote desktop +- **AI-harness (Interface Layer)**: Unified access to AI, knowledge base, and file services + +--- + +## Core Services + +### Connectivity + +- **900 MHz / 2.4/5 GHz Mesh WiFi** via B.A.T.M.A.N. routing (1 km+) +- **LoRa Radio** communication (Meshtastic node, 1-100s of km) +- **HaLow integration** for long-range WiFi mesh connectivity + +### Hardware Interface + +- **TV/Display connection** via OpenCast for live data visualization +- **Meshtastic LoRa node** for field operations and tracking +- **Radio frequency tools** (SDRAngel for spectrum analysis) + +### Reconnaissance & Security + +- WiFi & Bluetooth reconnaissance (Bettercap, nmap, masscan) +- Red team operations (aircrack, nikto, Metasploit) +- Radio frequency recon (SDRAngel) +- ADS-B plane tracking (tar1090) + +### Networking + +- Captive portal with QR code connection +- Hostapd + dnsmasq integration +- Local state feed at `localhost:8088/status` +- MCP server for LLM integration + +--- + +## Layered Architecture + +### MRS Core Layer + +MRS runs as the foundational service layer, handling all hardware connectivity and reconnaissance tools. It provides: + +- Mesh WiFi and LoRa backbone +- Reconnaissance tool orchestration +- Hardware telemetry and status +- Local API endpoint for layer communication + +### OpenCast Layer + +OpenCast serves as the control surface and media orchestrator: + +- Screen casting to display hardware +- Control panel for system navigation +- Built-in VNC remote desktop access +- Puppeteer management via API endpoints +- Runs on port 3000 + +### AI-harness Layer + +The harness provides a unified interface to knowledge and intelligence services: + +- Offline AI assistant (Liter + Gemma4-e2b) +- ZIM archive access (Kiwix) +- File hosting and management +- Notes and data management +- Replaces legacy Ollama/OpenWebUI and FileBrowser + +--- + +## Services + +### Screen & Display + +- **OpenCast TV**: Connects display hardware to MRS data streams +- **Blur/Sticky UI**: Persistent blur effect over idle data feeds +- **Notification overlay**: System alerts and event notifications + +### Media & Casting + +- **Puppeteer casting**: Web page "casting" to display +- **Image gallery**: Fallback to random images or local photo selection +- **Remote desktop**: VNC integration via OpenCast backend + +### Intelligence & Tools + +- **AI Assistant**: Gemma4-e2b-powered offline AI +- **ZIM Archive**: Kiwix offline knowledge base +- **Recon Suite**: Network, radio, and hardware scanning tools +- **File Management**: Harness-integrated file hosting and editing + +--- + +## Quick Start + +```bash +# Clone and install +git clone https://git.zakscode.com/ztimson/mrs +cd mrs + +# Install base dependencies +npm ci + +# Start services +# - MRS core: defaults to port 8088 +# - OpenCast: defaults to port 3000 +# - AI-harness: defaults to port 3001 +``` + +--- + +## Documentation + +- [Setup Guide](docs/setup.md) +- [Mesh Network](docs/mesh.md) +- [Maps & Geolocation](docs/maps.md) +- [API Documentation](docs/api.md) - Coming soon + +--- + +## Todo + +- [ ] Finalize service separation across layers +- [ ] Publish API contracts between MRS, OpenCast, and harness +- [ ] Add telemetry endpoint for remote monitoring +- [ ] Implement automated OTA update mechanism +- [ ] Add more recon tools to the core suite + +--- + +## License + +This project is licensed under the [MIT License](LICENSE). \ No newline at end of file