Homebridge UniFi Protect

Complete HomeKit support for the UniFi Protect ecosystem using Homebridge.

Originally based on homebridge-unifi-protect by HJD, licensed under the ISC License. This fork has been substantially rewritten by MP Consulting.

Overview

A Homebridge plugin that brings native HomeKit support to UniFi Protect devices. Provide your controller's IP address and credentials, and every supported device is automatically discovered and made available in HomeKit — cameras, doorbells, sensors, chimes, lights, and viewports.

Highlights

• Zero-config device discovery — devices are detected in realtime as they are added or removed from your Protect controller.
• HomeKit Secure Video — full HKSV support for all Protect cameras, including third-party cameras paired with an AI Port.
• High-performance streaming — hardware-accelerated live streams load in 0.2-0.3 s on Apple Silicon/Intel QSV; 1-2 s without acceleration.
• Doorbell support — ring notifications, two-way audio, package cameras, and LCD message presets.
• Smart motion & occupancy — motion and occupancy sensors with smart object filtering (person, vehicle, animal, etc.).
• Liveview scenes — map Protect liveviews to HomeKit security system presets and motion-detection switches.
• MQTT integration — publish realtime events to any MQTT broker.
• UniFi Access lock control — unlock Access-paired doors directly from HomeKit.
• Multi-controller — connect multiple Protect controllers in a single plugin instance.

Requirements

| Requirement | Version | |---|---| | Homebridge | >= 1.8.0 | | Node.js | >= 20 | | UniFi Protect | v6+ | | FFmpeg | Bundled, or any build with fdk-aac support |

[!IMPORTANT] Only official (non-beta, non-early-access) releases of UniFi Protect firmware and hardware are supported. Beta versions of Apple operating systems are also unsupported.

Quick Start

1. Install the plugin through the Homebridge UI, or via the CLI:

   npm install -g @mp-consulting/homebridge-unifi-protect

2. Add a platform entry to your Homebridge config.json:

   {
     "platforms": [
       {
         "platform": "UniFi Protect",
         "controllers": [
           {
             "address": "192.168.1.1",
             "username": "homebridge",
             "password": "your-password"
           }
         ]
       }
     ]
   }

3. Restart Homebridge. Your Protect devices will appear in HomeKit automatically.

For detailed setup instructions, see the Getting Started guide.

Documentation

| | | |---|---| | Getting Started | Installation, configuration, and first-run walkthrough | | Feature Options | Granular per-device and per-controller behavior options | | HomeKit Secure Video | HKSV setup and optimization | | Doorbells | Two-way audio, ring events, LCD messages | | Liveview Scenes | Security system presets and motion-detection switches | | MQTT | Event publishing to an MQTT broker | | Audio Options | Noise filter tuning for outdoor environments | | Autoconfiguration | How transcoding and transmuxing are auto-selected | | Best Practices | Recommendations for the best HomeKit experience | | Configuration Reference | Full JSON schema and field descriptions | | Troubleshooting | Diagnosing login, network, and streaming issues | | Realtime Events API | Protocol internals and event processing pipeline | | Changelog | Release history |

Supported Devices

All generally available UniFi Protect hardware is supported:

• Cameras — G3, G4, G5, G6, AI Pro series (with tamper detection on supported models)
• Doorbells — all UniFi Protect doorbells
• Sensors — motion, contact, and leak sensors, including SuperLink
• Chimes
• Lights
• Viewports
• Third-party ONVIF cameras — with full HKSV when paired with an AI Port

Scripts

| Command | Description | |---|---| | npm run build | Compile TypeScript to dist/ | | npm run clean | Remove the dist/ directory | | npm run lint | Run ESLint with zero-warnings policy | | npm test | Run the test suite (Vitest) | | npm run test:watch | Run tests in watch mode | | npm run test:coverage | Run tests with coverage report | | npm run watch | Build, link, and watch for changes (nodemon) | | npm run start | Build and launch Homebridge with a test config | | npm run monitor:events | Run the event schema monitor script |

Contributing

Contributions are welcome. Please open an issue first to discuss your proposed changes.

git clone https://github.com/mp-consulting/homebridge-unifi-protect.git
cd homebridge-unifi-protect
npm install
npm run build
npm test

License

Original work by HJD under ISC. Modifications by Mickael Palma under MIT.

Development