Comandi
Comandi CLI di MeshCore: la guida completa
Sintassi, effetti, esempi e rischi di ogni comando CLI per amministrare repeater e room server MeshCore.
Accesso alla CLI
Come raggiungere la console del nodo
Ogni repeater e room server MeshCore espone una console di comandi testuali, raggiungibile in due modi.
Il primo è via USB seriale: colleghi il nodo al computer con un cavo dati (non solo di ricarica) e apri una console seriale, ad esempio il web flasher ufficiale dal browser oppure picocom da terminale su Linux. Questo metodo funziona anche prima di aver mai configurato il nodo, perché non richiede una rete mesh già funzionante. Il secondo è da remoto, tramite un client MeshCore (app o web) già autenticato come amministratore sul nodo target: utile per un repeater o un room server già installato in un punto alto o difficile da raggiungere fisicamente. In entrambi i casi serve la password admin, il cui valore di default è password: cambiala non appena metti in servizio un nodo, con il comando descritto più sotto. Alcuni comandi diagnostici (stats-core, stats-radio, stats-packets, log) funzionano solo via USB seriale, segnati qui sotto con "(solo seriale)": da remoto l'equivalente è la richiesta di stato del repeater nell'app client, che mostra batteria, coda di trasmissione, noise floor, ultimo RSSI, pacchetti inviati/ricevuti e contatori flood/diretti, leggibile anche dagli ospiti senza permessi di amministrazione.
Per l'elenco delle board supportate e delle differenze tra chip ESP32 e nRF52 (rilevanti per capire quale comando OTA usare) consulta la guida hardware alle board LoRa compatibili con MeshCore. Se il flasher o il terminale seriale non vedono la porta su Linux, è quasi sempre un problema di permessi: la pagina soluzioni ai problemi più comuni di MeshCore spiega come risolverlo con setfacl.
Identità del nodo
Nome e password amministrativa
| Comando | Effetto |
|---|---|
set name <nome> | Cambia il nome del nodo mostrato negli advert e nei contatti degli altri nodi. |
password <nuova-password> | Cambia la password amministrativa della console (default password). |
Esempio per un repeater a Torino, seguendo la convenzione di naming della community: set name IT-Torino-RPT-01. Dopo un cambio nome è buona norma inviare subito un nuovo advert (vedi sotto) così che i nodi vicini aggiornino il contatto. Per la password, scegline una che non condividi con altri servizi: la console non offre un modo per leggerla in chiaro, solo per sovrascriverla.
Radio
Preset, potenza e diagnostica radio
| Comando | Effetto |
|---|---|
get radio / set radio <freq>,<bw>,<sf>,<cr> | Legge o imposta frequenza, banda, spreading factor e coding rate in un solo comando. Richiede reboot per applicarsi. |
get freq / set freq <MHz> | Legge o cambia la sola frequenza, senza toccare banda, SF o CR. |
get tx / set tx <dbm> | Legge o imposta la potenza di trasmissione in dBm (1–22). |
set lat <lat> / set lon <lon> | Imposta la posizione GPS del nodo, usata per la mappa pubblica e per l'advert. |
advert | Invia subito un advert flood, senza aspettare l'intervallo periodico. |
set flood.advert.interval <ore> | Cambia l'intervallo dell'advert flood periodico, 3–168 ore (default 12 sui repeater, 0 sui sensori = disattivato). |
set advert.interval <minuti> | Imposta l'intervallo dell'advert "zero-hop" (non ripropagato), 60–240 minuti (default 0 = disattivato). |
advert.zerohop | Invia subito un advert zero-hop, udibile solo dai vicini diretti, senza propagazione flood. |
discover.neighbors | Avvia una scoperta attiva dei vicini a zero hop, distinta dal semplice ascolto passivo di neighbors. |
set repeat <on|off> | Attiva o disattiva la ripetizione dei pacchetti altrui su un repeater o room server. |
set flood.max <hop> | Numero massimo di hop per qualsiasi pacchetto in flood (default 64). |
set flood.max.advert <hop> | Numero massimo di hop di propagazione per gli advert su repeater e room server (default 8): oltre questa distanza l'advert non viene più ripetuto. |
set dutycycle <1-100> | Limita il duty cycle radio in percentuale (fw ≥ 1.15, default 50%). Nella sotto-banda italiana 869.4–869.65 MHz, dove il limite normativo è 10%, imposta set dutycycle 10. |
set af <0-9> | Fattore di limitazione del duty cycle sulle firmware precedenti alla 1.15 (deprecato): duty ≈ 1/(1+af), default 1 (~50%). Per il 10% della sotto-banda italiana usa set af 9. |
neighbors | Elenca i vicini diretti uditi di recente: mostra solo gli 8 advert più recenti. Funziona anche da remoto. |
stats-radio (solo seriale) | Mostra noise floor, ultimo RSSI/SNR e airtime del radio. Comando USB seriale, non disponibile da remoto. |
stats-packets (solo seriale) | Mostra i contatori dei pacchetti ricevuti e inviati. Comando USB seriale, non disponibile da remoto. |
log start / log stop | Avvia o ferma la cattura del log di ricezione radio, utile per diagnosticare la copertura. Disponibile anche da remoto. |
log (solo seriale) | Stampa il log catturato. Comando USB seriale, non disponibile da remoto. |
Per allineare un nodo al preset condiviso dalla community italiana il comando è set radio 869.618,62.5,8,8 seguito da reboot: i dettagli sul preset, sul perché è cambiato e sulla differenza col vecchio preset deprecato sono nella pagina dedicata al preset radio italiano per MeshCore. Attenzione: cambiare i parametri radio su un nodo già in servizio lo disallinea immediatamente dal resto della mesh finché non lo riporti allo stesso preset di tutti gli altri; su un repeater o room server condiviso, annuncia la modifica nel gruppo prima di farla, così chi dipende da quel nodo non perde copertura senza preavviso. Il significato tecnico di banda, spreading factor, coding rate, RSSI, SNR e airtime è spiegato nel glossario dei termini tecnici MeshCore.
Alimentazione
Risparmio energetico e stato del nodo
| Comando | Effetto |
|---|---|
powersaving <on|off> | Attiva o disattiva il risparmio energetico: il nodo dorme tra una trasmissione e l'altra. |
stats-core (solo seriale) | Mostra stato batteria, uptime e coda messaggi del nodo. Comando USB seriale, non disponibile da remoto. |
Su un repeater alimentato a batteria o pannello solare, powersaving on è spesso la prima leva da usare se l'autonomia non basta, insieme a una potenza TX (set tx) non più alta del necessario per la copertura richiesta. Se la batteria si scarica comunque troppo in fretta, stats-core aiuta a capire se il problema è di consumo o se il nodo si sta riavviando in loop: la pagina soluzioni ai problemi più comuni di MeshCore copre anche questo caso insieme ad altri sintomi frequenti.
Orologio
Sincronizzazione dell'ora
| Comando | Effetto |
|---|---|
time <epoch> | Imposta manualmente l'orologio del nodo, utile su board senza GPS o senza fix. |
clock sync | Sincronizza l'orologio del nodo con quello del dispositivo collegato (companion o client admin). |
Un orologio sbagliato è una delle cause più comuni per cui un nodo sembra "sparito": gli advert non risultano validi e il nodo smette di comparire come recente nei contatti altrui. Su una board con GPS (ad esempio LilyGO T-Beam o T-Deck) il fix corregge l'ora da solo appena disponibile; su una board senza GPS, o finché il fix non arriva, usa clock sync da un client collegato oppure imposta l'epoch manualmente con time <epoch> via seriale.
Amministrazione e OTA
Riavvio e aggiornamento firmware
| Comando | Effetto |
|---|---|
reboot | Riavvia il nodo: necessario dopo aver cambiato parametri radio o nome. |
start ota | Avvia l'aggiornamento firmware via OTA (Wi-Fi su ESP32, DFU su nRF52). |
Su board ESP32 come Heltec V3, start ota apre un hotspot Wi-Fi chiamato "MeshCore OTA": ti colleghi a quell'hotspot dal telefono o dal computer e vai su 192.168.4.1/update per caricare il nuovo firmware. Su board nRF52 (RAK4631, Heltec T114, Seeed XIAO) lo stesso comando prepara il nodo, ma il caricamento avviene con l'app nRF DFU dello smartphone. In entrambi i casi non scollegare l'alimentazione del nodo durante il trasferimento: un OTA interrotto a metà può lasciare il nodo in uno stato da recuperare via USB con il web flasher. Nota anche la differenza tra bin "merged" (azzera l'abbinamento Bluetooth esistente ma mantiene nome, chiavi e preset salvati) e bin "non-merged" (mantiene l'abbinamento Bluetooth): la scelta sbagliata costringe a un nuovo pairing BLE non necessario. La domanda "come aggiorno il firmware" è coperta con più dettaglio anche nella pagina domande frequenti su MeshCore in italiano.
Novità firmware
Firmware recenti: path hash, loop detect e region scoping
| Comando | Effetto |
|---|---|
set path.hash.mode <0-2> | Dimensione dell'ID/hash con cui il repeater si annuncia negli advert: 0 = 1 byte (default, max 64 hop), 1 = 2 byte (max 32 hop), 2 = 3 byte (max 21 hop). Non cambia cosa il repeater inoltra: dalla 1.14 inoltra tutte le dimensioni. |
set loop.detect <off|minimal|moderate|strict> | Scarta i pacchetti flood in cui l'ID del repeater compare già troppe volte nel percorso, per fermare le tempeste di pacchetti causate da firmware difettosi (default off). |
set flood.max.unscoped <hop> | Numero massimo di hop per i pacchetti in flood non associati a una region (default 64). |
region home | Imposta la region "di casa" del nodo, usata come riferimento per lo scoping del traffico. |
region put <nome> | Aggiunge o aggiorna una region nella tabella locale del nodo. |
region allowf <nome> / region denyf <nome> | Consente o nega esplicitamente il flood verso/da una region. |
region save | Salva la configurazione delle region in memoria persistente. |
path.hash.mode e loop.detect sono stati introdotti in firmware 1.14: un repeater con firmware 1.13 o precedente scarta silenziosamente i pacchetti con hash di percorso a 2 o 3 byte, senza segnalare errore. Prima di impostare path.hash.mode 1 o 2 su un nodo condiviso, verifica che i repeater della zona siano aggiornati almeno alla 1.14 (release repeater corrente: v1.17.1), altrimenti i tuoi advert arriveranno meno lontano. Lo scoping per region (region home, region put, region allowf/denyf, region save, disponibile dalla 1.10) e flood.max.unscoped permettono di limitare la propagazione flood a un sottoinsieme di nodi, utile per reti molto estese dove non tutto il traffico deve raggiungere tutti gli hop.