Homebridge, the secret sauce to making HomeKit awesome

As mentioned in the previous post, my HomeKit setup is made up of quite a few devices. Many of these are not HomeKit compatible out of the box; they are either too old, or the manufacturer chose not to add HomeKit support. Homebridge magically makes all these available in my ecosystem as if they came with 1st party HomeKit support.

Homebridge logo

Homebridge allows you to integrate with smart home devices that do not support the HomeKit protocol.

Installation

It may be scary for the non technical person out there, but it should be. Homebridge is surprisingly straightforward to set up. I did it on a (very old) Mac Mini and I found the documentation to be accurate and up to date. As it’s usually the case, developers strictly provide installation guides for their own work, rather than for all the dependencies. Luckily Homebridge only has one dependency (Node.js) so this steps should not take long for you to complete. (I recommend you follow the official instructions, but if you’re in a hurry, you can try the steps below)

Node.js

First check that you don’t already have node installed. Open a Terminal window and run the command below. You need to see a result that shows v4.3.2 or greater.

node --version

If you don’t have Node installed, proceed with the installation by downloading it from here. Follow the installation instructions and then run the command above one more time to make sure you’re ready to install Homebridge.

Homebridge

Installing Homebridge is relatively straightforward. Open the Terminal app and issue this command to install the node package:

$ sudo npm install -g --unsafe-perm homebridge

Still in Terminal, move to your home folder and try running homebridge. You’re very likely to see a message like the one below, followed by a QR code and a HomeKit code. Ignore these for now! 

$ homebridge
No plugins found. See the README for information on installing plugins.

Rather than adding the bridge to HomeKit, you should take the time to create your very own configuration:

$ nano ~/.homebridge/config.json

Depending on the devices / plugins that wish you to add, paste the following:

{
    "bridge": {
        "name": "Homebridge",
        "username": "CC:22:3D:E3:CE:30",
        "port": 51826,
        "pin": "989-98-989"
    },
    
    "description": "This is an example configuration file and you should make sure to replace this description and the pin info above with something else",

    "accessories": [
        {
            "accessory": "TV",
            "name": "Panasonic",
            "description": "Lounge TV",
            "ip": "192.168.1.100",
            "maxVolume": 13
        }, 
        {
            "accessory": "Onkyo",
            "name": "Receiver",
            "ip_address": "192.168.1.111",
            "model" : "TX-NR509",
            "poll_status_interval": "900",
            "default_input" : "sat",
            "default_volume": "35"
         }
    ],

    "platforms": [
        {
            "platform":"BelkinWeMo",
            "name":"WeMo Platform",
            "ignoredDevices":[  
            ]
        }
    ]
}

Feel free to replace the description above with whatever you like. Just make sure you keep the quotes and the file contains valid JSON. If in doubt, use a JSON validator website to check the config.

Important: change the pin number above with whatever number you wish that matches the pattern provided (3 digits, 2 digits, 3 digits).

The “name” you see above is quite useful: Siri will use that to perform actions on your device. For example, I can say “Hey Siri, turn off the Panasonic” and Siri will switch the TV off.

The accessories and platforms are the main types of plugins that you can add. Simple things are usually just an accessory. You’ll see that each homebridge-plugin has its own configuration snippet that you will end up adding to the config above.

In my case, to add the TV accessory above, I did the following things:

 $ npm install -g homebridge-panasonictv
  • I then added an accessory to my configuration file
{
       "accessory": "TV",
       "name": "TV",
       "description": "Livingroom tv",
       "ip": "192.168.178.20",
       "maxVolume": 15
}

If you’re not familiar with code or JSON, think of the “accessories” (or “platforms”) line as a parent for multiple accessories (platforms), that are separated between each other with a comma. Don’t forget to use the JSON validator website when you’re not sure you added your accessory or platform right. The square brackets indicate a collection or siblings (multiple accessories separated by commas). The curly brackets simple encapsulate an accessory. Pay attention to how the TV and Onkyo accessories are grouped together inside the “accessories” parent.

You can add as many individual accessories (platforms) as you wish but remember to install the corresponding plugins first.

To recap, I have installed node, homebridge, and some plugins. I then updated my config file with my own settings for the plugins I selected, so it’s time to finally start homebridge:

$ homebridge

If all the stars are aligned, you should now be looking at a QR code. Launch the Home app on your iOS device (and now even on your Mac), tap the + button and then select Add Accessory. Follow the instructions and pair the Home app with your Homebridge installation.

Homebridge screenshot from the Home iOS app

Congratulations, you now have a working HomeKit bridge that can breathe new life into old tech!