hjdhjd / homebridge-unifi-protect

:video_camera: Complete HomeKit integration for all UniFi Protect device types with full support for most features including HomeKit Secure Video, and more. https://homebridge.io
Other
1.45k stars 93 forks source link
camera cameras doorbell homebridge homebridge-plugin homekit homekit-support motion-detection motion-sensor nvr security ubiquiti udm-pro unifi unifi-nvr unifi-os unifi-protect unifi-protect-controller unifi-protect-devices

[![homebridge-unifi-protect: Native HomeKit support for UniFi Protect](https://raw.githubusercontent.com/hjdhjd/homebridge-unifi-protect/main/images/homebridge-unifi-protect.svg)](https://github.com/hjdhjd/homebridge-unifi-protect) # Homebridge UniFi Protect [![Downloads](https://img.shields.io/npm/dt/homebridge-unifi-protect?color=%230559C9&logo=icloud&logoColor=%23FFFFFF&style=for-the-badge)](https://www.npmjs.com/package/homebridge-unifi-protect) [![Version](https://img.shields.io/npm/v/homebridge-unifi-protect?color=%230559C9&label=Latest%20Version&logo=ubiquiti&logoColor=%23FFFFFF&style=for-the-badge)](https://www.npmjs.com/package/homebridge-unifi-protect) [![UniFi Protect@Homebridge Discord](https://img.shields.io/discord/432663330281226270?color=0559C9&label=Discord&logo=discord&logoColor=%23FFFFFF&style=for-the-badge)](https://discord.gg/QXqfHEW) [![verified-by-homebridge](https://img.shields.io/badge/homebridge-verified-blueviolet?color=%23491F59&style=for-the-badge&logoColor=%23FFFFFF&logo=homebridge)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins) ## Complete HomeKit support for the UniFi Protect ecosystem using [Homebridge](https://homebridge.io).

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

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

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 capabilities to work, although it will work in a more limited form without administrative privileges.

Getting Started

To install homebridge-unifi-protect:

  1. Go to the Plugins tab in the Homebridge Config UI and searching for homebridge-unifi-protect and install it.
  2. Click on the Set Up icon located in the top right corner of the Homebridge UniFi Protect tile and then enter the hostname or IP address of the Protect controller as well as the username and password you created in the steps above and then login to the Protect controller.
  3. For the moment, don't make any other configuration changes and click Save and then click Restart Homebridge.
  4. After restarting Homebridge, click on the Set Up Child Bridge icon located in the top right corner of the Homebridge UniFi Protect tile. Toggle the child bridge setting for UniFi Protect to on and then save and restart Homebridge.
  5. After restarting Homebridge, click on the Connect to HomeKit icon located in the top right corner of the Homebridge UniFi Protect tile. Use the Home app on your iPhone and scan the QR code to connect UniFi Protect to HomeKit. The Home app may ask questions about where to locate your cameras and whether you want to enable HomeKit Secure Video. Answer according to your preferences.
  6. That's it! You should now be able to access all your UniFi Protect devices in HomeKit. You can further tailor your experience by going to the Homebridge UniFi Protect webUI and exploring the various features and options that are available to you.

[!NOTE] HBUP includes everything required to get up and running on many of the more popular platforms and operating systems. If you're running on an unsupported platform, you will need to install a working version of FFmpeg for homebridge-unifi-protect to work correctly with your cameras. Additionally, your FFmpeg will need to support the fdk-aac codec if you want audio support to work. Setting up and configuring FFmpeg is beyond the scope of this documentation.

[!TIP]

  • Only official releases of UniFi Protect and UniFi OS firmwares are supported. No beta, early access, or release candidate versions of any kind are supported.
  • Only official hardware releases for UniFi Protect are supported. Early access or beta hardware is unsupported.
  • No support is provided for any beta versions of Apple operating systems (iOS, iPadOS, macOS, tvOS, etc.).
  • My philosophy is to aggressively adopt the capability and features (that make sense in a HomeKit context) in the latest official Ubiquiti firmware releases and to deprecate old functionality that's been superceded by newer, richer, or more performant capabilities - either by HomeKit or Ubiquiti. Read the Changelog carefully for the latest information on what's new.

Plugin Development Dashboard

This is mostly of interest to the true developer nerds amongst us.

License Build Status Dependencies GitHub commits since latest release (by SemVer)