Prerequisite
What’s Integration?
Integrations in Home Assistant can be viewed as applications in computer/tablet/smart phones. In order to register i.e. integrate different smart home devices into the Home Assistant platform, you need to install the corresponding integration.
As a one of major point of confusion in current version of Home Assistant, there are various methods of integration installation. This is not based on user’s choice but developer’s choice i.e. each integration only support one way or the other. So if you do not know each options, you may end up viewing Home Assistant as rather limited platform.
After going installing a dozen of integrations a few times, I categorize Home Assistant to have four distinctive ways of integration installation.
On the top level, I see the integration can be divided into two categories. One is an official home assistant integration and the other is the unofficial through Home Assistant Community Store (HACS). Both are free and community member developed integrations, but I interpret these as one is officially approved and the other has not (yet).
Under the official installation, you have two main methods. One is through the user Interface (GUI) either web UI or smart phone app. The other is manually editing configuration text file, YAML format. The YAML editing can be viewed as legacy method of installation. Some of the UI install integrations can be automatically detected from your network and be suggested for configuration by the Home Assistant analogous to Plug & Play. The others may require you to manually search in the Home Assistant App’s integration listing section like App Store.
The HACS itself is a custom add-on to Home Assistant. This part will be talked in the next article.
Initially, I did not realize the existence of various methods of integration installation existed in Home Assistant so I got a bit confused. Once I started to conceptually organize integration installation as above, I now feel much more comfortable searching and installing new integrations for my devices.
In this guide, we will be focusing on official integrations with the real world examples that I have been through.
Official UI Install
Automatic Detection: Plug and Play
This category is a plug and play mode of Home Assistant. This is the easiest method of installation for new integrations in Home Assistant. Home Assistant automatically discovers devices on the network and list under integrations page.
Configuration > Integrations
Once you’ve decided to integrate a device into the Home Assistant, you just click “Configure” and follow the step by step instruction.
Example of products discovered by this method for my home network are:
- Google cast
- Philips Hue
- Apple TV
- Epson Printers (EcoTank series)
- Denon AVR with built in HEOS
- iRobot Roomba and Mop
- Sonos
- Homekit
Sonos
Sonos are WiFi speakers with the latest models have built in voice assistant either Alexa or Google Assistant.
Ease of Setup: 10/10
Sonos addition was the simplest integration installation. I just hit Configure button and it detected 3 Sonos speakers in my home. One of which is setup as 5.1 system so it did not separate surround speakers or bass but rather showed up as a single speaker entity. For my future organization, I just changed area where each speakers are located, which you can do afterwards. I just then hit submit and all speakers were ready to go.
Performance: 10/10
This works really well so far. One of the reason why I am getting into home automation lately is my mechanical doorbell ringer no longer working after Unifi Doorbell installation due to extreme cold temperature in my area. Basically, summer time all worked fine except winter time it made constant buzzing sound. So I added capacitor piece came with the Doorbell, which stopped buzzing sound but then mechanical chime stopped working. At this point, I need to exchange the transformer, but I struggled with this as I was not able to expose the existing transformer. So if I were to ask electrician to do this, I have to pay $200+. But that’s only to have old mechanical chime to make a sound, which did not reach to most part of my home to begin with. So rather than spending $200 here, I’ve decided to give a try on Home Automation system and have the chime be heard anywhere in my home.
The above setup required, setting up UniFi Protect, Sonos, and Homekit integrations in Home Assistant. Then I configured Homekit Home app. Lastly, I created an automation when Unifi Doorbell is pushed, play text to speech on Sonos (actually in Japanese). Below is the result of how fast the latency is from doorbell push to corresponding sound announcement.
NUC10 i7 with SSD drive uses ProxMox virtualization to run Home Assistant OS (2 CPU/8GB memory).
The time are subjectively counted as they are too fast for me to start and stop timer accurately anyways.
Homekit
Homekit integration allows otherwise Homekit incompatible devices to be registered to Homekit. For example, HomePods currently can only make chime sounds in response to Homekit compatible doorbell(s). My Unifi Doorbell is not natively compatible with Homekit. However, Home Assistant Homekit integration was able to register the doorbell as Homekit doorbell entity.
Ease of Setup: 8/10
The process here was by no means a difficult but as a new user of Home Assistant, I saw a few points of confusion that could be better addressed by improving UI. To start it off, I saw 3 HomeKit instances automatically detected and showed up on the integration page. I surmise this was due to the fact I had Homebridge, another Home Automation system, running two bridge instances in addition to main Home instance, hosted on one of HomePod Mini.
I had to think a few seconds here to decide which integration entry to configure. As the main purpose of Homekit integration for me here is to expose Home Assistant registered devices to Homekit platform, I chose an entry that just had Homekit, rather than Homekit Accessory Protocol entries.
Once you hit the configure button, you will see the screen below.
Although one can just hit submit without reading the description, it will end up exposing way too many devices that you probably do not want to be on HomeKit.
Here I can see UI could improve for user friendliness to be inline with typical smart phone/tablet apps. I wished they provide more step by step guidance like first page ask “Do you like to expose media player entity, single entity or multiple non-media player entities?” Based on the user’s choice, the second page set the Mode automatically do bridge or Accessory mode, and show corresponding filtered lists of entities. It does not seem too hard to code this.
In my case, I ended up hitting submit without reading first. So I ended up exposing entire entries in the Home Assistant to Homekit. The main page on the Home App was needless to say unmanageable due to too many entries. Then I used bridge mode and selected camera and cover in order to expose two of MyQ garage doors and two of UniFi Protect cameras. At this point, I was not able to see neither of my UniFi Protect camera with one being doorbell. So I read the instruction finally, and figured that cameras are media players even though bridge mode selection still allowed me to choose camera entities.
So at the end, I created individual accessory entries for each camera. In another word, I ended up creating 3 HomeKit integration instances to make the system work as I intended. For each, instance creation I needed to scan QC code to register to Homekit just like any other Homekit device does. This is another area of UI improvement potential I see. As I surmise many users may be interested in exposing many camera entities, they could perhaps ask “Do you like to add more entities?” question after each setup.
Performance: 10/10
Once devices are exposed to Homekit, they work extremely well. Unifi Doorbell push triggers HomePod mini chimes at instant speed as shown below.
Live video stream with sound also worked great. Arlo Base Station with Arlo Pro 2 camera are officially Homekit compatible setup. These cameras I have are older model so perhaps that may be playing a role here but Home Assistant OS integrated WiFi connected Unifi Doorbell performed far superior to the official Homekit compatible camera.
Manual search: Home Assistant App Store
Many integrations weren’t automatically recognized. So I needed to search on my own. This is analogous to searching an App on Apple or Android App Stores. In another word, this is still for non-technical users.
Configuration > Integrations > ADD INTEGRATION > [INTEGRATION NAME]
Once you find an integration, hit install and it will take us step by step guide, which differs significantly from one integration to another.
Integrations fell under this category for me are:
- MyQ (WiFi Garage Door Opener)
- August Smart Lock
- Sony Bravia TV
- Sony Playstation 4
MyQ
Ease of setup: 10/10
Adding this integration was one of the easiest. After selecting MyQ, a popup menu asked user name and password for MyQ. I used MyQ account information without creating any new account. Immediately, system recognized two garage doors and MyQ Hub.
Performance: 10/10
This works really well. Through Home Assistant, I have exposed/added this to Homekit. The door responds instantaneously to my requested command.
Extra-credit: Saved $90
Even if I were not interested in adding any automation to garage door yet, this allowed me to integrate MyQ garage doors to Homekit. LiftMaster has official Homekit compatible add-on, MyQ Homebridge. I am not certain its retail price but currently I see Amazon has it listed for $89.85 through 3rd party and looks like the lowest price it was at $55, average price of $90 since 2017 on Amazon. Considering the price of actual hardware to make my garage door WiFi compatible was merely $30, I felt $90 to just add Homekit compatibility was a bit too much.
August Smart Lock
Ease of setup: 10/10
After searching and hitting install, this takes step by step guide.
First page asked user name and password that is registered to August website. On the second page, it asked verification code that was sent to the email i.e. user name. Two step authentication is part of August so we can not avoid that.
Performance: 9/10
Just like other integrations so far, this works very well. It properly responded my 10-20 lock/unlock test without a single failure. However, when compared to using native August App on my iPhone, there is a slight delay when lock/unlock action is executed from Home Assistant UI. Considering door lock is not latency critical device, under 10 seconds of delay here is perfectly acceptable. In fact, if you did not test with native app, you may not even cared.
YAML Install: Legacy Install
As a new Home Assistant user, this can be a point of confusion. In fact, this has been criticized in the past.
Home Assistant has been included in a number of product and platform comparisons, where, like many other non-commercial home automation controllers/hubs, it has often in the past been criticized for forcing users into a tedious file-based setup procedure using text-based YAML markup-language instead of graphical user interfaces.
https://en.wikipedia.org/wiki/Home_Assistant
This is indeed one of the reason I tried Home Assistant couple years ago and left even though I got everything working at the time. It was just too tedious to maintain. Luckily, Home Assistant is moving away from this. So this is a legacy mode of integration install, but unfortunately, you may still encounter some device installation only through this method because developers has to implement UI installation support.
Configuration > Integrations > ADD INTEGRATION
If you are attentive unlike myself, you actually see an end page paragraph on the integration search screen. “Not all integrations can be configured via the UI yet.” When you hit the hyperlink, it will take you to the official home assistant integrations page (shown below).
The example integrations for my personal use case where UI store had no listing, but I was able to find integrations on the web page catalogue are:
- Amazon Alexa
- Google Assistant
- Lutron (for RadioRA2)
- Honeywell Lyric T6 Pro (Thermostat)
Each of these integrations has a detail, well written webpage instructions. The actual organization and detail of the instruction are far better than many others you see on the web, especially coming from US (poor instruction) standard. However, if one had not known where to look for these integrations, I can see some may conclude Home Assistant lacks support for particular device integration. In my case, that would have been automatic “no go” for Home Assistance because Lutron (RadioRA 2) is one of the main integration I need for my use.
From the user perspective, I can understand some integration lacking UI installation support as that’s developer dependent. However, Home Assistant developer could at least incorporate legacy integrations on the integration page (UI App Store) and label them as YAML or “legacy”. Clicking legacy integration can then simply take user to webpage instruction of the integration. This way user won’t be missing legacy integration options.
Once you’ve figured the integration existence, you will need to learn new method of integration, which is by editing YAML file.
What’s YAML file?
First let’s have you take a look at what it looks like.
The above example goes to line 886 and its not done yet because !include is a way to link/import from other files. I hope you felt how majority of normal people would feel.
Now as a starter, you have relatively clean YAML so it does not look as overwhelming but you may find out that editing/opening YAML file may not be as simple as going into specific folder and open via text editor. This is because Linux based Home Assistant OS running on your machine most likely won’t have direct UI to access folders. If you are familiar with how to SSH, setup mounting point on Docker etc. then you have no issue but I surmise most people reading this article aren’t.
Fortunately, if you install Home Assistant OS or supervised version and followed the installation guide, you should have YAML editor ready to go.
Lutron
Ease of Setup: 8/10
Go to the official integration webpage and type in integration brand/device name you are looking for.
Click the target integration item icon.
Read the instruction first. Make sure this is what you want. For example, Lutron has several product lines. In my case, I am looking for RadioRA 2 line, not Caseta or Homeworks. Sometimes clicking right upper corner area View on GitHub where source code/program files located have more detail. Lutron RadioRA2 supports shades but this integration does not.
For the case of this Lutron integration, starting with RadioRA2 version 12.2, Lutron deleted default log in for integration (ref). So I had to go into Main Repeater setup app and created new account specifically for this access. Then I wrote down the username and password.
Now you are ready to add entry into the configuration.yaml. In case of Lutron, I just needed to add 4 lines to the file.
Supervisor > YAML editor > Open configuration.yaml
It is important to note that YAML file cares about space/indentation i.e. two spaces before host, username and password are must. If you had 1 or 3, or tab, it won’t work. Visual Studio Code will flag you if your indentation is inappropriate but File Editor won’t.
Host: IP address of RadioRA 2 Main repeater. Highly recommend you to set Static IP for it; otherwise, Home Assistant may start failing when IP address changes.
username & password: Username and password on Lutron Main Repeater. First you can put actual username and password directly here.
*As stated above, after 12.2 default integration account on Lutron has been disabled/deleted. So you may need to recreate it or create new integration account.
Configuration > Server Controls
In order to have the new configuration.yaml entry to take its effect, you need to restart the Home Assistant. However, before restarting, you want to validate the configuration. This can be done by clicking the check configuration button. If there is an error, you need to go back to your configuration.yaml file and fix it. Now you can restart.
Now Lutron entries have been added. Surprisingly, you did not have to do actual “install” of any integration, just the text line addition on configuration.yaml did that.
Performance: 10/10
Once setup, the integration works very well.
Gold standard here is Lutron iOS App since that is the official Lutron product. Home Assistant essentially matched the latency on both input and output. Of note, the test is subjectively performed due to relative quick response I could not start and stop timers fast enough. They are also 100% reliable.
Better Practice Tip: YAML Organization
At this point, Lutron integration is working but I think it is good to get into the habit of organizing your YAML file. In this section, I am going to talk briefly about basic organization using comment and !secret.
Comment
Any line after the first “#” character is treated as a comment i.e. no impact on actual YAML file processing. However, you may end up having a few or many manual entries here as time goes by. So I’d personally recommend using comment to organize your YAML file, which is good standard practice on programming.
!Secret
!secret is a way to include password entries from the secrete.yaml file (official instruction). It is a good practice to separate sensitive information to secret.yaml. This is very straight forward task.
Honeywell Lyric
Although this entry showed up on UI integration list, it failed the integration initially.
As mentioned above, I would have personally preferred UI integration search page to have shown everything that official website has. In this case, Honeywell Lyric integration is doing part of this but in a bit confusing way. Despite August lock showed up on the search integration page clicking installation shows Aborted message.
I had wished there was a direct link to the Honeywell Lyric integration page rather than just plain text as above. This is just another illustration showing Home Assistant continues to lack refinement for user friendliness.
This integration uses one of commonly encountered theme for device integration to the Home Assistant, which is requiring you to create a developer user account. This is different from standard consumer user account. The developer account gives necessary access of the device to the Home Assistant integration.
Ease of setup: 7/10
Creating developer account here is essentially the same level of task as Lutron integration where required me to create a local integration account within Lutron Main Repeater. Just like Lutron, I then add the Honeywell credential to the configuration.yaml.
However, at this point integration was not complete yet. After rebooting the Home Assistant, I had to go back to integration page and add Honeywell Lyric integration where I originally got abort message. This time though Honeywell Lyric configuration does not fail but asks me to open web page. The page is of Honeywell website. It requests me to login using Honeywell account and grant permission to the thermostat I have registered on the account.
The documentation is well written, easy to follow. Each steps along the way are necessary. However, it remains to show the weakness of Home Assistant. UI can improve. This process would have felt more user friendly if first page say “Please create developer account” with the page hyperlink. Then ask user to enter created user account info and hit next. Now if necessary ask user to reboot and comeback, but ideally carry onto next step which then complete the last step i.e. granting access permission on Honeywell website. Does this sound familiar? Of course, this is commonly used process on Windows or Apple apps for decades though many cases we no longer need to reboot system for just simple application installation.
Performance: 10/10
I haven’t really played with this integration much but it looks like integration worked reliably for my short use and check.
Alexa
This integration allows Home Assistant registered devices to be exposed on Alexa so they can be controlled by Voice. Home Assistant provides step by step instruction to set this up, and that’s all free. For the full setup, this process will require network configuration i.e. well outside of Home Assistant itself and depends on your network. Alternatively, you can subscribed to official Home Assistant cloud service, NABU CASA for $5/mo.
The Nabu Casa subscription takes care of all the background setup to make Home Assistant work with Alexa and Google Assistant. Additionally, it provides secure remote access and natural text to speech. Since Home Assistant itself is free, this is one way perhaps best way to financially support Home Assistant. I have decided to pay this service at least for now.
In fact, if you are thinking of having remote access to your Home Assistant i.e. accessing outside of your home network, you will need to setup firewall port forwarding and also you should make sure setting up HTTPS access for security. Nabu Casa Home Assistant cloud subscription will take care of these setup.
My personal recommendation is if you’d like to see any of the functionality of the Home Assistant that are supported by Nabu Casa, try free 31 days trial. This saves your time and let you focus on assessing Home Assistant functionality. If you’d rather save $5/mo but still like Home Assistant, you can then start spending time configuring each components you need manually. Basically, Home Assistant Nabu Casa subscription does not add paid only service. It just makes thing a whole lot easier.
My personal recommendation is if you’d like to see any of the functionality of the Home Assistant that are supported by Nabu Casa, try free 31 days trial. This saves your time and let you focus on assessing Home Assistant functionality.
Ease of Setup: 8/10
Depending on whether you use Home Assistant cloud or not, amount of time you need to setup Alexa integration varies significantly. However, here I’d assume you would use cloud subscription. If you’ve decided to go manually setting this up, I assume you are comfortable with network setup.
When I used this integration 2 years ago, it worked fine except it exposed all the devices on Home Assistant and my obsession bothered me having 100’s of unused devices on Alexa, especially deleting devices from Alexa was one by one process. Later, I found out that I could edit YAML file to select which entity to expose, but that was still cumbersome, which I believe you’d still have to do if you manually setting up Alexa.
With cloud subscription, there is now UI configuration for entity exposure.
Configuration > Home Assistant Cloud > Alexa > Turn On
After turning Alexa “on”, you need to associated Home assistant account with Alexa account via means of installing Home Assistant Alexa skill to Alexa. What I really like here is this method allowed me to integrate Home Assistant to Japanese Alexa.
Although this is a uncommon situation, Alexa compatibility of devices varies by region. For example, Lutron have Alexa integration in US but not for Japanese Amazon. My Amazon Echos are set to Japanese region. So using Home Assistant I was able to make this integration work. Otherwise, I could had to set extra Amazon Echoes one for Japanese and the other for US. This is very situational but shows potential advantage of Home Assistant even on devices that may appear to have official Alexa integration.
Configuration > Home Assistant Cloud > Alexa > Manage Entities > Manage Domains
As you can see we can first decide what entity to expose based on the domain. In my case, I wanted to expose just Light. Once you set this up, you can turn on/off individual entities i.e. fine tune. This has made the process far easier.
However, from UI perspective, this is yet again Home Assistant can potentially improve. Given so many different entities be registered on Home Assistant, more filtering of devices in this screen would be helpful e.g. filter by device, integration. They can also add sort by name etc.
Configuration > Home Assistant Cloud > Alexa > SYNC ENTITIES TO AMAZON
Perfomance: 9/10
For some strange reason, I could not get some of the Lutron switch to work via voice command while others working perfectly fine. So I deleted the switch instance from Alexa and hit resynch on Home Assistant. Now they work. I am not sure if it was related to Home Assistant or Alexa’s issue. But for this I took 1 point off.
The latency here is impressive.
Next Up
Now that you know how to add official integrations, you would be interested in expanding your options by adding custom integrations.