-
Notifications
You must be signed in to change notification settings - Fork 8
Linux Installation and Errors
Most of the instructions, below, are now outdated for Raspberry Pi. The easiest way to install on Raspberry Pi is using Raspberry Pi Imager. Raspberry Pi Imager
From Raspberry Pi Imager, click on the "Choose OS" button, then "Other specific-purpose OS", then "Home Assistants and home automation" then "Homebridge" to build a Raspberry Pi image with homebridge already set up.
I believe these instructions are now a bit outdated and the instructions in the HomeBridge wiki may be a better guide. See https://github.com/nfarina/homebridge/wiki/Install-Homebridge-on-Debian-or-Ubuntu-Linux
This guide includes notes regarding installation on Linux and, specifically, on Raspberry Pi.
My Linux knowledge is limited, so I'd welcome any additional clarifications to this page from you Linux users out there! Here are the basics:
Check your 'node' version. From a command prompt, enter 'node -v' . Testing and development of this plugin was done using Node 13.x.x and I recommend you use that series of node. You can get an updated node from here: www.nodejs.org
Update: Jan. 2020 - I'm not sure this is still needed - I understand homebridge is now using a different bonjour library than when these instructions were originally written, but there is probably no harm installing it anyway.
Homebridge and its HAP-NodeJS component makes use of Apple's Bonjour technology. You must perform the following installation of a Bonjour compatible support package to get this to work!
sudo apt-get install libavahi-compat-libdnssd-dev
The next step is to install Homebridge using the following command. Make sure that installation completes without any errors.
sudo npm -g install --unsafe-perm homebridge
Once Homebridge installs, enter "homebridge" from a command line. If Homebridge installed correctly, you will see a brief "No plugins found" warning message followed by the display of a large QR code and PIN code (by default, the PIN is 031-45-154). If you reach this stage, you are ready to install plugins.
If you do encounter errors installing HomeBridge, please check out the "Installation Problems" section below.
sudo npm -g install homebridge-homeseer4
[This section can use additional clarification and cleanup! Edits welcome]
I prefer to use the 'systemd' method of staring HomeBridge.
Note that when starting homebridge using 'systemd' you won't see any of the 'normal' homebridge startup and warning messages, so you will have to pair homebridge to your iOS device using the PIN code method, rather than the QR code. Also, its very important that you have permissions set properly on your homebridge directory. See section C, below.
This section should be read as a 'supplement / update / additional hints' to the tutorial for starting homebridge using systemd which is set out at: https://github.com/nfarina/homebridge/wiki/Running-HomeBridge-on-a-Raspberry-Pi#running-homebridge-on-bootup-systemd (the "nfarina tutorial")
The nfarina tutorial references using both defaults file placed in /etc/defaults as well as a homebridge-service file in /etc/systemd/system. I have found that the separate /etc/defaults file aren't really necessary - all the separate 'defaults' file really does is to set the location of homebridge's config.json file/directory and that can, instead, be set in the homebridge.service file as a command line option using -U.
The following is an example of the homebridge.service file to be placed in /etc/systemd/system. This example assumes a user named 'homebridge' has been created (see tutorial link, above) and config.json is in the directory /home/pi/.homebridge
[Unit]
Description=Node.js HomeKit Server
After=syslog.target network-online.target
[Service]
Type=simple
User=homebridge
ExecStart=/usr/bin/homebridge -U /home/pi/.homebridge
Restart=on-failure
RestartSec=10
KillMode=process
[Install]
WantedBy=multi-user.target
After you've created this file, execute the following sequence to start homebridge:
sudo systemctl daemon-reload
sudo systemctl enable homebridge
sudo systemctl start homebridge
You can then check for errors and confirm that homebridge is running by executing:
sudo systemctl status homebridge
Note that if you are running HomeSeer on the same Raspberry Pi, you should set it up and execute its systemctl sequences to make sure it property starts before you execute the homebridge systemctl sequences
You can also run HomeBridge on the same Raspberry pi as HomeSeer. To do so:
-
set up a homeseer.service file following instructions set out here: https://forums.homeseer.com/showthread.php?p=1305368&styleid=8?
-
You will want homebridge to start after homeseer, so in your homebridge.service file, you need to indicate that homebridge starts second. You can do this by including the homeseer.target designation in the After= line of homebride.service, and by setting an ExecStartPre = /bin/sleep 45 to cause a 45 second starting delay for homebridge in homebridge.service. It shouldn't be necessary to do both, but for some reason that seems more reliable to me.
The following is an example of the revised homebridge.service file which will delay the start of homebridge to give homeseer a chance to start up. This example assumes a user named 'homebridge' has been created (see tutorial link, above) and config.json is in the directory /home/pi/.homebridge
[Unit]
Description=Node.js HomeKit Server
After=syslog.target network-online.target homeseer.target
[Service]
Type=simple
User=homebridge
ExecStartPre=/bin/sleep 45
ExecStart=/usr/bin/homebridge -U /home/pi/.homebridge
Restart=on-failure
RestartSec=10
KillMode=process
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
If running homeseer on the same Pi:
sudo systemctl enable homeseer
sudo systemctl start homeseer
The test if HomeSeer started properly. I.e., can you access its web interface.
If so, then start homebridge:
sudo systemctl enable homebridge
sudo systemctl start homebridge
You can then check of homebridge started properly by executing:
sudo systemctl status homebridge
Many Linux installation problems with Homebridge and HomeSeer seem to relate to Linux file permissions. It can be helpful to change all of node's node_modules, the HomeSeer plugin, and homebridge file permissions to rwxrwxrwx. Assuming you installed node and all the modules in their default locations, try the following:
** Note, install the plugin first, then execute:
sudo chmod -R 777 /usr/lib/node_modules
** The following assumes you are logged in as the user "pi" and your homebridge config.json file will be in its default location of /home/pi/.homebridge
sudo chmod -R 777 /home/pi/.homebridge
Finally, if the previews steps didn't help, some users have reported that executing the following commands helped fix their installations:
sudo npm install --unsafe-perm mdns
sudo npm rebuild --unsafe-perm
And then, some user's have reported that after trying everything above, a re-install of the plugin using the following two lines then resolved their problem. Don't know why this works, but its an easy "might as well try":
npm -g uninstall homebridge-homeseer-plugin-2018
npm -g install --unsafe-perm homebridge-homeseer-plugin-2018
In some cases, outdated cache information can cause problems after an update, so also try ...
npm -g cache verify
After an update to homebridge or if "too many" changes re made to config.json, you can sometimes get into a situation where the iOS Home Application either no longer recognizes a previously paired homebridge, or else it can't "see" homebridge for pairing.
The only way I've found to solve this is to do the following:
-
first delete the homebridge bridge from your iOS home application. This, unfortunately, has the effect of deleting all of the devices on that bridge from the iOS Home application.
-
You'll now want to re-pair iOS and Homebridge. However, if homebridge previously successfully paired, it won't pair again! To fix that, you need to delete the contents of two folders, "persist" and "accessories". The "persist" and "accessories" folders are located in the same folder as your config.json file.
-
Delete the contents of the "persist" and "accessories" folder and then re-start homebridge.
- In Linux, these folders are typically located at the path: /home/pi/.homebridge For Linux you may need to change the mode of the folders to 777 and delete using the following:
sudo chmod -R 777 /home/pi/.homebridge/persist
sudo chomod -R 777 /home/pi/.homebridge/accessories
rm -r /home/pi/.homebridge/persist
rm -r /home/pi/.homebridge/accessories
- After homebridge re-starts, then re-pair with the iOS Home application.
If you were unable to successfully install Homebridge, check out the wiki and issues section of the Homebridge site for additional information regarding installation on Linux. See: https://www.npmjs.com/package/homebridge and at www.github.comhttps://www.npmjs.com/package/homebridge. If searching in the issues section, you'll also want to see closed out issues so be sure not to include "is:open" in the search field.
This section is incomplete and is meant to outline the procedure for updating NodeJS on Linux. Usually, this should be straightfoward -- these instructions are to help if you get into trouble doing the update.
- Update nodejs
sudo npm install npm@latest -g
sudo npm cache clean -f
sudo npm install -g
sudo n stable
- Fix path of homebridge.service
(/usr/local/bin/homebridge)
- Restart homebridge
systemctl start homebridge
- Update config.json to add the "login" and "password" fields
"platform": "HomeSeer",
"name": "HomeSeer",
"host": "http://<MY HS SERVER IP>:80",
"ASCIIport":11000,
"login":"<MY USERNAME>",
"password":"<MYPASSWORD>",
-
Uninstall homebridge-homeseer-plugin-2018 plugin if you were using that.
-
Install the homebridge-homeseer4 plugin
-
Restart the homebridge plugin
I've deleted most of my "old" installation instructions that used to be here. Homebridge has updated their instructions and they are now more comprehensive than what I had. Just follow their instructions: https://www.npmjs.com/package/homebridge
And be sure to use config-ui-x. Its really great for setting up the plugin.
These instructions are now a bit out of date. You can follow them to set up the plugin, but there is now a settings interface in config-ui-x which makes it much easier.
-
Additional Notes on specific device types
Why won't my device names change after I edit them in config.json