Troubleshooting Unifi Protect Smart Home Integration
Integrating your Unifi Protect cameras with a smart home platform like Home Assistant or Apple HomeKit (via Homebridge) unlocks a world of automation possibilities. You can trigger lights when motion is detected, announce visitors on smart speakers, or view all your camera feeds in a single dashboard. However, when this integration fails, it can be tricky to diagnose.
This guide will help you troubleshoot the most common issues that arise when connecting Unifi Protect to third-party smart home systems, focusing on connection errors, authentication problems, and streaming failures.
## The Foundation: How Unifi Integration Works
Unlike many consumer brands that rely on the cloud, Unifi Protect integrations work by communicating directly with your Unifi controller (e.g., UDM Pro, Cloud Key Gen2+) on your local network. This is fantastic for privacy and speed but also means the setup requires careful network configuration.
The integration will need:
- The IP address of your Unifi Protect controller.
- A dedicated Local Access user account created within Unifi Protect.
- A clear network path between your smart home hub (e.g., Home Assistant server) and the Protect controller.
## Common Problem 1: Connection and Authentication Errors
If you're getting an "Authentication Failed," "Connection Refused," or "Unable to Connect" error during the initial setup, work through these steps.
### Step 1: Create a Dedicated Local User
Do not use your main Ubiquiti cloud account (owner role) for the integration. This is the number one mistake users make. You must create a new user specifically for this purpose.
- Log in to your Unifi Protect controller as an administrator.
- Go to the Users or Admins section.
- Create a new user with the "Local Access" account type.
- Assign this user a role with the necessary permissions. A "View Only" role is often sufficient and more secure if you only need to view streams. If you want to control camera settings, you'll need a more permissive role.
- Use this new local username and password in your Home Assistant or Homebridge configuration.
### Step 2: Verify Network Details
- Correct IP Address: Double-check that you are using the correct IP address for the Unifi Protect controller itself, not for an individual camera.
- Network Access: Your smart home hub and your Unifi controller must be on the same local network and subnet. If you are using VLANs, you must have firewall rules that allow the smart home hub to communicate with the Protect controller on its specific port (typically 7443 for HTTPS).
- Firewalls: Temporarily disable any firewalls on the machine running your smart home hub to see if that resolves the connection issue.
## Common Problem 2: Cameras Are Added, But Streams Won't Load
Sometimes the integration connects successfully and adds your cameras, but when you try to view the live feed, it's blank or shows a loading error.
- Enable RTSP Streams: For some integrations, particularly older or more complex ones, you may need to manually enable the RTSP (Real-Time Streaming Protocol) streams for each camera.
- In Unifi Protect, select a camera.
- Go to its Settings tab.
- Under the Advanced section, you should find options to enable RTSP streams for High, Medium, and Low quality. Enable at least one.
- Your smart home integration may then need this specific RTSP URL to pull the feed.
- Substreams vs. Mainstreams: A 4K camera stream can be very demanding. Many integrations are configured by default to use a lower-resolution "substream" for faster loading in dashboards. Check the integration's settings to ensure it's pulling a stream that your network and hardware can handle.
- SSL/HTTPS Issues: If you are using a self-signed certificate on your Unifi controller, your smart home platform might refuse the connection. Look for an option in the integration's configuration to "ignore SSL errors" or "verify SSL certificate" and disable it.
## Common Problem 3: Motion Events Not Triggering Automations
If your camera streams are working but motion events aren't firing in your smart home platform:
- Check User Permissions: The local user account you created needs permission to read motion event data. Ensure the role assigned to the user has "View" access for cameras.
- Event Polling: Most integrations poll the Unifi controller every few seconds to check for new events. There will always be a small, unavoidable delay. Don't expect instant triggers.
- Use Smart Detections: The best practice is to base your automations on Unifi's Smart Detections (Person/Vehicle) rather than generic motion. This is far more reliable and is well-supported by modern integrations like the official one for Home Assistant.
By systematically checking your user permissions, network settings, and stream configurations, you can resolve the vast majority of Unifi Protect integration failures.