fleet-node-agent/README.md

🛰️ Fleet Control Agent

🌍 Read in English | 🇮🇹 Leggi in Italiano

---

🇬🇧 English

The Fleet Control Agent is a lightweight monitoring and control script designed for remote MMDVM nodes. It acts as the bridge between your radio hardware and the Central Console.

ℹ️ Note: This is the Remote Agent repository, intended to be installed on individual repeater nodes. To manage and monitor all your fleet from a single web dashboard, you must also install the Fleet Control Console (Server) on your central hub.

✨ Key Features

• Real-Time Telemetry: Streams CPU, RAM, Disk usage, and Temperature data via MQTT.
• Service Management: Allows remote Start/Stop/Restart of system daemons (MMDVMHost, DMRGateway, etc.).
• Remote Configuration: Enables the Central Server to edit .ini files remotely.
• Hardware Reset: Supports physical MMDVM HAT reset via GPIO pins (requires RPi.GPIO).
• Auto-Healing: Automatically detects service failures and attempts to restart them.

🤖 Telegram Bot Integration

The agent features built-in support for Telegram Bot notifications. This allows system administrators to receive real-time alerts regarding node status, offline services, and critical system events directly on their mobile devices. Notifications are highly manageable: they can be dynamically enabled or muted for each individual node directly from the central NOC Fleet Console, ensuring you only get notified when it matters.

🛠️ Core Configuration Files

To enable full functionality, you must configure these three files:

• node_config.json: The main configuration. Here you set your MQTT broker, your unique client_id (e.g., IR3XXX), and the paths for the lists below.
• process_list.txt: List the names of the system services you want to monitor (e.g., mmdvmhost, dmrgateway). The agent will check their status and attempt to restart them if they crash (Auto-healing).
• file_list.txt: List the full absolute paths of the configuration files (e.g., /etc/MMDVMHost.ini) that you want to edit remotely from the Dashboard.

🚀 Installation Guide

0. Root Privileges

All installation steps must be executed as the root user. Before starting, elevate your privileges by running:

sudo su

1. Clone the Repository

Clone the agent into /opt to ensure path consistency:

sudo git clone https://git.arifvg.it/iv3jdv/fleet-node-agent.git /opt/fleet-node-agent
cd /opt/fleet-node-agent

2. Virtual Environment Setup

sudo python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Configuration

1. Main Config: cp node_config.json.example node_config.json and edit it with your MQTT credentials.
2. Processes: cp process_list.txt.example process_list.txt and add your service names (one per line).
3. Files: cp file_list.txt.example file_list.txt and add the absolute paths to your .ini files.

Note: To enable Telegram notifications, ensure you have configured your TELEGRAM_TOKEN and CHAT_ID in the agent's configuration file.

4. Systemd Service (Auto-start)

cp fleet-agent.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable fleet-agent
systemctl start fleet-agent

---

🇮🇹 Italiano

Il Fleet Control Agent è lo script di monitoraggio e controllo per i nodi remoti MMDVM. Funge da ponte tra l'hardware radio e la Console Centrale.

ℹ️ Nota: Questo è il repository dell'Agent Remoto, da installare sui singoli nodi ripetitore. Per gestire e monitorare tutta la flotta da un'unica dashboard web, devi installare anche la Fleet Control Console (Server) sul tuo hub centrale.

✨ Funzionalità Principali

• Telemetria Real-Time: Invia dati su CPU, RAM, Disco e Temperatura via MQTT.
• Gestione Servizi: Permette l'avvio, l'arresto o il riavvio remoto dei demoni di sistema (MMDVMHost, DMRGateway, ecc.).
• Configurazione Remota: Consente al Server Centrale di modificare i file .ini a distanza.
• Reset Hardware: Supporta il reset fisico della scheda MMDVM HAT tramite pin GPIO (richiede RPi.GPIO).
• Auto-Healing: Rileva automaticamente i crash dei servizi e tenta di riavviarli.

🤖 Telegram Bot Integration

L'agent dispone del supporto nativo per le notifiche tramite Bot Telegram. Questo permette agli amministratori di sistema di ricevere alert in tempo reale sullo stato dei nodi, sui servizi offline e sugli eventi critici direttamente sul proprio smartphone. La gestione degli avvisi è centralizzata: le notifiche possono essere attivate o silenziate dinamicamente per ogni singolo nodo direttamente dalla Fleet Console centrale, evitando spam inutile.

🛠️ File di Configurazione Chiave

Per il corretto funzionamento, è necessario definire i parametri in questi tre file:

• node_config.json: La configurazione principale. Qui imposti il broker MQTT, il tuo client_id univoco (es. IR3XXX) e i percorsi per le liste sottostanti.
• process_list.txt: Elenca i nomi dei servizi di sistema da monitorare (es. mmdvmhost, dmrgateway). L'agente ne controllerà lo stato e proverà a riavviarli in caso di crash (Auto-healing).
• file_list.txt: Elenca i percorsi completi dei file di configurazione (es. /etc/MMDVMHost.ini) che desideri poter modificare remotamente dalla Dashboard.

🚀 Guida all'Installazione

0. Privilegi di Root

Tutti i passaggi di installazione devono essere eseguiti come utente root. Prima di iniziare, eleva i tuoi privilegi eseguendo:

sudo su

1. Clonazione del Repository

Clona l'agente nella cartella /opt per garantire la coerenza con i servizi systemd:

sudo git clone https://git.arifvg.it/iv3jdv/fleet-node-agent.git /opt/fleet-node-agent
cd /opt/fleet-node-agent

2. Setup Ambiente Virtuale (venv)

sudo python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Personalizzazione

1. Config Principale: cp node_config.json.example node_config.json e inserisci i dati MQTT.
2. Processi: cp process_list.txt.example process_list.txt e aggiungi i nomi dei tuoi servizi (uno per riga).
3. File: cp file_list.txt.example file_list.txt e inserisci i percorsi assoluti dei tuoi file .ini.

Nota: Per abilitare le notifiche Telegram, assicurati di aver configurato il tuo TELEGRAM_TOKEN e il CHAT_ID nel file di configurazione dell'agent.

4. Esecuzione come Servizio (systemd)

cp fleet-agent.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable fleet-agent
systemctl start fleet-agent

---

Created by IV3JDV @ ARIFVG - 2026