OpenHAB’s core design keeps me wanting to invest my time into this platform. In order for me to get UniFi protect integration on OpenHAB, I had to spend multiple days to even a full week as I encountered different issue along each steps for this process. However, this does not mean overall setup was difficult. This simply illustrates extensive modularity of the OpenHAB can result in confusion and challenge the system simply designed differently and counterintuitively for new users. I hope this article saves you days of time or the worst case scenario of giving up on the platform entirely before giving its fair chance. This is OpenHAB version of Protect Unleashed series.
UniFi Protect products are powerful with motion detection, local storage and cloud independent operation. There are many reasons to choose UniFi Protect platform for home surveillance camera system. However, they do not support Alexa or Google Assistant voice control. They are not Homekit compatible. We cannot set scheduled recording. Excellent hardware but software is lacking. Should we wait and keep hoping someday Ubiquiti will add some of above features? The chance is slim. But you are not out of the luck. We can use Home Automation platform/system like Home Assistant to make UniFi Protect devices into not just real smart home device, but a genius one. In this new series I will share my personal experience how I am making UniFi Protect product unleashed using Home Assistant. The first in this series, I will talk about how to setup UniFi Protect integration with Home Assistant. The subsequent articles will talk about some of examples what you can do with unleashed UniFi Protect products.
Prerequisite
- Functioning OpenHAB OS Installation (recommend OpenHABian)
What do you need?
- UniFi Protect device & controller
- openHAB Hub with functioning SAMBA
In this article, you will learn:
- What is OpenHAB?
- Create Home Automation User account on UniFi Protect Controller
- Understanding OpenHAB device registration process
- How to add UniFi Protect Integration on OpenHAB
What’s openHAB?
openHAB stands for open Home Automation Bus, which is an open source home automation platform written in JAVA. It has started in 2010. This platform has a large, active community development team. According to the Black Duck Open Hub, OpenHAB is one of the most popular project (ref). The primary strength of this platform is relatively large lists of product support that is entirely free. The core system design is robust and limitation is essentially the users capability.
On December 2020, openHAB released its latest major version release, openHAB 3. One of the main theme of this version is simplification, which applies to the underlying core architecture all way to user interface overhaul. This is a great time to try/join openHAB.
One good example for this effort seems official support of Blockly for developing automation logic.
I am new to openHAB and never seen or used Blockly before myself; however, it is readily apparent how such visual programing tool can aid development of Home Automation platform where relatively short, often distinct logic based programming can take the system into whole new dimension. This is a great example for user friendly interface yet providing a level of control that no traditional UI with drop down boxes can achieve. The competing platform like Home Assistant users has been requesting this feature (ref, ref).
What’s home automation?
Let’s talk about Home Automation itself. Home Automation is an integration of various network connected so called, smart home devices to perform sequences of actions i.e. routine. Amazon’s Alexa, Google Assistant routines or Homekit’s automation function are the examples of home automation.
For example, rather than voice control to just turn on the kitchen light, you can create automation such as when you say “good morning”, the blinds throughout home opens, multiple lights and TV in the kitchen turns on, coffee maker power turns on and unlock front door while turning off bedroom lights and living room fan.
Platform and cloud independence
If big 3 already supports home automation, why do you want separate home automation hub/controller unit? There are several reasons but the biggest reason are two forms of independence, platform and cloud.
Platform independence
We live in Apple ecosystem; however, my security camera system is UniFi Protect. Unfortunately, they are not compatible with Homekit. I was able to make UniFi Protect to be Homekit compatible by using a software called, homebridge. This works really well and my Unifi Doorbell can make ring sounds to HomePod minis. If someone is looking for way to make a device Homekit compatible unofficially, my recommendation is try Homebridge first.
However, in my case we have other areas in home with Sonos speakers and not able to hear doorbell ring. So the real automation I like to do is UniFi Protect Doorbell push to announce “someone is at the door” on all my Sonos speakers and make a ring sounds on HomePods mini throughout home.
This is where dedicated home automation hub like OpenHAB plays a role. OpenHAB acts as home automation controller/brain unit and ties otherwise completely independent products from different venders to integrate together and allow them to form automations.
Cloud independence
Cloud independence means home automation runs independent of internet connection. Both Alexa and Google Assistant always use internet connection as that’s where brain of the automation located. Local operation of home automation provide 3 primary benefits.
- Reliability: Home automation will continue operating even while internet service is down.
- Improved speed/low latency operation.
- Security/Privacy: No information sent across internet; therefore, much reduced risk for privacy breech.
Create Home Automation User account on UniFi Protect Controller
As with any other automation platforms, OpenHAB needs to access UniFi Protect controller for this integration to work. For the security reason, you want create a dedicated user account for home automation device integration.
https://unifi.ui.com > Users
Add User > Add Admin
Role: Limited Admin.
Account Type: Local Access Only.
Local Username and password are what you will be entering in subsequent step when creating the integration. I put “HomeAutomation” as user name myself this time. This is because I’ve been creating a new user each time for UniFi Protect integration for each home automation testing but all with the exact same privilege settings i.e. Home Assistant, Home Bridge, HomeSeer and now openHAB. So I thought I’d just create one integration user account for all Home Automation integration.
Controller permissions: I like to give minimal required privilege here. In this case, UniFi Protect “Administrator” is needed here because Open HAB can change UniFi Protect device modes rather than just reading the data.
Understanding OpenHAB device registration process
Now that you have UniFi Protect integration account setup on the UniFi Controller, you are ready to add UniFi Protect devices into the OpenHAB.
If you are new to OpenHAB device setup, this is where it gets fun and may be potential source of confusion. So let me briefly explain overall concept of how OpenHAB works from the new user perspective.
Modular Platform with one at a time setup
The core concept of the openHAB platform to me is highly “modular system” design. It is also important to understand that openHAB’s default setup is to make user decide what to include in the system “one at a time” unlike other systems where include all available and later disable/remove unwanted parts. With these design decisions of openHAB, setting up each device may feel to involve more steps than the other platforms, especially for the new users.
Auto Inclusion Option
If you like to have available things automatically approved, you can change default setting.
Settings > System Services > Inbox
You can turn on the Auto Approve.
*At the time of this writing, I am not sure which approach I prefer. So I personally keep the default setting i.e. manual approve one at a time to stick with developer default setting.
Overall, the general steps for adding new device to openHAB are:
- Install a “Binding”
- Create a “Thing”
- Create an “Item”
| Concepts | Meaning | More Information |
|---|---|---|
| Bindings | are the openHAB component that provides the interface to interact electronically with devices | |
| Things | are the first openHAB (software) generated representation of your devices | click for more info on Things |
| Channels | are the openHAB (software) connection between “Things” and “Items” | |
| Items | are the openHAB (software) generated representation of information about the devices | click for more info on Items |
Basically, each device could have multiple features/functions. For the example of Unifi Doorbell can be seen as a combination of “doorbell ring” push detection sensor, “motion detection” sensor and “status light” on/off bidirectional switch etc.
In openHAB, registering this device will be done by first installing UniFi Binding so UniFi Protect physical device information can be processed within the openHAB. Then you will create Unifi Doorbell “Thing” instance in the openHAB, which can be seen as essential one to one match virtual entity of the physical Unifi Doorbell (so long as the binding supports all functionality of the Unifi Doorbell). This Unifi Doorbell “Thing” has multiple channels including 3 channels mentioned in this example. Amongst various channels, you want to interact with the three channels mentioned with openHAB. So in sense, you want to “register” selected attribute i.e. channels and ignore all the rest. To do this in openHAB, you must create an item for each channel. The thing and items are then used for creating automation.
Now let’s take a step by step look at how to do this.
Install UniFi Protect Custom Binding
OpenHAB has a UniFi binding on the official binding list, but this is for UniFi network and does not work for UniFi Protect. However, there is a custom binding for UniFi Protect. The installation of custom add-on in the OpenHAB is very easy so long as you have Samba enabled. The ease comes from the fact OpenHAB uses .jar file for add-on components. JAR file is an archive/compression file for JAVA programs, analogous to zip file. This makes the UniFi Protect binding installation is simple as downloading the corresponding JAR file and place it into the correct folder.
Download .jar file
UniFi Protect binding is available as un-official add-on (here).
In my case, I use OpenHabian 3.0.2 so I have downloaded 3.0.0-ALPHA12.jar file. You can click on the file name and next page, you have download button as shown below.
Connect to the Add-On Folder
This is where you need Samba running on the OpenHab machine. With OpenHabian version installation, this comes enabled by default. Samba allows you to access the machine’s files via classic file explore or finder app on the Windows or Macs, respectively. Once you are connected, it will be a simple drag and drop transfer of the file.
For MAC user, you can open Finder
Open Finder > Go > Connect to Server OR
Open Finder & hit Command+K
Here you want to enter openhabian’s IP address or local server name e.g. openhabian.local.
Default user ID and password are openhabian:openhabian.
You want to connect to “openHAB-addons” folder. Then you just need to drag and drop the UniFi Protect add on jar file to this folder.
That’s all for installing UniFi Protect custom binding.
Create UniFi Protect Things
For the rest of process, you need to access web UI of openHAB e.g. http://openhabian.local:8080 or http://[openHAB server IP address]:8080.
Register UniFi Protect Controller
Not surprisingly, the first “Thing” you should register for the UniFi Protect system integration is UniFi Protect Controller so the rest of UniFi Protect devices can be auto-discovered by OpenHAB with pre-populated fields. This is common practice in OpenHAB i.e. install “bridge” thing first to make the rest easier.
Settings > Things > Right lower corner + > UniFi Protect Binding
You should see UniFi Protect Binding here. This is because the binding has already been installed by simple copy of the .jar file in the earlier step. So you won’t be looking at the Binding installation section. Click the UniFi Protect Binding.
What you are seeing on this screen is types of supported devices that you could manually add. Here you can try hitting “Scan” and see if UniFi Protect Controller may be automatically discovered. In my case, it did not auto-discover the Protect Controller (UniFi Dream Machine Pro). So I personally went through manual step by selecting UniFi Protect NVR.
For the above configuration screen, you need to fill in the followings:
- Label: Name of the Device. My UniFi Protect Controller is UDM Pro. So I called UDMP Protect Controller but you can name anyway you like.
- Hostname: This is where you enter IP address to the UniFi Protect Controller i.e. in my case UDM Pro IP address e.g. 192.168.1.1. Obviously, UDM Pro must be accessible from the openHAB machine.
- Username & Password: This is what you created in the step above within UniFi Protect User.
- I kept the rest as default.
If connection is successful, after a few seconds the Status will turn into the Online.
Create UniFi Camera/Doorbell Thing
Connection and control of each camera device will be done through the Protect controller access so now that’s done, you can start adding individual UniFi Camera devices using auto-discovery.
Settings > Things > Right lower corner + > UniFi Protect Binding
This time you can hit “Scan” and it should list all your UniFi Protect devices. You want to configure one at a time, but via auto-discovery, required parameters are filled automatically e.g. Mac#. So up on clicking the device, you get a pop up to decide the name of the “Thing”.
Confirm the name is ok (or change anyway you like) and accept.
Repeat this step for each protect devices.
Create Items
There are different methods of creating items from each Thing. One can relatively intuitively create from the Thing’s individual menu, under channel section. However, recommended method by official guide and my preferred method at this time is via Model menu. Semantic Model is how openHAB organize various items within the platform. The default, called main UI, of openHAB use this Model to automatically display items in organized fashion i.e. Location, Equipment, and Property types.
As a user evaluating OpenHAB, this semantic modeling concept of OpenHAB indeed made me want to invest my time to openHAB despite rather steep learning curve compared to other platform I have tested so far. You can read about Semantic Model on the official site here. For this guide, I will use this route to create items.
Settings > Model
Create Equipment from Thing
This is was a bit of confusion to me. Location, Equipment and point are all subtypes or labeled “item”.
A Location is a Group Item that can contain sub-Locations, Equipment, and Points, and represents a physical location (building, room, etc.).
An Equipment is normally a Group Item that can contain sub-Equipment, and Points.
A Point is not a Group, but represents any other type of Item and is usually linked to a Channel.
A Property is an additional tag on a Point Item that indicates what sort of point it is. For example, a thermometer might be a Point of type Measurement with a Property of type Temperature.
https://www.openhab.org/docs/tutorial/model.html
I personally see the overall organization of items as following.
So Equipment creation makes nothing but a logical grouping of items to organize various point items. Specifically, in this example, we want to create an Unifi Doorbell equipment item with various point items (doorbell push, motion detection etc).
Now you want to select the Unifi Doorbell from the “Thing” selection list.
What is the difference between Thing and Equipment?
One may wonder why Thing itself can’t be just an Equipment and skip this whole process of creating equipment.
With my short time playing with openHAB, I have already encountered a situation where a Thing was not equal to an equipment. This will be covered in detail in the Part 2 of this series, but I basically had one Thing for UniFi Protect Camera streaming (topic of next article) and the other Thing for UniFi Protect device features (as being discussed in this article). However, I would like to combine the two Things into one equipment i.e. Unifi Doorbell because they are physically one single device. So in such case, 2 things became 1 equipment. One may have opposite situation where one thing may be separated into two equipments.
Name: You want to carefully choose the Name. It is a unique identifier of the “item” so we won’t be able change this later. I am still learning the best practice here, but more descriptive would be better.
TIP
Fill in the equipment name before selecting “channel” links. This is because channel links will create individual point items. Their names are constructed automatically using [Equipment Name]_[Channel Name] convention. However, once the channel is selected changing Equipment name won’t reflect the new name. So for instance, if you select channel link first while Equipment name is blank, those point items will have _[Channel Name] without a prefix, which is probably not the best practice.
Tip: Assign Equipment Name before selecting Channels
Label is what you typically refer the item and this accepts space, foreign language characters etc. This can be changed later.
Category: Not certain exactly what this does in contrast to the Semantic Class. Here I try to put specific device type, but doorbell is not pre-selectable category so I just manually typed in.
Semantic Class: Default here is Equipment. However, this categorization will be used for instance on the main UI page. If default equipment is kept, they will show up under Equipment tab, Miscellaneous. So if you can be more specific, it is better to do so. Doorbell is indeed the available option so I changed to it since it is more specific than Equipment.
Next you are looking at the list of Channels under currently selected Thing i.e. Unifi Doorbell camera in my example. The way I try to think channels are simply features/properties/attributes that available on the device i.e. Unifi Doorbell. However, they are just available at this point but not usable yet. So in order for us to be able to use these in OpenHAB, we need to register/expose them, which is basically done by creating a point for each channel that you want to expose/register. The official term here is linking channel to a new point.
If this were other platforms like Home Assistant or HomeSeer, they are automatically set to “Select All” and accept i.e. when you add new device, all available channels are exposed by default. Here in OpenHAB, user has to/get to manually expose each. Again, at this time I do not have preference/opinion which is better approach.
I see benefit to the both approach as well as cons. For those having many devices, openHAB approach may be a bit better because if it was all automatic expose/register, you can quickly see 100’s to 1000’s items and majority may have no use ever.
You can select all or some. If you do only select some, I’d recommend for sure to include following two.
- Doorbell Ding-Dong – To capture doorbell push
- Is Motion detected
Hit save and you are set. Items are now available within openHAB and that allows you to create automation rules, view in openHAB UIs.
You can repeat this step for other Protect devices.
What’s Next?
If your sole goal is to integrate UniFi Protect with the openHAB so that you can develop background home automation rules, check the status of the devices, you are all set. However, I surmise many users are looking for single goto interface for all smart home devices, especially with relatively modern and clean look of openHAB UI. In which case, you want to be able to view UniFi Protect camera streams on the web browser UI or app UI. Unlike competitors (Home assistant, HomeSeer etc.), this is not part of UniFi Protect binding so you need to do additional setup for this. This will be covered in Part 2.