How to install and configure Homebridge su Raspberry Pi

6 minutes of reading
  • Install and configure Homebridge, therefore have a personale HUB compatible Appthe HomeKits
  • Difficulty level: medium
  • software installation and configuration
  • Wifi network connected to the Internet
  • Raspberry Pi configured and connected to the home network
  • At least one device Apple with iOS operating system version superior to 8 connected to the Wifi network


Notes and disclaimer
  • qualsiasi eventuale modifica agli impianti domestici dev'essere progettata ed realizzata SOLO da personale qualificato;
  • any changes implemented in probefore is a propersonal responsibility as well as a profirst risk and danger (the contents of the present page are purely educational);
  • any changes implemented in proprior to a device it voids the guarantee, quality approvals and certifications.
Driving review: 1.1


As explained in the dedicated guide to the choice of which personale HUB implement, in case you have at least one device AppiOS is possible, through the adoption of Homebridge, equip oneself with a personale HUB staff to realize the profirst self-made home automation. To install Homebridge it is necessary first install Node.js, a fundamental software component, after which it is possible to install Homebridge itself, configure it for the first start, configure the produe to the start-up of the car in response to the switching on of the Raspberry, become familiar with the most typical commands.

Homebridge Logo

Logo Appthe HomeKitsATTENZIONE: remember that there is on our FORUM community an ad hoc section dedicated to Appthe Homekits, for any doubt, question, information on the specific merit of these components.


  1. Install Node.js
  2. Install and run Homebridge
  3. Add Homebridge al profirst iPhone and / or iPad
  4. Configure Homebridge in autostart on boot
  5. Operational advice
    1. multi-configuration
    2. Update Searchnamento
    3. changes to the coordinates of BRIDGE
    4. validation of the configuration syntax
  6. Resolution of proproblems
    1. Theapp"Home" indicates to initialize the device

1. Install Node.js

Once connected via ssh to the profirst Raspberry (using the "pi" user), execute the following two commands:

curl -sL | sudo -E bash -
sudo apt-get install -y nodejs

Which prothey install the 8 version of Node.js (note: at the time of writing this guide, the 8 version is the most stable one for Home usebridge, although there are more recent ones).

2. Install and run Homebridge

Installed Node.js, you can now install Homebridge via the following command:

sudo npm install -g homebridge --unsafe-perm

At the end of the proautomatic transfer, start the software for the first time (in order to create the home directory, even if the command generates an error) using the following command:


The command will cause an error, as mentioned, because the home directory does not yet exist. Don't worry: after the error, it will be created automatically.

Now it is necessary to create a basic configuration file. For brevity Click here to download a single file already pronto, which will be copied-pasted into the editor, which is executed with:

sudo nano /home/pi/.homebridge/config.json

After copying paste, exit via control / command + X (then pressing "Y" to save).

At this point, launch a second time Homebridge through the command:


3. Add Homebridge al profirst iPhone and / or iPad

Now the time has come to connect to profirst iPhone and / or iPad BRIDGE appena created.
At the first (correct) start, on the terminal apphave a screen similar to this:

Homebridge first run

the big one QRCode on the screen it is used to transmit to the iPhone and / or iPad the "coordinates" of the BRIDGE appena created. Having NOW care to be in the same wifi as the Raspberry that hosts the Homebridge appena installed, run theapp"House" indication on profirst iPhone and / or iPad.
Tappare then "add accessory":

Appthe HomeKit iOS start page

Now, with the help of the phone / tablet camera, frame the QRCode above. After a few moments, theappThe user will ask for confirmation to enter a new one BRIDGE as an accessory not certified. Don't worry about it, give consent and so finish the proprocedure.

Homebridge icon up Appthe HomeKit Home appCompliments! If on theapp "Home" will be appburned the icon you see on the left, you have finished the very first configuration of yours BRIDGE personal.
From here on, it's all downhill! 😉

4. Configure Homebridge in autostart on boot

If "so far so good", or if the execution of Homebridge manual is performed correctly and the bridge appbe properly at theappIOS "Home", we can configure Homebridge How service, so that it does not have to be launched manually but starts automatically (and remains started) when the Raspberry is turned on.

Then block the execution of Homebridge previously launched via control / command + X, thus returning to the procommand mpt.

Let's start by creating the default options for the future service:
To execute:

sudo nano /etc/default/homebridge

and copy the following text inside the editor:

# Defaults / Configuration options for homebridge
# The following settings tells homebridge where to find the config.json file and where to persist the data (i.e. pairing and others)
HOMEBRIDGE_OPTS=-U /var/homebridge

# If you uncomment the following line, homebridge will log more 
# You can display this via systemd's journalctl: journalctl -f -u homebridge

Save and exit the editor (usually with cntr + X, yes, enter).
Then execute the following command

sudo nano /etc/systemd/system/homebridge.service

and copy the following text inside the editor:

Description=Node.js HomeKit Server

ExecStart=/usr/local/bin/homebridge $HOMEBRIDGE_OPTS


CAUTION: the path ExecStart it is relative to the installation path of your Homebridge, which can be verified by the command:

