Set up Homebridge easily with an app

If you’re a committed HomeKit user you’ve probably heard of Homebridge at one point or another, but if you haven’t, consider the problem of finding a specific smart device, or wishing the newest cool thing had HomeKit support. Trying to find that smart gadget to work with your HomeKit setup has been somewhat of a trial since Apple released it’s smart home platform some years ago, especially if you are outside of the US. While the platform has a lot of promise, it’s taken device makers some time to get moving on adding support.

Apple has to own some of the blame for this by originally requiring specific licensed hardware components to manage secure communications. While the objective was laudable the impact on device makers, who often need to keep costs and development time low, was too much to encourage broad adoption. Apple recognized and rectified this roadblock with iOS11, allowing for a firmware based solution instead, and since then adoption has definitely increased. Even so, getting that device to do the thing you want can still be a challenge.

Homebridge helps to fill this gap. Created shortly after HomeKit was released and steadily maintained ever since, Homebridge is an open source project that was designed to fill the gap for HomeKit enthusiasts while device makers got up to speed. As it happens, this has not only taken longer than hoped, but continues to be a limitation even where manufacturers have provided HomeKit support. Sometimes this support only exists on US-specific products, and even if they can be sourced elsewhere, they may not be legal or even work.

A good example of this is garage door opener company Chamberlain. They recently added HomeKit support to much fanfare to their range of MyQ garage door openers via a new bridge device. Unfortunately, this device only uses US approved garage door frequencies, which vary in other countries and prevent the bridge from working. Homebridge can help here by providing unofficial HomeKit support to international MyQ bridge devices.

Some of the install documentation

Some of the install documentation

Being an open source project the setup can be a bit daunting to those not familiar with Linux or running their own server. The project provides detailed instructions, and there is reasonable support from the community, but for someone who just wants things to work it’s confronting. App Developer Niklas von Weihe has come to the rescue by creating an iOS app to take care of the setup and management of a Homebridge server for you.

The app is called, simply, Homebridge for RasberryPi, and is designed to take you through the setup of the Homebridge server on a fresh RasberryPi device. While there is a MacOS version of Homebridge, for most people using a cheap and unobtrusive RasberryPi device is the way to go. You want Homebridge to be humming away in the background just doing it’s thing as a part of your HomeKit smart home, which is the kind of job RasberryPi devices are perfectly suited for.

Setting Up the Server

Naturally, the first thing you’ll need is a RasberryPi and to have the Homebridge for RasberryPi app installed on an iPhone. There are many places to source a RasberryPi. I went for the newest 3B+ model starter kit on Amazon, which includes a clear case. I’d recommend getting the case as you can then safely stash it away somewhere without worrying about if getting covered in dust or damaged by stuff touching the board.

The starter kit will come with a MicroSD card preloaded with the NOOBS (New Out Of Box Software) operating system installer, specifically for the RasberryPi. You’ll need to insert the card into the device, and plug in a USB mouse, keyboard and HDMI monitor (you can do away with all three once you’re up and running). Power on the RasberryPi and let NOOBS boot up. Use NOOBS to install Raspbian (the recommended default) by simply selecting it from the menu.

The install will have you setup WiFi (optional) and a user account. After the OS is installed, the RasberryPi will boot you into a Linux desktop. Depending on your install location you can either have the Pi on WiFi or hard wired Ethernet. Homebridge should work fine on both, but I opted to hard wire into one of my routers LAN ports to ensure reliability and subsequently did not set up WiFi (to avoid any confusion over which it should be using). We’re almost ready to fire up the app on your iPhone, but there is one thing we need to do first, and that’s to ensure SSH is enabled. This is critical as it’s how thew app will communicate with the RasberryPi.

Turn on SSH

Turn on SSH

  1. Launch Raspberry Pi Configuration from the Preferences menu

  2. Navigate to the Interfaces tab

  3. Select Enable next to SSH

  4. Click OK

With that done, we’re now ready to fire up Homebridge for RasberryPi on your iPhone. The app will take your through a setup process which is pretty much hands off. This will take care of all the installation steps required to get Homebridge running on your RasberryPi and then provide an easy interface to manage the configuration afterwards. We’ll get to that part soon when we walk through installing a device, but first the basic configuration process.

The process checks your prerequisites are all in order first, which we’ve already taken care of. Then you’ll be asked if you’re setting up a new server or reinstalling an existing one. Finally, you just need to specify your RasberryPi connection details and login credentials for SSH. Using the Pi account created during your OS install is the default here and will have the necessary permission. Once done, you hit Feed Pi and the install commences. The app notes this can take up to 30 minutes, so just leave it running and it will chime you when it’s done.

Pairing the Bridge

Now the Homebridge server is set up and running, we need to add it to your HomeKit setup. You’ll need to specify your connection details again the first time, and you’ll then be connected and presented with a dashboard (shown as the Status tab at the bottom of the screen). The Homebridge configuration file contains a HomeKit set up code, you can optionally change this, but you should be able to use the default. If you do want to change it you can do so under Tools > Edit config manually. This will take you straight into the config file where you can edit the ‘pin’. This file needs to be perfect, so care should be taken if you choose to do this.

This set up code is shown on the Status dashboard near the top, so you just need to enter this in your Home app to pair the bridge with HomeKit. Ensure the Homebridge status is ‘Running’ then go into the Home app and hit the + to add a new Accessory. Tap Don’t Have a Code or Can’t Scan? at the bottom, then tap Enter code… on the next screen.

Once the device pairs with HomeKit, the bridge and a few new accessories will appear listed in your Default room.

Adding a Device

There will be a couple of default devices included in the base install to demo the system: A temperature sensor showing the onboard temperature of the RasberryPi itself, and a generic switch which can be used to send a Wake on LAN signal to a select device on your network. To add more we need to go back to the app and look at the plugins we have available.

Specific device support is provided by third party developers who create plugins. Being an open source project, these developers are generally individual enthusiasts who want to add support for something they have. Consequently, your mileage will vary in terms of functionality, stability and support. The app comes with a number of plugins already available and supported natively. some of these tie in other smart home systems to HomeKit, such as the Logitech Harmony Hub, and others provide support for products which actually have official HomeKit support, such as LIFX…I’m not sure why you would add those through an unofficial third party bridge. You can view the available plugins by going to the Plugins tab from the bottom of the screen, then tapping on +.

Generally speaking the thing you want to add to your smart home probably isn’t in the built-in list. Not to worry, Homebridge has a vast array of plugins available so there’s a good chance of finding what you’re after. The plugins are found on the NPM package repository and will be prefixed with the term “homebridge-”. You can search for the one you need here.

NPM homebridge search

NPM homebridge search

Adding these other plugins (known as Universal plugins) requires some configuration which looks complicated, but is actually pretty straightforward. Before we go any further, though, we need to address a technical matter which can cause some confusion. Devices in Homebridge are actually classified into two groups. Accessories and Platforms.

Accessories are those devices which are communicated with directly by the RasberryPi via the network. This would be things like smart plugs, lights and sensors.

Platforms are those devices which are communicated with indirectly via the maker’s servers. This is the same way things like Alex and Google Assistant communicate with devices in the home, and indeed how most devices handle their smartphone apps. If you needed to create an account somewhere to use your device, it’s probably in this group.

You can view the installed devices you have in both groups by tapping the Devices tab at the bottom of the app screen and then selecting the grouping at the top. You’ll see the two demo ones in the Accessories group.

You add new devices from here, but you’ll need to have the right plugin installed first. Going back to the NPM search, find a likely candidate plugin and then provide the name to the app to install it. On the Plugins page in the app, tap the + and then select Universal from the list. Type the exact name of the plugin from NPM into the box and tap the Install button at the bottom.

Now the plugin in installed, go to the Devices tab and hit + again to add a new instance (it doesn’t matter which group you are looking at at the time). You’ll be presented with a list of the installed plugins, so choose the one you’ve just added. Here you need three things. The name (can be whatever you want to call it in the app), the group (Accessory or Platform)  and an identifier. The last two must be correct and come from the plugin details. 

Plugin page on NPM

Plugin page on NPM

If you look at the NPM page for the plugin you’ll see an “Easy Config” section. In that will be a label that is either Platform or Accessory followed by a name. That line gives you the group and identifier you need.

 eg: “platform”: “TadoAC”,

Enter the identifier exactly (case sensitive) in the second box in the app. Once done you’ll be given a screen with String, Array, and Dictionary buttons. This is the bit that look confusing, but all you need to do is add the items from the plugin Config section on NPM. You can just use the Easy Config section for the basic setup, but most plugins will offer Advanced options as well. These will be detailed in the section below the config list in NPM so you can see what they do and what options are available. You can add any or all of the advanced options as you wish.

To add these options you simply select the type of entry to add from the buttons on the app screen. Most of these will be String entries, they just have a label and a single text value.

 eg: “username”: “user@email.com”,

Tap string on the app screen, enter the Key (the first part in quotes), and the Value (the second part in quotes). There is no OK button, just hit < Back in the room left. Your new value will be in the list now. Do this for each config entry required on the plugin page and tap Save in the top right. If you entered things correctly Homebridge will restart and your device should now appear in the Home app. A word of caution here, if there is an issue with the plugin, or even if you just made an entry error, you can cause Homebridge to become unstable or fail to start correctly.

As an example, I’ve taken the Tado Smart AC plugin (the one Tado product that doesn’t have HomeKit support) . This one can be found under homebridge-tado-ac on NPM. The easy config has only three lines:

  • ”platform”: “TadoAC”,
  • ”username”: “user@name.com”,
  • “password”: “**********”

The first line is taken care of by the initial Add accessory screen. The other two we need to add as string entries. I’ve additionally added a third, tadoMode, which the NPM page describes as determining the control mode that the Smart AC will use when being given a command from HomeKit. These modes equate to the three options in the Tado app when activating manual control; until ended by user, until next automated change, or for a set time. The values to use for each are in the field description below the configuration options on the NPM page. 

Troubleshooting

This is an area where the app also makes things easier for the less Linux familiar. The first port of call is to use Troubleshooting mode to check the start up log for any issues. This is found on the Tools tab. Tap Troubleshooting and then tap Start Debugging at the bottom. This will run as single debug instance of Homebridge and capture logging on the app screen. This is a good way to find any config file issues that are stopping things working. 

You can fix any errors in your data entry by going to the Devices tab and tapping on the device at issue. That will take you back to the config entries page for that device. You can edit or delete any individual entries from there. Alternatively, you can use the Edit config manually option from the Tools tab to edit the config file directly. This is obviously more risky as formatting errors can make things worse, but if you’re comfortable editing config files this is a handy way to get to it quickly.

I’ve found in one case that a plugin install caused Homebridge to become highly unstable and fail to respond to HomeKit at all. In this case uninstalling and reinstalling the affected plugin resolved it. You can uninstall a plugin by going to the Plugins tab, tapping on the plugin and then on Deinstall. If you’re removing a dud install, you may also have to edit the config file to remove the relevant section if it doesn’t clean it up correctly. 

As the plugins are all third party, it pays to install one and monitor things for a bit to ensure it’s working as intended. By limiting yourself to one at a time it makes resolving these kinds of issues a bit easier. You’ll know what was changed and thus the likely cause of the problem.

Conclusion

The Homebridge for RasberryPi app makes setting up and using Homebridge vastly easier and more accessible, opening the use of this tool to many more HomeKit than would otherwise be possible. There is still some configuration required for most plugins, but hopefully the descriptions I’ve provided help to demystify that somewhat. Once you understand the basic config structure and device groupings, adding new plugins and devices is pretty easy.

It’s unfortunate that something like Homebridge is required to provide the functionality we may want out of our smart home, but it’s an issue not isolated to HomeKit. All smart home platforms are dependant on device support to work, and none of them support everything we could want to use. Homebridge is a valuable addition to any HomeKit home that also includes smart devices that don’t support Apple’s platform natively. Adding these devices to HomeKit isn’t just about Siri voice control, but being able to use them in scenes and automations as well. Many of these will have plugins available where the device has a suitable HomeKit definition available, which allows for a significant expansion of device options we have to play with, especially outside the US.