Integrating UniFi Network with Home Assistant for Advanced Automation

Bringing Your Network into Your Smart Home: UniFi Integration with Home Assistant

Your home network is the backbone of your smart home, connecting devices, streaming media, and enabling remote access. For users with Ubiquiti UniFi equipment (like access points, switches, or gateways), integrating this robust network infrastructure with Home Assistant opens up a wealth of possibilities for advanced automation, presence detection, and network health monitoring.

While Home Assistant excels at controlling individual devices, knowing the state of your network adds another layer of intelligence. Imagine automating actions based on who is home (detected by their device connecting to WiFi), restarting a misbehaving PoE camera automatically, or getting alerts if your internet connection drops. The UniFi integration makes these scenarios possible by exposing data and control points from your UniFi controller directly within Home Assistant.

Prerequisites

• A running instance of Home Assistant.
• A Ubiquiti UniFi Controller (running on a Cloud Key, UDM/UXG, or software on a server/Docker).
• One or more UniFi network devices (Access Points, Switches, Gateways).
• Network connectivity between your Home Assistant instance and your UniFi Controller.

Setting Up the UniFi Integration

Integrating UniFi with Home Assistant is straightforward. The integration communicates directly with your UniFi Controller API.

1. Create a Dedicated UniFi User: It's a best practice for security to create a dedicated user account on your UniFi Controller specifically for Home Assistant. This user should have limited permissions. A 'Read Only' user is sufficient for monitoring and client presence. If you want to control PoE ports or block/unblock clients, you'll need a user with 'Limited Admin' privileges, granting access only to relevant sites.

2. Add the Integration in Home Assistant:

   • Navigate to Settings -> Devices & Services.
   • Click the '+ Add Integration' button.
   • Search for 'UniFi Network' and select it.

3. Configure the Integration: A configuration window will pop up asking for connection details:

   • Controller Host: Enter the IP address or hostname of your UniFi Controller.
   • Controller Port: The standard API port is 8443 (for HTTPS). Ensure this port is accessible from your Home Assistant instance.
   • Username: Enter the username of the dedicated UniFi user you created.
   • Password: Enter the password for that user.
   • Verify SSL Certificate: If your UniFi Controller uses a valid, trusted SSL certificate, keep this enabled. If it uses a self-signed certificate, you may need to disable this (at the risk of a less secure connection) or configure Home Assistant to trust the certificate. Disabling is generally only recommended for internal networks you fully trust.
   • Site: Select the UniFi site you want Home Assistant to monitor and control. Most home users have only one site ('default').

4. Advanced Options (Optional):

   • Ignore clients that are not wired or active: Enable this to filter out less relevant clients, reducing clutter.
   • Include wired clients: Include devices connected via Ethernet to UniFi switches.
   • Include AP/Switch/Gateway clients: Include the UniFi network devices themselves as clients (useful for monitoring their own connectivity).
   • Include guest clients: Include devices connected to guest networks.
   • Poll enabled clients only: Only poll devices Home Assistant determines should be tracked (e.g., based on device tracker settings).
   • Track network devices: Create entities for your UniFi switches, access points, and gateway. Highly recommended.
   • Allow control of network devices: Enables services like port power cycling. Requires appropriate user permissions.

5. Submit and Finish: Click submit. If the connection is successful, Home Assistant will discover your UniFi devices and clients. You may be asked to assign areas to the discovered devices.

Understanding UniFi Entities in Home Assistant

Once configured, the integration will create various entities:

• Device Trackers (`device_tracker.`): For each connected client (phone, laptop, smart TV, etc.) that isn't filtered out, a device tracker entity is created. Its state is 'home' when connected to the UniFi network and 'not_home' when disconnected. This is incredibly valuable for presence detection.

• Network Devices (`switch.`, `sensor._traffic`, etc.): Entities representing your UniFi switches, access points, and gateway. Switches may have child entities representing individual ports (`switch.`). These entities expose information like status, connected clients, traffic statistics, and power usage (for PoE ports).

