update readme

README.md

@@ -1,4 +1,4 @@
-# 🤖 Fleet Control Agent
+# 🛰️ Fleet Node Agent
 
 🌍 *[Read in English](#english) | 🇮🇹 [Leggi in Italiano](#italiano)*
 
@@ -7,53 +7,124 @@
 <a name="english"></a>
 ## 🇬🇧 English
 
-The **Fleet Control Agent** is a lightweight monitoring script designed for remote nodes (Raspberry Pi / Linux). It collects hardware telemetry and executes commands sent from the Central Dashboard via MQTT.
+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.
 
-### ✨ Features
-* **Real-Time Telemetry:** Monitors CPU usage, RAM, Temperature, and Disk space.
-* **Service Management:** Remote Start, Stop, or Restart of system daemons (MMDVMHost, DMRGateway, etc.).
-* **Smart Auto-Healing:** Automatically detects crashed services and attempts to revive them.
-* **Hardware Reset (GPIO):** Physically reboot the MMDVM radio HAT via GPIO pins directly from the dashboard.
+> ℹ️ **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)](https://git.arifvg.it/iv3jdv/fleet-control-server) on your central hub.
 
-### 🚀 Quick Installation
+### ✨ 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.
 
-1. **Clone the repo:**
+### 🤖 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.
 
-        git clone https://git.arifvg.it/iv3jdv/web-control-agent.git web-control
-        cd web-control
+### 🛠️ 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.
 
-2. **Install dependencies:**
+### 🚀 Installation Guide
 
+#### 0. Root Privileges
+All installation steps must be executed as the `root` user. Before starting, elevate your privileges by running:
+```bash
+sudo su
+```
+
+#### 1. Clone the Repository
+Clone the agent into `/opt` to ensure path consistency:
+```bash
+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
+```bash
+python3 -m venv venv
+source venv/bin/activate
 pip install -r requirements.txt
+```
 
-3. **Configure:** Edit `node_config.json` with your MQTT credentials and a unique `client_id`.
-4. **Run:** `python3 system_monitor.py`
+#### 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)
+```bash
+cp fleet-agent.service /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable fleet-agent
+systemctl start fleet-agent
+```
 
 ---
 
 <a name="italiano"></a>
 ## 🇮🇹 Italiano
 
-Il **Fleet Control Agent** è uno script di monitoraggio leggero progettato per i nodi remoti (Raspberry Pi / Linux). Raccoglie la telemetria hardware ed esegue i comandi inviati dalla Dashboard Centrale tramite protocollo MQTT.
+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.
 
-### ✨ Funzionalità
-* **Telemetria in Tempo Reale:** Monitoraggio di utilizzo CPU, RAM, Temperatura e spazio su Disco.
-* **Gestione Servizi:** Avvio, arresto o riavvio remoto dei demoni di sistema (MMDVMHost, DMRGateway, ecc.).
-* **Auto-Healing Intelligente:** Rileva automaticamente i servizi andati in blocco e tenta di riavviarli autonomamente.
-* **Reset Hardware (GPIO):** Invia un impulso di reset fisico alla scheda radio MMDVM tramite i pin GPIO direttamente dalla dashboard.
+> ℹ️ **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)](https://git.arifvg.it/iv3jdv/fleet-control-server) sul tuo hub centrale.
 
-### 🚀 Installazione Rapida
-1. **Clona il repository:**
+### ✨ 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.
 
-        git clone https://git.arifvg.it/iv3jdv/web-control-agent.git web-control
-        cd web-control
+### 🤖 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.
 
-2. **Installa le dipendenze:**
+### 🛠️ 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:
+```bash
+sudo su
+```
+
+#### 1. Clonazione del Repository
+Clona l'agente nella cartella `/opt` per garantire la coerenza con i servizi systemd:
+```bash
+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)
+```bash
+python3 -m venv venv
+source venv/bin/activate
 pip install -r requirements.txt
+```
 
-3. **Configurazione:** Modifica il file `node_config.json` inserendo le tue credenziali MQTT e un `client_id` univoco.
-4. **Avvio:** `python3 system_monitor.py`
+#### 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)
+```bash
+cp fleet-agent.service /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable fleet-agent
+systemctl start fleet-agent
+```
 
 ---
 *Created by IV3JDV @ ARIFVG - 2026*

