homebridge-unifi-protect is a Homebridge plugin that provides HomeKit support to the UniFi Protect device ecosystem. UniFi Protect is Ubiquiti's video security platform, with rich camera, doorbell, and NVR controller hardware options for you to choose from, as well as an app which you can use to view, configure and manage your video camera and doorbells.

Why Use This Plugin For UniFi Protect Support In HomeKit?

This plugin attempts to bridge a gap in the UniFi Protect ecosystem by providing native HomeKit support on par with what you would expect from a first-party native HomeKit solution. My north star has always been to create a plugin that just works with minimal required configuration by you to get up and running. All you need is the hostname or IP address of the Protect controller and local user credentials on the Protect controller. That's it. The defaults are sane and correct for the vast majority of people. For the adventurous, there are rich capabilities you can explore to enable you to further tailor your experience. All provided through an elegant webUI accessed through the Homebridge Config UI that allows you to explore all of the more sophisticated capabilities of this plugin in an approachable way.

What does it just works mean in practice? It means that this plugin will discover all your supported UniFi Protect devices and make them available in HomeKit. It supports all current UniFi Protect controller releases.

For the more technically inclined - this plugin has continued to pioneer the HomeKit user experience for UniFi Protect by being the first Homebridge plugin (and first third-party app, to my knowledge) to successfully reverse engineer the UniFi Protect realtime events API that was introduced with UniFi OS. This allows instantaneous, realtime capturing of events as they occur in the Protect ecosystem, allowing us to provide that same level of realtime sensor and camera feedback to HomeKit. Since reverse engineering the realtime events API, most of the major open source smart automation projects have benefited and also incorporated our work, improving the experience for everyone across smart home ecosystems.

Features

• Easy configuration - all you need is your UniFi Protect controller IP address, username, and password to get started. The defaults work quite well for the vast majority of users. When you want more, there are additional options you can play with, if you choose.

• Full HomeKit support for the UniFi Protect ecosystem. All generally available UniFi Protect devices are supported, including cameras (with tamper detection and ambient light sensors on supported models), chimes, doorbells, lights, sensors (including the growing SuperLink family, such as fobs, glass break sensors, and relays), and Viewports.

• Complete HomeKit Secure Video support for all UniFi Protect cameras. Complete HomeKit Secure Video support, without the need for additional plugins or software beyond FFmpeg. Another community first - all without the need for additional tools to get a complete solution. Third party cameras using an AI Port are also fully supported.

• Third-party camera support. ONVIF-compatible third-party cameras added to Protect are supported with some constraints: no motion sensor is exposed by the Protect controller, which means HKSV is unavailable for these cameras. However, if a third-party camera is paired with an AI Port, full HKSV support becomes available as the AI Port provides the necessary motion detection capabilities.

• Incredibly high performance. I've spent the time to optimize the video streaming experience to ensure it feels very responsive, and just works. HBUP keeps a standing timeshift buffer of each camera that powers live viewing, HomeKit Secure Video, and snapshots...a big part of why live views start so quickly. For those that have hardware-accelerated CPUs and GPUs, live video stream load times using the Home app on iOS average at 0.2-0.3 seconds on a day-to-day basis, which is often better than the native UniFi Protect app! Supported hardware-accelerated platforms are currently: Apple Macs (both Intel and Apple Silicon), Intel Quick Sync Video-enabled CPUs, and Raspberry Pi 4. When not using hardware acceleration, or on slower systems, you can expect live video streams to load within 1-2 seconds.

• Full UniFi Protect Doorbell support.. This plugin provides complete support for UniFi Protect Doorbells. We support all features of UniFi Protect doorbells including - doorbell rings, two-way audio, package camera support, and the use of the onboard LCD screen for messages. Two-way audio has caveats you should be aware of.

• Two-way audio support for all UniFi Protect cameras that support it. Some Protect devices that support two-way audio capabilities include UniFi Protect Doorbells, the UniFi Protect AI Pro Cameras, and more. If the Protect device supports two-way audio, that functionality is available to you in HomeKit.

• Support for multiple controllers. This plugin can support multiple UniFi Protect controllers. If you have more than one controller, it's easy to add them to this plugin, and integrate them seamlessly into HomeKit.

• Automatic realtime detection and configuration of all UniFi Protect devices. By default - all of your supported UniFi Protect devices are made available in HomeKit without needing any further configuration on your part. Additionally, if you add or remove cameras or other devices to your UniFi Protect controller, this plugin will autodetect those configuration changes and add or remove those devices in HomeKit, seamlessly, in realtime. No need to restart Homebridge to see your new Protect devices added or removed.

