homebridge/homebridge-apt-pkg

Debian / Ubuntu package and repo for Homebridge

Homebridge

Homebridge is a lightweight Node.js server you can run on your home network that emulates the iOS HomeKit API. It supports Plugins, which are community-contributed modules that provide a basic bridge from HomeKit to various 3rd-party APIs provided by manufacturers of "smart home" devices.

Since Siri supports devices added through HomeKit, this means that with Homebridge you can ask Siri to control devices that don't have any support for HomeKit at all. For instance, using just some of the available plugins, you can say:

• Siri, unlock the back door. [pictured to the right]
• Siri, open the garage door.
• Siri, turn on the coffee maker.
• Siri, turn on the living room lights.
• Siri, good morning!

You can explore all available plugins at the NPM website by searching for the keyword homebridge-plugin.

Community

The official Homebridge Discord server and Reddit community are where users can discuss Homebridge and ask for help.

HomeKit communities can also be found on both Discord and Reddit.

Installation

Raspberry Pi

Official Homebridge Raspberry Pi Image
Install Homebridge on Raspbian

---

Linux

Debian or Ubuntu Linux | Red Hat, CentOS or Fedora Linux | Arch / Manjaro Linux|Install Homebridge on Arch Linux

---

macOS

Install Homebridge on macOS

---

Windows 10 / 11

Install Homebridge on Windows 10 / 11 Using Hyper V

---

Docker

Install Homebridge on Docker
Synology | Unraid | QNAP | TrueNAS Scale

---

Synology DSM

Install Homebridge on Synology DSM 7

Other Platforms

Other Platforms

Adding Homebridge to iOS

1. Open the Home app on your device.
2. Tap the Home tab, then tap .
3. Tap Add Accessory, then scan the QR code shown in the Homebridge UI or your Homebridge logs.

If the bridge does not have any accessories yet, you may receive a message saying Additional Set-up Required, this is ok, as you add plugins they will show up in the Home app without the need to pair again (except for Cameras and TVs).

Cameras and most TV devices are exposed as separate accessories and each needs to be paired separately. See this wiki article for instructions.

Interacting with your Devices

Once your device has been added to HomeKit, you should be able to tell Siri to control your devices. However, realize that Siri is a cloud service, and iOS may need some time to synchronize your device information with iCloud.

One final thing to remember is that Siri will almost always prefer its default phrase handling over HomeKit devices. For instance, if you name your Sonos device "Radio" and try saying "Siri, turn on the Radio" then Siri will probably start playing an iTunes Radio station on your phone. Even if you name it "Sonos" and say "Siri, turn on the Sonos", Siri will probably just launch the Sonos app instead. This is why, for instance, the suggested name for the Sonos accessory is "Speakers".

Plugin Development

The https://developers.homebridge.io website contains the Homebridge API reference, available service and characteristic types, and plugin examples.

The Homebridge Plugin Template project provides a base you can use to create your own platform plugin.

There are many existing plugins you can study; you might start with the Homebridge Example Plugins or a plugin that already implements the device type you need.

When writing your plugin, you'll want Homebridge to load it from your development directory instead of publishing it to npm each time. Run this command inside your plugin project folder so your global installation of Homebridge can discover it:

npm link

You can undo this using the npm unlink command.

Then start Homebridge in debug mode:

homebridge -D

This will start up Homebridge and load your in-development plugin. Note that you can also direct Homebridge to load your configuration from somewhere besides the default ~/.homebridge, for example:

homebridge -D -U ~/.homebridge-dev

This is very useful when you are already using your development machine to host a "real" Homebridge instance (with all your accessories) that you don't want to disturb.

Common Issues

Home App Says Accessory Already Added

To fix this, Reset Homebridge.

My iOS App Can't Find Homebridge

Try the following:

1. Swap between the Bonjour HAP and Ciao mDNS Advertiser options. See the wiki for more details.
2. iOS DNS cache has gone stale or gotten misconfigured. To fix this, turn airplane mode on and back off to flush the DNS cache.

Limitations

• One bridge can only expose 150 accessories due to a HomeKit limit. You can however run your plugins as a Child Bridge or run Multiple Homebridge Instances to get around this limitation.
• Once an accessory has been added to the Home app, changing its name via Homebridge won't be automatically reflected in iOS. You must change it via the Home app as well.

Why Homebridge?

Technically, the device manufacturers should be the ones implementing the HomeKit API. And I'm sure they will - eventually. When they do, this project will be obsolete, and I hope that happens soon. In the meantime, Homebridge is a fun way to get a taste of the future, for those who just can't bear to wait until "real" HomeKit devices are on the market.

Credit

