Community Hass.io Add-ons: Homebridge

This add-on provides the installation, configuration, and integration forHomebridge.

Deprecation warning

This add-on is in a deprecated state!

At this point it is unsure how long this add-on keeps available orupdated.

This add-on was originally developed to add HomeKit support toHome Assistant. Meanwhile, Home Assistant gained native supportfor HomeKit.

https://www.home-assistant.io/components/homekit/

Because of this, is very likely that the plugins this add-on rely, onwill no longer be developed or maintained.

We STRONGLY suggest to migrate to the Home Assistant HomeKit component.

About

Homebridge is a server that emulates the iOS HomeKit API, allowing you tocontrol your Home Assistant via Apple devices (including Siri).

Since Siri supports devices added through HomeKit, this means that withHomebridge you can ask Siri to control devices that don't have any support forHomeKit at all. For instance, you could say:

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

Installation

The installation of this add-on is pretty straightforward and not different incomparison to installing any other Hass.io add-on.

1. Add our Hass.io add-ons repository to your Hass.io instance.
2. Install the "Homebridge" add-on.
3. Start the "Homebridge" add-on.
4. Check the logs of the "Homebridge" add-on to see if everything went wellmoreover, to find the pin code needed to add your Home Assistant instance toyour iOS device

Please read the rest of this document further instructions.

NOTE: Do not add this repository to Hass.io, please use:https://github.com/hassio-addons/repository.

Docker status

Configuration

On the first run, this add-on creates the necessary configuration filesfor you. Stored in /config/homebridge/. You can modify the configurationto your liking. For documentation on configuring Homebridge, please referto the Homebridge GitHub repository. For documentation onconfiguring the Home Assistant for Homebridge plugin, please refer to theHome Assistant for Homebridge GitHub repository.

The add-on has a configuration possibilities as well.

Note: Remember to restart the add-on when the configuration is changed.

Example add-on configuration:

{
  "log_level": "info",
  "avahi_interfaces": "",
  "avahi_hostname": "",
  "avahi_domainname": "local",
  "enable_ipv6": true,
  "packages": [],
  "init_commands": [],
  "plugins": []
}

Option: log_level

The log_level option controls the level of log output by the addon and canbe changed to be more or less verbose, which might be useful when you aredealing with an unknown issue. Possible values are:

• trace: Show every detail, like all called internal functions.
• debug: Shows detailed debug information.
• info: Normal (usually) interesting events.
• warning: Exceptional occurrences that are not errors.
• error: Runtime errors that do not require immediate action.
• fatal: Something went terribly wrong. Add-on becomes unusable.

Please note that each level automatically includes log messages from amore severe level, e.g., debug also shows info messages. By default,the log_level is set to info, which is the recommended setting unlessyou are troubleshooting.

Using trace or debug log levels puts the Homebridge server into debug mode.

Option: avahi_interfaces

Set a comma separated list of allowed network interfaces that should be used bythe Avahi service. Other interfaces will be ignored. If left empty, the add-onwill try to auto-detect the interfaces, which should be fine in most cases.

Note: There is a special internal interface for Hass.io called hassio.This interface is always added to the list automatically

Option: avahi_hostname

Set the hostname to Avahi server. The add-on tries to register on your networkusing this hostname. If left empty the hostname will be automatically detectedvia the Hass.io API, which sould be fine in most cases.

Option: avahi_domainname

Set the default domain name for Avahi. The add-on tries to register its hostnameand services on your network. In most cases, the default, local, should befine.

Option: enable_ipv6

In some situations, IPv6 might cause more problems then it solves.Setting this option to false, partially disables IPv6 support causingAhahi and Homebridge to only listen for connections on IPv4

Option: insecure

Allow unauthenticated requests to Homebridge (for easier hacking). Someplugins require this as well. Be aware of the possible security implicationthis has.

Option: packages

Allows you to specify additional Alpine packages to beinstalled to your Homebridge setup (e.g., python, g++. make, ffmpeg).

Note: Adding many packages will result in a longer start-up timefor the add-on.

Option: init_commands

Customize your Homebridge setup even more with the init_commands option.Add one or more shell commands to the list, and they will be executed everysingle time this add-on starts.

Option: plugins

This Homebridge add-on has support for installing additional Homebridge plugins.Plugins are NodeJS modules published through NPM and tagged with the keywordhomebridge-plugin. They must have a name with the prefix homebridge-,like homebridge-mysmartlock.

The homebridge-homeassistant plugin is already installed for you.

You can install a plugin by adding it to the add-on configuration. The add-onensures the plugin is installed on start.

Example add-on configuration (partial):

{
  "plugins": [
    "homebridge-dummy",
    "homebridge-mysmartlock"
  ]
}

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

Note: Some plugins require build tools or other packages. You might need toinstall these packages using the packages option first.

