What Is Homebridge?

I’m sure some of you have been frustrated with the lack of option with Homekit devices, especially compared to Alexa and Google Assistant compatible ones, let alone all of the Z-wave devices hitting the market.

Luckily some smart folks have figured out a way to allow these devices to communicate with HomeKit!

Disclaimer: Amazon links are affiliate links; these do not cost you anything, they just help fund the site. More details are in the disclaimers page.

Homebridge works as hub interface for non-Homekit compatible devices. There are so many Z-wave and Zigbee devices that are very popular, but aren’t natively supported by HomeKit, such as Nest Thermostat or Ring doorbells.

Homebridge allows you to recognize and control these devices with Siri and directly from the Home app on your iPhone.

To complete this Homebridge Guide you’ll need a Raspberry Pi, an SD Card, and a computer. I’m using my Mac, but I will leave links to all the resources I used along the way so you can follow along if you’re using a Windows machine.

Homebridge Guide – Installing Raspbian OS

The first thing you’ll need to do with your Raspberry Pi is have it running Raspbian OS. The easiest way to do that is to plug the SD card in your computer, and use an application called PiFiller. (http://ivanx.com/raspberrypi/)

You can download Raspbian Here: https://www.raspberrypi.org/downloads/

Once both are downloaded, run PiFiller, select the SD Card you want to install the OS on, and then select the downloaded OS file. Wait a few minutes, and that’s it. Raspbian is installed.

PiFiller will automatically format your SD Card in the FAT format.

It will prompt you to Enable SSH (you want to select YES)

If you don’t have a Mac, you can follow the raspberrypi.org guide using their NOOBS software to install the OS on the card.

Once it is installed, you’ll want to connect your Raspberry Pi to your monitor and do the initial setup process. There isn’t much to do, but it is recommended to change the default password of the Pi.

If you don’t have a keyboard you can hit the X in the top right corner of that window, and change the password manually only using your mouse.

To do so, you’ll click the Raspberry button in the top left of the screen, and go to Preferences, and select Raspberry Pi Configuration.

By doing it this way, you can actually use your mouse to select text, and copy paste a bunch of letters to make a new password for yourself. You then click Change Password, and paste the new password into the window that pops up.

Now we’ll switch back to the computer, and use the Terminal to SSH into the Raspberry Pi. This basically allows us to remotely control the Raspberry Pi. (if you are able to keep your Raspberry Pi connected to a monitor with an internet connection, you can simply type the commands into the built-in terminal there.)

Homebridge Guide – Installing Prerequisites for Homebridge

In order to SSH into your Raspberry Pi, you will Open Terminal and type in

ssh pi@raspberrypi.local

It may give you a prompt asking if you are sure you want to enter SSH, just type yes and hit enter.

It will prompt you for the password, which by default is “pi”; however it was recommended that you change it during the setup process. In which case you should enter whatever new password you chose.

Note: characters are hidden when typing in a password, so don’t be alarmed that nothing is showing up when you type.

There are several steps we need to take before Homebridge can be installed.

(source:https://github.com/nfarina/homebridge/wiki/Easy-Install-Raspberry-PI-(With-Start-with-boot))

The first step is to get all updates to the system.

To do this, you will type in the command:

sudo apt-get update

This typically doesn’t take too long, it just depends on your internet connection.

Once it is complete, we will install these updates:

sudo apt-get upgrade

This command will install all of the updates that we just downloaded. This command does take a while to install, just be sure your computer doesn’t go to sleep or lose connection with the Raspberry Pi. It may appear to be frozen or hang towards the end, but it will eventually finish.

Next command is to install curl. This is usually very quick.

sudo apt-get install curl

The next step will vary a little depending on which model Raspberry Pi you have. You can check the version by typing in the command

cat /proc/cpuinfo

If it says “ARMv7” under the model number, then you can go ahead and proceed with the following command:

curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash –

If you have an older Raspberry Pi that says “ARMv6” you’ll need to take a slightly different approach. (source:

wget https://nodejs.org/dist/v6.17.0/node-v6.17.0-linux-armv6l.tar.gz

tar -xzf node-v6.17.0-linux-armv6l.tar.gz

You can check to see if this worked by typing in the command:

node-v16.7.0-linux-armv6l/bin/node -v

It should spit out “v16.7.0”

Now that you have the files downloaded, you can go ahead and install nodejs using the command:

sudo apt-get install -y nodejs

This shouldn’t take longer than a minute or so.

The last step before installing Homebridge will be to install some library files:

sudo apt-get install libavahi-compat-libdnssd-dev

It will prompt you saying this will take up ~1.2MB of disk space, just type in “Y”and let it proceed. It will take a couple minutes.

Now all of the prerequisites for Homebridge have been successfully installed; we can go on and actually install homebridge.

Homebridge Guide – Installing Homebridge

The simple command is (there are 2 dashes before “unsafe” perm):

sudo npm install -g –unsafe-perm homebridge

This will take a little while, about 20 minutes or so, depending on which Raspberry Pi you have. There’s not much to while it’s installing, so just make sure your computer doesn’t lose connection and doesn’t shut off/go to sleep.

I tend to reboot the system after a big install, to make sure the changes have gone into effect; it may not be necessary so you can do it if you wish. If you do want to, the commands will be:

sudo reboot

Give it a minute or two to boot back up, and then ssh back into it with the following command:

ssh pi@raspberrypi.local

If all went according to plan, Homebridge should be working now. You can test this out by simply starting Homebridge:

Homebridge

If it worked, you’ll see a big QR code and some text showing that it’s running. However you still need two things to make it actually do anything. Firstly we need a plugin, and secondly we need a config file for that plugin.

Homebridge Guide – Setting Up Homebridge

I used the Samsung Smartthings plugin in the video, though obviously you can choose whichever plugin you need depending on which devices you want to connect to HomeKit. Most will have their own page on npm or github with instructions. They will also most often include a sample config text to use in your config.json file.

As for the config.json file, you can download the full homebridge package here: (https://github.com/nfarina/homebridge) You’ll notice there’s a file called “config-sample.json”

Now you’ll need a code editor to make the changes properly because using something like NotePad or TextEdit will format the text in a way that cannot be read/compiled by Homebridge.

I recommend either Sublime Text or BBEdit to open and edit the file.

Homebridge Guide – Config File Setup

There are 3 components to the config.json file. The “Bridge” at the top, this information is default and the same for everyone, you can technically change it if you want, but I don’t see any reason to.

The next is “Accessories”. This is often where you’ll have single devices, it will all depend on how the plugin is designed.

Lastly you have “Platforms”. Similar to accessories, though more common.

I’d like to point out the syntax and formatting of all this.

Notice under “Accessories” you have [] that encapsulates everything, and then {} that will include individual accessories.

NOTE: If you don’t have any accessories, delete the {} altogether. So your Accessories part will look like the screenshot above.

This is because if you keep the {}, even though they are empty, Homebridge will think there’s a plugin, but it’s blank, and this will cause errors.

If you have multiple Accessories or Platforms, you’ll have to include a comma after each one, but not the last one, like in the screenshot below.

There’s a nice tool at (https://jsonlint.com) that will verify your code and point out any errors. So you can copy paste your config.json file in there and see if it works before copying it over to Homebridge.

Once you have saved it as “config.json” you can transfer it over to the Raspberry Pi. If you have done everything on a Mac so far you’ll be wondering how to transfer a file from your computer to the Raspberry Pi via SSH. It’s quite simple (after hours of research). (Source: https://www.raspberrypi.org/forums/viewtopic.php?t=35152)

You’ll want to open Terminal and stay in the Mac part of things (no SSH connection). You will then change the operating directory to wherever your config.json file is. If you downloaded that folder, it will most likely be in a folder named Homebridge in your Downloads.

In Terminal, you’ll want to change the operating directory to that folder by typing the following:

cd /Downloads/homebridge

You should notice that the base line of terminal now includes that directory. You can check to see if your config file is there by typing:

ls

This simply lists out all the folders and files in that directory. You should see config.json there.

Now the command that moves it over:

scp config.json pi@raspberrypi.local:~/.homebridge

You will be prompted to type in your Raspberry Pi password, and then the transfer will be complete. It’s a tiny file so it should be near instant.

Homebridge Guide – Homebridge Startup on Boot

This is the last step to getting the Homebridge complete in terms of functionality. However there is one more step we are going to take, which will ensure that Homebridge automatically starts up whenever you boot up your raspberry pi.

We are going to SSH back into the Raspberry Pi.

ssh pi@raspberrypi.local

We will then run the following command to install the startup sequencer.

sudo npm install -g pm2

You can do this with or without the additional “—unsafe-perm” at the end of the command. I got some errors when I included it so you can try it either way.

This is a long process, about 20 minutes, so as always, just make sure your computer doesn’t lose connection with the Raspberry Pi.

Once it is complete we’ll start it up by typing:

pm2 startup

Starting the program for the first time, it will prompt you to copy paste a line of code to enable it as a startup program, so just follow the on screen instructions.

Once you’ve done that, have it start homebridge as part of its startup procedure:

pm2 start homebridge

When it has started and you can type another command, just type in:

pm2 save

This will save the sequence of homebridge starting up whenever the Raspberry Pi is turned on. All that’s left is to reboot your Raspberry Pi to make sure it worked, and that’s it!

Now you can add the Homebridge to your HomeKit, just as you would any other device, by tapping the + icon in the top right corner of your Home app.

You can either scan the QR code it generates when you run it independently, or you can type in the code manually (preferable since you won’t need to muck around with terminal anymore). The code is the same for everyone:

031-45-154

It will first find the Homebridge, and then it will also add any plugins / devices that you have added. It’s not instant so don’t worry if it takes a minute on your phone.

And just like that, you can now control non Homekit devices straight from the Home app and with Siri.

Resources:

PiFiller: (http://ivanx.com/raspberrypi/)

Raspbian OS: (https://www.raspberrypi.org/downloads/)

Homebridge Guide: (https://github.com/nfarina/homebridge/wiki/Easy-Install-Raspberry-PI-(With-Start-with-boot)

Config Files: (https://github.com/nfarina/homebridge)

Config File Transfer: (https://www.raspberrypi.org/forums/viewtopic.php?t=35152)

Config.json Validation Tool: (https://jsonlint.com)