Oficiální integrace UniFi Network propojí Home Assistant s aplikací UniFi Network. Umí sledovat přístupové body, switche, brány i připojené klienty. Telefon lze využít pro detekci přítomnosti, u síťových prvků sledovat stav a vytížení a s odpovídajícím oprávněním například vypínat Wi-Fi síť nebo ovládat PoE port.
Jde o jinou integraci než UniFi Protect pro kamery a UniFi Access pro dveřní systém. HACS není potřeba. Návod je ověřený podle dokumentace, nikoli fyzickým testem konkrétní sestavy.
Jak propojení funguje
Home Assistant komunikuje přímo s aplikací UniFi Network v místní síti. Změny klientů, zařízení a konfigurace přijímá přes místní WebSocket, tedy průběžně a bez běžného dotazování v intervalu. Při přerušení spojení se pokusí znovu připojit; do té doby mohou být entity nedostupné.
Cloudový účet Ubiquiti SSO pro přihlášení integrace nestačí. V konzoli vytvoříte samostatného místního uživatele. Data klientů tak nemusí kvůli Home Assistantu procházet cloudem, vzdálený přístup a jiné služby UniFi ale mohou cloud používat podle vašeho nastavení.
Integrace podporuje UniFi OS konzole i samostatně provozovanou Network Application. Early Access a Release Candidate nejsou podporované.
Co budete potřebovat
- funkční aplikaci UniFi Network a alespoň jeden spravovaný síťový prvek,
- stabilní verzi UniFi Network a případně UniFi OS,
- místní adresu nebo DNS název řadiče, obvykle port
443, - samostatné místní uživatelské jméno a silné heslo pro Home Assistant,
- síťovou cestu z Home Assistantu k řadiči,
- správný čas na obou systémech, ideálně přes NTP.
Home Assistant nemusí být ve stejné VLAN jako telefony ani AP. Musí ale dosáhnout na aplikaci UniFi Network. Integrace pravidla mezi segmenty neobchází a VLAN nevytváří.
1. Vytvoření místního účtu
Na UniFi OS konzoli otevřete správu uživatelů People a vytvořte nového správce omezeného na místní přístup. Podle aktuální dokumentace Home Assistantu:
- zvolte Create New, doplňte název, uživatelské jméno a heslo,
- zapněte správní účet a Restrict to local access only,
- vypněte předdefinovanou roli,
- nastavte oprávnění Network: Full Management,
- pro OS Settings ponechte None.
Plný přístup k aplikaci Network zpřístupní také ovládací entity. Není však vždy nutný: s omezeným účtem integrace vytvoří méně entit a místo některých přepínačů nabídne jen senzory. Z bezpečnostního hlediska proto nejdřív rozhodněte, zda chcete pouze monitoring, nebo i změny sítě. Nepoužívejte osobní účet vlastníka konzole.
U samostatně provozované Network Application se názvy nabídek mohou lišit. Stále potřebujete místní účet, který se umí přihlásit přímo k dané aplikaci.
2. Přidání integrace
- V Home Assistantu otevřete Nastavení → Zařízení a služby.
- Zvolte Přidat integraci a vyhledejte UniFi Network.
- Zadejte místní adresu řadiče, uživatelské jméno, heslo a port. Výchozí port je
443. - Ověřování SSL ponechte zapnuté. Vypínejte je jen u vlastního certifikátu v důvěryhodné místní síti a až po zvážení rizika.
- Pokud řadič spravuje více sites, vyberte správné Site ID.
- Po dokončení otevřete zařízení a entity integrace a ověřte, co váš účet skutečně zpřístupnil.
Nastavení je celé v rozhraní; integraci nekonfigurujte v configuration.yaml.
Klienti, přístupové body a senzory
V Nastavení → Zařízení a služby → UniFi Network → Nastavit můžete určit, co se má sledovat. Důležité volby jsou:
- vytváření
device_trackerentit pro síťové klienty, - zahrnutí kabelových klientů,
- sledování UniFi zařízení, například AP a switchů,
- omezení sledování bezdrátových klientů na vybraná SSID,
- doba od posledního výskytu do stavu mimo domov; výchozí je 300 sekund,
- ignorování klientů s náhodnou soukromou MAC adresou,
- výběr konkrétních klientů, pro které mají vzniknout entity,
- volitelné senzory přenosové rychlosti a doby provozu.
Podle zařízení a oprávnění mohou vzniknout senzory stavu, vytížení, teploty, přenosů nebo rychlosti portu a update entity firmwaru. Plná práva mohou přidat restart, PoE power cycle a přepínače portů, Wi-Fi či pravidel provozu. Některé entity jsou ve výchozím stavu vypnuté.
Názvy jako device_tracker.telefon_anna nebo switch.wifi_hoste jsou pouze příklady. Skutečné ID vždy zjistěte na stránce entity.
VLAN bez zbytečných problémů
VLAN rozdělují fyzickou síť na oddělené logické segmenty, například domácí, hostovský a IoT. Přenos mezi nimi řídí brána a firewall.
Pro integraci jsou důležité dvě odlišné cesty:
- Home Assistant se musí připojit k aplikaci UniFi Network.
- Síťoví klienti a UniFi prvky musí být správně spravované samotným řadičem.
Home Assistant nepotřebuje přímý přístup ke každému IoT klientovi jen kvůli zobrazení v integraci. Je-li řadič v management VLAN, povolte spojení na jeho konkrétní adresu a port, ne celý segment.
SSID lze přiřadit ke konkrétní VLAN. Na trunku mezi switchem a AP musí být povolená; tuto konfiguraci řešte v UniFi Network.
Příklad 1: světlo při příchodu telefonu
Detekci přítomnosti nejdřív několik dnů sledujte bez kritických akcí. V telefonu pro domácí Wi-Fi vypněte náhodnou MAC adresu nebo nastavte stálou soukromou adresu, aby UniFi zařízení pokaždé poznalo. V Home Assistantu nahraďte tracker a světlo skutečnými entitami. Celý blok vložte do YAML editoru jedné nové automatizace.
alias: UniFi – světlo při návratu domů
triggers:
- trigger: state
entity_id: device_tracker.telefon_anna
from: "not_home"
to: "home"
conditions:
- condition: state
entity_id: sun.sun
state: "below_horizon"
actions:
- action: light.turn_on
target:
entity_id: light.predsin
mode: single
Spouštěčem je přechod telefonu do stavu doma. Podmínka dovolí rozsvícení jen po západu slunce. Výpadek telefonu, Wi-Fi nebo řadiče může stav zkreslit, proto samotný síťový tracker nepoužívejte k odemykání dveří ani vypnutí zabezpečení.
Příklad 2: hostovská Wi-Fi podle času
Tento příklad vyžaduje přepínač WLAN, který se zobrazí jen s odpovídajícím oprávněním účtu. Vypnutí Wi-Fi vyvolá novou konfiguraci dotčených AP a odpojí klienty. Nahraďte switch.wifi_hoste skutečnou entitou a celý blok vložte do YAML editoru nové automatizace.
alias: UniFi – noční plán hostovské Wi-Fi
triggers:
- trigger: time
at: "23:00:00"
id: noc
- trigger: time
at: "07:00:00"
id: rano
conditions: []
actions:
- choose:
- conditions:
- condition: trigger
id: noc
sequence:
- action: switch.turn_off
target:
entity_id: switch.wifi_hoste
- conditions:
- condition: trigger
id: rano
sequence:
- action: switch.turn_on
target:
entity_id: switch.wifi_hoste
mode: single
Dva časové spouštěče mají vlastní ID. Větev noc síť vypne a větev rano ji znovu zapne. Než plán aktivujete, ověřte, že na daném WLAN nejsou zařízení potřebná přes noc.
Detekce přítomnosti: nejčastější omezení
Telefon může měnit MAC adresu pro každou Wi-Fi síť. Pak vznikají nové klientské záznamy a původní tracker se nevrátí domů. Nastavení měňte pouze pro vlastní důvěryhodné SSID; globální vypnutí ochrany soukromí není potřeba. Integrace také umí náhodné adresy ignorovat.
Když telefon zůstává doma i po odchodu, zkontrolujte stav klienta přímo v UniFi. Dokumentace upozorňuje, že u některých verzí může odpojení zkreslovat 802.11r Fast Roaming. Zkontrolujte také shodný čas Home Assistantu a řadiče a vhodně nastavte prodlevu „last seen“. Kratší prodleva reaguje rychleji, ale zvyšuje riziko falešného odchodu při krátkém výpadku Wi-Fi.
Pro důležité automatizace kombinujte síťovou přítomnost s dalším zdrojem. Stav home znamená připojený klient, nikoli ověřenou totožnost člověka.
Když integrace nefunguje
- Přihlášení je odmítnuto: použijte místní účet, ne Ubiquiti SSO; ověřte heslo přímým místním přihlášením.
- Nelze se připojit: z Home Assistantu ověřte adresu řadiče, port, DNS, firewall a směrování mezi VLAN.
- Chyba certifikátu: použijte platný certifikát nebo správně důvěryhodnou interní autoritu. Vypnutí kontroly SSL je až poslední možnost.
- Chybějí přepínače a tlačítka: účet nemá potřebná práva nebo je entita ve výchozím stavu vypnutá. Omezený účet často dostane pouze senzory.
- Klient nemá tracker: zapněte sledování klientů, zkontrolujte filtr SSID a seznam vybraných klientů. U náhodné MAC nastavte stálou adresu pro domácí síť.
- Telefon zůstává doma: porovnejte stav v UniFi, synchronizujte čas, zvažte vypnutí 802.11r a upravte prodlevu.
- Entity jsou nedostupné: zkontrolujte stav aplikace Network a WebSocket spojení; integrace se po obnovení pokusí připojit sama.
- Zůstaly staré entity: klient nebo zařízení musí být nejprve odstraněné z UniFi a neznámé při startu či znovunačtení integrace; potom lze záznam odstranit v Home Assistantu.
Pro podrobné logování lze do configuration.yaml přidat následující blok a Home Assistant restartovat. Použijte jej jen po dobu diagnostiky, protože log může rychle růst.
logger:
default: info
logs:
aiounifi: debug
homeassistant.components.unifi: debug
Výhody, nevýhody a bezpečnost
Výhodou je místní push spojení, přehled o klientech a síťových prvcích a využití jejich stavů v automatizacích bez instalace agentů.
Nevýhodou je citlivost na změny API mezi verzemi UniFi, požadavek na místní účet a omezení přítomnosti dané chováním telefonu. Ovládací entity mohou měnit síť, PoE i pravidla firewallu; chybná automatizace proto může odpojit zařízení nebo uživatele.
Heslo účtu uložte pouze do Home Assistantu. Pro monitoring použijte co nejnižší funkční oprávnění. Plný přístup povolte jen tehdy, když opravdu potřebujete ovládání, a změny WLAN, portů či pravidel nejdřív vyzkoušejte ručně. Integrace nenahrazuje zálohy konfigurace UniFi ani dohled dostupnosti z nezávislého systému.