• Controller Status (`binary_sensor.unifi_controller_status`): Indicates if Home Assistant can successfully connect to the UniFi Controller.

Automation Use Cases and Tips

Now that your network is visible in Home Assistant, let's look at how to leverage it for automation:

1. Presence Detection

The most common use case. Combine device tracker entities from multiple household members to determine if anyone is home.

automation:
  - alias: 'Turn on lights when someone arrives home (UniFi)'
    trigger:
      - platform: state
        entity_id: device_tracker.phone_of_person1, device_tracker.phone_of_person2
        to: 'home'
    condition:
      - condition: state
        entity_id: group.all_devices # Requires a group of all tracked devices
        state: 'home'
    action:
      - service: light.turn_on
        target:
          entity_id: light.living_room_lights

Tip: Device tracker reliability depends on client behavior (some devices disconnect WiFi when asleep). Combine UniFi presence with other methods (GPS, router pings, Bayesian sensors) for more robust results.

2. Automating PoE Ports

If you have PoE-powered devices (IP cameras, other access points), you can use Home Assistant to cycle their power via the UniFi switch ports they are connected to.

automation:
  - alias: 'Restart Camera if it goes offline'
    trigger:
      - platform: state
        entity_id: camera.driveway_camera
        to: 'unavailable'
        for: '00:05:00' # Wait 5 minutes before restarting
    action:
      - service: unifi.power_port_restart # Requires 'Allow control of network devices' enabled
        data:
          entity_id: switch.usw_8_60w_port_4 # Replace with the entity ID of the camera's switch port

Tip: Ensure you have the correct entity ID for the specific port. You can find this in Developer Tools -> States.

3. Network Monitoring and Alerts

Get notified if your network experiences issues.

automation:
  - alias: 'Notify if UniFi Controller is offline'
    trigger:
      - platform: state
        entity_id: binary_sensor.unifi_controller_status
        to: 'off'
        for: '00:01:00'
    action:
      - service: notify.mobile_app_your_phone # Replace with your notification service
        data:
          title: "Home Assistant Alert"
          message: "UniFi Controller is offline!"

You can also create automations based on WAN status reported by your USG/UDM/UXG (often exposed as a binary sensor or status attribute) or if a specific AP goes offline.

4. Controlling Client Access

With appropriate permissions, you can enable/disable (block/unblock) specific client devices via Home Assistant services (`unifi.block_client`, `unifi.unblock_client`). This could be used for parental controls or isolating suspicious devices.

Best Practices for a Reliable Integration

• Dedicated User: Always use a dedicated user on your UniFi Controller with the minimum necessary permissions. This limits the potential damage if your Home Assistant instance is compromised.

• Controller Stability: Ensure your UniFi Controller is running reliably. If the controller is down, Home Assistant cannot get updates or control devices.

• Polling Frequency: The UniFi integration polls the controller periodically. While not usually user-configurable via the standard options, be aware that very large UniFi networks with many clients might slightly increase load on both the controller and Home Assistant. For most home networks, this is negligible.

• Filter Clients: Use the 'Ignore clients that are not wired or active' option and potentially ignore specific MAC addresses in Home Assistant's device tracker settings to avoid cluttering your system with irrelevant devices.

• Secure Connection: Prefer using HTTPS with a valid SSL certificate for connecting to your Controller. If using a self-signed certificate, understand the security implications of disabling SSL verification.

• Resource Usage: On very low-power Home Assistant hosts, tracking a large number of UniFi clients might consume noticeable resources. Monitor CPU/memory if you encounter performance issues.

Conclusion

Integrating your Ubiquiti UniFi network with Home Assistant is a powerful way to enhance your smart home. It transforms your network from a passive infrastructure into an active participant in your automations, enabling more intelligent and responsive control based on real-world network events and device presence. By following the setup steps and best practices, you can build a more reliable, secure, and automated smart home ecosystem leveraging the strengths of both platforms.