install.txt

@@ -1,34 +1,58 @@
 ============================================================
-       INSTALLATION GUIDE - FLEET CONTROL AGENT
+       INSTALLATION GUIDE - FLEET NODE AGENT
 ============================================================
 
 This script is meant to be installed on each remote node
-(e.g., Raspberry Pi, MMDVM host).
+(e.g., Raspberry Pi, MMDVM host). [cite: 11]
+
+------------------------------------------------------------
+0. IMPORTANT: ROOT PRIVILEGES
+------------------------------------------------------------
+All installation steps must be executed as the "root" user.
+Before starting, elevate your privileges by running:
+   sudo su
 
 ------------------------------------------------------------
 1. PRE-REQUISITES & INSTALLATION
 ------------------------------------------------------------
-Ensure Python 3 is installed.
+Ensure Python 3 is installed. [cite: 12]
 
 Install dependencies:
-   pip install -r requirements.txt
+   sudo git clone https://git.arifvg.it/iv3jdv/fleet-node-agent.git /opt/fleet-node-agent
+   cd /opt/fleet-node-agent
+   sudo python3 -m venv venv
+   source venv/bin/activate
+   pip install -r requirements.txt [cite: 12]
 
 ------------------------------------------------------------
-2. CONFIGURATION
+2. CONFIGURATION (CRITICAL STEPS)
 ------------------------------------------------------------
-1. Copy 'system_monitor.py' and 'node_config.json' to 
-   your preferred folder (e.g., '/opt/node_agent/').
-2. Edit 'node_config.json' with a unique 'client_id' and
-   your MQTT broker credentials.
-3. (Optional) Install 'RPi.GPIO' if you want hardware reset.
+A) MAIN CONFIG:
+   cp node_config.json.example node_config.json
+   Edit 'node_config.json' with a unique 'client_id' and
+   your MQTT broker credentials. [cite: 13]
+
+B) MONITORING PROCESSES (process_list.txt):
+   cp process_list.txt.example process_list.txt
+   Add the names of services you want to monitor (one per line). [cite: 8]
+   Example: mmdvmhost
+
+C) REMOTE EDITING FILES (file_list.txt):
+   cp file_list.txt.example file_list.txt
+   Add the full absolute paths of the .ini files you want 
+   to edit remotely from the dashboard. [cite: 10]
+   Example: /etc/MMDVMHost.ini
+
+D) OPTIONAL:
+   Install 'RPi.GPIO' if you want hardware reset. [cite: 14]
 
 ------------------------------------------------------------
 3. RUNNING AS A SERVICE (SYSTEMD)
 ------------------------------------------------------------
-1. sudo cp fleet-agent.service /etc/systemd/system/
-2. sudo systemctl daemon-reload
-3. sudo systemctl enable fleet-agent
-4. sudo systemctl start fleet-agent
+1. cp fleet-agent.service /etc/systemd/system/
+2. systemctl daemon-reload
+3. systemctl enable fleet-agent
+4. systemctl start fleet-agent
 
 
 ============================================================
@@ -36,29 +60,54 @@ Install dependencies:
 ============================================================
 
 Questo script va installato su ogni nodo remoto 
-(es. Raspberry Pi, MMDVM host).
+(es. Raspberry Pi, MMDVM host). [cite: 11]
+
+------------------------------------------------------------
+0. IMPORTANTE: PRIVILEGI DI ROOT
+------------------------------------------------------------
+Tutti i passaggi di installazione devono essere eseguiti 
+come utente "root". Prima di iniziare, eleva i tuoi privilegi:
+   sudo su
 
 ------------------------------------------------------------
 1. REQUISITI E INSTALLAZIONE
 ------------------------------------------------------------
-Assicurarsi di avere Python 3 installato.
+Assicurarsi di avere Python 3 installato. [cite: 15]
 
-Installa le dipendenze:
-   pip install -r requirements.txt
+Installazione:
+   sudo git clone https://git.arifvg.it/iv3jdv/fleet-node-agent.git /opt/fleet-node-agent
+   cd /opt/fleet-node-agent
+   sudo python3 -m venv venv
+   source venv/bin/activate
+   pip install -r requirements.txt [cite: 15]
 
 ------------------------------------------------------------
