Unifi-Protect-Camera-Motion

This Homebridge plugin allows you to add your Unifi Protect Cameras (and their Motion Sensors) to Homekit. It adds smart detection by using a machine learning model to detect specific classes of objects in the camera view.

How it Works

This plugin will automatically discover all the Unifi cameras from your Protect installation, and provide the following sensors for each one it finds:

• Camera, for viewing live RTSP streams
• Motion sensor, for sending push-notifications when motion or one of the desired objects have been detected
• A Switch, for easily enabling and disabling motion detection (on by default and after a Homebridge restart)
• A Switch, to trigger a motion event manually, forcing a rich notification
• (if enabled) A switch, that acts as a doorbell trigger, to manually trigger a rich doorbell notification

Motion Events and object detection

The plugin uses the Unifi Protect API to get motion events on a per camera basis. When motion has been detected one of the two methods below will be used to generate a motion notification in Homekit:

• The basic method: The "score" of the Unifi Protect motion event. (Which currently has a bug and is 0 as long as the motion is ongoing.)
• The advanced method: Object detection by use of yolov5. (recommended) This logic/model runs on-device, and no data will be sent to any online/external/cloud source or service. It is based on the coco ssd project.

Installation

Before installing this plugin, please make sure all the prerequisites have been met first. Consult the readme and the wiki before proceeding.

In short, the main dependencies are:

General:

• Python 3 and pip3 must be installed and on the path!

• Raspberry Pi / Ubuntu / Debian Linux:

  • Install: sudo apt-get install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev
  • Install libgl: sudo apt install libgl1

• Mac OS:

  • Install via Homebrew: brew install pkg-config cairo pango libpng jpeg giflib librsvg

• Linux:

  • Install g++: sudo apt install g++
  • Install libgl: sudo apt install libgl1

• Other OSes:

  • See the node-canvas documentation
  • See the node-gyp documentation => install any dependencies for your OS!

Next, to install this plugin simply type:

sudo npm install homebridge-unifi-protect-camera-motion -g --unsafe-perm=true

Next, open the config.json that contains your Homebridge configuration, and add a block like the following one to the platforms array:

{  
    "platform": "UnifiProtectMotion", 
    "name": "Unifi protect cameras & motion sensors", 
    "unifi": { 
        "controller": "https://protect-ip:controller-ui-port", 
        "controller_rtsp": "rtsp://protect-ip:controller-rtsp-port", 
        "username": "username", 
        "password": "password", 
        "excluded_cameras": [
            "id-of-camera-to-exclude-1",
            "id-of-camera-to-exclude-2"
        ],
        "motion_interval": 5000, 
        "motion_repeat_interval": 30000, 
        "motion_score": 0, 
        "enhanced_motion": true, 
        "enhanced_motion_score": 50, 
        "enhanced_classes": ["person"], 
        "enable_motion_trigger": true,
        "enable_doorbell_for": [
            "id-of-camera-to-act-as-doorbell-1",
            "id-of-camera-to-act-as-doorbell-1"
        ],
        "save_snapshot": true,
        "debug": false, 
        "debug_network_traffic": false,
    },
    "upload_gphotos": false,
    "googlePhotos": {
        "auth_clientId": "CLIENT-ID",
        "auth_clientSecret": "CLIENT-SECRET",
        "auth_redirectUrl": "http://localhost:8888/oauth2-callback"
    },
    "mqtt_enabled": false,
    "mqtt": {
        "broker": "mqtt://broker-ip",
        "username": "MQTT-BROKER-USERNAME",
        "password": "MQTT-BROKER-PASSWORD",
        "topicPrefix": "motion/cameras"
    }
}  

You can verify the correctness of your config file by using jsonlint. The config must be valid or Homebridge will fail to restart correctly. If you are using Homebridge Config X, it will do its best to alert you to any syntax errors it finds.

General configuration fields

Unifi configuration fields

Google Photos configuration

To enable the upload to Google Photos functionality please read the relevant wiki article

MQTT configuration

Camera configuration

• Make sure each of your Unifi cameras has at least one RTSP stream enabled. However, I suggest enabling all available qualities for the best user experience as the plugin will choose the most appropriate one based on the request coming from Homekit.
  • To enable an RTSP stream: Login on the Protect web UI and go the settings of the camera and open the 'manage' tab
    Make sure all your cameras have the same port for the RTSP stream!
    For optimal results it is best to assign a static ip to your cameras
    

How to add the cameras to your Homekit setup

As per 0.4.1 the enumerated cameras and accompanying switches/triggers will show up automatically, You don't need to add them in manually anymore! If you add your Homebridge instance to the Home app the cameras will automatically be there.

Upgrade notice

If you are upgrading from a pre 0.4.1 the cameras you previously had in the Home app will no longer work and will have to be removed! Tap on a camera preview to open the camera feed, click the settings icon and scroll all the way to the bottom, there select Remove camera from home.

How to enable rich notifications (with image preview)

• Go to the settings of the camera view in the Home app
• Each camera has an accompanying motion sensor
• Enable notifications for the camera
• Whenever motion has been detected you will get a notification from the home app with a snapshot from the camera

Tested with

• Ubuntu VM with node 16
• UDM Pro with Protect 2.0.x
  
  
• 2x Ubiquiti UniFi Video UVC-G3-AF - PoE Camera
  
  
  
• 2x Ubiquiti Unifi Video UVC-G3-Flex - PoE Camera
  
  
  

Limitations, known issues & TODOs

Limitations

• Running this plugin on CPUs that do not support AVX (Celerons in NAS systems, ...) is not supported because there are no prebuilt Tensorflow binaries. Compiling Tensorflow from scratch is out of scope for this project!
  • Run it on a Raspberry Pi or machine with macOS / Windows / Linux (Debian based)
• Unifi Protect has a snapshot saved for every event, and there is an API to get these (with Width & Height), but the actual saved image is pretty low res and is scaled up to 1080p. Using the Anonymous snapshot actually gets a full resolution snapshot which is better for object detection.
• There is no way to know what motion zone (from Unifi) a motion has occurred in. This information is not present is the response from their API.
• The enhanced object detection using CoCo is not perfect and might not catch all the thing you want it to. It should do fine in about 95% of cases though.

TODOs

• Add more unit and integration tests (Ongoing)
• Add support for MQTT (Ongoing)
• Upgrade tfjs-node, now held back because newer versions (Upgrade to 2.x.x in future release) (Done)
• Implement required changes to make this work with Unifi OS
• Figure out how to get higher res streams on iPhone (only iPad seems to request 720p streams) (Done)
• Extend documentation & wiki (Done)
• Add support for two-way audio (Done)

Plugin development

• Checkout the git repo
• Run npm install in the project root folder
• Create a dummy config.json file under resources/test-config/
• use npm run watch to automatically watch for changes and restart Homebridge if needed, you can also add a remote debugger on port 4444 to debug the code.
• use npm run homebridge to start a Homebridge instance that points to the local config that does not auto-reload when changes are saved.

Credits

A big thanks to the developers of Homebridge Camera FFmpeg and Homebridge-unifi-protect for their contributions and valuable insights in how to get things working!

Disclaimer

This plugin is provided free of charge and without any warranty of its functionality.
The creator cannot be held responsible for any damages, missed motion notifications that cause damage or harm.