hjdhjd / unifi-protect

UniFi Protect API A complete UniFi Protect API implementation. is a library that enabled you to connect to and communicate with the Ubiquiti UniFi Protect API and ecosystem. UniFi Protect is Ubiquiti's next-generation 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 library for UniFi Protect support? In short - because I use it every day to support a very popular Homebridge plugin named homebridge-unifi-protect that I maintain. I have been occasionally asked if I would consider packaging the core API library separately from the plugin so that other open source projects can take advantage of the work that's been done here to understand and decode the UniFi Protect API. In addition, this implementation is unique: it's the first complete open source implementation of the realtime UniFi Protect update API, enabling instantaneous updates to Protect-related events. It's also the first (and to my knowledge only) complete implementation of the livestream API provided by UniFi Protect. Note: this is **not** the RTSP URLs that are provided by UniFi Protect controllers, but rather, true access to the H.264 datastream for any camera connected to the Protect controller. Finally - the most significant reason that you should use this library: it's very well-tested, it is modern, and most importantly, *it just works*. It's quite easy to add support for UniFi Protect in your project using this library, and you can rely on the fact that the code is used by a significant population of users out there who ensure its continued robustness. How you can contribute and make this library even better This implementation is largely feature complete. I strive to add support for meaningful features to a broad groups of people in order to avoid any unnecessary cruft and technical debt that may accrue over time. The UniFi Protect API is undocumented and implementing a library like this one is the result of many hours of trial and error as well as community support. Features • Full access to the UniFi Protect NVR JSON. • The ability to retrieve the JSON details, including status, of any supported UniFi Protect device. • The ability to modify the Protect NVR JSON or Protect devices. • The ability to programmatically access the H.264 livestream for any camera. This is useful when you want lightweight access to the full camera feed without resorting to RTSP. For example, this is how homebridge-unifi-protect implements HomeKit Secure Video capabilities, resulting in a lighter weight solution than trying to read the RTSP streams for each camera from the Protect controller. Changelog • Changelog: changes and release history of this library. Installation To use this library in Node, install it from the command line: Documentation Documentation and examples for using this library to access UniFi Protect controllers is available here. Additionally, if you'd like to see all this in action in a well-documented, real-world example, please take a good look at my homebridge-unifi-protect project. It relies heavily on this library for the core functionality it provides. UniFi Protect Realtime Events API So...how does UniFi Protect provide realtime events? On UniFi OS-based controllers, it uses a websocket called . This connection provides a realtime stream of health, status, and events that the cameras encounter - including motion events and doorbell ring events. Reverse engineering the realtime events API is a bit more difficult than the system events API because it's based on a binary protocol. The Protect system events API is a steady stream of JSONs published on all UniFi OS controllers over the websocket. It's used by more than just UniFi Protect, which makes it interesting for future exploration. The Protect realtime events API, however, is a binary protocol published over the websocket, and until now has been undocumented. I spent time analyzing what's happening in the Protect browser webUI as well as observing the controller and various Protect versions themselves to reverse engineer what's going on. Pouring through obfuscated code is like solving a puzzle with all the pieces in front of you - you know it's all there, you're just not always sure how it fits together. For the impatient, you can take a look at the code for how to decode and read the binary protocol here in protect-updates-api.ts and the interface information located in protect-types.ts as well. I welcome any additions or corrections to the protocol for the benefit of the community. I hope this helps others launch their own exploration and create new and interesting Protect-enabled capabilities. Non-Ubiquiti Apps Using the Protect API This list represents all known apps that are using the realtime events API for UniFi Protect. If you're using the information you discovered on this page for your own UniFi Protect-based solution, please open an issue and I'm happy to add a link to it below. I hope this can serve as a repository of sorts for UniFi Protect-based apps and solutions in the community. • homebridge-unifi-protect: Seamless integration of UniFi Protect into HomeKit with support for cameras, doorbells, and more. Connecting • Login to the UniFi Protect controller and obtain the bootstrap JSON. The URL is: . You can look through protect-api.ts for a better understanding of the Protect login process and how to obtain the bootstrap JSON. • Open the websocket to the updates URL. The URL is: . You can grab lastUpdateId from the bootstrap JSON in the prior step. You can see an example in protect-api.ts. • Then you're ready to listen to messages. You can see an example of this in protect-nvr.ts. Those are the basics and gets us up and running. Now, to explain how the updates API works... Updates Websocket Binary Format UniFi OS update data packets are used to provide a r…