Homebridge was originally created by Nick Farina.

The original HomeKit API work was done by Khaos Tian in his HAP-NodeJS project.

homebridge-apt-pkg's Issues

Repo updates brings back node 18 from node 20

Analysis

When upgrading from 1.1.5 to 1.1.6 my node was set back to 18.

Expected Behavior

Repo updates shouldn't affect node version.

Steps To Reproduce

run sude apt-get update;sudo apt-get upgrade --y via ssh

Logs

sorry

Configuration

nothing

Environment

• OS: Debian GNU/Linux 12 (bookworm)
• Software: homebridge repo plugin 1.1.5
• Node: 20.10
• npm: 9.2.0

Process Supervisor

hb-service

Additional Context

No response

Problem install on Raspberry Pi OS (64-bit) debian 12 bookworm

Analysis

When running "sudo apt-get install homebridge" here is the output error

Preparing to unpack .../homebridge_1.0.34_arm64.deb ...
Running pre-install steps...
Unpacking may take several minutes on low powered devices.
Unpacking homebridge (1.0.34) ...
Setting up homebridge (1.0.34) ...
Running post-install steps...
Adding system user homebridge' (UID 112) ... Adding new group homebridge' (GID 122) ...
Adding new user homebridge' (UID 112) with group homebridge' ...
Not creating `/nonexistent'.
cp: cannot create regular file '/home/homebridge/.bashrc': No such file or directory
chown: cannot access '/home/homebridge/.bashrc': No such file or directory
Starting Homebridge service....

Homebridge Installation Complete!
You can access the Homebridge UI via:

• http://192.168.1.11:8581

Thanks for installing Homebridge!

ℹ Updating Node.js from v18.16.0 to v18.18.1...
ℹ Target: /opt/homebridge
✔ Download complete.
✔ Cleaned up npm at at /opt/homebridge/lib/node_modules/npm
✔ Installed Node.js v18.18.1
⚠ Please restart Homebridge for the changes to take effect.

Expected Behavior

expected no error

Steps To Reproduce

sudo apt-get install homebridge

Logs

When running "sudo apt-get install homebridge" here is the output error 

Preparing to unpack .../homebridge_1.0.34_arm64.deb ...
Running pre-install steps...
Unpacking may take several minutes on low powered devices.
Unpacking homebridge (1.0.34) ...
Setting up homebridge (1.0.34) ...
Running post-install steps...
Adding system user `homebridge' (UID 112) ...
Adding new group `homebridge' (GID 122) ...
Adding new user `homebridge' (UID 112) with group `homebridge' ...
**Not creating `/nonexistent'.
cp: cannot create regular file '/home/homebridge/.bashrc': No such file or directory
chown: cannot access '/home/homebridge/.bashrc': No such file or directory**
Starting Homebridge service....

Homebridge Installation Complete!
You can access the Homebridge UI via:

* http://192.168.1.11:8581

Thanks for installing Homebridge!

ℹ Updating Node.js from v18.16.0 to v18.18.1...
ℹ Target: /opt/homebridge
✔ Download complete.
✔ Cleaned up npm at at /opt/homebridge/lib/node_modules/npm
✔ Installed Node.js v18.18.1
⚠ Please restart Homebridge for the changes to take effect.

Configuration

fresh install

Environment

• OS: Raspberry Pi OS (64-bit) debian 12 bookworm
• Software:
• Node:
• npm:

Process Supervisor

hb-service

Additional Context

When installing plugin, I have another error about directory "nonexistent"

$ hb-service add homebridge-tydom
ℹ CMD: npm --prefix "/var/lib/homebridge" add homebridge-tydom@latest
npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! path /nonexistent
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied, mkdir '/nonexistent'
npm ERR! [Error: EACCES: permission denied, mkdir '/nonexistent'] {
npm ERR! errno: -13,
npm ERR! code: 'EACCES',
npm ERR! syscall: 'mkdir',
npm ERR! path: '/nonexistent'
npm ERR! }
npm ERR!
npm ERR! The operation was rejected by your operating system.
npm ERR! It is likely you do not have the permissions to access this file as the current user
npm ERR!
npm ERR! If you believe this might be a permissions issue, please double-check the
npm ERR! permissions of the file and its containing directories, or try running
npm ERR! the command again as root/Administrator.

npm ERR! Log files were not written due to an error writing to the directory: /nonexistent/.npm/_logs
npm ERR! You can rerun the command with --loglevel=verbose to see the logs in your terminal
✖ Plugin installation failed.

workaround : add homebridge user by yourself before installation

Python package virtualenv as a dependency

Current Situation

Hi everyone,

first of all I want to say that I am very greatful for this amazing project. It really has changed the way I use my HomeKit home.

I am currently developing the plugin homebridge-appletv-enhanced which enables more possibilities than the vanilla integration of Apple TV into HomeKit. It is still in beta phase, but my aim is to provide a painless experience to the users from installation to initial setup to the usage. I am aiming to get this plugin verified.

The plugin is utilizing the pyatv python package because sadly there is no maintained npm packages which implements the protocol to control an Apple TV … and I know what you are thinking now … how could a plugin that is utilizing a python package provide a painless installation experience?

First, let’s talk about how easy it is for the user up until now.

1. The user installs the plugin, no postinstall scripts necessary
2. The user configures the plugin via the UI
3. The user restarts the homebridge
4. The plugin starts (PythonChecker.ts)
   a. The plugin checks if a supported Python version is installed
   b. The plugin checks if the python package virtualenv is installed
   c. The plugin creates a virtual environment in the user storage path of homebridge (if not already created)
   d. The plugin installs python packages according to a requirements.txt (if requirements not already satisfied)
   e. The plugin discovers devices and so on … installation complete

Since Python 3 is in the docker image, the apt package and the raspian image by default, this requirement should not be a problem.

However, now we are finally coming to the problem I currently have, in order to comply with the requirements of getting a plugin verified, the plugin is not allowed to modify the users system, which is totally understandable and right to do in my mind. So my plugin creates a virtual environment (steps c-d) in the users storage path which is allowed according to the verified requirements. The issue with that is, that many users do not have installed the python package virtualenv. There was already an issue created in my repository regarding this problem.

Proposed Change

Include the apt package python3-venv in the docker image, the raspian image and as a dependency in the apt package.

What would be the benefit?

• Plugins that depend on python packages could rely on virtualenv being present. This would encourage to use virtual python environments which isolates the plugins that utilize python.
• Users don‘t need to install ˋvirtualenvˋ manually
• In cases such as mine with the Apple TV plugin where there is simply no npm package which meets the needs, one can use a python package in an venv without worrying if the venv can be created or not

Wouldn‘t it be better to "just" use plain type-/javascript? Of course, but in many cases there is not the time to create complex JavaScript libraries that provide functionality that can already be provided by a well maintained python package, like in my case. When not supporting virtualenv many developers may be deterred since in the end, there will be no way of installing a plugin painlessly and complying to the verified requirements at the same time without virtualenv (when utilizing python).

Additional Context

No response

Latest homebridge version

Current Situation

Hi there,

I am using oznu/docker-homebridge which relies on homebridge-apt-pkg version 1.0.32 as far as I can see in the Dockerfile. In the running container, homebridge shows me v1.5.0.
According to the release date, 1.0.32 contains definitely not the latest version of homebridge. Can you please do a new release so that homebridge v1.6.0 becomes available for Docker?

Kind regards,
tosate

Logs

[11/23/2022, 2:48:39 PM] [HB Supervisor] Homebridge Process Ended. Code: 143, Signal: null
[11/23/2022, 2:50:05 PM] [HB Supervisor] OS: Linux 4.4.180+ x64
[11/23/2022, 2:50:05 PM] [HB Supervisor] Node.js v18.12.1 /opt/homebridge/bin/node
[11/23/2022, 2:50:05 PM] [HB Supervisor] Homebridge Path: /var/lib/homebridge/node_modules/homebridge/bin/homebridge
[11/23/2022, 2:50:05 PM] [HB Supervisor] UI Path: /opt/homebridge/lib/node_modules/homebridge-config-ui-x/dist/bin/standalone.js
[11/23/2022, 2:50:08 PM] [Homebridge UI] Homebridge Config UI X v4.50.2 is listening on :: port 8581
[11/23/2022, 2:50:08 PM] [HB Supervisor] Starting Homebridge with extra flags: -P /var/lib/homebridge/node_modules --strict-plugin-resolution
[11/23/2022, 2:50:08 PM] [HB Supervisor] Started Homebridge v1.5.0 with PID: 147

Configuration

not applicable

Environment

• OS: Linux 4.4.180+ x64
• Homebridge: 1.5.0
• Node: v18.12.1

Process Supervisor

Docker (Mention image name in Additional Context)

Additional Context

No response

V 1.1.1 and 1.1.2 is downgrading Node from V20 to V18

Raspberry Pi Model

Raspberry Pi 4 B

Describe The Bug

While updating the apt package the installer downgrades Node from V20.9.0 to V18.18.2

It’s better to verify the version and avoid already upgraded Node installations.

Logs

Updated to the latest release with Node 20.9.0 installed. After the update, homebridge started with 18.18.2:

^[[37m[11/11/2023, 19:17:55]^[[0m ^[[36m[HB Supervisor]^[[0m OS: Linux 6.1.21-v8+ arm64
^[[37m[11/11/2023, 19:17:55]^[[0m ^[[36m[HB Supervisor]^[[0m Node.js v18.18.2 /opt/homebridge/bin/node

I ran hb-service update-node after the apt update and got an error, but it was updated to 20.09.0 again.
Cannot attach the log from the update-node command, I think this command will not be logged in a logfile.
Should be easy to reproduce.

APT Repository node.js version overwrites later installed node.js version

Analysis

Updating Homebridge using sudo apt update/upgrade results in current node.js version being overwritten by a =n earlier version.

Expected Behavior

Upgrades via apt should not overwrite later already installed node.js versions.

Steps To Reproduce

• Homebridge installed on a Pi4 (Debian GNU/Linux Bullseye (11)).
• Homebridge was installed using the "sudo apt install homebridge" method currently prescribed for a Pi.
• Homebridge was at version v1.7.0 and node.js was at v20.10.0 (node.js upgraded from v18 using hb-service update-node when the UI prompted that an upgrade was available).
• Ran sudo apt update/sudo apt upgrade on the Pi4 resulting in the following apt message: "Unpacking homebridge (1.1.4) over (1.1.3) ..."
• After Homebridge service reloads node.js version has downgraded to 18.18.2 and the UI is again prompting to upgrade node.js
• Ran hb-service update-node again, node.js updated back to v20.10.0

Logs

None generated

Configuration

Not applicable

Environment

• OS: Debian GNU/Linux Bullseye (11) (ie Raspberry Pi OS)
• Software: 1.7.0
• Node: 20.10.0
• npm: 10.2.3

Process Supervisor

hb-service

Additional Context

No response

Why would this package require gcc, g++ and python?

Current Situation

Hi, just a question, I noticed that this debian package requires gcc, g++ and python3.

Just wondering why? Shouldn’t homebridge be able to run with pure Node.js?

Logs

N/A

Configuration

Debian

Environment

• OS: LInux, Debian-based self built docker image
• Software: Debian, Docker
• Node:
• npm:

Process Supervisor

hb-service

Additional Context

No response

homebridge-apt-pkg dowgrade nodejs from V20 to V18

Feature Description

Hb-service update-node install node V20. homebridge-apt-pkg dowgrade nodejs from V20 to V18.

Not very consistent for me.

apt full-upgrade - downgrading homebridge?

Raspberry Pi Model

Raspberry Pi 4 B

Describe The Bug

When I run sudo apt full-upgrade (from ssh) it will update all components but downgrade Homebridge to 1.6.1, also downgrade Homebridge Config Ui and also downgrade node from 20 to 18. Why?

The second issue is the fact that you cannot run this command in Homebridge Terminal if Homebridge appears in the update list.

Mayby exclude Homebridge from the apt full-upgrade command? So that full-upgrade command can be run directly in Homebridge Terminal? And so that it does not cause downgrade?

Unable to start hb-service after upgrading on RPI from 1.0.30 to 1.0.31

Analysis

Please see bug report on main Homebridge page linked here: homebridge/homebridge#3259

Expected Behavior

Homebridge should update and continue to work.

Steps To Reproduce

On RPi, update from 1.0.30 to 1.0.31 via apt upgrade.

Logs

Starting Homebridge...
homebridge.service: Failed to determine supplementary groups: No such process
homebridge.service: Failed at step GROUP spawning /bin/run-parts: No such process
Started Homebridge.
homebridge.service: Failed to determine supplementary groups: No such process
homebridge.service: Failed at step GROUP spawning /opt/homebridge/start.sh: No such process
homebridge.service: Main process exited, code=exited, status=216/GROUP
homebridge.service: Failed with result 'exit-code'.
homebridge.service: Scheduled restart job, restart counter is at 12.
Stopped Homebridge.

Configuration

N/A

Environment

• OS: Ubuntu 22.04
• Node:v18.12.1

Process Supervisor

hb-service

Additional Context

homebridge/homebridge#3259

The homebridge package must not be upgraded from the Homebridge UI Terminal.

Analysis

Attempting to upgrade Homebridge inside a LXC container results in

ERROR: The homebridge package must not be upgraded from the Homebridge UI Terminal.

Expected Behavior

The upgrade succeeds

Steps To Reproduce

pct enter 110
apt upgrade

Logs

Fields marked with an asterisk (*) are required.

Configuration

Fields marked with an asterisk (*) are required.

Environment

• OS: Debian 11.7
• Software: 1.0.34

Process Supervisor

hb-service

Additional Context

It seems like Homebridge is trying to see if the process indicated by $$ has 'hb-service' anywhere in its process tree (using pstree), however, in LXC it is common for administrators to create a shell that is detached from the main process tree (and thus, doesn't have the init process in it's process tree), this confuses pstree and shows the tree for the init process, which will have hb-service as a child.

For example, in this case, the shell has PID 371043, which has the PPid 370985, which has the PPid 0, without the init process (1) in this chain.

root@homebridge:~# echo $$
371043
root@homebridge:~# cat /proc/$$/task/$$/status | grep PPid
PPid:	370985
root@homebridge:~# cat /proc/370985/task/370985/status | grep PPid
PPid:	0

Calling pstree on pid 0 without -s reveals this.

root@homebridge:~# pstree 0
?─┬─fish───bash───pstree
  └─systemd─┬─3*[agetty]
            ├─cron
            ├─dbus-daemon
            ├─hb-service─┬─homebridge───10*[{homebridge}]
            │            └─10*[{hb-service}]
            ├─master─┬─pickup
            │        └─qmgr
            ├─rsyslogd───2*[{rsyslogd}]
            ├─systemd-journal
            ├─systemd-logind
            ├─systemd-network
            └─systemd-resolve

It might be possible to check if the pstree output doesn't contain ┬ or common processes that will never own Homebridge such as systemd-resolve?

Or, you could check that an EnvVar such as HOMEBRIDGE_APT_PACKAGE is not set?

Homebridge package missing from recent versions of Debian-like apt repos

Analysis

Previously to now, you could run a command like apt get homebridge in Debian based OSes (including RPi images like the official Homebridge image)

This no longer seems to be the case. Analyzing the most recent repositories for Buster and Bullseye shows no sign of the Homebridge package, and thus you cannot manually install, upgrade, reinstall, etc.

If this is intentional, can we get some documentation updates and info as to why/what the new package management method is meant to be?

Expected Behavior

Package management commands like apt get homebridge should work

Steps To Reproduce

1. Log into an official Homebridge RPi image, or really any Debian based variant
2. Run an apt update
3. Run an apt list | grep home and observe that no homebridge packages exist
4. Attempt to run apt get homebridge or similar and notice they fail

Logs

pi@homebridge:~ $ apt list | grep home

WARNING: apt does not have a stable CLI interface. Use with caution in scripts.

debian-edu-artwork-homeworld/oldstable 2.11.6-1 all
golang-github-mitchellh-go-homedir-dev/oldstable 1.1.0-1 all
hdhomerun-config/oldstable 20210210-1 armhf
homebank-data/oldstable 5.5.2-1 all
homebank/oldstable 5.5.2-1 armhf
homer-api-mysql/oldstable 5.0.6+dfsg2-3.2 armhf
homer-api-postgresql/oldstable 5.0.6+dfsg2-3.2 armhf
homer-api/oldstable 5.0.6+dfsg2-3.2 armhf
homesick/oldstable 1.1.6-3 all
kodi-pvr-hdhomerun-dbg/oldoldstable 3.5.0-1~buster armhf
kodi-pvr-hdhomerun/oldoldstable 3.5.0-1~buster armhf
libfile-homedir-perl/oldstable 1.006-1 all
libfile-save-home-perl/oldstable 0.11-1 all
libhdhomerun-dev/oldstable 20210210-1 armhf
libhdhomerun4/oldstable 20210210-1 armhf
librust-home-dev/oldstable 0.5.1-1 armhf
minetest-mod-homedecor/oldstable 20200604.1-1 all
oddjob-mkhomedir/oldstable 0.34.6-1 armhf
prometheus-homeplug-exporter/oldstable 0.3.0-2 armhf
python3-ofxhome/oldstable 0.3.3-3 all
r-cran-psychometric/oldstable 2.2-2 armhf
sweethome3d-furniture-editor/oldstable 1.25-1 all
sweethome3d-furniture-nonfree/oldstable 1.6.2-2 all
sweethome3d-furniture/oldstable 1.8-1 all
sweethome3d-textures-editor/oldstable 1.6-3 all
sweethome3d/oldstable 6.4.2+dfsg-2 all
unburden-home-dir-doc/oldstable 0.4.1.2 all
unburden-home-dir/oldstable 0.4.1.2 all
pi@homebridge:~ $ 

### Configuration

```json
NA

Environment

• OS: Linux homebridge 5.10.103-v7+
• Software: Homebridge 1.70
• Node: v20.10.0
• npm: 10.2.4

Process Supervisor

hb-service

Additional Context

No response