docs: update README with layered architecture
Co-authored-by: Zakary Timson
This commit is contained in:
Zakary Timson
@@ -3,80 +3,148 @@
|
||||
---
|
||||
|
||||
###### By: Zakary Timson
|
||||
###### Date: September 16, 2025
|
||||
###### Date: September 2026
|
||||
###### Version: 1.0
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
> 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.
|
||||
> Offline-first radio and connectivity hub for service-denied or isolated environments.
|
||||
> Designed for disaster response, long-range tracking, reconnaissance, and resilient communications.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
- [Multipurpose Radio Server](#multipurpose-radio-server-mrs)
|
||||
- [Description](#description)
|
||||
- [Inspiration](#inspiration)
|
||||
- [Capabilities](#capabilities)
|
||||
- [Manual](#manual)
|
||||
- [Setup](docs/setup.md)
|
||||
- [Introduction](#introduction) <!-- Home + Settings page -->
|
||||
- [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)
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
## Description
|
||||
## Core Services
|
||||
|
||||
### 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)
|
||||
### Connectivity
|
||||
|
||||
### Capabilities
|
||||
- **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
|
||||
|
||||
**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
|
||||
### Hardware Interface
|
||||
|
||||
**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**
|
||||
- **TV/Display connection** via OpenCast for live data visualization
|
||||
- **Meshtastic LoRa node** for field operations and tracking
|
||||
- **Radio frequency tools** (SDRAngel for spectrum analysis)
|
||||
|
||||
**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**
|
||||
### Reconnaissance & Security
|
||||
|
||||
**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**
|
||||
- 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user