How to connect incompatible accessories to HomeKit using Homebridge

Wish you could have a house full of HomeKit-enabled products? Homebridge might be able to help with that!

If you're tired of waiting for your favorite home automation products to get HomeKit support, you might try Homebridge! Homebridge is a NodeJS server that acts as a HomeKit-enabled bridge, linking up non-HomeKit-enabled products to your HomeKit setup. Once you've set up a Homebridge server, you can download plugins for non-HomeKit-enabled devices in order to access them with the iOS Home app and control them using your voice with Siri.

We're going to proceed through the tutorial assuming you want to install Homebridge on your Mac. You can also install Homebridge on Windows, Raspberry Pi, and other devices, but I've found the macOS installation process to be fairly straightforward and user-friendly.

Caveats and warnings

Before we dig in to Homebridge, there's some stuff we need to talk about. Firstly, HomeKit-enabled products are such a small subset of the home automation market for a reason: Apple is very serious about compatibility and security.

HomeKit-enabled products have to go through rounds of testing and adhere to certain security guidelines. The same can't be said for non-HomeKit-enabled products. Secondly, Homebridge and its accessory plugins are created and maintained by a community of developers — not a company.

If you choose to install Homebridge, proceed with caution and be mindful of what you choose to install on your computer and your devices. Homebridge requires some fussing with code and interaction with Terminal; if you're uncomfortable with either of those things, it's best not to proceed with this tutorial.

Lastly, don't forget to back up your devices; if you mess something up along the way, it's far easier to roll back changes than having to do a fresh install of macOS.

How to install Homebridge on your Mac

• The prerequisites
• Create the NodeJS server
• Set up the configuration file
• Understand the configuration file
• How to install plugins

The prerequisites

1. Make sure you have Xcode installed on your Mac. It's free in the Mac App Store — here's a link to download it.

2. Download and install Node.js (which comes with the NPM package manager). It's free — here's a link to download it.

   Note: Installing Node.js is very straightforward. You'll install it like any other non-Mac-App-Store application: Download, double click on the file, and follow along with the installation guide.

Create the NodeJS server

Here's where we're going to start working with Terminal. You'll be typing in (or copy-pasting code) to the command line. Follow along step-by-step to properly install Homebridge.

1. Launch Spotlight by pressing the following keyboard shortcut: Command ⌘ + Space bar.
2. Start typing in Terminal. When the app appears in Spotlight, you can press Enter.

3. Once Terminal's up and running, enter the following to install Homebridge globally:

   sudo npm install -g --unsafe-perm homebridge

4. Homebridge will be installed using the NPM package manager. Wait until the process is complete.
5. Type homebridge into Terminal to launch it.

6. You should see the following message:

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

   That means you've successfully installed Homebridge on your Mac!

7. Quit Homebridge by pressing the following keyboard shortcut: Control ⌃ + C.

   

Note: If you have trouble installing Homebridge on your Mac, check out the Homebridge support page or visit the Homebridge Slack to get help from the developers.

Set up the configuration file

Homebridge requires two things to add a new accessory to your HomeKit setup: a plugin (more on those in a bit) and an entry in the Homebridge configuration file. We need to create the configuration file before proceeding.

1. Open up a Finder window and press the following keyboard shortcut: Shift ⇧ + Command ⌘ + G to open up the Go to Folder dialog.

2. Paste the following path into the Go to Folder dialog:

   /usr/local/lib/node_modules/homebridge and press Enter on the keyboard.

3. Copy the file called config-sample.json to your Desktop.
4. Open up a Finder window and press the following keyboard shortcut: Shift ⇧ + Command ⌘ + G to open up the Go to Folder dialog.

5. Paste the following path into the Go to Folder dialog:

   ~/.homebridge and press Enter on the keyboard.

6. Drag the config-sample.json file from your Desktop to the .homebridge folder.

7. Rename the file config.json (delete the -sample portion).

   

Great work! You've installed the configuration file in the proper location. Before we get a little more familiar with the configuration file, you'll need to download a plain text editor. TextEdit on the Mac is great, but it's been known to mess up the configuration by changing quotes and apostrophes to "smart quotes" and "smart apostrophes" which is a big no-no for the configuration file. Homebridge suggests the Atom text editor. It's what I use to edit the Homebridge configuration and it works well!

Understand the configuration file

Open up the Homebridge configuration file (the one you copied to the following location ~/.homebridge) in the Atom text editor. You should see four groups of information: bridge, description, accessories, and platforms.

