[unifiprotect] Initial Contribution #19411
Merged
lsiepel merged 24 commits intoopenhab:mainfrom Dec 12, 2025
Merged
Conversation
Signed-off-by: Dan Cunningham <dan@digitaldan.com>
Contributor
Author
Contributor
|
How does this related to this binding: https://github.com/seaside1/unifiprotect that also has a marketplace entry: |
Contributor
Author
|
@lsiepel if you read the bottom of my first i comment, i addressed this. |
Contributor
Sorry, i somehow overlooked those lines. Did you try to contact @seaside1 ? |
Contributor
Author
|
I have not, he has not been on the forums since march, and in the end the binding would have needed a massive overhaul if submitted as a PR, regardless of the new API. Plus the binding has been untouched since Oct 2024, despite activity on the forums about issues. So i assumed it was mostly abandoned at this point. After a weekend of trying to refactor the code, i ran out of steam and decided to start over starting with the published openapi.json as the basis for forming the DTO model, then the API client, and finally informing that shape of things and channels before writing the handlers. This lead to a different structure that is much more naturally suited to the official API. |
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR introduces the initial contribution of a UniFi Protect binding for openHAB. The binding provides integration with Ubiquiti UniFi Protect NVR systems using the official Protect Integration API for local communication via HTTPS and WebSockets.
- Comprehensive binding implementation supporting cameras, floodlights, and sensors with real-time event processing
- WebRTC streaming support with go2rtc integration for low-latency video and 2-way audio capabilities
- STUN support for external access through NATs when using openHAB cloud services
Reviewed Changes
Copilot reviewed 125 out of 128 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| bundles/pom.xml | Adds the new unifiprotect module and removes unnecessary whitespace |
| bundles/org.openhab.binding.unifiprotect/src/main/resources/OH-INF/thing/thing-types.xml | Complete thing type definitions for NVR bridge and device types (cameras, lights, sensors) with channel configurations |
| bundles/org.openhab.binding.unifiprotect/src/main/resources/OH-INF/i18n/unifiprotect.properties | Internationalization properties for labels and descriptions |
| bundles/org.openhab.binding.unifiprotect/src/main/resources/OH-INF/config/config.xml | Binding configuration for binary downloads and STUN usage |
| bundles/org.openhab.binding.unifiprotect/src/main/resources/OH-INF/addon/addon.xml | Addon metadata definition |
| bundles/org.openhab.binding.unifiprotect/src/main/java/org/openhab/binding/unifiprotect/internal/media/*.java | Media service implementation for WebRTC streaming and go2rtc integration |
| bundles/org.openhab.binding.unifiprotect/src/main/java/org/openhab/binding/unifiprotect/internal/handler/*.java | Thing handlers for NVR bridge and device types (cameras, lights, sensors) |
| bundles/org.openhab.binding.unifiprotect/src/main/java/org/openhab/binding/unifiprotect/internal/dto/*.java | Complete data transfer object model for UniFi Protect API entities and events |
Comments suppressed due to low confidence (1)
bundles/org.openhab.binding.unifiprotect/src/main/java/org/openhab/binding/unifiprotect/internal/media/NativeHelper.java:1
- There is a spelling error: 'stupported' should be 'supported'.
/*
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
bundles/org.openhab.binding.unifiprotect/src/main/resources/OH-INF/thing/thing-types.xml
Show resolved
Hide resolved
...c/main/java/org/openhab/binding/unifiprotect/internal/api/dto/reference/CameraReference.java
Outdated
Show resolved
Hide resolved
lolodomo
added
the
new binding
Collaborator
|
This pull request has been mentioned on openHAB Community. There might be relevant details there: https://community.openhab.org/t/unifi-binding-beta-3-2-0-3-6-0/131156/195 |
Contributor
|
I've tried to contact seaside months (a year?) ago, but no response. I'd gladly also join your test audience. |
Member
|
@digitaldan: I see you're updating snapshots before triggering channels when events come in. My first gut is to swap that (because I don't care about the snapshot when I'm taking actions like turning on lights) and sometimes taking a snapshot can take a non-trivial amount of time, but then I realized perhaps that's on purpose because another legitimate case is to send a notification with the snapshot when an event happens. What do you think the best course is to resolve these opposing goals? We could add a configuration to just never update snapshots automatically in response to events, then a user could choose, but that's still problematic if someone has both types of rules. Perhaps a 3-state option: no automatic snapshots, automatic snapshots before triggering channels, or automatic snapshots after triggering channels? Then if someone cares about both use cases, they can use the post-trigger update, and watch the snapshot channel itself (probably with additional state to only care shortly after an event was triggered). |
Contributor
Author
So thats exactly the reason, in rules i react to a item or trigger and send the image off. I was not aware of a significant delay grabbing images, but to be honest have not benchmarked that, so i can take a look. I'm ok adding an advanced option to swap the order if you thinks its a significant enough delay (more then a second i guess).
I could have sworn i was checking if a channel was linked before taking a image snapshot, but i think i'm doing that on another binding i'm working on now that i look at it, i'm going to add that so if you don't link an item, we don't waste resources. |
Contributor
Author
|
Actually i am checking if a channel is linked before taking a snapshot 😅 |
Member
I haven't checked through the official API like this, but I've run into issues fetching snapshots completely with a rule that fetches the snapshot itself.
yes, you are doing exactly that. but that doesn't help I still want the snapshot, but want both snapshot-less and snapshotting rules |
Member
BUT: In other words it took nearly half a second to fetch the image. So not terrible. And perhaps my (wireless) doorbell is just behaving well today. |
AFAICT, this is the only way to identify a doorbell Signed-off-by: Cody Cutrer <cody@cutrer.us>
Contributor
Author
|
Are you thinking a binding config or channel config (or something else)? We could add it something like but yes, i could see a wifi device delaying this, my doorbell also has notorious connectivity issues likely b/c of where you have to place it. |
Member
|
I was thinking thing level (not binding level), but I like the idea of channel level too. That way you could configure it differently depending on event type - you might be okay with a minor delay for object or audio detection, but want to send off a notification immediately for a doorbell button press. |
Signed-off-by: Dan Cunningham <dan@digitaldan.com>
lsiepel
reviewed
Oct 20, 2025
Contributor
lsiepel
left a comment
lsiepel
left a comment
There was a problem hiding this comment.
Just two comments i noticed when looking at this PR.
bundles/org.openhab.binding.unifiprotect/src/main/resources/OH-INF/thing/thing-types.xml
Show resolved
Hide resolved
add ring channels based on presence of lcdMessage in camera details
Signed-off-by: Dan Cunningham <dan@digitaldan.com>
Signed-off-by: Dan Cunningham <dan@digitaldan.com>
Signed-off-by: Dan Cunningham <dan@digitaldan.com>
|
I have been looking to add support for openHAB 5 for the UniFi Protect binding, however this looks promising and I can maybe help out to test and contribute here. |
Signed-off-by: Dan Cunningham <dan@digitaldan.com>
Signed-off-by: Dan Cunningham <dan@digitaldan.com>
Signed-off-by: Dan Cunningham <dan@digitaldan.com>
|
@digitaldan Edit 1: just created my nvr an doorbell cam with the ui, linked the items... but the same result. Edit 2: just downgraded to openhab 5.0.3, copied the 5.0.4 version off the jar to my addons folder and the stream is now working Edit 3: few minutes later and it stopped working again Yes i am using text files for my config, i will try to create my things in the ui and test again! For now, this is the logging when unpausing my bridge thing: |
Signed-off-by: Dan Cunningham <dan@digitaldan.com>
Contributor
Author
|
Hmm, can you stop the binding and startup again and post that log? so in the openHAB CLI thats
I'm looking for an error message trying to load the streaming libraries. |
@digitaldan restarting with restart org.openhab.binding.unifiprotect gives the following lines: Not sure if you have seen my edits... i got it working again for a few minutes by downgrading to openhab 5.0.3... probably i can get it to work again if i upgrade again to 5.1.0 |
Contributor
Author
That restarts the whole bundle, there should be a ton (hundreds) of lines. Out of curiosity, you don't have the marketplace version installed as well do you ? |
@digitaldan this is the version i have running retried the restart, now i see a lot more logging |
Contributor
Author
|
can you please run Just want to make sure there's not 2 hangin around. Also if you could restart the binding and grab the logs from the start that would be great, it would be helpful to have the continuous stream of logs in order from binding start, to stream start, to not streaming and not omit anything (so a complete, in order set of logs with no gaps). |
@digitaldan also see my previous post where i dropped a long log i could get when i restarted the binding |
Contributor
Author
Well, that would prevent the camera from registering its streams with the WebRTC service, I need to look at it deeper as i think this is when its setting the mic volume like
but from the JSON, Was there no more logging after that exception ? |
@digitaldan found the problem, i used this item for mic volume changed it to now everything seems to work |
Contributor
Author
|
Yes, thats the problem, its a Number channel not a dimmer, and the docs and examples all show that as well, but i think a dimmer, which seems very logical in your item config, is the better choice then a number, so i will update that so a dimmer item can be used, thanks for the feedback 👍 |
No idea how the dimmer got there, i pretty much copy pasted your example... But thanks for all the help, wouldn't have found it! If you ever need something tested with one of these devices, just mention me here! |
Signed-off-by: Dan Cunningham <dan@digitaldan.com>
Contributor
Author
|
So there is an API to list chimes. By itself its not very useful, but it might lead me to believe that the NVR is sending chime events in real time as they are happening, which might be interesting. Those would be in the TRACE logs when a chime event happens, events are not very well documented in the API so i have to mostly depend on seeing the raw messages to use. I don't see anything about viewports, but i'm not sure what would be controllable or what events would be triggered by a HDMI camera display dongle. |
I will try to catch a chime event tomorrow. For the viewport, it has realy only 1 setting that interest me. in the screenshot you see the selectable multi view, i created 1 with the 4 most importand camera's and i created 1 with only the doorcam in it. It would be nice to change to the view with only the doorcam when sombody rings the doorbell. |
Contributor
|
I have some time this weekend to finish the review. |
ccutrer
reviewed
Dec 9, 2025
| */ | ||
| @Component(service = UnifiMediaService.class, immediate = true, configurationPid = UnifiProtectBindingConstants.SERVICE_ID, property = Constants.SERVICE_PID | ||
| + "=" + UnifiProtectBindingConstants.SERVICE_ID) | ||
| @ConfigurableService(category = "system", label = "UnifiProtect", description_uri = "binding:unifiprotect") |
Member
There was a problem hiding this comment.
This is putting the configuration under System Settings rather than Add-On Settings as one would expect.
EDIT: Actually, if I expand it to the right, it shows up there, too (and with the same configuration settings)! That's definitely confusing.
Signed-off-by: Dan Cunningham <dan@digitaldan.com>
lsiepel
approved these changes
Dec 12, 2025
Contributor
lsiepel
left a comment
lsiepel
left a comment
There was a problem hiding this comment.
Thanks, LGTM
I'd like to merge it as is unless @digitaldan is working on some area that is about to be added. wdyt?
lsiepel
changed the title
Contributor
Author
|
I think its in a pretty good state and i would be good with merging ! Thanks for the review and feedback, always super appreciated . |
Contributor
|
Now, you could add the binding's logo to the openHAB website. See https://www.openhab.org/docs/developer/addons/#add-your-add-on-s-logo-to-the-openhab-website-and-the-ui |
Contributor
Author
|
Yep, i will do that today, thanks again. |
Contributor
|
@digitaldan, can I safely update the (I assume that automatic updates of the firmware should still be disabled after that update?) |
Contributor
Author
|
I let my cameras update to the latest firmware automatically. Since we are using the official API, I don't anticipate firmware versions being an issue. |
Contributor
|
Is there a dedicated topic in the community forum for this binding? In any case: I've got a
It does have a channel which isn't in the documentation: Furthermore, I think the documentation wrongly mentions |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
8 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This binding integrates Ubiquiti UniFi Protect into openHAB. It connects to your Protect NVR/CloudKey/UNVR and provides live events and configurable settings for Cameras, Floodlights, and Sensors.
It uses the official Protect Integration API locally over HTTPS and WebSockets
Features
I know there is another protect binding in the marketplace, and i did first try and modify that, but after a day it became very obvious i would end up rewriting most of it completely to fit the official API. Also that binding has not been updated in almost a year.
I'm opening this PR up early to get some feedback from other protect users, will mark as WIP until ready for review.
Also See openhab/openhab-webui#3368 for updates to our video widget to support 2-way audio (can be merged independent of this)