• A builtin webUI using the Homebridge webUI plugin framework allows you the ability to customize the plugin to your needs. You can apply options globally, for all devices connected to a specific Protect controller, or for individual Protect devices in an intuitive way using the Homebridge HBUP webUI.

• Motion sensor control from within HomeKit. By default, all detected cameras have a motion sensor service. An additional motion switch service can be enabled if you want even more granular control: the motion switch allows you to selectively activate and deactivate motion detection of your cameras. This is especially useful in automation scenarios where you wish to activate or deactivate motion detection selectively when you leave your home or arrive home, for example, or to enable specific groups of cameras to turn on and off motion detection through automation.

• Occupancy sensors for HomeKit. Any device with a motion sensor can also be used as an occupancy sensor with the appropriate feature option. This further simplifies automation scenarios where say you want to turn on a light in a room but only when there's motion detected over a certain period of time. Taking it one step further, on Protect devices with smart motion event notification, you can configure the occupancy sensor to only trigger when a person is in the room.

• Create scenes or presets for groups of cameras. If you choose to create specific liveviews, a security system accessory will appear in HomeKit, enabling you to have motion-detection scenes or presets a tap away. For even more customization, you can create liveview-based switches that will allow you to enable or disable motion detection on groups of cameras. They're easy and intuitive to create and can amplify your user experience in HomeKit.

• MQTT support. MQTT support is available for those that want to make UniFi Protect accessible to an MQTT broker.

• UniFi Access integration. For UniFi Access readers paired with a Protect camera on the same controller, HBUP exposes a lock accessory allowing you to unlock the door from HomeKit. Note: due to Protect API limitations, only unlocking is supported - locking must be done through the Access app or automatically by the Access system. A UniFi Access intercom's doorbell press also surfaces in HomeKit as a doorbell ring.

• And more...

What's Not In This Plugin Yet

Acoustic Echo Cancellation (AEC) support for two-way audio in UniFi Protect. We're most of the way there with two-way audio support, and hopefully AEC support can be reverse-engineered in the future.

I hope to continue to work on this one to get AEC working for two-way audio. You can also read more on about two-way audio support here.

Documentation

• Getting Started

  • Installation: installing this plugin, including system requirements.
  • Plugin Configuration: how to quickly get up and running.
  • Best Practices: best practices for getting the most of your HomeKit setup and UniFi Protect.
  • Troubleshooting: running into login problems or streaming issues? Give this a read before looking anywhere else.
  • Changelog: changes and release history of this plugin, starting with v3.0.

• Additional Topics

  • Feature Options: granular options to allow you to set the camera quality individually, show or hide specific cameras, controllers, and more.
  • Autoconfiguration: how HBUP sources and selects your video (the timeshift buffer, stream selection, transcoding, and transmuxing), autoconfigures your controller, and why.
  • Audio Options: options to further tailor how audio is handled from Protect, such as background noise reduction.
  • Doorbells: how UniFi Protect doorbell support works in this plugin, and how to use all the available features including doorbell messages.
  • HomeKit Secure Video: how HomeKit Secure Video support works in this plugin with UniFi Protect.
  • Liveview Scenes: use the UniFi Protect liveviews feature (available in the UniFi Protect controller webUI) to create motion-detection scenes.
  • Viewports: control what a UniFi Protect Viewport displays on screen, right from HomeKit.
  • MQTT: how to configure MQTT support.
  • Plugin Configuration Reference: complete list of configuration options available in this plugin.

Installation

[!IMPORTANT]

Prerequisites

• Ensure you are using a machine that can handle the CPU and GPU requirements of homebridge-unifi-protect. The more cameras you have, the higher the performance requirements. If you intend to use HomeKit Secure Video, in particular, you will need a capable, modern CPU. Raspberry Pi 4 is a great piece of hardware, but it cannot keep up with the demands of more than a few Protect cameras, and definitely not the higher end members of the Protect camera ecosystem.
• If you are new to Homebridge, please first read the Homebridge documentation and installation instructions before proceeding. Ensure you've installed Homebridge and the Homebridge Config UI before proceeding.
• Ensure you have a local user account on your UniFi console dedicated to homebridge-unifi-protect. To create a local user account on your UniFi console:
  • Go to the OS Settings tab on the Protect controller web interface. This is typicaly near the top left of the Protect controller UI page.
  • Click Add Admin located near the top right of the OS Settings page.
  • Click Restrict to local access only and then enter in a username and password for the new local user.
  • Optionally customize the role of the user to adjust the roles. HBUP requires the Full Management role for all of it's