Adding Homebridge to iOS

Using the Home app (or most other HomeKit apps), you should be able to add thesingle accessory "Home Assistant", assuming that you are still running theHomebridge add-on and you are on the same (Wifi) network. Adding this accessoryautomatically adds all accessories and platforms defined in yourHome Assistant instance.

When you attempt to add the "Home Assistant" accessory, it will ask for a"PIN code". This pin code is randomly generated when this add-on is run forthe first time. You can find the generated PIN code in the add-on logs and inyour /config/homebridge/config.json file (where you, of course,can change it as well).

Known issues and limitations

• Once your device has been added to HomeKit, you should be able to tell Siri tocontrol your devices. However, realize that Siri is a cloud service and iOSmay need some time to synchronize your device information with iCloud.
• Siri will almost always prefer its default phrase handling over HomeKitdevices. 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 Radiostation 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 accessoryis "Speakers".
• One installation of Homebridge can only expose 100 accessories due to aHomeKit limit.
• Once an accessory has been added to the Home app, changing its name viaHomebridge will not be automatically reflected in iOS. You must change it viathe Home app as well.
• If you have set up SSL using a self-signed certificate, you will need toset verify_ssl to false in your /config/homebridge/config.json file toallow bypassing the NodeJS certificate checks.
• Errors on startup. The following errors are experienced when startingHomebridge and can be safely ignored.

*** WARNING *** The program 'nodejs' uses the Apple Bonjour compatibility layer
of Avahi
*** WARNING *** Please fix your application to use the native API of Avahi!
*** WARNING *** For more information see
http://0pointerde/avahi-compat?s=libdns_sd&e=nodejs
*** WARNING *** The program 'nodejs' called 'DNSServiceRegister()' which is not
supported (or only supported partially) in the Apple Bonjour compatibility layer
of Avahi
*** WARNING *** Please fix your application to use the native API of Avahi!
*** WARNING *** For more information see
http://0pointerde/avahi-compat?s=libdns_sd&e=nodejs&f=DNSServiceRegister

FAQ

Homebridge cannot connect or login to Home Assistant

Please be sure to set the host and password parameters in the/config/homebridge/config.json file.

We recommend using http://hassio/homeassistant as the host with anempty password, which allows Homebridge to talk to Home Assistant directly.

My iOS App Cannot Find Homebridge/Home Assistant

Two reasons why Homebridge may not be discoverable:

1. Homebridge server thinks it has been paired with, but iOS thinks otherwise.Fix: deleted persist/ directory which is in your config/homebridgedirectory and restart the add-on.

2. iOS device has gotten your Homebridge username (looks like a MAC address)"stuck" somehow, where it is in the database but inactive. Fix: change yourusername in the "bridge" section of /config/homebridge/config.json to besome new value and restart the add-on.

Changelog & Releases

This repository keeps a change log using GitHub's releasesfunctionality. The format of the log is based onKeep a Changelog.

Releases are based on Semantic Versioning, and use the formatof MAJOR.MINOR.PATCH. In a nutshell, the version will be incrementedbased on the following:

• MAJOR: Incompatible or major changes.
• MINOR: Backwards-compatible new features and enhancements.
• PATCH: Backwards-compatible bugfixes and package updates.

Support

Got questions?

You have several options to get them answered:

• The Community Hass.io Add-ons Discord chat server for add-onsupport and feature requests.
• The Home Assistant Discord chat server for general HomeAssistant discussions and questions.
• The Home Assistant Community Forum.
• Join the Reddit subreddit in /r/homeassistant

You could also open an issue here GitHub.

Contributing

This is an active open-source project. We are always open to people who want touse the code or contribute to it.

We have set up a separate document containing ourcontribution guidelines.

Thank you for being involved! ��

Authors & contributors

The original setup of this repository is by Franck Nijhof.

For a full list of all authors and contributors,check the contributor's page.

Credits

A big shout out to the following people, without them this add-on was notpossible:

• The team & community of Home Assistant for developing suchan excellent home automation toolkit
• Nick Farina for developing Homebrige

This add-on has been inspired by the following repositories:

• docker-homebridge by Oznu
• homebridge-dockerby ckuburlis
• hassio-addonsby Olivier Guerriat

Thank you all!

We have got some Hass.io add-ons for you

Want some more functionality to your Hass.io Home Assistant instance?

We have created multiple add-ons for Hass.io. For a full list, check outour GitHub Repository.

License

MIT License

Copyright (c) 2017 Franck Nijhof

Permission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealin the Software without restriction, including without limitation the rightsto use, copy, modify, merge, publish, distribute, sublicense, and/or sellcopies of the Software, and to permit persons to whom the Software isfurnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in allcopies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THEAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THESOFTWARE.