Mastering Network-Aware Automations: Integrating Home Assistant with Unifi Network Controller

In the realm of smart home automation, Home Assistant stands as a powerful hub, orchestrating devices and services to create a truly intelligent living space. While many integrations focus on sensors, lights, and switches, a critical yet often underutilized layer of intelligence lies within your home network itself. If you're a user of Ubiquiti's Unifi ecosystem – with its robust Access Points, Switches, and Gateways managed by a central Unifi Network Controller – you possess a goldmine of data waiting to be harnessed by Home Assistant.

This guide delves into integrating Home Assistant with your Unifi Network Controller, transforming your network from a passive infrastructure into an active participant in your smart home automations. Beyond basic network monitoring, this integration provides granular insights into device connectivity, network health, and most importantly, incredibly reliable presence detection.

Why Integrate Unifi with Home Assistant?

• Advanced Presence Detection: Forget unreliable pings or GPS-based methods alone. Unifi knows precisely which devices are connected to your Wi-Fi, offering highly accurate and instantaneous 'home' or 'away' states for individuals based on their phones.
• Network Health Monitoring: Get real-time alerts if an Access Point goes offline, a switch port experiences issues, or if your internet connection drops.
• Device Management & Control: Monitor client connection details (e.g., which AP they're connected to, signal strength), and in some cases, even control PoE ports to power cycle stubborn devices.
• Enhanced Security: Receive notifications when new or unrecognized devices join your network, adding a crucial layer of security awareness.
• Contextual Automations: Trigger automations based on network events, such as a gaming console turning on, or guests connecting to the guest Wi-Fi network.

Prerequisites

1. A Running Home Assistant Instance: Any supported installation method (Home Assistant OS, Supervised, Container, Core).
2. Unifi Network Controller: This can be a physical Cloud Key, a UDM/UDM Pro, or a software controller running on a server (e.g., Raspberry Pi, Docker container). Ensure it's running and accessible on your local network.
3. Unifi Network Devices: At least one Unifi Access Point. Switches and Gateways (USG, UDM) will expose more entities.
4. Administrative Access to Unifi Controller: You'll need credentials to create an API user.

Setting Up the Unifi Integration in Home Assistant

The Unifi integration is officially supported and can be set up directly from the Home Assistant UI:

1. Create a Dedicated Unifi API User: For security best practices, do NOT use your main admin account.
• Log in to your Unifi Network Controller (web UI).
• Navigate to System Settings > Admins (or similar, depending on your Controller version).
• Click 'Add New Admin'.
• Create a new user (e.g., homeassistant).
• Assign a strong, unique password.
• Set the role to Read-only or Site Admin if you need to control PoE ports or block clients later. Read-only is sufficient for presence detection and monitoring.
• Save the new admin.
2. Add the Integration in Home Assistant:
• In Home Assistant, go to Settings > Devices & Services.
• Click + ADD INTEGRATION.
• Search for 'Unifi Network' and select it.
• You'll be prompted for the following details:
• Controller Host: The IP address or hostname of your Unifi Controller (e.g., 192.168.1.1 or unifi.local).
• Controller Port: Typically 8443 for HTTPS.
• Username: The dedicated API user you created (e.g., homeassistant).
• Password: The password for the API user.
• Site: If you have multiple sites configured in Unifi, select the relevant site. Default is usually 'Default'.
• Verify SSL Certificate: Keep this enabled unless you have a custom or self-signed certificate causing issues (not recommended for production).
• Click 'Submit'. If successful, Home Assistant will discover your Unifi devices and create entities.
• You'll be asked to select which clients, devices, and ports you want to track as Home Assistant entities. It's often best to select only the essential ones to avoid cluttering your system.
• Finish the setup.

Key Entities Exposed and Their Uses

Upon successful integration, Home Assistant will create a variety of entities. Here are some of the most useful:

• device_tracker. entities for clients: For every selected client (e.g., your phone, tablet), a device_tracker entity will be created (e.g., device_tracker.my_iphone_wifi). Its state will be home when connected to your Unifi network and not_home when disconnected. This is the cornerstone of robust presence detection.
• sensor. entities for network statistics: These provide data like network speed, number of clients, DPI statistics (if enabled on your Unifi Gateway), and more. Examples: sensor.unifi_download_speed, sensor.unifi_number_of_clients.
• binary_sensor. entities for device status: Indicate the online/offline status of your Unifi Access Points, Switches, and Gateways. Useful for health monitoring. Example: binary_sensor.unifi_ap_living_room_connected.
• switch. entities for PoE ports: If you have Unifi Switches, you can control the Power over Ethernet (PoE) status of individual ports, effectively power cycling connected devices. Example: switch.unifi_switch_port_1_poe.
• button. entities for device actions: Some integrations expose buttons to perform actions like restarting an AP or a switch. Example: button.unifi_access_point_restart.

Practical Use Cases & Automations

Now, let's put this powerful integration to work!

1. Advanced Presence Detection for Personalization

Combine Unifi's precise device tracking with other presence methods (e.g., Home Assistant Companion App, GPS) using a person entity or a Bayesian binary sensor for an extremely reliable 'who's home' status.

Example Automation (Basic): Turn off lights when last person leaves

alias: 'House Empty: Turn Off Lights'
description: 'Turns off all lights when the last person leaves'
trigger:
  - platform: state
    entity_id: person.john_doe, person.jane_doe
    from: 'home'
    to: 'not_home'
    for: '00:02:00' # Add a short delay to prevent false positives
condition:
  - condition: state
    entity_id: person.john_doe
    state: 'not_home'
  - condition: state
    entity_id: person.jane_doe
    state: 'not_home'
action:
  - service: light.turn_off
    target:
      entity_id: all_lights
mode: single

The person entity itself can be configured to use multiple device_tracker entities, including the one from Unifi, ensuring robust detection.

2. Network Health Alerts

Be proactively informed about network issues.

Example Automation: Notify if an AP goes offline

alias: 'Unifi AP Offline Alert'
description: 'Notifies when a Unifi Access Point goes offline'
trigger:
  - platform: state
    entity_id: binary_sensor.unifi_ap_living_room_connected
    from: 'on'
    to: 'off'
    for: '00:05:00' # Add a delay to prevent transient drops
action:
  - service: notify.mobile_app_your_phone
    data:
      message: 'Warning: Living Room Access Point has gone offline!'
      title: 'Home Network Alert'
mode: single

3. Automated Guest Wi-Fi Management

Temporarily enable guest Wi-Fi when specific conditions are met (e.g., a 'guest mode' helper is toggled, or certain unknown devices are detected).

While the Unifi integration doesn't directly expose a switch for guest Wi-Fi, you can achieve this by linking it to a network schedule in Unifi, or by using Home Assistant to trigger webhooks/scripts that interact with the Unifi API for more advanced control (requires more complex setup beyond this guide).

4. Power Cycling Stubborn Devices (PoE)

If you have a camera or another PoE device that occasionally freezes, you can automate its power cycle.

Example Automation: Reboot PoE camera if it loses connectivity

alias: 'Reboot Front Door Camera'
description: 'Power cycles the front door camera if it loses connectivity'
trigger:
  - platform: state
    entity_id: binary_sensor.front_door_camera_connected
    from: 'on'
    to: 'off'
    for: '00:01:00' # Ensure it's truly offline
condition: []
action:
  - service: switch.turn_off
    target:
      entity_id: switch.unifi_switch_port_front_camera_poe # Replace with your port entity
  - delay: '00:00:10'
  - service: switch.turn_on
    target:
      entity_id: switch.unifi_switch_port_front_camera_poe # Replace with your port entity
mode: single

5. Alert on New/Unknown Devices

Enhance your network security by getting notified when an unfamiliar device connects.

This requires a slightly more advanced approach using a template sensor or an AppDaemon script to monitor device_tracker entities that are not part of your known devices, or by monitoring Unifi logs directly (outside the scope of the default integration).

A simpler method is to monitor the sensor.unifi_new_devices or sensor.unifi_unauthorized_clients (if available and enabled by your setup) and trigger an alert if its state changes from 0.

alias: 'New Unifi Device Alert'
description: 'Notifies when a new device connects to Unifi'
trigger:
  - platform: state
    entity_id: sensor.unifi_number_of_guests # Or sensor.unifi_number_of_clients if you monitor that for unexpected jumps
    above: 0 # Assuming 0 is the baseline when no guests are present
condition:
  # Optional: Add condition to ensure it's not a known guest device
action:
  - service: notify.mobile_app_your_phone
    data:
      message: 'New or unauthorized device detected on Unifi network!'
      title: 'Network Security Alert'
mode: single

Best Practices for a Reliable Integration

• Dedicated API User: Always use a dedicated, non-admin user for Home Assistant to interact with Unifi. Grant only the necessary permissions (Read-only for most monitoring, Site Admin for control actions).
• Choose Relevant Entities: During setup, Home Assistant will present a long list of potential entities. Select only the ones you genuinely need to track. This reduces Home Assistant's load and keeps your entity registry clean. You can always add more later from the integration options.
• Polling Interval: The Unifi integration polls your controller for updates. While usually efficient, be aware that a very busy controller or a very large number of tracked entities might slightly increase load.
• Static IPs for Key Devices: For critical devices used in presence detection (like your phone), assign a static IP address in Unifi. This ensures their DHCP lease doesn't expire unexpectedly, which could briefly mark them as 'not_home'.
• Consider Dependencies: If your Home Assistant relies heavily on Unifi for presence, ensure your Unifi Controller is stable and always running.
• Troubleshooting: If the integration fails, double-check your controller's IP/hostname, port (usually 8443 for HTTPS), and API user credentials. Ensure your Home Assistant instance can reach the Unifi Controller over the network.

Conclusion

Integrating Home Assistant with your Unifi Network Controller unlocks a powerful layer of network-aware intelligence for your smart home. From hyper-accurate presence detection that truly understands when you're home or away, to proactive network health monitoring and even remote device power cycling, the possibilities are vast. By transforming your network infrastructure into an active data source, you can create more robust, secure, and responsive automations that elevate your smart home experience. Dive in, experiment with the data, and watch your smart home become even smarter.