16 KiB
📡 Fleet Control Console - Server (Central Hub)
🌍 Read in English | 🇮🇹 Leggi in Italiano
🇬🇧 English
Fleet Control Console is a professional, real-time command and control (C2) dashboard designed for amateur radio repeater networks (MMDVM). This repository contains the Server (Central Hub) component, which provides a centralized web interface to monitor and manage a fleet of remote digital voice nodes (DMR, NXDN, YSF, P25).
ℹ️ Note: This is the Central Server repository. To monitor remote repeaters, you must install the Fleet Control Agent on each node.
🏗️ Architecture & Technology Stack
The server acts as the brain of the network, built on a highly scalable foundation (v5.0+):
- Modular Backend: Completely decoupled architecture (
core/,services/,routes/) for high maintainability and robust background task handling. - Core Engine: Flask (Python) with
geventfor high-concurrency WebSocket handling. - Database: SQLite (WAL mode) for robust User Management, Audit Logs, and Radio Traffic storage.
- Communication: MQTT for instant data routing + WebSockets (SocketIO) for zero-latency UI updates.
- Frontend: Vanilla JS with a modern Glassmorphism Borderless Executive NOC (Network Operations Center) design and fully separated logic (
app.js,modals.js). Full i18n (Internationalization) support.
✨ Ultimate Features
🛡️ Proactive Diagnostics (Watchdog) & Global Alerts
- Hardware Monitoring: Continuous analysis of remote CPU temperatures and disk space saturation. Automatically triggers Push Notifications before critical failures occur.
- RF Anomaly Detection: Real-time monitoring of local RF BER (Bit Error Rate). Detects hardware RF degradation on local transits and alerts admins instantly.
- Global Service Alerts (v5.3+): Daemon crashes (e.g.,
SVC KO: MMDVMHOST) are instantly propagated to the global Dashboard grid and interactive Fleet Map for immediate visibility.
⚡ Zero-Latency Real-Time Dashboard
- WebSocket Powered: The dashboard updates instantly upon radio traffic or telemetry changes. No heavy HTTP polling, no page reloads.
- Live MQTT Status: A real-time badge continuously monitors the connection to the MQTT broker.
- PWA Ready: Install the dashboard as a Progressive Web App on iOS/Android for a native, full-screen mobile experience with offline asset caching.
🔔 Web Push Notifications
- Get instant, native alerts directly on your desktop or mobile device when:
- A node goes offline or comes back online.
- A critical system daemon crashes (Auto-healing failed).
- The Watchdog detects thermal warnings, disk full alerts, or high RF BER.
- Works securely even when the web app is closed or in the background.
🛠️ Advanced Remote Control & Maintenance
- OTA Server Updates: Apply server-side Git updates with a single click directly from the admin dashboard (Over-The-Air) without SSH access, featuring a synchronous, cache-bypassing update checker.
- Remote .INI Editor: Edit daemon configuration files (e.g., MMDVMHost.ini) directly from the web interface.
- Service Management: Start, Stop, or Restart remote system daemons.
- Scoped Global Overrides: Switch profiles (e.g., Profile A/B) simultaneously on multiple nodes, dynamically scoped to the operator's authorized repeaters.
- Hardware Interventions: Trigger a physical OS reboot or a hard GPIO reset of the MMDVM HAT directly from the web panel.
📊 Unified Monitoring & Statistics
- Interactive Fleet Map: Real-time GIS map showing repeater locations, online/offline status, active TX states (pulsing pins), and active watchdog/service warnings.
- Live Heard Log: A centralized view of radio traffic across the entire network, auto-resolving DMR and NXDN IDs into callsigns.
- Software & Firmware Tracking: Instantly view MMDVM firmware versions and Pi-Star/Gateway component versions for each node.
- Daily Analytics: Automatically tracks Top Talkgroups, Top Callsigns, Average duration, and daily transit counts.
🔐 Security & Access Control
- Strict Role-Based Access Control (RBAC): True Zero-Trust architecture.
- Granular Permissions: Node management (reboots, config edits, service controls) is strictly bound to explicitly assigned nodes in
allowed_nodes, uniformly enforced for both Operators and Admins. - System Administration: Admins retain exclusive rights to global server settings and user management, separated from node-level control.
- Audit Trail: Every critical action is securely logged with username, timestamp, and target node.
⚠️ Security Requirement: HTTPS
Please note that Web Push Notifications and the Service Worker require a secure connection to function. For security reasons, modern browsers only enable these features over HTTPS. If you are accessing the console via HTTP (outside of localhost), the "Push" button and notification registration will not work. We recommend using a reverse proxy (like Nginx, Caddy, or Traefik) with an SSL certificate.
⚠️ Reverse Proxy & WebSocket Configuration
If you expose the Fleet Console through a reverse proxy like Apache on a public IP (HTTPS), standard HTTP proxying will drop Socket.IO real-time connections. You must enable the WebSocket tunnel in Apache:
sudo a2enmod proxy_wstunnel rewrite headers
And insert the Rewrite rules before the ProxyPass directives inside your <VirtualHost *:443> block:
RewriteEngine On
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://127.0.0.1:9000/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]
RewriteRule /(.*) http://127.0.0.1:9000/$1 [P,L]
ProxyPass /socket.io/ ws://127.0.0.1:9000/socket.io/
ProxyPassReverse /socket.io/ ws://127.0.0.1:9000/socket.io/
ProxyPass / http://127.0.0.1:9000/
ProxyPassReverse / http://127.0.0.1:9000/
🚀 Installation Guide
0. Root Privileges
All installation steps must be executed as the root user.
apt update
apt install build-essential python3-dev libssl-dev libffi-dev python3-pip python3-venv
1. Clone Repository
Clone the repository into the /opt directory to ensure all systemd paths work correctly:
git clone https://git.arifvg.it/iv3jdv/fleet-control-server.git /opt/fleet-control-server
cd /opt/fleet-control-server
2. Virtual Environment Setup (Recommended)
To prevent conflicts with OS packages (PEP 668), create an isolated environment:
cd /opt/fleet-control-server
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
3. Configuration
- Copy
config.example.jsontoconfig.json. - Configure your MQTT broker credentials.
- Define your repeaters in
clients.json. - Generate VAPID keys at vapidkeys.com and add them to
config.jsonto enable Web Push notifications. (Note: Push notifications require HTTPS). - Configure dynamic log rotation sizes (
log_max_mbandlog_backup_count) directly inconfig.jsonto manage disk space.
4. Running as a Service
To run the server continuously in production using Gunicorn:
cp fleet-console.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable fleet-console
systemctl start fleet-console
(Ensure the .service file points to the gunicorn executable inside your venv).
🇮🇹 Italiano
Fleet Control Console è una dashboard di comando e controllo (C2) professionale in tempo reale, progettata per le reti di ripetitori radioamatoriali (MMDVM). Questo repository contiene il Server (Central Hub), che fornisce un'interfaccia web centralizzata per monitorare e gestire una flotta di nodi digitali remoti (DMR, NXDN, YSF, P25).
ℹ️ Nota: Questo è il repository del Server Centrale. Per monitorare i ripetitori, devi installare il Fleet Control Agent su ciascun nodo remoto.
🏗️ Architettura e Tecnologie
Il server agisce da cervello della rete, basato su fondamenta altamente scalabili (v5.0+):
- Backend Modulare: Architettura completamente disaccoppiata (
core/,services/,routes/) per un'elevata manutenibilità e gestione robusta dei task in background. - Motore Core: Flask (Python) con
geventper la gestione ad alta concorrenza dei WebSocket. - Database: SQLite (in modalità WAL) per gestire in sicurezza Utenti, Log operativi e traffico radio.
- Comunicazione: MQTT per il routing istantaneo dei dati + WebSockets (SocketIO) per aggiornare la UI a latenza zero.
- Frontend: Vanilla JS con layout Borderless Executive in stile NOC (Network Operations Center), logica completamente separata (
app.js,modals.js) e supporto nativo i18n (internazionalizzazione multilingua dinamica).
✨ Funzionalità Principali
🛡️ Diagnostica Proattiva (Watchdog) & Avvisi Globali
- Monitoraggio Hardware: Analisi continua delle temperature CPU e della saturazione disco da remoto. Innesca automaticamente notifiche Push prima che si verifichino guasti critici.
- Rilevamento Anomalie RF: Monitoraggio in tempo reale del BER (Bit Error Rate) sul traffico RF locale. Rileva il degrado hardware in radiofrequenza avvisando istantaneamente gli amministratori.
- Propagazione Service Alerts (v5.3+): Il crash di un demone remoto (es.
SVC KO: MMDVMHOST) viene segnalato in tempo reale sulla griglia principale e sulla Mappa di Flotta, senza dover ispezionare il singolo nodo.
⚡ Dashboard Real-Time a Latenza Zero
- Motore WebSocket: La dashboard scatta all'istante al passaggio di traffico radio o ai cambi di telemetria. Nessun polling HTTP pesante, nessun refresh della pagina.
- Stato MQTT Live: Un badge in tempo reale monitora continuamente la connessione al broker MQTT.
- PWA Ready: Installabile su smartphone Android e iOS come Progressive Web App per un'esperienza nativa a schermo intero con cache offline intelligente.
🔔 Notifiche Web Push
- Ricevi avvisi nativi e immediati su PC o smartphone quando:
- Un nodo va offline o torna operativo.
- Un demone di sistema remoto si blocca (fallimento auto-healing).
- Il Watchdog rileva allarmi termici, disco pieno o anomalie BER.
- Funzionano in modo sicuro anche quando la web app è chiusa o in background.
🛠️ Controllo Remoto & Manutenzione Avanzata
- Aggiornamenti Server OTA: Applica gli aggiornamenti del server tramite Git direttamente dalla dashboard (Over-The-Air) con un clic. Controllo aggiornamenti sincrono e possibilità di bypass della cache di sicurezza.
- Editor .INI Remoto: Modifica i file di configurazione (es. MMDVMHost.ini) direttamente dal pannello web.
- Gestione Demoni: Avvia, arresta o riavvia i servizi di sistema remoti.
- Override Globali Scoped: Cambia i profili operativi simultaneamente su più nodi, filtrati dinamicamente in base ai nodi assegnati all'operatore in uso.
- Interventi Hardware: Innesca un riavvio del sistema operativo o un reset fisico (tramite pin GPIO) della scheda MMDVM.
📊 Monitoraggio & Statistiche
- Mappa Interattiva di Flotta: Mappa GIS in tempo reale che mostra la posizione dei ripetitori, stato online/offline, trasmissione attiva (pin lampeggianti) e allarmi diagnostici di servizio in corso.
- Log Ascolti Live: Vista unificata in tempo reale del traffico radio di tutta la rete, con traduzione automatica degli ID DMR e NXDN in nominativi.
- Tracciamento Versioni: Controlla all'istante le versioni firmware MMDVM e software a bordo di ciascun nodo.
- Analisi Giornaliera: Statistiche automatiche su Top Talkgroups, Top Callsign, durata media e numero totale di transiti.
🔐 Sicurezza e Controllo Accessi
- Strict Role-Based Access Control (RBAC): Architettura Zero-Trust reale. La gestione del sistema (System Admin) è nettamente separata dalla gestione dei nodi.
- Permessi Granulari Ferrei: Anche un utente
adminpuò interagire o configurare esclusivamente i nodi che gli sono stati esplicitamente assegnati nella listaallowed_nodes, con barriera di sicurezza verificata lato backend ad ogni chiamata API. - Audit Trail: Ogni azione critica (riavvii, modifiche file, gestione demoni) viene registrata con data, ora, utente e nodo di destinazione.
⚠️ Sicurezza Richiesta: HTTPS
Si prega di notare che le Notifiche Web Push e il Service Worker richiedono una connessione sicura per funzionare. Per motivi di sicurezza, i browser moderni abilitano queste funzionalità solo su HTTPS. Se accedi alla console via HTTP (al di fuori di localhost), il tasto "Push" e la registrazione delle notifiche non saranno attivi. Si consiglia l'uso di un reverse proxy (come Nginx, Caddy o Traefik) con certificato SSL.
⚠️ Configurazione Reverse Proxy & WebSocket
Se esponi la Fleet Console tramite un reverse proxy come Apache su IP pubblico (HTTPS), il proxy HTTP standard farà cadere continuamente la connessione in tempo reale di Socket.IO. Devi abilitare il tunnel WebSocket in Apache:
sudo a2enmod proxy_wstunnel rewrite headers
E inserire le regole di Rewrite prima del ProxyPass all'interno del tuo blocco <VirtualHost *:443>:
RewriteEngine On
RewriteCond %{HTTP:Upgrade} =websocket [NC]
RewriteRule /(.*) ws://127.0.0.1:9000/$1 [P,L]
RewriteCond %{HTTP:Upgrade} !=websocket [NC]
RewriteRule /(.*) http://127.0.0.1:9000/$1 [P,L]
ProxyPass /socket.io/ ws://127.0.0.1:9000/socket.io/
ProxyPassReverse /socket.io/ ws://127.0.0.1:9000/socket.io/
ProxyPass / http://127.0.0.1:9000/
ProxyPassReverse / http://127.0.0.1:9000/
🚀 Guida all'Installazione
0. Privilegi di Root
Tutti i passaggi di installazione devono essere eseguiti come utente root.
apt update
apt install build-essential python3-dev libssl-dev libffi-dev python3-pip python3-venv
1. Clonazione dei Repository
Clona il repository nella cartella /opt per assicurarti che tutti i percorsi dei servizi systemd siano corretti:
git clone https://git.arifvg.it/iv3jdv/fleet-control-server.git /opt/fleet-control-server
cd /opt/fleet-control-server
2. Setup Ambiente Virtuale (Consigliato)
Per evitare conflitti con i pacchetti di sistema (regola PEP 668), crea una "bolla" isolata:
cd /opt/fleet-control-server
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
3. Configurazione Base
- Copia
config.example.jsoninconfig.json. - Inserisci le credenziali del broker MQTT.
- Definisci i ripetitori nel file
clients.json. - Genera le chiavi VAPID su vapidkeys.com e inseriscile in
config.jsonper attivare le notifiche Push. (Attenzione: le notifiche Push richiedono obbligatoriamente un certificato HTTPS). - Configura le dimensioni della rotazione dei log (
log_max_mbelog_backup_count) direttamente nelconfig.jsonper gestire lo spazio su disco.
4. Esecuzione come Servizio (systemd)
Per eseguire il server in produzione in modo continuo e stabile con Gunicorn:
cp fleet-console.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable fleet-console
systemctl start fleet-console
(Assicurati che il file .service punti all'eseguibile gunicorn situato all'interno della cartella venv).
Created by IV3JDV @ ARIFVG - 2026