-2. CONFIGURAZIONE
+2. CONFIGURAZIONE (PASSAGGI CRITICI)
 ------------------------------------------------------------
-1. Copia 'system_monitor.py' e 'node_config.json' in 
-   una cartella (es. '/opt/node_agent/').
-2. Modifica 'node_config.json' inserendo un 'client_id'
-   univoco e i dati del server MQTT.
-3. (Opzionale) Installa 'RPi.GPIO' per il reset hardware.
+A) CONFIGURAZIONE PRINCIPALE:
+   cp node_config.json.example node_config.json
+   Modifica 'node_config.json' inserendo un 'client_id'
+   univoco e i dati del server MQTT. [cite: 16]
+
+B) MONITORAGGIO PROCESSI (process_list.txt):
+   cp process_list.txt.example process_list.txt
+   Aggiungi i nomi dei servizi da monitorare (uno per riga). [cite: 8]
+   Esempio: mmdvmhost
+
+C) EDITING FILE REMOTO (file_list.txt):
+   cp file_list.txt.example file_list.txt
+   Aggiungi i percorsi assoluti dei file .ini che desideri
+   poter modificare remotamente dalla dashboard. [cite: 10]
+   Esempio: /etc/MMDVMHost.ini
+
+D) OPZIONALE:
+   Installa 'RPi.GPIO' per il reset hardware. [cite: 17]
 
 ------------------------------------------------------------
 3. ESECUZIONE COME SERVIZIO (SYSTEMD)
 ------------------------------------------------------------
-1. sudo cp fleet-agent.service /etc/systemd/system/
-2. sudo systemctl daemon-reload
-3. sudo systemctl enable fleet-agent
-4. sudo systemctl start fleet-agent
+1. cp fleet-agent.service /etc/systemd/system/
+2. systemctl daemon-reload
+3. systemctl enable fleet-agent
+4. systemctl start fleet-agent
+============================================================

system_monitor.py

@@ -14,12 +14,17 @@ import configparser
 import logging
 from logging.handlers import RotatingFileHandler
 
+# --- CALCOLO PERCORSI DINAMICI ---
+AGENT_DIR = os.path.dirname(os.path.abspath(__file__))
+LOG_FILE = os.path.join(AGENT_DIR, 'node_agent.log')
+CONFIG_FILE = os.path.join(AGENT_DIR, 'node_config.json')
+
 # ==========================================
 # 0. LOGGING & HARDWARE CONFIGURATION
 # ==========================================
 logging.basicConfig(
     handlers=[
-        RotatingFileHandler('/opt/node_agent.log', maxBytes=2000000, backupCount=3),
+        RotatingFileHandler(LOG_FILE, maxBytes=2000000, backupCount=3),
         logging.StreamHandler()
     ],
     level=logging.INFO,
@@ -38,7 +43,7 @@ except ImportError:
 # ==========================================
 # 1. UNIFIED CONFIGURATION LOADING
 # ==========================================
-CONFIG_PATH = Path("/opt/node_config.json")
+CONFIG_PATH = Path(CONFIG_FILE)
 
 def load_config():
     try:
@@ -170,10 +175,7 @@ def get_system_status():
         "disk_usage_percent": psutil.disk_usage('/').percent,
         "processes": {},
         "timestamp": time.strftime("%H:%M:%S"),
-        "profiles": {
-            "A": cfg.get('profiles', {}).get('A', {}).get('label', 'PROFILE A'),
-            "B": cfg.get('profiles', {}).get('B', {}).get('label', 'PROFILE B')
-        }
+        "profiles": { k: v.get('label', f'PROFILE {k}') for k, v in cfg.get('profiles', {}).items() }
     }
     proc_path = Path(cfg['paths'].get('process_list', ''))
     if proc_path.exists():

systemd/fleet-agent.service

@@ -6,8 +6,8 @@ After=network.target
 Type=simple
 # Agent must be run as root for services restart (MMDVMHost etc.) and use GPIO
 User=root
-WorkingDirectory=/opt/node_agent
-ExecStart=/usr/bin/python3 /opt/node_agent/system_monitor.py
+WorkingDirectory=/opt/fleet-node-agent
+ExecStart=/opt/fleet-node-agent/venv/bin/python3 /opt/fleet-node-agent/system_monitor.py
 Restart=always
 RestartSec=10