From f91d23802dacc020026265b4521e5a2ccc438284 Mon Sep 17 00:00:00 2001 From: Roby Date: Sun, 26 Apr 2026 16:17:47 +0200 Subject: [PATCH] update README & install --- README.md | 103 +++++++++++++++++++++++++++++++++++++--------------- install.txt | 73 +++++++++++++++++++++++++++---------- 2 files changed, 128 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 12f9830..aaf8dc3 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# 🤖 Fleet Control Agent +# 🛰️ Fleet Control Agent 🌍 *[Read in English](#english) | 🇮🇹 [Leggi in Italiano](#italiano)* @@ -7,53 +7,98 @@ ## 🇬🇧 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. +### ✨ 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. -### 🚀 Quick Installation +### 🛠️ 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. -1. **Clone the repo:** +### 🚀 Installation Guide - git clone https://git.arifvg.it/iv3jdv/fleet-control-agent.git /opt/fleet-control-agent - cd /opt/fleet-control-agent +#### 1. Clone the Repository +Clone the agent into `/opt` to ensure path consistency: +```bash +sudo git clone [https://git.arifvg.it/iv3jdv/fleet-control-agent.git](https://git.arifvg.it/iv3jdv/fleet-control-agent.git) /opt/fleet-control-agent +cd /opt/fleet-control-agent +``` -2. **Install dependencies:** +#### 2. Virtual Environment Setup +```bash +sudo python3 -m venv venv +source venv/bin/activate +sudo pip install -r requirements.txt +``` - 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. -3. **Configure:** Edit `node_config.json` with your MQTT credentials and a unique `client_id`. -4. **Run:** `python3 system_monitor.py` +#### 4. Systemd Service (Auto-start) +```bash +sudo cp fleet-agent.service /etc/systemd/system/ +sudo systemctl daemon-reload +sudo systemctl enable fleet-agent +sudo systemctl start fleet-agent +``` --- ## 🇮🇹 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. +### ✨ 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. -### 🚀 Installazione Rapida -1. **Clona il repository:** +### 🛠️ 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. - git clone https://git.arifvg.it/iv3jdv/web-control-agent.git /opt/fleet-control-agent - cd /opt/fleet-control-agent +### 🚀 Guida all'Installazione -2. **Installa le dipendenze:** +#### 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-control-agent.git](https://git.arifvg.it/iv3jdv/fleet-control-agent.git) /opt/fleet-control-agent +cd /opt/fleet-control-agent +``` - pip install -r requirements.txt +#### 2. Setup Ambiente Virtuale (venv) +```bash +sudo python3 -m venv venv +source venv/bin/activate +sudo 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`. + +#### 4. Esecuzione come Servizio (systemd) +```bash +sudo cp fleet-agent.service /etc/systemd/system/ +sudo systemctl daemon-reload +sudo systemctl enable fleet-agent +sudo systemctl start fleet-agent +``` --- *Created by IV3JDV @ ARIFVG - 2026* diff --git a/install.txt b/install.txt index 34d8a6c..c574ad5 100644 --- a/install.txt +++ b/install.txt @@ -3,24 +3,41 @@ ============================================================ 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] ------------------------------------------------------------ 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-control-agent.git /opt/fleet-control-agent + cd /opt/fleet-control-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/fleet-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) @@ -36,24 +53,41 @@ Install dependencies: ============================================================ Questo script va installato su ogni nodo remoto -(es. Raspberry Pi, MMDVM host). +(es. Raspberry Pi, MMDVM host). [cite: 11] ------------------------------------------------------------ 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-control-agent.git /opt/fleet-control-agent + cd /opt/fleet-control-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) @@ -62,3 +96,4 @@ Installa le dipendenze: 2. sudo systemctl daemon-reload 3. sudo systemctl enable fleet-agent 4. sudo systemctl start fleet-agent +============================================================