Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Running Homebridge on a Raspberry Pi
- Finding your Pi
- Basic setup preparations
- Install C++14 (Skip if this part if you are on Raspbian Jessie)
- Install Node
- Install Avahi and other Dependencies
- Install Homebridge and dependencies
- Proceed as Usual
- Running Homebridge on Bootup
- Running Homebridge on Bootup (systemd)
- Running Homebridge on Bootup (init.d)
- Running Homebridge on Bootup (/etc/rc.local) using Screen
- Running Homebridge on Bootup using pm2 a node.js process manager
Running Homebridge on a Raspberry Pi is straightforward. These instructions have been tested on a Raspberry Pi B+ with Raspbian, a Raspberry Pi 2 with Raspbian, and a Raspberry Pi 3 with Raspbian Jessie Lite.
For help installing an operating system like NOOBS on your Pi, check the official Raspberry Pi documentation.
For a video (in English), check this out.
Finding your Pi
After you install the operating system and connect your Pi to your network (and into power), you'll need to locate it so you can
ssh into it and run some commands.
The default "Raspbian" OS will automatically broadcast its presence on your network under the mDNS name "raspberrypi". If you are using Mac or Linux, you can reach your Pi easily:
Note that in SSH is disabled by default in recent version of Raspbian; see this page for instructions to re-enable it.
The default username for Raspbian is
pi and the password is
If you have a different OS installed on your Pi or you can't find it via
firstname.lastname@example.org then you can try connecting to your home router by pointing your web browser at somewhere like http://192.168.0.1, http://192.168.1.1, http://10.1.1.1 etc. (this depends on the router you're using and your network setup). Once you are logged in, you can usually find a list of devices connected to your network under "DHCP".
Windows does not support
ssh on the command line, but you can use a free SSH client like Putty to connect to your Pi.
Basic setup preparations
Once you're logged into your Pi, you should begin by updating the default system packages (note that these commands may be different if you are not running Raspbian OS).
sudo apt-get update sudo apt-get upgrade
For OSMC or other stripped down Raspberry OS, you may need to install git and make
sudo apt-get install git make
Install C++14 (Skip this part if you are on Raspbian Jessie)
If you are running a version of the Raspbian OS based on Debian Wheezy, it comes with a C++ compiler that is too old for some of the packages Homebridge requires. You'll need to follow these instructions to install an updated version of the C++14 compiler.
You should be able to type:
> g++-4.9 -v ... gcc version 4.9.2 (Raspbian 4.9.2-10)
Now you have the needed compiler, but it is not yet set to be the default compiler. You can fix that using the instructions here.
In my case I simply did this:
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.9 60 --slave /usr/bin/g++ g++ /usr/bin/g++-4.9 sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-4.6 40 --slave /usr/bin/g++ g++ /usr/bin/g++-4.7
You should be able to now type:
> g++ -v ... gcc version 4.9.2 (Raspbian 4.9.2-10)
For OSMC or other stripped down Raspberry OS, you may need to install g++
sudo apt-get install g++
Starting with version 4.0.0, NodeJS now supports ARM-based platforms like Raspberry Pi by default.
Node.js package manager install (Easiest, Preferred)
If you are running a newish Raspberry Pi with an ARMv7 chip or better, you can install NodeJS using their apt-get repository. Follow the instructions here.
curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash - sudo apt-get install -y nodejs
To check what chip your Raspberry Pi has, type:
The response will look something like:
Linux raspberrypi 4.4.50-v7+ 970 SMP Mon Feb 20 19:18:29 GMT 2017 armv7l GNU/Linux
Notice the armv7l which indicates that this method will work.
Node.js binaries install
If you have an older ARM chip, you can grab Node binaries for armv6 from here.
wget https://nodejs.org/dist/v6.9.5/node-v6.9.5-linux-armv6l.tar.xz tar xJvf node-v6.9.5-linux-armv6l.tar.xz sudo mkdir -p /opt/node sudo mv node-v6.9.5-linux-armv6l/* /opt/node/ sudo update-alternatives --install "/usr/bin/node" "node" "/opt/node/bin/node" 1 sudo update-alternatives --install "/usr/bin/npm" "npm" "/opt/node/bin/npm" 1
Node.js manual install
To manually install Node.js you can follow either of these guides:
Following those instructions explicitly will install version 4.0.0. There are many new versions published since then; to install the latest version (or any other version, Homebridge now requires a minimal Node.js version of v5.10.0), modify those instructions with the appropriate directory in the nodejs.org repository.
Install Avahi and other Dependencies
This is required by the
mdns package in
sudo apt-get install libavahi-compat-libdnssd-dev
Proceed as Usual
Now you can simply follow the instructions in the README to install Homebridge and start it up.
Alternate Installation (Untested)
If the "proceed as usual" section above didn't work for you, you might try these instructions which another user posted (but I have not verified because the simple
npm install -g homebridge worked for me):
Only try these if normal way doesn't work!
sudo npm install -g --unsafe-perm homebridge hap-nodejs node-gyp cd /usr/local/lib/node_modules/homebridge/ sudo npm install --unsafe-perm bignum cd /usr/local/lib/node_modules/hap-nodejs/node_modules/mdns sudo node-gyp BUILDTYPE=Release rebuild
/usr/local/lib should be replaced with
/usr/lib/ if you installed node using apt-get method above or with
/opt/node/lib/ if binary method used)
Running Homebridge on Bootup
Note that you should first make sure you can successfully run Homebridge manually as described in the main README
If you are new to Linux and the Raspberry Pi, it is recommended you read the instructions for all three methods before implementing your chosen method.
Running Homebridge on Bootup (systemd)
Follow this Guide
On newer Raspberry Pi and Debian systems (Jessie +), managing of services with
init.d is (transparently) replaced with
systemd. If you wish to use
systemd for running Homebridge on boot, you can find instructions in a Gist under johannrichard/homebridge. As you can see, the service definition is much shorter than a comparable init.d script.
Download the two files and place
/etc/systemd/system on your Raspberry Pi.
In order to use the systemd service as is, the following folders and user have to exists:
- A system user named
homebridge. You can easily create this user with
useradd --system homebridgeor choose a different name
- A directory called
/var/lib/homebridge, writable by the user created above, and a corresponding
config.jsonfile in that directory. Homebridge by default looks for its configuration in
/home/<username>/.homebridge. This is unsuitable for services and the
-U /var/lib/homebridgeflag ensures the config is read from a different place.
Then Enable and run the service (first time) with the following commands:
systemctl daemon-reload systemctl enable homebridge systemctl start homebridge
You can check the status of the service by calling
systemctl status homebridge
On subsequent reboots, it should start automatically, if not, use the
journalctl -u homebridge to check the error cause.
- The service will restart after 10 seconds if it fails for any reason (or if you kill it for example with
kill -s SIGSEGV <pid>)
- You might also try the tips in this Tutorial.
- To see the homebridge output, call
sudo journalctl -au homebridge. Make sure to specify
-n, or the QR code won't be displayed.
Running Homebridge on Bootup (init.d)
If you would like your Pi to start up Homebridge automatically on reboot, you will need to install an "init script". This free init script template is a great place to start.
For example, first go to the raw template file and select the whole page and copy it to your clipboard. Then connect to your pi:
ssh email@example.com sudo nano /etc/init.d/homebridge [paste clipboard contents]
Now you'll need to modify the top of the file. Here's an example:
#!/bin/sh ### BEGIN INIT INFO # Provides: homebridge # Required-Start: $network $remote_fs $syslog # Required-Stop: $remote_fs $syslog # Default-Start: 2 3 4 5 # Default-Stop: 0 1 6 # Short-Description: Start daemon at boot time # Description: Enable service provided by daemon. ### END INIT INFO dir="/home/pi" cmd="DEBUG=* /usr/local/bin/homebridge" user="pi"
This assumes you have installed Homebridge globally via
sudo npm install -g homebridge.
Now type CTRL+o to save, then enter, then CTRL+x to exit. Now change the file permissions and "install" the script:
sudo chmod 755 /etc/init.d/homebridge sudo update-rc.d homebridge defaults
It should now run when your Pi reboots. You can also start it up manually like this:
sudo /etc/init.d/homebridge start
To view the running logs, you can
tail the output log or error log:
tail -f /var/log/homebridge.log tail -f /var/log/homebridge.err
Running Homebridge on Boot (/etc/rc.local) using Screen
If you would like your Pi to start up Homebridge automatically in a Screen session on reboot, you need to install Screen and edit the Pi's
sudo apt-get install screen
sudo nano /etc/rc.local
Add this line before the
exit 0 line:
su -c "screen -dmS homebridge homebridge" -s /bin/sh pi
Hit Ctrl+X, Y to save and exit.
rc.local is similar to adding things to your Login items on macOS or putting things in your Startup folder on Windows. The command is run once when you boot the Pi.
The example above will open Homebridge using Screen. Screen acts like a separate terminal session that is run on the server rather than on your local computer. The advantage of this is that you can disconnect from the server without disrupting whatever was running in the Screen session. Typically when you open a terminal session session from one computer to another, when you exit (or get disconnected) everything running in the session at that time would be stopped (read more here: https://www.rackaid.com/blog/linux-screen-tutorial-and-how-to/).
Unless you are familiar with Screen or have a specific reason for using Screen, it is recommended that you set up Homebridge as a Service using
init.d. If running Jessie or above then ideally
systemd (especially if you are new to Linux)
Whilst it would get Homebridge running on boot, using Screen does add an extra layer of complexity. Using a Service is considered the "correct" way and has other advantages notably self restarting after a fail.
Running Homebridge on Boot using pm2 a node.js process manager
This assumes you have installed Homebridge globally via
sudo npm install -g homebridge.
First install pm2:
npm install -g pm2
Follow the instructions on screen.
Then add homebridge to pm2:
pm2 start homebridge pm2 save
Homebridge will now run when your Pi reboots.