Set up Homebridge easily with an app

When you buy through links in this article, I may earn an affiliate commission. Learn More.

Updated: 30 June 2020

The app discussed in this article is currently not working. Due to recent changes to the minimum versions of dependencies for HomeBridge and the fact that this app forces an older unsupported version, using this process will not be successful.

There are also issues with using this app on a raspberry pi 4, which results in incorrect system stats and unstable connection.

Not to worry though, there is a better way to get into Homebridge now. Check out how to use the HOOBS project to get up and running fast.

——

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.

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, in another country.

Some of the normal install documentation

Some of the normal 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 Raspberry Pi, and is designed to take you through the setup of the Homebridge server on a fresh Raspberry Pi device. While there is a MacOS version of Homebridge, for most people using a cheap and unobtrusive Raspberry Pi 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 Raspberry Pi devices are perfectly suited for.

Setting Up the Server

Naturally, the first thing you’ll need is a Raspberry Pi and to have the Homebridge for Raspberry Pi app installed on an iPhone. There are many places to source a Raspberry Pi. You can get a very bare bones model, but for the purposes of running a permanent head-less server, which your Homebridge will be, you really want an enclosed case to keep it protected from knocks, bugs, and dust (to the extent any computer can be). I’d recommend the CanaKit Raspberry Pi 3 B+ (B Plus) Starter Kit which includes a case, a good size storage card and everything you need to set up from scratch.

 
 

The included MicroSD card is preloaded with the NOOBS (New Out Of Box Software) operating system installer, specifically for the Raspberry Pi. 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 Raspberry Pi and let NOOBS boot up. Use NOOBS to install Raspbian (the recommended default) by simply selecting it from the menu.

The install will boot you into a Linux desktop to complete the setup. You’ll have to set up a password, the default admin user account is called ‘pi’. Note this down as you’ll need it for to connect the app later.

Next you’ll be able to connect to your WiFi network, but you can use a wired Ethernet connection if you prefer.

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 Raspberry Pi.

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 Raspberry Pi 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 Raspberry Pi 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 Raspberry Pi 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 Raspberry Pi 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 Raspberry Pi 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.

Plugin Issues

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.

Homebridge won’t start and shows no errors

A common issue that may arise is the failure of Homebridge to start (or stay running) after a power failure or plugin install. This is most likely caused by a corrupt log file. If the RasberryPi is turned off suddenly it could cause the log to become incorrectly terminated, and prevent Homebridge from starting normally. This can be confirmed by running Debug mode as above, as this uses a local config and bypasses the log files normally used. If that runs fine, then you can try simply deleting the log file at issue.

Unforftunately there is no option to do this in the app, but you can use the Terminal option on the Tools tab to access it. Once the terminal is open you can confirm the log file issue by entering the following commands:

cd /var/log
ls -l homebridge*

This will show the file size of both log files. If either is more than 9 digits it’s probably corrupt. Delete it with the command

sudo rm homebridge.<log>

where <log> is the extension of the affected file. Once done, try starting Homebridge again.

Bridged Accessory error

Sometimes after adding a new accesory you may be unable to start homebridge, and if you check the error log by going to Tools > Logs you might see (somewhere near the top) an error like this:

Error: Cannot add a bridged Accessory with the same UUID as another bridged Accessory

This is a fairly normal occurence resulting from junk in the homebridge accessory cache. The app provides a quick fix. On the Tools tab under the top Actions section is the option to Clear cached accessories. Just tap that (it won’t do anything visually), and try starting Homebridge again.

Conclusion

The Homebridge for Raspberry Pi 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. 


David Mead

David Mead is an IT infrastructure professional with over 20 years of experience across a wide range of hardware and software solutions. David holds numerous IT certifications and has dedicated himself to helping others with technology throughout his career.

Previous
Previous

Smart devices, Machine learning, and why you should care

Next
Next

IoT worms Mirai and Gafgyt get an upgrade