Introduction: Install Homebridge on Raspberry Pi and Windows
This tutorial is for people who want to install Homebridge on Raspberry Pi and Windows.
Initially, this tutorial was written in Portuguese here in Brazil. I tried my best to write it in English. So forgive me for some mistakes that might be in writing.
This instruction was divided as follows:
Step 1: What is Homekit?
Step 2: What is Homebridge?
Step 3: Installing Homebridge on Raspberry Pi
Step 4: Starting Homebridge on Raspbian Boot
Step 5: Installing the Homebridge Config UI X Plugin (Raspberry Pi)
Step 6: Installing Homebridge on Windows
Step 7: Installing the Homebridge Config UI X Plugin (Windows)
Step 8: Starting Homebridge with Windows
Step 9: Linking Homebridge to the Home app
Step 1: What Is Homekit?
Homekit is a development package provided by Apple for developers to build Internet of Things (IoT) solutions. This development package enables Apple-built devices (iPhone and iPad, for example) to control other devices, such as lamps or sensor information. From iOS 9 and Watch OS Homekit became a native tool, and due to all the technology implemented by Apple it is possible to create automation systems simply with this kit.
To identify Homekit-compatible devices that are active on the network and to configure and control these devices, you must have the Home app installed on any Apple device (iPhone, iPad, iPod touch, Apple Watch, Apple TV, HomePod, or Mac). Devices to integrate with the Home app can have a QR code that allows pairing with the Home app on your Apple device.
After configuring the device in the Home app, the user can control the device through a shortcut that is created on the main screen of the app or use Siri (voice assistant provided by Apple) and send voice commands to trigger the device.
Apple hardware and software requirements for Homekit use are:
- iPhone, iPad, or iPod touch (running iOS 10 or later);
- Apple Watch (running WatchOS 3 or later);
- Apple TV (4th generation);
- Apple HomePod;
- Macs (running macOS 10.14 Mojave or later);
When it comes to home automation and IoT, there are a number of cost-effective solutions on the market, however, the vast majority are not Apple-certified and are therefore not natively compatible with Homekit. If you're tired of waiting for Apple to certify these solutions for use with Homekit, you should use Homebridge.
Step 2: What Is Homebridge?
Developed by Nick Farina, Homebridge is a NodeJS server that emulates the Homekit API and makes it possible to use non-Apple certified devices with the Home app and Siri. The server is lightweight, can run on a home network and is modular, meaning it supports multiple plugins created and made available by an extremely active community in strengthening the tool.
The plugins are installed on Homebridge and most of them are intended to make Homekit compatible any non-Apple certified device. Plugins for use with Homebridge are installed directly from the NPM website.
Homebridge installation can be done on various systems, however, for this instructable will be used Raspberry Pi 3 Model B + running Raspbian operating system, and I will also explain how to install on Windows.
Step 3: Installing Homebridge on Raspberry Pi
Ideally, Homebridge should be available anytime you need it, so you should leave the server running 24/7. For this you can install the server on Raspberry Pi and keep running constantly on your home network.
If you do not have Raspbian installed and configured on the memory card, I recommend that you read the Instructable Install and Configure Raspbian on Raspberry Pi, follow the steps below and then return to continue.
With your Raspberry Pi running Raspbian, in the system home screen open the terminal:
At the terminal, type the first command below, press enter, and if prompted to confirm the action type Y and press enter. This type of confirmation often appears when removing or installing packages. Then type the second command, enter, confirm the command if prompted, and wait. These commands check and update the system if necessary:
sudo apt-get update
sudo apt-get upgrade
Type the command below at the terminal and hit enter:
ifconfig
Some information will be returned. If you are using a network cable to provide a network connection to your Raspberry Pi, go to the information part after “eth0:” and look for the eight-digit network card's MAC address and it will be after the word “ether " If you are using a WiFi connection to assign a network connection to your card, go to the information part after “wlan0:” and look for the MAC address of the eight-digit network card that will also be after the word “ether”:
Copy the eight-digit MAC address for your network card and save it in Notepad, as this address will be required later.
As I reported earlier, Homebridge is a NodeJS server and the plugins for it are installed directly from the NPM site. Raspbian usually comes with the NodeJS and NPM packages installed, however, there may be incompatibility between versions of both packages, so it is best to remove both installations and then reinstall.
To remove NPM, type the command below at the terminal, enter, confirm the command if prompted, and wait for the package removal to complete:
sudo apt --auto-remove purge npm
To remove NodeJS, type the command below at the terminal, enter, confirm the command if prompted, and wait for the package removal to complete:
sudo apt --auto-remove purge nodejs
After removing NodeJS and NPM, we can proceed to install the updated packages. To install NodeJS, type the command below into the terminal, enter, confirm the command if prompted, and wait for the package installation to complete:
sudo apt install nodejs
To install NPM, type the command below into the terminal, enter, confirm the command if prompted, and wait for the package installation to complete:
curl -L https://www.npmjs.com/install.sh | sudo sh
Type each of the commands below and press enter after each to confirm that the package installation was successful. These commands return the version of each package that has just been installed:
node -v
npm -v
Install Avahi and its dependencies. Enter the command below, enter, confirm the command if prompted, and wait for the installation to complete:
sudo apt-get install libavahi-compat-libdnssd-dev
After these procedures are completed we can install the Homebridge. Enter the command below, enter, confirm the command if prompted, and wait for the installation to complete:
sudo npm install -g --unsafe-perm homebridge
Then type the command below and hit enter to boot Homebridge:
homebridge
Homebridge will return some information:
1) The config.json file was not found by Homebridge. This file provides basic settings for running Homebridge and any installed plugins. Later we will create the config.json file and its settings.
2) No plugin installed. Homebridge without plugins installed is completely useless.
3) To link devices to the Home app you can read the QR code that gives you the information you need to pair. Since the config.json file was not created and configured, and there is no plugin installed, this QR code is currently not good, although in the Home app you will already be able to find Homebridge available for linking, but do not.
4) Another way to link devices to the Home app is through the “Add Accessory”, “I Don't Have a Code or Cannot Scan” option, and under “Nearby Accessories” the device is selected and you will then be prompted for the setup code. Note that the terminal is shown the eight digit code and must be entered to match the application.
You can later use either the QR code or the eight-digit code to link Homebridge to the Home app on your Apple device.
Press the CTRL + C keys on the terminal to have Homebridge shut down and the message “Got SIGINT, shutting down Homebridge…” will be returned.
To create the file config.json type the command below in the terminal and press enter. The blank file will open:
sudo nano ~/.homebridge/config.json
Download the file below. Open this file, copy the contents and paste into the file that is open in the terminal:
1) In “username” delete the sequence XX: XX: XX: XX: XX: XX and enter the eight digit MAC address of the network card you had previously noted. The letters of the address you enter must be all uppercase.
2) In "pin" you can keep the eight numeric digits or you can change to a sequence you want, remembering to keep the same separation format with the dashes. This will be the code you must enter at the time you link Homebridge to the Home app.
The other file information you can keep, as as you add plugins and accessories you can enter the required information.
To save the file edits press CTRL + O, press enter and then CTRL + X to close the file.
Attachments
Step 4: Starting Homebridge on Raspbian Boot
Starting Homebridge manually every time you turn on your Raspberry Pi is not very practical, so it is best to have the server run immediately after Raspbian starts.
Type the command below at the terminal and hit enter. The blank file will open:
sudo nano /etc/default/homebridge
Download the file below. Open this file, copy the contents and paste into the file that is open in the terminal:
To save the file edits press CTRL + O, press enter and then CTRL + X to close the file.
Type the command below at the terminal and hit enter. The blank file will open:
sudo nano /etc/systemd/system/homebridge.service
Download the file below. Open this file, copy the contents and paste into the file that is open in the terminal:
To save the file edits press CTRL + O, press enter and then CTRL + X to close the file.
To create a user who will run the service automatically at startup and give them the appropriate permissions, type each of the following commands and press enter after each:
sudo useradd --system homebridge
sudo mkdir /var/homebridge
sudo cp ~/.homebridge/config.json /var/homebridge/
sudo cp -r ~/.homebridge/persist /var/homebridge
sudo chmod -R 0777 /var/homebridge
sudo systemctl daemon-reload
sudo systemctl enable homebridge
sudo systemctl start homebridge
To restart the system type the command below and press enter:
sudo reboot
After system reboot, open the terminal again, type the command below and press enter to check if the service is already running:
systemctl status homebridge
If everything is OK the service will be running and you can see written “active (running)” and below the eight digit code that was previously entered in config.json.
Press the CTRL + C keys on the terminal. Type the command below and press enter to check the log of logged information:
journalctl -f -u homebridge
Press the CTRL + C keys on the terminal.
Attachments
Step 5: Installing the Homebridge Config UI X Plugin (Raspberry Pi)
To demonstrate the installation of a plugin on Homebridge I chose to use Homebridge Config UI X. This plugin allows through a browser to be able to configure, monitor, backup and restart Homebridge.
To install the plugin type the command below into the terminal, enter, confirm the command if prompted and wait for the installation to complete:
sudo npm install -g --unsafe-perm homebridge-config-ui-x
Type the command below at the terminal and hit enter. A file will open:
sudo nano /etc/sudoers
Using the keyboard down arrow or rolling the mouse, scroll to the end of the file and add the following line:
homebridge ALL=(ALL) NOPASSWD: ALL
To save the file press CTRL + O and then CTRL + X to close the file.
Type the command below at the terminal and hit enter. A file will open:
sudo nano /etc/default/homebridge
Using the arrow keys, scroll to the end of the line HOMEBRIDGE_OPTS=-U /var/homebridge, give a space and insert:
-I
To save the file press CTRL + O and then CTRL + X to close the file.
You will now need to edit config.json and add the plugin information added to Homebridge.
If you made step 4 to get Homebridge running immediately after Raspbian started, type the command below and hit enter:
sudo nano /var/homebridge/config.json
If you didn't put Homebridge to start with Raspbian, type the command below and hit enter:
sudo nano ~/.homebridge/config.json
The config.json will open:
Within the “platform” structure, all plugins that are being installed on Homebridge must be informed.
For Homebridge Config UI X, you must add the following code snippet that is in the file below. Download it, open it, copy the content and paste it into the file that is open on the terminal:
Using the arrow keys, go to “platforms” and enter the code snippet you copied from the file. In the image below you can see what the “platforms” structure will look like after adding the information:
If you want to validate the structure of your code after editing, just go to the JSONLint site, paste all the config.json code, click on "Validate JSON" and if everything is OK the message "Valid JSON" will be returned. If your code has any error will be pointed to the line with the error and returned a message describing the error:
To save the file press CTRL + O and then CTRL + X to close the file.
Reboot the system by typing the command below, hit enter and wait for the reboot:
sudo reboot
To open Homebridge Config UI X through the browser directly in Raspberry Pi you must access the address:
If you want to open Homebridge Config UI X in a browser from another computer connected on the same network as the board, simply replace the localhost word from the above address with your Raspberry Pi's IP. To verify the IP assigned to your Raspberry Pi, simply access the terminal, enter the command below and enter:
ifconfig
Probably the IP assigned to your Raspberry Pi starts with “192.168…”.
In my case, the board is IP 192.168.2.129, so just access the URL below any computer on my network:
A page similar to the image below will open and you will be prompted for a login and password. For both login and password, type admin and enter to access:
Please note that on the homepage is shown the QR code and below it the 8 digit pin that can be used to link Homebridge to the Home app. In the "Config" option of the tool, you can access config.json, edit if you need to and then save.
Browse through the features available in Homebridge Config UI X and familiarize yourself with the tool.
To stop the execution of Homebridge you can use the command below in the terminal:
sudo service homebridge stop
To restart Homebridge you can use the command below:
sudo service homebridge restart
To start Homebridge execution you can use the command below:
sudo service homebridge start
With the server running go to step 9 to continue linking Homebridge with the Home app on your Apple device.
Attachments
Step 6: Installing Homebridge on Windows
If you do not have a Raspberry Pi or other embedded platform that can run Homebridge, you can leave your server running on Windows.
You will need to install NodeJS and an alternative text editor to Windows Notepad.
Download NodeJS from one of the links below and then install it:
https://nodejs.org/en/download/
During installation check the checkbox that allows you to automatically install the necessary tools:
NodeJS is not a graphical interface program, so all actions are done on it from a command prompt.
Download Notepad ++ from one of the links below and then install it:
https://notepad-plus-plus.org/downloads/
In the Windows options menu when right clicking on any file will appear the option “Edit with Notepad ++” and you can select this option whenever you need to edit some text file or Homebridge file.
Go to the Windows "Start" menu, type and search for "Settings" and when found access the option. Click on "Network & Internet" and then click on "Network and Sharing Center." Under "Access Type" click on your active connection, click "Details" and copy the eight digit MAC address for your network card and save it in notepad, as this address will be required later:
In the Windows "Start" menu, type and search for "cmd" (Command Prompt) and when you find it, right click on it and select "Run as administrator":
With the terminal open, type each of the commands below and press enter after each to confirm that the NodeJS / NPM installation was successful. These commands return the version of each of the packages that were installed:
node -v
npm -v
After these procedures are completed we can install the Homebridge. Enter the command below, enter and wait for the installation to complete:
npm install -g --unsafe-perm homebridge
Then type the command below and hit enter to boot Homebridge:
homebridge
Homebridge will return some information:
1) The config.json file was not found by Homebridge. This file provides basic settings for running Homebridge and any installed plugins. Later we will create the config.json file and its settings.
2) No plugin installed. Homebridge without plugins installed is completely useless.
3) To link devices to the Home app you can read the QR code that gives you the information you need to pair. Since the config.json file was not created and configured, and there is no plugin installed, this QR code is currently not good, although in the Home app you will already be able to find Homebridge available for linking, but do not.
4) Another way to link devices to the Home app is through the “Add Accessory”, “I Don't Have a Code or Cannot Scan” option, and under “Nearby Accessories” the device is selected and you will then be prompted for the setup code. Note that the terminal is shown the eight digit code and must be entered to match the application.
Press the CTRL + C keys on the terminal to close Homebridge. The message “Got SIGINT, shutting down Homebridge…” will be returned and you will be prompted for confirmation, where you must type the letter Y and press enter.
To create the config.json file open Notepad ++, click on the menu "File", "New" and a new window will open. Click on the "Language" menu, scroll to the letter J in the list, and select "JSON."
Download the file below. Open this file, copy the content and paste it into the file that is open in Notepad ++:
1) In “username” delete the sequence XX: XX: XX: XX: XX: XX and enter the eight digit MAC address of the network card you had previously noted. The letters of the address you enter must be all uppercase.
2) In “pin” you can keep the eight numeric digits or you can change to a sequence you want, remembering to keep the same separation format with the dashes. This will be the code you must enter at the time you link Homebridge to the Home app.
The other file information you can keep, as as you add plugins and accessories you can enter the required information.
Click on the menu "File", "Save", name the file config.json and save it to the path "C:\Users\YOUR NAME OR DOCUMENTS\.homebridge":
Close Notepad ++.
Attachments
Step 7: Installing the Homebridge Config UI X Plugin (Windows)
To demonstrate the installation of a plugin on Homebridge I chose to use Homebridge Config UI X. This plugin allows through a browser to be able to configure, monitor, backup and restart Homebridge.
To install the plugin type the command below into the terminal, hit enter and wait for the installation to finish:
npm install -g --unsafe-perm homebridge-config-ui-x
NOTE: If during the installation of the plugin you find an error containing the terms MSBUILD / VCBuild.exe, just run each of the following commands independently and then try to install again from the above command:
npm install -g node-gyp
npm install --global --production windows-build-tools
npm install --global --production windows-build-tools --vs2015
You will now need to edit config.json and enter the plugin information added to Homebridge. Go to the path “C:\Users\YOUR NAME OR DOCUMENTS\.homebridge” and through Notepad ++ open config.json that was created earlier:
Within the “platform” structure, all plugins that are being installed on Homebridge must be informed.
For Homebridge Config UI X, you must add the following code snippet that is in the file below. Download, open, copy the content and paste it into the file that is open in Notepad ++:
Go to "platforms" and enter the code snippet you copied from the file. In the image below you can see what the “platforms” structure will look like after adding the information:
If you want to validate the structure of your code after editing, just go to the JSONLint site, paste all the config.json code, click on "Validate JSON" and if everything is OK the message "Valid JSON" will be returned. If your code has any error will be pointed to the line with the error and returned a message describing the error:
Save the file, close Notepad ++, and restart Windows.
To open Homebridge Config UI X through the browser go to:
A page similar to the image below will open and you will be prompted for a login and password. For both login and password, type admin and enter to access:
Please note that on the homepage is shown the QR code and below it the 8 digit pin that can be used to link Homebridge to the Home app. In the "Config" option of the tool, you can access config.json, edit if you need to and then save.
Browse through the features available in Homebridge Config UI X and familiarize yourself with the tool.
Attachments
Step 8: Starting Homebridge With Windows
Homebridge Config UI X provides a command that can be used to configure Homebridge as a service so that the server can be booted together with Windows. At the prompt type the command below, enter and wait for the installation to complete:
hb-service install
NOTE: If your Windows firewall requests permission to access the private network, grant it.
After the installation is complete, close the command prompt and restart Windows.
After the system boots, press CTRL + ALT + DEL to open Windows Task Manager. Go to the "Services" tab, look for Homebridge in the list and see if "Status" is "Running":
Right clicking on the Homebridge service will open the options where you can stop the service, restart and if the service is stopped you can start:
If you want to remove Homebridge from Windows startup, simply enter the command below, enter and wait for the uninstall to complete:
hb-service uninstall
NOTE: Depending on which antivirus you use you may have difficulty finding Homebridge from your mobile device. For testing purposes, when it is time to link Homebridge to the Home app, if the server is not found within two minutes, disable your antivirus, disable Windows Defender, restart the Homebridge service through Windows Task Manager, and try again to find the server from the Home app.
Step 9: Linking Homebridge to the Home App
The following guidelines are valid for both Homebridge running on Raspberry Pi and Windows. Make sure the server is running as the Home app will only find Homebridge if it is online.
I used an iPhone 8 Plus for this post, so from here the steps will be iOS based. For other Apple Homekit compatible devices, I suggest you check the menus for the following options.
Go to your iPhone's home screen and look for the Home app from the apps. If you can't find it, go to the App Store and install the app:
With the Home app open click on “Add Accessory”:
At the screen that opens click on “I Don't Have a Code or Cannot Scan?”:
In “Nearby Accessories” you will see the Homebridge. Click on it to open the pairing screen:
A message will open and you must click "Add Anyway":
You will be prompted for the “Homebridge Setup Code”. Fill in the code (PIN) you set in config.json and wait:
If all goes well you will see a screen stating that Homebridge has been added and is ready for use:
NOTE: If you receive a message stating that the code was not accepted or could not be added, close the Home app, restart Homebridge, and try the steps again.
On the next screen you will see the message “Additional Setup Required” as there is no Homebridge device yet. Click DONE and the app will return to the home screen:
On the home screen click on a house symbol, on the next screen click on “Hubs & Bridges”, click on the newly added Homebridge and you will see some information, and IF you later need to remove the Homebridge link, just Click on “Remove Bridge from Home”:
If you remove Homebridge from the Home app and want to add it again, you will need to delete the “accessories” and “persist” folders from the server.
In Raspberry Pi:
Terminate Homebridge by typing the command below into the terminal and pressing enter:
sudo service homebridge stop
If you made step 4 to get Homebridge running immediately after Raspbian started, type the command below and hit enter:
cd /var/homebridge
If you didn't put Homebridge to start with Raspbian, type the command below and hit enter:
cd .homebridge/
Type each of the commands below and press enter after each to delete the "accessories" and "persist" folders:
sudo rm -r persist/
sudo rm -r accessories/
Digite o comando abaixo no terminal e dê enter para iniciar o Homebridge:
sudo service homebridge start
Do the steps again to link Homebridge to the Home app.
On Windows:
Stop the Homebridge service through Windows Task Manager, go to the path “C:\Users\YOUR NAME OR DOCUMENTS\.homebridge”, and delete the“ accessories ”and“ persist folders. Start the Homebridge service through Windows Task Manager.
Do the steps again to link Homebridge to the Home app.
It's important to note that any device built into the Home app is powered locally. To be able to control Home app devices via an external network (3G / 4G connection, for example), you will need to set up an automation hub from one of the following Apple devices: iPad (running iOS 10 or later) , Apple TV (4th generation), or HomePod. This way, even away from home you will be able to remotely control your automation and IoT devices that are integrated with the Home app through Homebridge or Homekit.
By linking Homebridge to the Completed Home app you can explore the functions of this great tool. In the link below you can see the list of plugins available for use with Homebridge and by clicking on each one you can see their information and how to install:
https://www.npmjs.com/search?q=homebridge-plugin
If you have an IoT or home automation device and want to integrate it with Homebridge, just search if there is a plugin already created that will allow you to use this device in the Home app.
Since the root user is not enabled on Raspbian, for plugin installations always remember to use the word sudo before the terminal install command. If you do not use sudo the system will always prompt you to enter the system password to perform the action or you may return a message stating that you do not have permission.
On Windows, the command prompt must be running as administrator to be able to execute the command lines, and you should not use the word sudo as it will not be recognized by the system.
Whenever you install a plugin, be sure to add its information in config.json and restart Homebridge so that the Home app can be updated with the information from the added plugins. Likewise, whenever you uninstall a Homebridge plugin, be sure to remove the plugin's config.json information, as if you do not remove the server you may have startup issues.
Below are some links that may be helpful in finding more information about Homebridge and Homekit:
https://github.com/nfarina/homebridge
https://support.apple.com/pt-br/HT204893
If you have Sonoff devices and would like to use them with the Home app and Siri, I recommend you read the instructable Integrate Sonoff With Home App (Apple IPhone IOS).
