Guida all'installazione
Versione corrente: v2.0
MeshCore Trace-Path Monitor è una dashboard web sviluppata in Node.js per il monitoraggio e l'analisi dei percorsi (Path) all'interno di una rete MeshCore.
Il sistema è composto da tre componenti principali.
Lo script trace.sh esegue periodicamente le acquisizioni delle tracce MeshCore.
data/trace.json;
Lo script backup.sh gestisce l'archiviazione mensile dei dati raccolti.
backup/;
trace.json
per il mese successivo;
La dashboard web costituisce l'interfaccia di consultazione del sistema e permette di:
Il progetto è stato sviluppato e testato su sistemi Linux.
Attualmente sono stati verificati i seguenti ambienti:
In generale il software è compatibile con qualsiasi distribuzione Unix/Linux dotata di Python 3 e Node.js.
L'utilizzo in ambiente Windows non è attualmente previsto, poiché alcuni componenti del sistema fanno uso di strumenti e funzionalità specifiche dell'ambiente Unix/Linux.
Prima di procedere con l'installazione del progetto è consigliabile aggiornare il sistema operativo e i pacchetti installati.
Di seguito sono riportati i principali comandi di aggiornamento per le distribuzioni Linux attualmente supportate.
sudo apt update sudo apt upgrade -y
sudo dnf update -y
Al termine dell'aggiornamento del sistema sarà possibile procedere con l'installazione dei componenti software necessari, descritti nei capitoli successivi.
La presente guida assume che l'installazione
venga eseguita utilizzando un utente dedicato
chiamato meshcore, appartenente al gruppo
degli utenti autorizzati all'utilizzo del comando
sudo.
Nel corso della documentazione verrà utilizzata come directory principale del progetto:
/home/meshcore/trace-mon
Tutti i percorsi e gli esempi riportati fanno riferimento a questa configurazione.
Prima di procedere è possibile verificare se Python è già presente nel sistema eseguendo il comando:
python3 --version
L'ambiente di riferimento utilizzato per lo sviluppo e i test del progetto è basato su:
Versioni successive della stessa major release dovrebbero risultare compatibili.
Se Python non è presente, oppure si desidera installare tutti i componenti richiesti dal progetto, è possibile utilizzare i seguenti comandi.
sudo apt install -y \ python3 \ python3-venv \ python3-pip \ python3-serial
sudo dnf install -y \ python3 \ python3-venv \ python3-pip \ python3-pyserial
Al termine dell'installazione è possibile verificare il corretto funzionamento dei componenti principali:
python3 --version pip3 --version
Se entrambi i comandi restituiscono una versione valida, l'ambiente Python è stato installato correttamente.
Nel capitolo successivo verrà creato un
ambiente virtuale Python dedicato
(.venv) all'interno della
directory:
/home/meshcore/trace-mon
All'interno di questo ambiente verrà
installato il pacchetto
meshcore-cli, utilizzato
dagli script del progetto per
l'acquisizione delle tracce MeshCore.
Dopo aver completato l'installazione dei componenti software necessari, è possibile procedere con l'installazione del pacchetto MeshCore Trace-Path Node.
Il pacchetto software è disponibile nell'area Software Download del sito web del progetto.
Scaricare la versione desiderata e decomprimere il contenuto all'interno della directory di lavoro:
/home/meshcore/trace-mon
Il pacchetto contiene tutti i file necessari al funzionamento del nodo, inclusi:
trace.sh,
backup.sh,
e
sync-meshnode.sh;
requirements.txt;
meshcore-trace-mon.service.
Una volta completata l'estrazione dei file, sarà possibile proseguire con la configurazione della struttura del progetto, descritta nel capitolo successivo.
Dopo aver completato l'installazione del software, la directory principale del progetto presenterà una struttura simile alla seguente.
trace-mon/ | |-- .venv/ |-- backup/ |-- data/ |-- public/ | |-- parser.js |-- server.js |-- package.json
Le principali directory del progetto hanno le seguenti funzioni.
Contiene l'ambiente virtuale
Python e tutte le dipendenze
necessarie all'esecuzione
di meshcore-cli.
Contiene gli archivi mensili
compressi generati dallo
script backup.sh.
Ogni archivio utilizza una nomenclatura del tipo:
trace-2026-06.json.gz
Contiene il file dati live utilizzato dalla dashboard:
trace.json
Questo file viene aggiornato
periodicamente dallo script
trace.sh.
Contiene tutti i file statici utilizzati dalla dashboard web.
public/ | |-- app.js |-- index.html |-- style.css
Costituisce il server web Node.js che espone la dashboard e rende disponibili i dati raccolti dal nodo.
Implementa le funzioni di elaborazione dei dati e prepara le informazioni utilizzate dalla dashboard.
È il file di configurazione
del progetto Node.js e contiene
le informazioni relative alle
dipendenze installate tramite
npm.
Durante l'installazione verranno inoltre create automaticamente eventuali directory e file aggiuntivi necessari al corretto funzionamento dell'ambiente Node.js.
A questo punto è possibile procedere
con l'installazione del pacchetto
meshcore-cli e delle
relative dipendenze Python necessarie
al funzionamento del nodo.
Le operazioni descritte in questo capitolo devono essere eseguite utilizzando l'utente meshcore.
L'utente dovrà:
sudo;
/dev/ttyUSB*;
requirements.txt,
fornito insieme al pacchetto
software del progetto.
Tutte le operazioni successive dovranno essere eseguite all'interno della directory principale del progetto:
cd /home/meshcore/trace-mon
Il progetto utilizza un ambiente
virtuale Python dedicato
(.venv) per mantenere
separati i componenti software
necessari al funzionamento del nodo
dal resto del sistema operativo.
python3 -m venv .venv
Prima di procedere con l'installazione delle dipendenze, è consigliabile aggiornare il gestore dei pacchetti Python:
.venv/bin/pip install --upgrade pip
Il file
requirements.txt
contiene l'elenco completo dei
pacchetti Python richiesti
dal progetto.
Oltre al pacchetto
meshcore-cli,
verranno installati automaticamente
anche gli altri moduli necessari
alla comunicazione con il
dispositivo LoRa.
.venv/bin/pip install -r ./requirements.txt
Al termine della procedura,
tutti i componenti Python necessari
saranno disponibili all'interno
della directory
.venv.
Gli script del progetto utilizzeranno direttamente gli eseguibili presenti nell'ambiente virtuale mediante percorsi assoluti, senza richiedere l'attivazione manuale dell'ambiente Python.
La dashboard MeshCore Trace-Path
è sviluppata utilizzando
Node.js e richiede
la presenza del gestore dei
pacchetti npm.
Prima di procedere con l'installazione è possibile verificare se Node.js è già presente nel sistema.
node -v npm -v
Se entrambi i comandi restituiscono una versione valida, è possibile procedere direttamente all'inizializzazione del progetto.
Se Node.js non risulta
installato, si consiglia
di utilizzare
nvm
(Node Version Manager),
che permette di gestire
facilmente gli aggiornamenti
e le future versioni di
Node.js.
Installare quindi il
pacchetto nvm.
Al momento della stesura di questa guida è possibile utilizzare il seguente comando:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
Si tratta di un semplice
riferimento operativo che
potrebbe non essere aggiornato
nelle future versioni del
progetto nvm.
In caso di problemi di installazione o per verificare la disponibilità di versioni più recenti, si consiglia di consultare la documentazione ufficiale del progetto.
Dopo aver installato
nvm,
utilizzare il comando
previsto dalla documentazione
ufficiale per installare
l'ultima versione
LTS (Long Term Support)
di Node.js.
nvm install --lts
Al termine dell'installazione, verificare nuovamente il corretto funzionamento eseguendo:
node -v npm -v
Posizionarsi nella directory principale del progetto:
cd /home/meshcore/trace-mon
Inizializzare il progetto Node.js con il comando:
npm init -y
Questo comando creerà il file
package.json,
utilizzato da Node.js per
la gestione del progetto e
delle relative dipendenze.
La dashboard utilizza il
framework
express
per fornire il servizio web.
Procedere quindi con l'installazione del modulo:
npm install express
Al termine della procedura il progetto Node.js sarà inizializzato correttamente e conterrà tutte le dipendenze necessarie al funzionamento della dashboard web.
Nel capitolo successivo verrà illustrata l'installazione del pacchetto software del nodo e la struttura finale del progetto.
Il pacchetto software include
lo script trace.sh,
utilizzato per eseguire
periodicamente le acquisizioni
dei percorsi MeshCore e
aggiornare il file dati live
data/trace.json.
Di seguito viene riportato un semplice esempio di configurazione dello script.
#!/bin/bash
cd /home/meshcore/trace-mon/data
APP="/home/meshcore/trace-mon/.venv/bin/meshcore-cli -j -s /dev/ttyUSB0 -b 115200 trace"
NODE="node_01"
PATHS=(
"0d28,8dbb,0d28"
)
for T_PATH in "${PATHS[@]}"
do
DATE=$(date +"%Y%m%d_%H%M%S")
echo "$DATE $T_PATH" >> trace.json
$APP "$T_PATH" >> trace.json
sleep 10
done
scp -P 15450 trace.json trace-mon@77.81.226.128:/home/trace-mon/data/$NODE
exit 0
La variabile APP
contiene il comando utilizzato
per eseguire
meshcore-cli.
In base alla propria configurazione hardware potrebbe essere necessario modificare i parametri utilizzati, come ad esempio la porta seriale o eventuali opzioni aggiuntive.
La variabile NODE
contiene il codice del nodo da
identificare sul server centrale.
Per eseguire più rilevazioni
durante la stessa esecuzione
dello script, è possibile
modificare opportunamente
il valore della variabile
PATHS.
Lo script completo fornito con il pacchetto può essere ulteriormente personalizzato in base alle esigenze della propria rete MeshCore.
Il pacchetto software include
lo script
backup.sh,
utilizzato per eseguire
automaticamente
l'archiviazione mensile
del file dati live.
Di seguito viene riportato un esempio dello script.
#!/bin/bash
cd /home/meshcore/trace-mon
NODE="node_01"
YEAR=$(date +"%Y")
MONTH=$(date +"%m")
MONTH=$((10#$MONTH - 1))
if [ $MONTH -eq 0 ]; then
MONTH=12
YEAR=$((YEAR - 1))
fi
MONTH=$(printf "%02d" "$MONTH")
FILEOUT="trace-$YEAR-$MONTH.json"
FILEOUTZIP="trace-$YEAR-$MONTH.json.gz"
cp data/trace.json backup/$FILEOUT
sleep 10
gzip backup/$FILEOUT
sleep 10
rm -f data/trace.json
sleep 10
touch data/trace.json
sleep 10
cd /home/meshcore/trace-mon/backup
scp -P 15450 $FILEOUTZIP trace-mon@77.81.226.128:/home/trace-mon/backup/$NODE
exit 0
Lo script esegue automaticamente le operazioni necessarie per chiudere il periodo di acquisizione corrente ed iniziare quello nuovo.
trace.json;
backup/;
trace.json
per il mese successivo.
L'esecuzione automatica
degli script viene gestita
tramite il servizio
cron.
Per modificare il proprio crontab utilizzare il comando:
crontab -e
Un esempio di configurazione utilizzata dal progetto è il seguente:
*/30 * * * * /home/meshcore/trace-mon/trace.sh > /dev/null 2>&1 2 0 1 * * /home/meshcore/trace-mon/backup.sh > /dev/null 2>&1
trace.sh
viene eseguito ogni
30 minuti;
backup.sh
viene eseguito alle
ore 00:02 del primo
giorno di ogni mese.
Il pacchetto software include
già il file
meshcore-trace-mon.service,
configurato per la struttura
standard descritta in questa
guida e normalmente non richiede
modifiche manuali.
Per installare il servizio copiarlo nella directory dei servizi di sistema:
sudo cp meshcore-trace-mon.service /etc/systemd/system/
Aggiornare quindi la configurazione di systemd:
sudo systemctl daemon-reload
Abilitare l'avvio automatico del servizio:
sudo systemctl enable meshcore-trace-mon
Avviare il servizio:
sudo systemctl start meshcore-trace-mon
Verificare il corretto funzionamento:
sudo systemctl status meshcore-trace-mon
I seguenti comandi consentono di arrestare, riavviare oppure disabilitare il servizio.
sudo systemctl stop meshcore-trace-mon sudo systemctl restart meshcore-trace-mon sudo systemctl disable meshcore-trace-mon