Il problema: il mio controller non ha un'integrazione pronta
In casa ho due access point Omada gestiti da un controller che gira in Docker sullo stesso mini PC di Home Assistant. Volevo nella mia dashboard quattro cose: se ogni access point è online, quanti client ha, quanto traffico passa e un avviso se uno smette di rispondere. Per il mio controller (versione 3.2) non ho usato un'integrazione già pronta: ho scritto uno script.
Lo script fa esattamente quello che farebbe l'interfaccia web del controller: accede con un utente, chiede l'elenco degli access point, dei client attivi e le statistiche globali, e stampa un unico JSON. Home Assistant lo legge con un sensore command_line ogni 60 secondi. Poiché usa l'API web della stessa interfaccia, può cambiare con una versione nuova del controller: se un giorno smette di funzionare, il primo sospetto è l'aggiornamento.
Lo script omada_status.py
Sta in config/scripts/ e usa solo la libreria standard di Python, quindi non richiede di installare nulla nel container di Home Assistant. Tre scelte lo rendono affidabile:
- Riusa la sessione. Salva cookie e token in
/tmpe rifà il login solo se la sessione è scaduta, invece di accedere a ogni lettura. - Certificato autofirmato. Il controller usa un certificato suo, quindi lo script non verifica il nome del certificato. È una scelta accettabile perché la chiamata resta dentro casa.
- Errore chiaro. Se qualcosa va storto scrive il motivo su stderr ed esce con codice 1: il sensore diventa «non disponibile» e ne parlo negli avvisi qui sotto.
class Omada:
def __init__(self, base, user, password):
self.base, self.user, self.password = base, user, password
ctx = ssl.create_default_context()
ctx.check_hostname = False # certificato autofirmato del controller
ctx.verify_mode = ssl.CERT_NONE
self.jar = http.cookiejar.LWPCookieJar(COOKIE_FILE)
self.opener = urllib.request.build_opener(
urllib.request.HTTPCookieProcessor(self.jar),
urllib.request.HTTPSHandler(context=ctx),
)
def login(self):
data = self._post(self.base + "/api/user/login?ajax",
{"method": "login", "params": {"name": self.user, "password": self.password}})
token = (data.get("result") or {}).get("token")
if not token:
raise RuntimeError(f"login fallito: {data.get('msg')}")
...
def call(self, method, params=None):
url = f"{self.base}/web/v1/controller?userStore&token={self.token}"
data = self._post(url, {"method": method, "params": params or {}})
if data.get("errorCode") != 0:
raise RuntimeError(f"{method}: errorCode {data.get('errorCode')} {data.get('msg')}")
return data.get("result")
# letture usate: getGridAps, getGridActiveClients ({"type": "all"}), getGlobalStat
Il JSON finale contiene i contatori globali (access point online, offline, in attesa, client attivi e ospiti, avvisi), un elenco degli access point (nome, stato, modello, firmware, client, traffico trasmesso e ricevuto, canale a 2,4 GHz, aggiornamento disponibile) e un elenco dei client (nome, indirizzo, access point, rete Wi-Fi, segnale, traffico, ospite sì o no).
Alla fine lo script scrive anche una copia del JSON in config/logs/omada-status.json, con scrittura atomica. Serve all'inventario dei dispositivi, che parte da lì per sapere cosa è collegato in questo momento.
L'installazione in Home Assistant
Un unico script PowerShell (da amministratore) fa il lavoro noioso, e prima di toccare un file ne salva una copia con la data.
- Copia
omada_status.pyinconfig\scripts. - Chiede in una finestra mascherata la password dell'utente Omada. Il comando completo finisce in
secrets.yamlcomeomada_command, così la password non compare mai nel pacchetto YAML. - Crea
packages\omada.yamlcon il sensore principale e i sensori per ogni access point. - Se manca, abilita la cartella
packagesinconfiguration.yaml. Se c'è già un bloccopackages:, non lo tocca e ti avvisa. - Controlla la configurazione con il comando di verifica di Home Assistant. Non riavvia: alla fine ti dice cosa fare.
Tengo ogni funzione in un pacchetto suo: uno per il Wi-Fi, uno per la rete, uno per i backup. Le password stanno nel file dei segreti e i pacchetti le richiamano con !secret.
# packages/omada.yaml (estratto)
command_line:
- sensor:
name: Omada dati
unique_id: omada_dati
command: !secret omada_command
scan_interval: 60
command_timeout: 30
value_template: "{{ value_json.global.aps_online }}"
json_attributes: [updated, global, aps, ssids, clients]
# I dati grezzi cambiano di continuo: non servono nella cronologia
recorder:
exclude:
entities:
- sensor.omada_dati
template:
- sensor:
- name: Omada client attivi
unique_id: omada_client_attivi
unit_of_measurement: client
state_class: measurement
availability: "{{ has_value('sensor.omada_dati') }}"
state: "{{ (state_attr('sensor.omada_dati', 'global') or {})['clients_active'] | int(0) }}"
- binary_sensor:
- name: Omada problema AP
unique_id: omada_problema_ap
device_class: problem
availability: "{{ has_value('sensor.omada_dati') }}"
state: "{{ ((state_attr('sensor.omada_dati', 'global') or {})['aps_offline'] | int(0)) > 0 }}"
Per ogni access point lo script genera altri quattro sensori con un modello ripetuto: online (connectivity), client, traffico trasmesso e traffico ricevuto (in GB, con state_class: total_increasing). Basta passare i nomi dei tuoi access point come parametro, come -Aps 'AP-SCALE','AP-DEPOSITO' per i miei due. Il nome deve coincidere con quello scritto nel controller.
Riavvia Home Assistant solo dopo aver letto l'esito del controllo: se ci sono errori di configurazione li vedi lì, prima che fermino l'avvio.
La scheda «Wi-Fi» del dashboard
- Access point: un indicatore online/offline per ognuno dei miei due, il numero dei client attivi e quello degli avvisi del controller.
- Client per access point (24 ore): il grafico di quanti dispositivi ha ognuno.
- Traffico degli access point: trasmesso e ricevuto, per ognuno.
- Client connessi: l'elenco dei dispositivi collegati, preso dagli attributi del sensore principale.
L'elenco dei client mi serve anche fuori dalla dashboard: dal telefono posso chiedere «wifi» o «client» a Home Assistant via messaggio e mi risponde con questi dati (lo racconto nella guida sui messaggi).
Gli avvisi
- Access point non raggiungibile: parte se
Omada problema APresta acceso per due minuti. Il messaggio elenca i nomi degli access point offline e non si ripete prima di 30 minuti. - Access point di nuovo online: parte quando il problema rientra, ma solo se era durato più di due minuti.
- Controller non raggiungibile: se il sensore principale resta «non disponibile» per cinque minuti (contenitore fermo o password cambiata), al massimo un avviso ogni sei ore.
Sono automazioni che passano dallo script comune avviso, per cui il canale di ricezione si sceglie dalla scheda «Messaggi».