homebridge-elmo

# homebridge-elmo Plugin Homebridge per integrare i sistemi di antifurto Elmo con HomeKit. ## Descrizione Questo plugin permette di controllare il tuo sistema di antifurto Elmo tramite l'app Casa di Apple. Supporta le seguenti funzionalità: - Visualizzazione dello stato del sistema (armato/disarmato) - Armamento e disarmamento del sistema - Supporto per diverse modalità di armamento (Casa, Via, Notte) - Configurazione personalizzata dei settori per ogni modalità - **Supporto per dispositivi individuali** (sensori di movimento, contatti magnetici, sensori di fumo) - **Polling veloce per dispositivi** con aggiornamenti in tempo reale (fino a 1 secondo) - Creazione automatica di accessori HomeKit per ogni dispositivo rilevato ## Sistemi supportati - Elmo e-Connect - IESS Metronet ## Dispositivi supportati Il plugin rileva automaticamente e crea accessori HomeKit per: - **Sensori di movimento/PIR** - Visualizzati come sensori di movimento in HomeKit - **Contatti magnetici** - Visualizzati come sensori di contatto (porte/finestre) - **Sensori di fumo** - Visualizzati come sensori di fumo - **Altri sensori** - Visualizzati come sensori di contatto generici Ogni dispositivo viene aggiornato con un polling veloce (configurabile da 1 a 60 secondi) per fornire aggiornamenti in tempo reale dello stato. ## Requisiti - Homebridge v1.3.0 o superiore - Node.js v14 o superiore - Python 3.6 o superiore - python3-venv - Un sistema di antifurto Elmo con accesso alle API cloud ## Installazione 1. Installa Homebridge (se non l'hai già fatto) 2. Installa questo plugin tramite l'interfaccia web di Homebridge o con il comando: ```bash npm install -g homebridge-elmo ``` 3. Configura il plugin tramite l'interfaccia web di Homebridge o modificando manualmente il file `config.json` ## Configurazione Ecco un esempio di configurazione: ```json { "platforms": [ { "platform": "ElmoSecuritySystem", "name": "Elmo Security System", "username": "il_tuo_username", "password": "la_tua_password", "code": "il_tuo_codice", "system": "e-connect", "domain": "default", "pollInterval": 30, "debug": false } ] } ``` ### Parametri di configurazione | Parametro | Tipo | Obbligatorio | Predefinito | Descrizione | |-----------|------|--------------|-------------|-------------| | `name` | string | No | `Elmo Security System` | Nome del dispositivo nell'app Casa | | `username` | string | Sì | - | Username per accedere al sistema Elmo | | `password` | string | Sì | - | Password per accedere al sistema Elmo | | `code` | string | Sì | - | Codice numerico per armare/disarmare il sistema | | `system` | string | No | `e-connect` | Tipo di sistema Elmo (`e-connect` o `metronet`) | | `domain` | string | No | `default` | Dominio utilizzato per accedere alla pagina di login via web | | `pollInterval` | number | No | `30` | Intervallo in secondi tra le richieste di aggiornamento dello stato del sistema | | `devicePollInterval` | number | No | `10` | Intervallo in secondi tra le richieste di aggiornamento dello stato dei dispositivi (1-60) | | `enableDevices` | boolean | No | `true` | Abilita la creazione di accessori per dispositivi individuali | | `debug` | boolean | No | `false` | Abilita i log di debug | | `homeSectors` | string | No | `""` | Settori da armare in modalità Casa (es: "1,3") | | `awaySectors` | string | No | `""` | Settori da armare in modalità Via (es: "1,2,3") | | `nightSectors` | string | No | `""` | Settori da armare in modalità Notte (es: "2,3") | ### Esempio di configurazione con polling ultra-veloce ```json { "platforms": [ { "platform": "ElmoSecuritySystem", "name": "Elmo Security System", "username": "il_tuo_username", "password": "la_tua_password", "code": "il_tuo_codice", "system": "e-connect", "domain": "default", "pollInterval": 30, "devicePollInterval": 2, "enableDevices": true, "debug": false, "homeSectors": "1,3", "awaySectors": "1,2,3", "nightSectors": "2,3" } ] } ``` ### Esempio di configurazione con dispositivi personalizzati ```json { "platforms": [ { "platform": "ElmoSecuritySystem", "name": "Elmo Security System", "username": "il_tuo_username", "password": "la_tua_password", "code": "il_tuo_codice", "system": "e-connect", "domain": "default", "pollInterval": 30, "devicePollInterval": 10, "enableDevices": true, "defaultDeviceType": "contact", "devices": [ { "id": 1, "type": "contact", "name": "Porta Ingresso" }, { "id": 2, "type": "motion", "name": "Sensore Salone" }, { "id": 3, "type": "motion", "name": "Sensore Camera" } ], "debug": false } ] } ``` ## Configurazione dei dispositivi ### Scoperta degli ID dispositivi Per configurare i dispositivi correttamente, devi prima scoprire i loro ID: 1. **Abilita il debug**: Imposta `"debug": true` nella configurazione 2. **Riavvia Homebridge**: I dispositivi verranno scoperti automaticamente 3. **Controlla i log**: Cerca righe come "Dispositivi trovati:" che mostrano ID, nome e stato 4. **Annota gli ID**: Ogni dispositivo ha un ID numerico univoco (campo "element") ### Configurazione manuale dei tipi Una volta ottenuti gli ID, puoi configurare ogni dispositivo: ```json "devices": [ { "id": 1, // ID del dispositivo dal sistema Elmo "type": "contact", // Tipo di sensore in HomeKit "name": "Porta" // Nome personalizzato (opzionale) } ] ``` **Tipi disponibili:** - **`contact`**: Sensori di contatto (porte, finestre, contatti magnetici) - **`motion`**: Sensori di movimento o PIR - **`smoke`**: Sensori di fumo ### Tipo predefinito Se non configuri un dispositivo specificamente, verrà utilizzato il `defaultDeviceType`: ```json "defaultDeviceType": "contact" // Tutti i dispositivi non configurati saranno sensori di contatto ``` ## Come funziona Il plugin utilizza la libreria Python `econnect-python` per comunicare con le API cloud di Elmo. Quando viene avviato, il plugin installa automaticamente le dipendenze Python necessarie e crea gli script per comunicare con il sistema Elmo. Il plugin esegue un polling periodico per aggiornare lo stato del sistema e reagisce ai comandi inviati dall'app Casa. ## Gestione dei dispositivi ### Polling ottimizzato Il plugin utilizza due intervalli di polling diversi: - **Sistema di sicurezza**: Polling ogni 30 secondi (configurabile, 10-300 secondi) - **Dispositivi individuali**: Polling configurabile da 1 a 60 secondi (default: 10 secondi) #### Raccomandazioni per l'intervallo di polling dispositivi: - **1-3 secondi**: Aggiornamenti quasi istantanei, ma può causare conflitti frequenti se usi spesso l'app mobile - **5-10 secondi**: Buon compromesso tra reattività e stabilità (raccomandato) - **15-30 secondi**: Più conservativo, ideale se usi frequentemente l'app mobile - **30+ secondi**: Minimizza i conflitti ma riduce la reattività ⚠️ **IMPORTANTE**: Intervalli molto bassi (1-3 secondi) possono causare: - Conflitti di lock più frequenti con l'app mobile Elmo - Maggiore carico sul server Elmo - Possibili rate limiting da parte del servizio cloud ### Ottimizzazione per polling veloce Per utilizzare al meglio il polling veloce: 1. **Evita l'uso simultaneo dell'app mobile** quando hai impostato intervalli sotto i 5 secondi 2. **Monitora i log** per verificare la presenza di errori di lock frequenti 3. **Aumenta l'intervallo** se noti instabilità o errori ricorrenti 4. **Usa il debug** per monitorare le prestazioni del polling ## Risoluzione dei problemi ### Problema: Errore "Sistema occupato" **Causa**: Il sistema Elmo è attualmente utilizzato da un'altra sessione (app mobile, interfaccia web, ecc.). **Soluzione**: - Chiudi completamente l'app Elmo sul telefono - Attendi 1-2 minuti prima di riprovare - Il plugin riproverà automaticamente con intervalli crescenti - Se il problema persiste, riavvia l'app Elmo e aspetta qualche minuto ### Problema: Comandi lenti o che falliscono occasionalmente **Causa**: Conflitti di accesso simultaneo al sistema Elmo. **Soluzione**: - Il plugin include un sistema di retry automatico con gestione intelligente dei conflitti - Evita di usare l'app mobile contemporaneamente ai comandi HomeKit - I comandi di lettura (polling) hanno timeout più brevi e fallimenti silenziosi - I comandi di controllo (arm/disarm) hanno timeout più lunghi e retry multipli ### Problema: Il plugin non appare in Homebridge **Soluzione**: - Verifica che il plugin sia installato correttamente - Riavvia Homebridge - Verifica i log di Homebridge per eventuali errori ### Problema: Errori di lock frequenti con polling veloce **Causa**: Intervallo di polling troppo aggressivo che entra in conflitto con altre sessioni. **Soluzione**: - Aumenta il valore di `devicePollInterval` (prova 5-10 secondi) - Evita di usare l'app mobile durante il polling veloce - Considera se hai realmente bisogno di aggiornamenti così frequenti - Usa la modalità debug per monitorare i conflitti ## Gestione avanzata degli errori Il plugin include una gestione avanzata degli errori specifici di Elmo: - **Lock conflicts**: Rilevamento automatico quando il sistema è occupato da altre sessioni - **Retry intelligente**: Tentativi multipli con tempi di attesa progressivi - **Timeout ottimizzati**: Timeout diversi per operazioni di lettura vs controllo - **Fallback graceful**: Continua a funzionare anche con errori temporanei ### Tempi di retry - **Polling normale**: Continua senza interruzioni anche in caso di conflitti temporanei - **Polling veloce (1-3s)**: Maggiore tolleranza ai fallimenti per evitare spam di log - **Comandi di controllo**: Fino a 5 tentativi con attesa da 10 a 40 secondi - **Autenticazione**: Fino a 3 tentativi con attesa da 5 a 15 secondi ## Crediti Questo plugin è fortemente ispirato dall'integrazione di Elmo per Home Assistant di [palazzem](https://github.com/palazzem), e utilizza la sua libreria [econnect-python](https://pypi.org/project/econnect-python/) per interagire con il sistema Elmo.