Hermes: Installazione e problemi comuni
Guida operativa per mettere in piedi Hermes e per capire cosa non va quando la mesh sembra funzionare ma in Home Assistant non succede niente.
Per cosa fa l’integrazione e come impostarla in sicurezza vedi Hermes - Come funziona e sicurezza.
Prerequisiti
- Home Assistant recente: servono config flow, options flow moderno e
TargetSelector. - Integrazione Meshtastic ufficiale già installata e configurata (
domain: meshtastic), con almeno un gateway connesso. Hermes dipende dal suo eventomeshtastic_api_text_messagee dal serviziomeshtastic.send_text. Solo una integrazione può tenere la connessione al nodo: non farne girare due sullo stesso dispositivo. - Firmware Meshtastic con PKC (≥ 2.5) se vuoi usare i messaggi diretti come canale affidabile.
- Sapere quale nodo è il gateway, cioè quello fisicamente collegato a Home Assistant.
Firmware: allineare tutto prima di iniziare
Tutti i nodi e i repeater dovrebbero avere la stessa versione firmware, o versioni note come compatibili. Versioni miste producono il caso confuso in cui un messaggio arriva a un nodo e non a un altro, e nessuna configurazione lato Home Assistant lo risolve.
I messaggi diretti richiedono firmware recente su entrambi i lati: dopo il passaggio alla crittografia a chiave pubblica, un DM da o verso un nodo con build vecchia non è decifrabile dall’altro capo. Il messaggio non arriva mai a Home Assistant, nessuna entità cambia stato e nel log di Hermes non compare nulla. Se un nodo non è aggiornabile, usa un canale per quel nodo.
Home Assistant conosce la versione firmware del solo gateway: la trovi nella tab Settings. Le altre vanno verificate dall’app Meshtastic.
Installazione via HACS
- Aggiungi il repository
Pricesswg/Hermes_Messengercome integrazione custom in HACS, poi Download. - Riavvia Home Assistant.
- Impostazioni → Dispositivi e servizi → Aggiungi integrazione → Hermes.
- Aggiungi la card a una dashboard: Modifica dashboard → Aggiungi card → Hermes.
La card si registra da sola: non c’è nessuna risorsa Lovelace da aggiungere a mano. Una vista Panel (1 card) è la sistemazione migliore, perché la card occupa tutto lo schermo.
Prima configurazione
| Passo | Cosa scegliere |
|---|---|
| Nodo gateway | Il nodo collegato a Home Assistant |
| Modalità | Ascolta su un canale oppure Ascolta i messaggi diretti |
| Canale | In modalità canale: la lista è letta dalla radio, si sceglie per nome |
| Nodi autorizzati | Solo questi possono attivare comandi; tutti gli altri sono ignorati senza risposta |
Tutto è modificabile in seguito dalla card, sezione Settings, senza ricreare nulla.
Le card disponibili
type: custom:hermes-card # pannello completo
type: custom:hermes-summary-card # riepilogo di sola lettura
type: custom:hermes-chat-card # lettura e invio messaggiLe due card ridotte prendono solo l’altezza che serve e non modificano nessuna impostazione: stanno bene in una colonna accanto a luci e termostato.
Dopo un aggiornamento
Riavvia Home Assistant, poi ricarica la pagina con un hard refresh (Ctrl+Shift+R, Cmd+Shift+R su Mac).
Il motivo: il Python cambia solo al riavvio, mentre la card è un modulo JavaScript che il browser tiene in cache, e Home Assistant continua ad annunciare l’URL ricevuto all’avvio finché non riparte. Hermes serve la card da una copia in /config/www e non dalla propria cartella, perché HACS cancella e riscrive quella cartella durante l’aggiornamento: la copia mantiene disponibile l’ultimo bundle funzionante invece di rispondere 404 mentre i file vengono sostituiti.
La tab Status mostra le due versioni affiancate, quindi un disallineamento è visibile. Se la card si dichiara ancora unknown element, la console del browser stampa la versione caricata come HERMES-CARD <versione>.
Non arriva niente: diagnosi in ordine
Apri Status e leggi il pannello Reception dall’alto. Ogni riga esclude quelle sotto.
1. La radio è connessa?
Se dice radio not connected, fermati qui: l’integrazione Meshtastic non ha link al suo nodo, quindi nessun messaggio può arrivare e nessuno può partire.
Trappola classica: un’app collegata direttamente alla radio continua a mostrare il traffico perfettamente, perché non passa da Home Assistant. Vedere i messaggi lì non significa che Home Assistant li stia ricevendo.
2. Hermes sta girando?
Not running significa che l’integrazione non si è caricata. Le impostazioni continuano a mostrarsi correttamente perché sono lette dallo storage, quindi una configurazione rotta sembra sana. Controlla Impostazioni → Dispositivi e servizi.
3. Gli eventi arrivano?
Il contatore Mesh events reaching Hermes conta ogni messaggio prima di qualsiasi filtro.
- Zero mentre i messaggi attraversano la mesh → il problema è a monte, non in Hermes.
- Sale → Hermes riceve, e l’errore è nella configurazione.
4. Corrisponde a questo gateway?
Il pannello affianca ciò che il gateway ascolta all’ultimo messaggio effettivamente arrivato. Se le due righe differiscono ottieni nothing is getting through, e ti dicono esattamente cosa cambiare in Settings.
La correzione va fatta a mano di proposito: adottare automaticamente quello che l’ultimo messaggio usava sposterebbe un gateway dai messaggi diretti a un canale sulla base di un pacchetto casuale, ed è esattamente la differenza tra un mittente verificato dal protocollo e chiunque possieda la chiave del canale.
Il gateway è sempre il nodo collegato a Home Assistant, mai quello da cui invii. Con più nodi sulla scrivania è un errore facilissimo.
5. Cosa ha deciso Hermes?
La tab Log mostra ogni messaggio letto, comprese le scartate e il perché:
| Esito | Significato |
|---|---|
command run | Corrispondenza trovata ed eseguita |
no command matched | Ricevuto, ma nessuna keyword corrisponde |
sender not authorized | Non in whitelist, scartato in silenzio |
ignored, another gateway | Arrivato tramite un nodo diverso |
ignored, another channel | Arrivato dove questo gateway non ascolta |
rate limit reached | Troppi comandi da quel nodo (default: 6 in 60 s) |
failed while being handled | Bug: i dettagli sono nel log di Home Assistant |
Altri problemi ricorrenti
La risposta non arriva o arriva monca. La radio può scartare le risposte immediate. In Configure → Send timing ci sono 5 s di attesa iniziale prima della prima risposta e 2 s tra le parti: sono default ragionevoli, non verità sperimentali, e vanno tarati sui tempi reali della propria mesh.
Messaggi troncati. Il limite di 200 byte per parte è il valore documentato; conviene confermarlo con il proprio firmware. Ogni messaggio in uscita passa comunque dallo splitter con intestazione (i/n) e non taglia mai a metà un carattere multibyte.
Un comando si ripete decine di volte. Quasi sempre un nodo guasto o un repeater che duplica pacchetti. È esattamente il caso che il rate limit intercetta: non disattivarlo.
Le maiuscole rompono il matching. Per default il confronto ignora le maiuscole, proprio perché le tastiere dei telefoni capitalizzano da sole la prima lettera. Esiste un’impostazione per renderlo stretto, ed è quasi sempre da lasciare disattivata.
Nodi senza posizione sulla mappa. Molti nodi pubblicano la posizione solo in fixed-point (latitudeI/longitudeI) e non nei campi float. Hermes legge entrambi, ma se un nodo non compare vale la pena verificare che stia effettivamente trasmettendo la posizione.
Dopo un aggiornamento maggiore dell’integrazione Meshtastic ufficiale. Schema dell’evento e firma di send_text sono verificati contro il branch main di meshtastic/home-assistant: dopo un major update vanno riconfermati.