Integrazione per Home Assistant che si connette al controller UniFi OS 3.2+ / 5.x tramite Integration API v1 con autenticazione a chiave API nativa (no username/password, no cookie session).

• Home Assistant Core ≥ 2024.1
• UniFi OS 3.2 o superiore (UniFi OS 5.x raccomandato)
• Controller raggiungibile dalla rete di Home Assistant
• Una API Key generata dalla console UniFi OS

⚠️ Non compatibile con controller UniFi self-hosted basati su Debian/bare-metal senza UniFi OS (es. UniFi Network Application standalone). Richiede UniFi OS con Integration API v1.

1. Accedi alla console UniFi OS: https://<ip-controller>
2. Vai in Settings → API Keys
3. Clicca Create API Key
4. Assegna un nome (es. homeassistant) e salva la chiave generata

1. In HACS, vai su Integrations → ⋮ → Custom repositories
2. Aggiungi l'URL di questo repository, categoria Integration
3. Cerca UniFi Network (API Key) e installa
4. Riavvia Home Assistant

1. Scarica l'ultima release (.zip) dalla pagina Releases
2. Estrai la cartella unifi_api/ in <config>/custom_components/
3. La struttura finale deve essere:

   custom_components/
   └── unifi_api/
       ├── __init__.py
       ├── api.py
       ├── binary_sensor.py
       ├── config_flow.py
       ├── const.py
       ├── coordinator.py
       ├── device_tracker.py
       ├── manifest.json
       ├── sensor.py
       ├── strings.json
       └── translations/
           └── en.json
   

4. Riavvia Home Assistant

1. Vai in Impostazioni → Dispositivi e Servizi → Aggiungi integrazione
2. Cerca UniFi Network (API Key)
3. Compila il modulo:

Il Site ID viene rilevato automaticamente al primo collegamento. Se hai più siti, verrà selezionato il primo disponibile.

L'integrazione interroga il controller ogni 30 secondi (polling locale). Non richiede accesso a internet.

unifi_api/
├── __init__.py          # Setup/unload entry, piattaforme
├── api.py               # Client HTTP aiohttp per Integration API v1
├── binary_sensor.py     # Binary sensor: online, firmware update
├── config_flow.py       # UI config flow (API Key + host)
├── const.py             # Costanti, endpoint API, domain
├── coordinator.py       # DataUpdateCoordinator (polling 30s)
├── device_tracker.py    # Presence detection client di rete
├── manifest.json        # Metadati integrazione
├── sensor.py            # Sensor: contatori client, stato device, firmware
├── strings.json         # Stringhe UI (italiano)
└── translations/
    └── en.json          # Stringhe UI (inglese)

Fix deprecazioni HA Core (compatibilità futura garantita):

Tutti questi alias deprecati verranno rimossi in HA Core 2027.x. Aggiornamento consigliato.

• Supporto Integration API v1 (UniFi OS 3.2+ / 5.x)
• Autenticazione con API Key nativa
• Sensor: contatori client WiFi/cablati, stato dispositivi, firmware
• Binary sensor: online/offline, aggiornamento firmware
• Device tracker: presence detection per tutti i client di rete
• Config flow UI completo
• Rilevamento automatico Site ID

Il controller non risponde (cannot_connect)

• Verifica che l'IP/hostname sia raggiungibile da HA: ping <ip-controller>
• Controlla la porta (di default 443)
• Se usi un certificato self-signed, disabilita Verifica SSL

API Key non valida (invalid_auth)

• Rigenera la chiave dalla console UniFi OS
• Assicurati che la chiave abbia i permessi di lettura

Endpoint 404

• Verifica che il controller sia UniFi OS 3.2 o superiore
• L'Integration API v1 non è disponibile su UniFi Network Application standalone

Nessun device tracker creato

• I client vengono rilevati solo se connessi al momento del polling
• Attendi un aggiornamento (max 30 secondi) o riavvia l'integrazione

MIT License — vedi LICENSE

Sviluppato per Home Assistant con supporto all'UniFi Integration API v1.
API reference: developer.ui.com/unifi-api