Getting started with Homebridge on a Raspberry Pi Zero W

This post is a continuation of my original post guiding you through setting up a headless Raspberry Pi Zero W on macOS. Immediately after I wrote that post, not much happened with my rPi and it sat unplugged for a few months while I mulled over a project to put it to use for. Over the coming months however I have been increasingly interested in home automation exclusively with HomeKit. I got to wondering, “I should be able to control all the connected devices in my home using just the Home app running iOS 11 on my iPhone 7 Plus and not these other inferior apps!”.

While doing research for home automation, I stumbled on homebridge and it dawned on me that to use my rPi just for it. After getting everything installed and setup a few times (wiping the SD card between installs and retrying), I came to realize how surprisingly easy it is to setup! In this post I’m going to show you how to get your own rPi running homebridge, and even recommend some plugins to use to make it useful.

To start, I began taking inventory of all the things in my house I could add to homebridge to use with HomeKit. I had initially planned on only integrating my 2016 Samsung Smart TV and Playstation 4 in some fashion, but once I got everything installed and running I purchased a few TP-Link HS100 smart wifi plugs. The wifi plugs were on sale at my local BestBuy for $20/ea which is 50% off the normal price 😱 I couldn’t say no, plus I’d had my eye on them already since research into homebridge plugins yielded them to have very good support with the system regardless of not being supported at all by HomeKit.

Install node and homebridge

Start by installing node with npm from here (don’t install from apt-get because the package in the PPA is incredibly out of date). An alternative to npm would be to use yarn, but that route remains untested to my knowledge.

Once node is installed, go ahead and install homebridge. Installing it is as simple as installing a global npm package!

npm install -g homebridge

Running homebridge

You can experiment with running homebridge from the cli once installed by just calling the executable. It’ll look for config in /home/<user>/.homebridge so feel free to add a basic config file there for testing.

The ideal way to use homebridge, however, is running it as a service in the background with systemd. This allows homebridge to auto-run on startup and doesn’t require a shell being open on your computer. One caveat I found with this setup, though easily solvable, is that the path to the homebridge executable is unknown to the required homebridge system user you have to create while seting it up. Its not documented anywhere, but can be fixed by adding the node bin path to the user. You can do this by creating a new file in /etc/profile.d and making it executable

sudo touch /etc/profile.d/node.sh
sudo chmod +x /etc/profile.d/node.sh

where the contents are

export PATH=$PATH:/opt/nodejs/bin

What this does is add /opt/nodejs/bin to the PATH environment variable of every user profile. This means the system user homebridge can now run the homebridge exectuable normally without a full path to its location. The alternative is to specify the full path of the executable when calling it.

Configuring homebridge

At this point, reboot the pi for the system user to pick up the path to the homebridge executable and start it up. You won’t have any configuration setup for homebridge to use (unless you jumped ahead to here 😉) and it will complain about this. You can see the live stream of logs for the homebridge service with

sudo journalctl -u homebridge -f

Create the file /var/lib/homebridge/config.json and fill it with the the following starter configuration

{
  "bridge": {
    "name": "Homebridge",
    "username": "1A:2B:3C:4D:5E:6F",
    "port": 45525,
    "pin": "937-19-468"
  },
  "description": "SmartHome with Homebridge",
  "accessories": [...],
  "platforms": [...]
}

Notes

• Use this tool to generate a random username value in the configuration
• Replace ... with the plugins that you desire once you confirm homebridge can run on it’s own

After you’ve made all your changes, ensure that the homebridge user has ownership of the /var/lib/homebridge folder with

sudo chown -R homebridge /var/lib/homebridge

NOTE This step is very crucial because if the homebridge executable can’t write it’s various caches to the folder, things might blow up on you!

Extending homebridge

Homebridge by itself isn’t very useful you’ll find, and where it really shines is its community-backed plugin system. Just doing a search on npmjs.com for homebridge-plugin yields a few hundred plugins to choose from. Sort by popularity and the first few pages are full of good plugins.

Here’s a list of the ones I’m using/recommending:

• https://www.npmjs.com/package/homebridge-cmdswitch2
  • 👆 In combination with https://github.com/dhleong/ps4-waker
• https://www.npmjs.com/package/homebridge-samsungsmarttv
  • My ongoing fork (waiting for iOS 11 to support the Speaker service properly in the Home app, they’re part of the HomeKit spec just not implemented at the time of writing)
• https://www.npmjs.com/package/homebridge-tplink-smarthome (Support for switches, bulbs, and plugs)

Using homebridge with the iOS 11 Home app

The moment you’ve probably been waiting for: setting Homebridge and “accessories” (connected devices) up in iOS Home is very straight forward. The in-app documentation is very easy to follow, and if you’re running the homebridge cli tool from a terminal (not the service-based system user), you can just scan the QR code that is generated when you run homebridge with the Home app. The alternate Home setup method is that you’ll have to enter the pin you configured in the config.json file intead.

Below is a video of the end product and how well it works with the iOS 11 Home app. The video starts out showing how the different devices are triggered in the app (and how some devices have to be interfaced with, particularly my smart TV and PS4 there is some latency which I can go into in detail later) followed by show how to interface with devices through Home Scenes using Siri.