• Bridge: This is information used to describe your bridge (like a Philips Hue or Lutron bridge). You can change its name and the HomeKit pin.
• Description: This is a description of your bridge and the various plugins you've installed. You can edit the entire text portion.
• Accessories: These are individual, bridgeless accessories you've connected to your bridge (like a smart switch or plug).
• Platforms: These are accessories that are typically connected through a bridge (like Philips Hue or Lutron Caséta).

Homebridge will launch just fine with these faux accessories and platforms in place, but I've found it's best to delete them so you can start fresh when you install real plugins. You'll want to leave the accessories and platforms categories in place — just delete the data inside of the categories.

When you've cleaned out your file, it should look like this:

{

"bridge": {

"name": "Homebridge",

"username": "CC:22:3D:E3:CE:30",

"port": 51826,

"pin": "031-45-154"

},

"description": "This is an example configuration file with one fake accessory and one fake platform. You can use this as a template for creating your own configuration file containing devices you actually own.",

"accessories": [ ],

"platforms": []

}

How to install plugins

Homebridge plugins serve as the bridge between non-HomeKit-enabled accessories and the Homebridge server. The plugins speak the language of your home automation accessories and translate your iOS Home app and Siri commands. You can find plugins on NPM; all Homebridge plugins begin with the text homebridge-. I'll walk you through the installation of a plugin for the TP-Link HS105 Smart Wi-Fi Plug Mini. The installation process is exactly the same for all NPM Homebridge plugins, so you need only to find the plugin that corresponds with your product and follow along!

1. Visit the NPM site by going to this link. The link will take you to a search query for Homebridge plugins.
2. Start to type in hs100 until you see the homebridge-hs100 NPM plugin. Click on it.
3. Underneath the Installation section, look for the text that tells you how to install it.

4. Open up Terminal and enter the following:

   npm install -g homebridge-hs100

5. This will install the TP-Link Homebridge plugin, so wait for the process to complete.

6. Head back to the plugin page and look in the Configuration section. This will show you the text you need to enter into your Homebridge configuration file.
7. Open up the Homebridge configuration file (the one you copied to the following location ~/.homebridge) in the Atom text editor.
8. Enter the configuration text in the proper location and save your file. If you're installing the TP-Link plugin, your configuration file should look like this:

{

"bridge": {

"name": "Homebridge",

"username": "CC:22:3D:E3:CE:30",

"port": 51826,

"pin": "031-45-154"

},

"description": "This is an example configuration file with one fake accessory and one fake platform. You can use this as a template for creating your own configuration file containing devices you actually own.",

"accessories": [],

"platforms": [

{

"platform": "Hs100"

}

]

}

How to connect Homebridge to your HomeKit house

Alright, we've got Homebridge installed, we've got a plugin ready to go, and we're ready to get Homebridge up and running! Here's how you add Homebridge to HomeKit and start controlling your accessories.

1. Launch Terminal on the Mac.
2. Type homebridge and press Enter.
3. Homebridge should launch and begin to load up platforms and plugins.
4. Head to your iOS device and launch the Home app.
5. Tap the Add button in the top right corner of the screen (looks like a plus sign).
6. Tap Add Accessory.
7. Tap on the Homebridge accessory (mine's just called Homebridge).
8. You will see an alert that says, "This accessory is not certified and may not work reliably with HomeKit." tap Add Anyway.
9. Tap Enter Code Manually at the bottom of the screen.
10. Enter the HomeKit code for your Homebridge accessory. You can find it in the Terminal window underneath the text that reads, "Scan this code with your HomeKit App on your iOS device to pair with Homebridge."
11. Add your Homebridge accessory and tap Next.

12. Add your TP-Link Smart Plug (or other accessory you installed with a Homebridge plugin) and tap Done.

    

Congratulations! You've successfully linked a non-HomeKit-enabled smart home accessory to HomeKit. As long as there's a plugin available, you can add any non-HomeKit-enabled accessories you like. Just be sure to install the plugin, fill out the configuration file, and quit and relaunch Homebridge in Terminal.

How are you feeling?

Installing Homebridge is no small task! Were you able to pull it off? Struggle along the way? Did you find help in the Homebridge support pages and Slack or are you still looking for assistance? I'm looking forward to hearing about your experience and your thoughts on Homebridge; share them with me in the comments below or over on Twitter!