Il nodo non compare in app
Diagnosi: il nodo è acceso e nel raggio radio ma non compare nella lista contatti o discover del client. Causa: quasi sempre un problema di orologio: su un T-Deck può mancare il fix GPS o il baud rate GPS è sbagliato, oppure il nodo remoto ha l'ora sbagliata e i suoi advert vengono scartati. Soluzione: da un client admin lancia clock sync per sincronizzare l'orologio del nodo collegato, oppure imposta l'ora manualmente con time <epoch> via seriale; poi lancia advert per forzare un nuovo annuncio.
Il Bluetooth (BLE) non si accoppia
Diagnosi: il client MeshCore non trova il nodo tra i dispositivi Bluetooth disponibili, oppure il pairing fallisce. Causa: sul nodo è stato flashato il firmware Companion USB-only invece di Companion BLE: solo un companion accetta connessioni Bluetooth, un repeater o un room server non ne aprono mai una. Soluzione: verifica con il web flasher di aver installato il firmware Companion BLE corretto per la tua board; il PIN di pairing di default è 123456.
Il web flasher non vede la board (Linux)
Diagnosi: il browser mostra un errore del tipo “Failed to open serial port” quando provi a collegarti alla board dal web flasher. Causa: su Linux l'utente non ha i permessi di lettura e scrittura sulla porta seriale USB assegnata alla board. Soluzione: assegna i permessi con sudo setfacl -m u:$USER:rw /dev/ttyUSB0 (adatta il device path, ad esempio /dev/ttyACM0 per una board nRF), poi ricarica la pagina del web flasher e riprova la connessione.
Nessun nodo è raggiungibile
Diagnosi: il nodo trasmette regolarmente ma non riesce a sentire né a farsi sentire da nessun altro nodo della mesh. Causa: il preset radio — frequenza, banda, spreading factor o coding rate — non corrisponde a quello del resto della mesh: due nodi su preset diversi non comunicano, anche se vicini. Soluzione: controlla il preset attuale con get radio e riallinealo con set radio 869.618,62.5,8,8, poi riavvia con reboot.
La batteria dura poco
Diagnosi: un repeater alimentato a batteria si scarica molto più rapidamente del previsto. Causa: il risparmio energetico non è attivo, oppure la potenza di trasmissione è impostata più alta del necessario per la copertura richiesta. Soluzione: attiva il risparmio energetico con powersaving on — il nodo dorme tra una trasmissione e l'altra — e riduci la potenza TX con set tx <dbm> (intervallo 1–22 dBm); controlla il valore attuale con get tx.
Il firmware va aggiornato via OTA/DFU
Diagnosi: la board è già installata in un punto scomodo da raggiungere via USB e serve aggiornare il firmware da remoto. Causa: gli aggiornamenti via cavo richiedono accesso fisico alla board a ogni versione. Soluzione: su ESP32 lancia start ota dal client admin, collegati all'hotspot Wi-Fi “MeshCore OTA” e vai su 192.168.4.1/update; su board nRF (RAK, T114, Seeed XIAO) usa start ota insieme all'app nRF DFU sullo smartphone.
Il Bluetooth si disconnette in continuazione (Heltec V3)
Diagnosi: il collegamento BLE tra companion e app cade spesso, anche a pochi metri di distanza. Causa: su Heltec V3 l'antenna Bluetooth/Wi-Fi integrata è una piccola bobina sul circuito stampato, con portata di pochi metri. Soluzione: resta vicino al nodo durante l'uso; in alternativa, chi ha dimestichezza con la saldatura può sostituire l'antenna a bobina con un filo di circa 31 mm per migliorare la portata BLE — è una modifica hardware da valutare con cautela.
Il repeater sembra sordo, non sente più i nodi vicini
Diagnosi: un repeater che prima funzionava smette di sentire nodi che dovrebbero essere in portata, pur restando acceso e configurato correttamente. Causa: può trattarsi dell'AGC (Automatic Gain Control) del chip radio SX1262, che può bloccarsi in presenza di forti interferenze vicine alla frequenza usata. Soluzione: imposta un reset periodico dell'AGC con set agc.reset.interval <numero> — il valore è in secondi, in multipli di 4; set agc.reset.interval 4 è un buon punto di partenza.
Il dispositivo sembra corrotto o bloccato
Diagnosi: il nodo non risponde più correttamente o non entra più in funzionamento normale. Causa: una configurazione o un firmware corrotti, spesso dopo un aggiornamento interrotto. Soluzione: se riesci a collegarti dall'app, esporta le impostazioni, esegui un factory reset e poi reimportale dopo aver ripristinato il pairing Bluetooth; se non riesci a collegarti, usa il web flasher per entrare in modalità DFU, esegui “Erase Flash” e poi reinstalla il firmware con “Flash!”. Dalla versione firmware 1.7.0, le board con pulsante utente (alcune RAK, T114) hanno anche una modalità di recovery: tienilo premuto entro 8 secondi dall'accensione per accedere alla console del web flasher.