which homebridge

Corrected if necessaryExecStart, save and exit the editor.
Now create the user to run the service, we will call it "homebridge"

sudo useradd --system homebridge

Then, create the home folder and copy the current configuration into it, or the one that your iPhone and / or iPad has "learned" in the previous step:

sudo mkdir /var/homebridge
sudo cp ~/.homebridge/config.json /var/homebridge/

Finally, arrange the permissions:

sudo chmod -R 0777 /var/homebridge

Finally, enable the service and start it:

sudo systemctl daemon-reload
sudo systemctl enable homebridge
sudo systemctl start homebridge

Il BRIDGE is now working e in automatic execution.

To verify it, simply open theapp "Home" and verify that the BRIDGE do not include the word "not available". Regardless, you can check the status of the service through the command:

sudo systemctl status homebridge

Usually, the service is in normal execution against a similar response:

Active: active (running)

5. Operational advice


The configuration described in this guide has an important operational advantage: configured as follows, homebridge runs as an automatic service starting from the folder / Var / homebridge, or how applicense launched manually by / Home / pi / homebridge (Or ~ / .Homebridge) - after stopping any instance that has been automatically executed.
Thus configured, Homebridge presents two configuration files (both appointed config.json) in the two respective paths listed above: the first, for automatic execution, the second for the manual one.

Given that in automatic execution the software does not give (except to the log files) any textual feedback, the possibility of using the "isolated" manual execution - also as configuration - it allows the latter to be used as laboratory for experiments, while the automatic one as of ordinary exercise.

In the face of a need for Home configuration changebridge (addition and / or modification of a plugin and / or accessory), it is useful to run the following mini proprocedure:

  1. stop Homebridge of the automatic instance
  2. change the configuration of the manual ai profirst purposes
  3. execute the manual one, verifying if the effects are those expected
  4. copy the manual instance configuration over the automatic one
  5. restart the automatic instance.

To do this:

stop Homebridge of the automatic instance

sudo systemctl stop homebridge

change the configuration of that manual ai profirst purposes

sudo /home/pi/homebridge/config.json

(edit the file, then exit saving)
execute the manual one, verifying if the effects are the ones expected (typically using theapp "Home" of the phone / tablet)


(stop Homebridge with ctrl / command + x)
copy the manual instance configuration over the automatic one

sudo cp ~/.homebridge/config.json /var/homebridge/
sudo cp -r ~/.homebridge/persist /var/homebridge
sudo chmod -R 0777 /var/homebridge

restart the automatic instance

sudo systemctl daemon-reload
sudo systemctl start homebridge

Now relaunch theapp"House" indication to verify that the BRIDGE answer correctly.


To perform the greaternameof Homebridge you must first stop running it. If it has been configured (as explained above) as an automatic service, the command is as follows:

sudo systemctl stop homebridge

The command to execute later for prosee atupdate is the following:

sudo npm update -g homebridge
Changes to the coordinates of BRIDGE

The initial part of the config.json configuration file usually reports a block similar to the following:

"bridge": {
           "name": "Homebridge",
           "username": "CC:22:3D:E3:CE:30",
           "port": 51826,
           "pin": "031-45-154"

It is important to know that this information, if modified AFTER the addition of BRIDGE on 'app"Home" location causes most of the time a function blocknamento at theapplation itself. To solve, it is sufficient remove the BRIDGE dall 'appand re-add it as explained in this guide (paragraph 3).

This configuration can be consulted, for the manual instance, through the command:

sudo nano /home/pi/homebridge/config.json

mentre for the automatic instance:

sudo nano /var/homebridge/config.json
Validation of the configuration syntax

One of the causes more classic of the failed functionnameof Homebridge is the failure to comply with the semantic rules of the configuration file config.json. This file is written, for theappanointed, in json notation, which may be appromelts here.

Before any change to the configuration file we always recommend make a backup and to submit always the new site validation file Jsonlint.

To the Home configurationbridge and related file "config.jsonwe devote a large section to this.

Based on the installation by you appena carried out on Windows, the file you are going to modify ("config.json") will be positioned at the course:


6. Resolution of proproblems

Create and view log files

If an automatic launch configuration is used as per paragraph 7, the execution logs are available at:


Please note: replace "username" with the username in use on macOS.

To consult the log file in real time while running Homebridge, use the following command:

tail -f ~/.homebridge/logfile.log

This case, which sometimes occurs when adding Homebridge toapp"House" statement is resolved trivially changing the "user" fieldname"Of the file"config.json"And setting it with a different value (random). Just change a single character, (eg from "CC: 22: 3D: E3: EC: 30” a “C1:22:3D:E3:CE:30"), Relaunch Homebridge and re-add the BRIDGE toapp"Home" indication.

10. Configuration customization

Now it is necessary prosee the configuration customization, to which we devote a large section to this.

Logo Appthe HomeKitsATTENZIONE: remember that there is on our FORUM community an ad hoc section dedicated to Appthe Homekits, for any doubt, question, information on the specific merit of these components.

inDomus telegram channel