This gist walks you through the method I used for setting up Homebridge on my Raspberry Pi 3 Model B. Many aspects are taken from the original Homebridge wiki. Note that steps can vary between Raspberry Pi models and as packages are updated or changed.
Mandatory
- Prerequisites
- Basic setup
- Install
node
andnpm
withnvm
- Install Homebridge
- Configuring Homebridge
- Starting Homebridge automatically on boot
Optional
- You have already installed the latest version of Raspbian
- You are capable of connecting to the Pi via SSH
Once logged into your Pi, update the system packages:
sudo apt-get update && sudo apt-get upgrade
Ensure git
, make
, g++
and avahi
are installed:
sudo apt-get install git make g++ libavahi-compat-libdnssd-dev
Install node
and npm
with nvm
Install nvm
:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash
Restart the terminal window then run the following command, replacing VERSION
with the latest LTS number from the Node.js webpage:
nvm install VERSION
Note: With nvm
, npm
is not accessible via sudo
. As a result, when following guides which list commands like sudo npm install ...
, you must use npm install ...
instead. The same applies for any other npm
command prefixed by sudo
.
Install Homebridge with:
npm install -g homebridge
You can verify it is installed by running:
homebridge
This should start up homebridge successfully. Note that you will likely be presented with errors you can ignore like:
No plugins found. See the README for information on installing plugins.
...
Couldn't find a config.json file
This is due to the fact you have not completed your Homebridge setup, i.e. installed plugins and added their relevant configurations to the config.json
file. Despite the fact that Homebridge is bare-bones at the moment, you can still pair it with the Home app by scanning the QR code. When finished, you can stop Homebridge with control
+ c
.
Now that you have Homebridge set up, you can install plugins by using the command:
npm install -g PLUGIN_NAME
In order to integrate the plugins with Homebridge, you must modify your config.json
file located at ~/.homebridge/config.json
.
Most plugins will supply an example section of a config.json
, simply integrate this into yours. Note that all acessories/platforms are placed in the same config.json
file; a new file is not required for each plugin. Verify the formatting of your config.json
file with a tool like JSONLint.
By default, there is no mechanism for starting up Homebridge if your Pi restarts. This can be solved by a variety of methods listed on the original Homebridge setup Wiki. However, I prefer using pm2
due to its reliability, stability and features.
Install pm2
:
npm install -g pm2
Start pm2
with:
pm2 startup
Make sure to follow instructions displayed on the screen during this stage! Following this, add Homebridge to pm2
with:
pm2 start homebridge
pm2 save
That's it, you may want to verify that this step has worked by rebooting your Pi with:
pm2 stop homebridge
sudo reboot
After rebooting, you can check on the status of Homebridge through pm2
:
pm2 list
You can also monitor Homebridge when running with pm2
by using the command:
pm2 monit
Note: You can find homebridge logs from pm2
in this directory: /home/pi/.pm2/logs
. To clear the logs, simply run pm2 flush
Maintenance is vital for keeping your setup both reliable and secure.
First and foremost, you should constantly ensure that you have the latest system packages by using the commands:
sudo apt-get update && sudo apt-get upgrade
Update npm
packages with:
npm install -g PACKAGE_NAME
Whilst you don't need to do this too frequently, you may have to update your version of node
if it becomes too outdated.
To update, stop the pm2
instance, then run the following commands, replacing OLD_VERSION
with your previous version, and NEW_VERSION
with the new version:
nvm install NEW_VERSION
Uninstall the old version:
nvm uninstall OLD_VERSION
Set new version as default:
nvm use NEW_VERSION
nvm alias default NEW_VERSION
Reboot the Pi:
sudo reboot
Reinstall homebridge (config.json
is preserved):
npm install -g homebridge
Reinstall all homebridge plugins:
npm install -g PACKAGE_NAME PACKAGE_NAME PACKAGE_NAME
Finally, you must set up pm2
again. Go to the instructions and follow the instructions
Simply run the install command again:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.0/install.sh | bash
-
If you are having problems formatting your
config.json
, use JSONLint to validate it. -
Depending on your situation, it may also be a good idea to have your Pi accessible via SSH from outside your local network. To allow this, open port 22 on your router and direct it to the IP of your Pi. Consider setting up a dynamic DNS like FreeDNS on your Pi to automatically update your home's IP address to allow this functionality. However: be aware of the security risks associated with opening ports to the web; take a look at this guide.
-
For quick and simple maintenance via SSH, consider using an app like Terminus on your iPhone.
-
If you're using ethernet instead of Wi-Fi, you can completely disable your Pi's Wi-Fi by adding the following to your
/etc/modprobe.d/raspi-blacklist.conf
file (you can disable Bluetooth as well):
#Disable Wi-Fi
blacklist brcmfmac
blacklist brcmutil
#Disable Bluetooth
blacklist btbcm
blacklist hci_uart
Hi Tom, first of all, I would like to thank you for your work on the homebridge plugin. I am trying to make work the homebridge-web-garage with an ESP8266. I was able to get status of the door from the ESP, but when I try to open the door threw the home app on my phone, it crashes. I would like to know if you can help me to figure this out. You can contact me on my email : alexandreviau@live.ca
Thank you for your help.