Pushing HomeKit to the Limit: Homebridge Setup Guide

In my last post, I spoke about Homebridge and how I used it to expose non-Homekit devices to Apple’s ecosystem. While there are guides out there, I often find they don’t include all the information–or are far too technical. So here it is, my guide to setting up Homebridge!

Hardware-wise I recommend the Raspberry Pi 3b. I chose this as the power consumption is low–as well as the fact that I had one lying around. The 3b also has built-in WiFi so it gives flexibility for the future. If you’ve already got your Pi set up, you can jump straight to Homebridge Prerequisites section. For running the Pi I installed Raspbian Stretch Lite, which is the headless version.

Installing Raspbian

The first thing you’ll want to do is download Raspbian Stretch Lite from their website here. Extract the .ZIP and you’ll find a .IMG file inside. You need to flash the Pi’s Micro SD card with this .IMG, my software of choice for this is Etcher by Belena.

Once you’ve flashed the SD card there’s one more step before booting the Pi. This is enabling SSH so you won’t have to connect a keyboard and screen to the Pi. To do this create a file called ssh without a file extension and put it in the root folder of the Pi. Doing this will enable SSH when the Pi next boots. Worry not, if you’ve already booted the Pi, this method works at any point.

Connecting to your Pi

Now your Pi is up and running, SSH into it, I recommend PuTTY (if running Mac or Linux you can use Terminal). The default mDNS should be raspberrypi, but if you have several Pi’s you’ll need to find the IP address. You can do this with your router, but I find it much easier to use Advanced IP Scanner or Angry IP Scanner. The default username/password is pi/raspberry. You can change the default password using the command passwd.

Next, you’ll want to give the Pi a static IP address. You can use your router, or set it up through the Pi itself. As everyone’s router is different I’ll show the Pi method. To give the Pi a static IP address first type:

sudo nano /etc/dhcpcd.conf

Scroll to the bottom of the config file and uncomment and adjust the following lines of code:

interface eth0
static ip_address=chosen IP i.e. 192.168.0.50/24
static routers=192.168.0.1
static domain_name_servers=192.168.0.1

Save the file using Ctrl + o and then exit nano using Ctrl + x. After this, you should then reboot your Pi. To do this use the command

sudo reboot

Once your Pi boots up, log in and type sudo ifconfig, this should return with the IP address you set. Note: The router/DHCP method is much better as if you move/change router it’ll cause issues. Trust me it’ll avoid future headaches…

Homebridge Prerequisites

You can now begin the process of installing the prerequisites needed to get Homebridge working. There are a few bits to install before you can install Homebridge itself. First, you’ll want to update the default system packages, to do this type the below commands:

sudo apt-get update
sudo apt-get upgrade

This may take a little while to install depending on when you installed/last updated your Pi. It will also ask you if you want to continue, simply press [y]. You’ll then want to install the Node.js package manager–this is how you install plugins for Homebridge. To do this type the below commands:

curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
sudo apt-get install -y nodejs

The final step will be to install Avahi and its dependencies. These are for the mDNS package within HAP-NodeJS’s library. To install, use the below command, again pressing [y] when required:

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

Setting up Homebridge app

Now that the prerequisites are installed you can install Homebridge! Homebridge is published through NPM, to install using the below command:

sudo npm install -g --unsafe-perm homebridge

While not necessary, I recommend including the –unsafe-perm section of the code. This avoids an issue where the user root doesn’t have access to /root/.node-gyp/5.5.0. After this Homebridge is now installed. To run Homebridge, type homebridge, you should see this screen.

You can now sync up to Homekit, but you’ll want to install some plugins first. If Homebridge is running simple press Ctrl + c to stop it. I’ve written a guide on setting up an IR Blaster through Homebridge which you can find here. You can find a list of all available plugins from Homebridge here. Once you’ve got your desired plugins installed you can then start working on the config.json file. To start writing your config.json you’ll want to type the following command:

sudo nano ~/.homebridge/config.json

This will open up a blank page–because the file doesn’t currently exist. Below is a blank config.json for you to add your plugins to–if left empty will give out an error if you don’t have anything in a section delete it. You can change the name, username, pin, and description. but don’t need to.

{
    "bridge": {
        "name": "Homebridge",
        "username": "CC:22:3D:E3:CE:30",
        "port": 51826,
        "pin": "031-45-154"
    },
    "description": "Description of Homebridge Pi.",
    "accessories": [
        {
        }
    ],
    "platforms": [
        {
        }
    ]
}

You’ll want to add the accessories/platform settings. These will differ for each plugin, so you’ll need to refer to plugin creator’s readme information. You can startup Homebridge, it should look like the below picture. You may end up with one or two smaller errors in the config, so recommend putting your config through a parser.

Getting Homebridge to run on boot

Now that you’ve got Homebridge up and running you’ll want it to start on boot. The method I use is via systemd, as this means that if for any reason it crashes it will restart. The steps for this are straightforward and doesn’t take long to setup. The first stage is to paste some code, the first code to paste is this gist, and you’ll want to paste it here:

sudo nano /etc/default/homebridge

You’ll then save and exit. The next code you’ll want to paste will be this gist, and you’ll want to paste it here:

sudo nano /etc/systemd/system/homebridge.service

Note: You may have to remove the /local/ in the above document. For my install, I had to remove this, so it’s likely you will too. Simply change the line /usr/local/bin/homebridge to /usr/bin/homebridge.

Save and exit, then create a new user to run the service, to do this type the below commands:

sudo useradd --system homebridge
sudo mkdir /var/homebridge

Copy across the Homebridge files you’ve been working on and move them to the Homebridge user’s directory. As well as assigning the relative permissions. This is where you’ll now alter your config.json in the future. To do this type the below commands:

sudo cp ~/.homebridge/config.json /var/homebridge/
sudo cp -r ~/.homebridge/persist /var/homebridge
sudo chmod -R 0777 /var/homebridge

After this is all setup you’ll then need to reload and start the systemctl system. To do this type the below commands:

sudo systemctl daemon-reload
sudo systemctl enable homebridge
sudo systemctl start homebridge

Homebridge will now start on boot. You can check the status of Homebridge anytime using the command:

sudo systemctl status homebridge

If you do want to adjust the Homebridge config you’ll want to stop Homebridge, to do this type:

sudo systemctl stop homebridge

I recommend that you test any config changes. Use the config located in /.homebridge/, as is easier to debug. You’ll need to copy the config.json over again to see the changes.

Welcome to the magical world of Homebridge. It’s a great way to get almost anything into the Apple Homekit ecosystem–but once you start you’ll want to automate everything! If you’ve had any issues setting up Homebridge drop a comment below and I’d be more than happy to answer them!

Credit to johannrichard for the systemd code: https://gist.github.com/johannrichard

---

by Sam Brooks

Sam is the founder and editor for Tech Trail. With a background in Broadcast Engineering, and great enthusiasm for smart home and emerging technologies.

More by Sam →

• 
• 
• 

---