Getting started with Homebridge on a Raspberry Pi Zero W
Tags: raspberrypi, homebridge
Published: 2018-03-24 18:51:22

---
title: Getting started with Homebridge on a Raspberry Pi Zero W
published: true
tags: raspberrypi,homebridge
canonical_url: https://brandonb.ca/getting-started-with-homebridge-on-a-raspberry-pi-zero-w-with-homekit
---

This post is a continuation of my original post guiding you through [setting up a headless Raspberry Pi Zero W on macOS](/raspberry-pi-zero-w-headless-setup-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](https://www.macrumors.com/guide/homekit-101-getting-started-beginners/). 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](https://github.com/nfarina/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.

<!-- break -->

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](https://github.com/sdesalas/node-pi-zero#v890) (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](https://yarnpkg.com/en/), but that route remains untested to my knowledge.

Once node is installed, go ahead and install [homebridge](https://github.com/nfarina/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](https://gist.github.com/johannrichard/0ad0de1feb6adb9eb61a/). 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](https://www.miniwebtool.com/mac-address-generator/) 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](https://www.npmjs.com/search?q=homebridge-plugin&page=1&ranking=popularity). 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](https://www.npmjs.com/package/homebridge-cmdswitch2)
  - 👆 In combination with [https://github.com/dhleong/ps4-waker](https://github.com/dhleong/ps4-waker)
- [https://www.npmjs.com/package/homebridge-samsungsmarttv](https://www.npmjs.com/package/homebridge-samsungsmarttv)
  - [My ongoing fork](https://github.com/brandonb927/homebridge-plugin-samsungsmarttv) (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](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.

<video width="100%" height="320" controls="">
        <source src="https://dc1r9kxqg42ml.cloudfront.net/brandonb.ca/posts/getting-started-with-homebridge-on-a-raspberry-pi-zero-w-with-homekit/homebridge-ios-home-demo.mp4" type="video/mp4"></source>
        <p>Hmm, your browser doesn't seem to support HTML5 video.</p>
      </video>