Mastering Your Network: Integrating Ubiquiti Unifi with Home Assistant

Introduction

In today's smart home, the network is the backbone connecting all your devices. For many enthusiasts and even small businesses, Ubiquiti's Unifi ecosystem provides robust and managed networking gear – access points, switches, and routers (USG/UDM). While Unifi offers its own excellent controller for management and monitoring, integrating it with Home Assistant unlocks a new level of automation and unified visibility.

By bringing your Unifi network data into Home Assistant, you can tie network events directly into your smart home automations. Imagine turning lights on when a specific phone connects to the Wi-Fi, pausing streaming on a kids' device at bedtime, or getting alerts if a critical device goes offline. The Unifi integration provides device tracking, network sensor data, and even control over Power over Ethernet (PoE) ports.

Why Integrate Unifi with Home Assistant?

• Centralized Monitoring: View the status of your network devices (clients, access points, switches) alongside your smart home devices in one dashboard.
• Advanced Presence Detection: Utilize reliable Wi-Fi connection status for sophisticated room or home presence detection.
• Network-Aware Automations: Trigger actions based on who is connected, which device comes online or goes offline, or network performance metrics.
• PoE Control: Power cycle or disable PoE ports on your Unifi switches directly from Home Assistant (useful for resetting cameras, access points, etc.).
• Unified Alerts: Receive notifications about network events (like a specific device disconnecting) through your Home Assistant notification channels.

Prerequisites

Before you begin, ensure you have the following:

1. A running instance of Home Assistant.
2. A Ubiquiti Unifi network with a self-hosted or Cloud Key controller (UDM/UXG models also act as controllers).
3. User credentials for your Unifi controller. It's highly recommended to create a dedicated read-only user for Home Assistant for security purposes. This user needs appropriate permissions to read client, device, and site data. Check the Unifi documentation for specific role requirements, but a limited administrator or a custom role with monitoring permissions is usually sufficient.
4. Ensure your Home Assistant instance can reach your Unifi controller over the network (firewall rules permitting).

Setting Up the Unifi Integration in Home Assistant

The Unifi integration is available in the Home Assistant Integrations page.

1. Go to Settings -> Devices & Services.
2. Click on the + Add Integration button in the bottom right corner.
3. Search for "Unifi" and select the integration.
4. A configuration window will pop up. You will need to provide the following details:
• Controller Host: The IP address or hostname of your Unifi controller (e.g., !$0$!, !$1$!).
• Controller Port: The port the controller uses. The default API port is 8443, but this can be changed in your Unifi controller settings. UDM/UXG models typically use port 443.
• Username: The username of the Unifi controller user you created for Home Assistant.
• Password: The password for that user.
• Site: Select the Unifi site you want to monitor. Most home users only have the "default" site.
• Verify SSL certificate: Keep this checked unless you have specific reasons not to (e.g., self-signed certificates, though fixing the certificate is recommended).
• Detection interval (seconds): How often Home Assistant should poll the controller for client updates (defaults to 30 seconds).
5. Click Submit. Home Assistant will attempt to connect to your controller.
6. If the connection is successful, you will be presented with options for configuring which device trackers and network devices to include:
• Enable device tracker for all clients: Creates a device tracker entity for every connected client. You'll likely want to disable this initially and only enable tracking for specific, relevant devices later.
• Enable device tracker for wired clients: Include wired devices in device tracking.
• Enable device tracker for wireless clients: Include wireless devices in device tracking.
• Consider Home Assistant as a guest client: If your Home Assistant instance appears as a client, you can tell the integration to treat it as a guest.
• Only track network devices (non-clients): Creates device trackers for your Unifi access points, switches, etc.
• Enable network sensor entities: Creates sensors for network health, traffic, etc.
• Enable switch entities for PoE ports: Creates switch entities allowing control of PoE ports on your Unifi switches.
7. Configure these options based on your needs. You can always change these settings later via the integration options.
8. Click Finish.

The integration will now start fetching data from your Unifi controller and creating entities in Home Assistant.

Discovering Unifi Entities in Home Assistant

Once the integration is set up, a variety of entities will appear:

• Device Trackers (!$2$!): If enabled, you'll see entities for connected clients (e.g., !$3$!). These have states like !$4$! (connected) and !$5$! (disconnected). Attributes often include IP address, connection speed, connected access point, etc.
• Network Devices: Unifi Switches, Access Points, and the Gateway will appear as devices in Home Assistant, with various sensors and controls attached.
• Sensors (!$6$!): Depending on your configuration, you might get sensors for:
• Uptime of network devices.
• Client count (wired/wireless).
• Traffic statistics (upload/download speeds).
• PoE power usage per port or device.
• System health metrics for the controller or devices.
• Switches (!$7$!): If enabled, you'll see switch entities for each PoE port on your Unifi switches (e.g., !$8$!). Toggling these will enable/disable PoE power on that specific port.

Use Cases and Automation Examples

Here are a few ways to leverage your Unifi data in Home Assistant:

1. Enhanced Presence Detection:

Use the device tracker entities for mobile phones or other key devices as part of your overall presence detection strategy. Combine Wi-Fi presence with other methods (like GPS, ping, or Bluetooth) for more robust detection.

!$9$!

2. Alerting When a Critical Device Goes Offline:

Monitor devices that should always be connected, like a server, smart TV, or security camera.

!$10$!

3. Automating PoE Port Control:

Create a button in the Home Assistant UI to power cycle a PoE device, or automate the power cycling if a device tracker for that device goes offline unexpectedly.

!$11$!

4. Monitoring Network Traffic:

Display network traffic sensors on your dashboard or use them to trigger alerts if bandwidth usage exceeds certain thresholds.

!$12$!

Best Practices for a Reliable Unifi Integration

• Dedicated Unifi User: Always create a separate, limited-permission user on your Unifi controller specifically for Home Assistant. This minimizes the security risk if your Home Assistant instance is compromised.
• Static IPs or DHCP Reservations: Assign static IP addresses or configure DHCP reservations for critical devices you track. This ensures their device tracker entities remain consistent even after reconnects or network reboots.
• Careful Device Tracking Selection: Don't enable device trackers for *all* clients unless you genuinely need them. Too many device trackers can clutter your entity registry and potentially add unnecessary load, though the Unifi integration is generally efficient. Only enable tracking for phones, tablets, or other mobile devices relevant to presence detection or specific automations.
• Understand Polling Interval: The detection interval determines how quickly Home Assistant reacts to devices connecting or disconnecting. A shorter interval means faster detection but slightly higher load on both Home Assistant and the Unifi controller. The default 30 seconds is usually a good balance.
• Controller Reliability: The integration depends entirely on your Unifi controller being online and accessible. Ensure your controller (Cloud Key, UDM, software controller) is running reliably.
• Firewall Rules: Double-check that your network's firewall allows Home Assistant to connect to the Unifi controller on the specified port.

Conclusion

Integrating Ubiquiti Unifi with Home Assistant brings your network from being just infrastructure to an active participant in your smart home. From sophisticated presence detection to automated power cycling and network health monitoring, the Unifi integration provides valuable data and control points. By following the setup steps and best practices outlined above, you can build a more intelligent, responsive, and reliable smart home ecosystem powered by your network data.