Skip to content

Instantly share code, notes, and snippets.

@phenotypic
Last active November 15, 2021 17:10
Show Gist options
  • Save phenotypic/c2de35f0dec0235c8600cfed29b59c1e to your computer and use it in GitHub Desktop.
Save phenotypic/c2de35f0dec0235c8600cfed29b59c1e to your computer and use it in GitHub Desktop.
Homebridge on a Raspberry Pi

Homebridge on a Raspberry Pi

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.

Index

Mandatory

Optional

Prerequisites

  • You have already installed the latest version of Raspbian
  • You are capable of connecting to the Pi via SSH

Basic setup

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

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.

Configuring Homebridge

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.

Starting Homebridge automatically on boot

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

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

Updating node and npm

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

Updating nvm

Simply run the install command again:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.0/install.sh | bash

Tips

  • 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
@biscuit303
Copy link

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.

@phenotypic
Copy link
Author

@biscuit303 Please open an issue within the relevant project with a full description of the issue including any additional information and error messages from within Homebridge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment