# 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).