HomeKit
The homekit
integration allows you to forward entities from Open Peer Power to Apple HomeKit, so they can be controlled from Apple’s Home app and Siri. Please make sure that you have read the considerations listed below to save you some trouble later. However if you do encounter issues, check out the troubleshooting section.
# Example configuration.yaml entry configuring HomeKit
homekit:
filter:
include_domains:
- alarm_control_panel
- light
- media_player
include_entities:
- binary_sensor.living_room_motion
entity_config:
alarm_control_panel.home:
code: 1234
binary_sensor.living_room_motion:
linked_battery_sensor: sensor.living_room_motion_battery
low_battery_threshold: 31
light.kitchen_table:
name: Kitchen Table Light
lock.front_door:
code: 1234
media_player.living_room:
feature_list:
- feature: on_off
- feature: play_pause
- feature: play_stop
- feature: toggle_mute
switch.bedroom_outlet:
type: outlet
Setup
To enable the HomeKit integration in Open Peer Power, add the following to your configuration file:
# Example for HomeKit setup
homekit:
After Open Peer Power has started, the entities specified by the filter are exposed to HomeKit if they are supported. To add them:
- Open the Open Peer Power frontend. A new card will display the
pin code
. Note: If pin code is not displayed, check “Notifications” (the bell icon) in the lower-left of the Open Peer Power UI. - Open the
Home
app. - Click
Add Accessory
, then selectDon't Have a Code or Can't Scan?
and choose theOpen Peer Power Bridge
. - Confirm that you are adding an
Uncertified Accessory
by clicking onAdd Anyway
. - Enter the
PIN
code. - Follow the setup by clicking on
Next
and lastlyDone
in the top right-hand corner. - The
Open Peer Power
Bridge and the Accessories should now be listed in theHome
app.
After the setup is completed, you should be able to control your Open Peer Power integrations through Apple’s Home and Siri.
Move Open Peer Power install
If you like to retain your HomeKit pairing through a move to a new Open Peer Power device or installation, besides copying the configurations files you need to copy the .homekit.state
file inside your configurations directory. Keep in mind though that the file is usually hidden by default, depending on your operating system.
Before you copy it, make sure to stop the old and new Open Peer Power instances first entirely, otherwise it won’t work.
Considerations
Accessory ID
Currently, this integration uses the entity_id
to generate a unique accessory id (aid)
for HomeKit
. The aid
is used to identify a device and save all configurations made for it. This, however, means that if you decide to change an entity_id
all configurations for this accessory made in the Home
app will be lost.
Device Limit
The HomeKit guidelines only allow a maximum of 100 unique accessories (aid
) per bridge. Be mindful of this when configuring the filter(s).
Persistence Storage
Unfortunately HomeKit
doesn’t support any persistent storage - only the configuration for accessories that are added to the Open Peer Power Bridge
are kept. To avoid problems, it is recommended to use an automation to always start HomeKit
with at least the same entities setup. If for some reason some entities are not set up, their configuration will be deleted. (State unknown or similar will not cause any issues.)
A common situation might be if you decide to disable parts of the configuration for testing. Please make sure to disable auto start
and turn off
the Start HomeKit
automation (if you have one).
Disable Auto Start
Depending on your setup, it might be necessary to disable Auto Start
for all accessories to be available for HomeKit
. Only those entities that are fully set up when the HomeKit
integration is started, can be added. To start HomeKit
when auto_start: false
, you can call the service homekit.start
.
If you have Z-Wave entities you want to be exposed to HomeKit, then you’ll need to disable auto start and then start it after the Z-Wave mesh is ready. This is because the Z-Wave entities won’t be fully set up until then. This can be automated using an automation.
# Example for Z-Wave
homekit:
auto_start: false
automation:
- alias: 'Start HomeKit'
trigger:
- platform: event
event_type: zwave.network_ready
- platform: event
event_type: zwave.network_complete
- platform: event
event_type: zwave.network_complete_some_dead
action:
- service: homekit.start
For a general delay where your integration doesn’t generate an event, you can also do:
# Example using a delay after the start of Open Peer Power
homekit:
auto_start: false
automation:
- alias: 'Start HomeKit'
trigger:
- platform: openpeerpower
event: start
action:
- delay: 00:05 # Waits 5 minutes
- service: homekit.start
In some cases it might be desirable to check that all entities are available before starting HomeKit
. This can be accomplished by adding an additional binary_sensor
as follows:
# Example checking specific entities to be available before start
homekit:
auto_start: false
automation:
- alias: 'Start HomeKit'
trigger:
- platform: openpeerpower
event: start
action:
- wait_template: >-
{% if not states.light.kitchen_lights %}
false
{% elif not states.sensor.outside_temperature %}
false
# Repeat for every entity
{% else %}
true
{% endif %}
timeout: 00:15 # Waits 15 minutes
continue_on_timeout: false
- service: homekit.start
Configure Filter
By default, no entity will be excluded. To limit which entities are being exposed to HomeKit
, you can use the filter
parameter. Keep in mind only supported components can be added.
# Example filter to include specified domains and exclude specified entities
homekit:
filter:
include_domains:
- alarm_control_panel
- light
exclude_entities:
- light.kitchen_light
Filters are applied as follows:
- No includes or excludes - pass all entities
- Includes, no excludes - only include specified entities
- Excludes, no includes - only exclude specified entities
- Both includes and excludes:
- Include domain specified
- if domain is included, and entity not excluded, pass
- if domain is not included, and entity not included, fail
- Exclude domain specified
- if domain is excluded, and entity not included, fail
- if domain is not excluded, and entity not excluded, pass
- if both include and exclude domains specified, the exclude domains are ignored
- Neither include or exclude domain specified
- if entity is included, pass (as #2 above)
- if entity include and exclude, the entity exclude is ignored
- Include domain specified
Safe Mode
The safe_mode
option should only be used (and only works) if you encounter issues during the pairing. (Pairing hangs - zeroconf error).
To use safe_mode
, add the option to your homekit
configuration:
homekit:
safe_mode: true
Restart your Open Peer Power instance. If you don’t see a pincode
, follow the guide here. Now you should be able to pair normally.
Docker Network Isolation
The advertise_ip
option can be used to run this integration even inside an ephemeral Docker container with network isolation enabled, e.g., not using the host network.
You may also need to set zeroconf_default_interface
to true
.
To use advertise_ip
, add the option to your homekit
configuration:
homekit:
advertise_ip: "STATIC_IP_OF_YOUR_DOCKER_HOST"
zeroconf_default_interface: true
Restart your Open Peer Power instance. This feature requires running an mDNS forwarder on your Docker host, e.g., avahi-daemon
in reflector mode. This kind of setup most likely requires safe_mode
during the bridge setup.
Supported Components
The following integrations are currently supported:
Component | Type Name | Description |
---|---|---|
alarm_control_panel | SecuritySystem | All security systems. |
automation / input_boolean / remote / scene / script | Switch | All represented as switches. |
binary_sensor | Sensor | Support for co2 , door , garage_door , gas , moisture , motion , occupancy , opening , smoke and window device classes. Defaults to the occupancy device class for everything else. |
climate | Thermostat | All climate devices. |
cover | GarageDoorOpener | All covers that support open and close and have garage as their device_class . |
cover | WindowCovering | All covers that support set_cover_position . |
cover | WindowCovering | All covers that support open_cover and close_cover through value mapping. (open -> >=50 ; close -> <50 ) |
cover | WindowCovering | All covers that support open_cover , stop_cover and close_cover through value mapping. (open -> >70 ; close -> <30 ; stop -> every value in between) |
device_tracker / person | Sensor | Support for occupancy device class. |
fan | Fan | Support for on / off , direction and oscillating . |
fan | Fan | All fans that support speed and speed_list through value mapping: speed_list is assumed to contain values in ascending order. The numeric ranges of HomeKit map to a corresponding entry of speed_list . The first entry of speed_list should be equivalent to off to match HomeKit’s concept of fan speeds. (Example: speed_list = [off , low , high ]; off -> <= 33 ; low -> between 33 and 66 ; high -> > 66 ) |
light | Light | Support for on / off , brightness and rgb_color . |
lock | DoorLock | Support for lock / unlock . |
media_player | MediaPlayer | Represented as a series of switches which control on / off , play / pause , play / stop , or mute depending on supported_features of entity and the mode list specified in entity_config . |
media_player | TelevisionMediaPlayer | All media players that have tv as their device_class . Represented as Television and Remote accessories in HomeKit to control on / off , play / pause , select source , or volume increase / decrease , depending on supported_features of entity. Requires iOS 12.2/macOS 10.14.4 or later. |
sensor | TemperatureSensor | All sensors that have Celsius or Fahrenheit as their unit_of_measurement or temperature as their device_class . |
sensor | HumiditySensor | All sensors that have % as their unit_of_measurement and humidity as their device_class . |
sensor | AirQualitySensor | All sensors that have pm25 as part of their entity_id or pm25 as their device_class |
sensor | CarbonMonoxideSensor | All sensors that have co as their device_class |
sensor | CarbonDioxideSensor | All sensors that have co2 as part of their entity_id or co2 as their device_class |
sensor | LightSensor | All sensors that have lm or lx as their unit_of_measurement or illuminance as their device_class |
switch | Switch | Represented as a switch by default but can be changed by using type within entity_config . |
water_heater | WaterHeater | All water_heater devices. |
Troubleshooting
Deleting the .homekit.state
file
The .homekit.state
file can be found in the configurations directory. You might need to enable view hidden files
to see it.
- Stop Open Peer Power
- Delete the
.homekit.state
file - Start Open Peer Power
Errors during pairing
If you encounter any issues during pairing, make sure to:
- Stop Open Peer Power
- Delete the
.homekit.state
file - Edit your configuration (see below)
- Start Open Peer Power
logger:
default: warning
logs:
openpeerpower.components.homekit: debug
pyhap: debug
homekit:
filter:
include_entities:
- demo.demo
PIN doesn’t appear as persistent status
You might have paired the Open Peer Power Bridge
already. If not, delete the .homekit.state
file (guide).
Open Peer Power Bridge
doesn’t appear in the Home App (for pairing)
This is often setup and network related. Make sure to check the other issues below as well, but things that might work include:
- Check your router configuration
- Try with Wi-Fi and LAN
- Change the default port
Remember that the iOS device needs to be in the same local network as the Open Peer Power device for pairing.
Open Peer Power Bridge
doesn’t appear in the Home App (for pairing) - Docker
Set network_mode: host
. If you have further problems this issue might help.
You can also try to use avahi-daemon
in reflector mode together with the option advertise_ip
, see above.
Open Peer Power Bridge
doesn’t appear in the Home App (for pairing) - VirtualBox
Configure the network mode as networkbridge
. Otherwise the Open Peer Power Bridge won’t be exposed to the network.
Pairing hangs - zeroconf error
Pairing eventually fails, you might see and an error message NonUniqueNameException
. Add the safe_mode
option to your configuration, see safe_mode.
Pairing hangs - only works with debug configuration
Pairing works fine when the filter is set to only include demo.demo
, but fails with normal configuration. See specific entity doesn’t work
Pairing hangs - no error
- Make sure that you don’t try to add more than 100 accessories, see device limit. In rare cases, one of your entities doesn’t work with the HomeKit component. Use the filter to find out which one. Feel free to open a new issue in the
open-peer-power
repository, so we can resolve it. - Check logs, and search for
Starting accessory Open Peer Power Bridge on address
. Make sure Open Peer Power Bridge hook up to a correct interface. If it did not, explicitly sethomekit.ip_address
configuration variable.
Duplicate AID found when attempting to add accessory
Two of your entities share the same entity_id
. Either resolve this or configure the filter to exclude them.
Issues during normal use
Some of my devices don’t show up - Z-Wave / Discovery
My entity doesn’t show up
Check if the domain of your entity is supported. If it is, check your filter settings. Make sure the spelling is correct, especially if you use include_entities
.
HomeKit doesn’t work on second Open Peer Power instance
To use the HomeKit integration with to different Open Peer Power instances on the same local network, you need to set a custom name for at least one of them. config/name
Specific entity doesn’t work
Although we try our best, some entities don’t work with the HomeKit integration yet. The result will be that either pairing fails completely or all Open Peer Power accessories will stop working. Use the filter to identify which entity is causing the issue. It’s best to try pairing and step by step including more entities. If it works unpair and repeat until you find the one that is causing the issues. To help others and the developers, please open a new issue here: open-peer-power/issues/new
Accessories are all listed as not responding
See specific entity doesn’t work
Accessory not responding - after restart or update
See device limit
Accessory not responding - randomly
Unfortunately, that sometimes happens at the moment. It might help to close the Home
App and delete it from the cache. Usually, the accessory should get back to responding after a few minutes at most.
Accessories not responding / behaving unusual - Upgrade from 0.65.x
To fix this, you need to unpair the Open Peer Power Bridge
, delete the .homekit.state
file (guide) and pair it again. This should only be an issue if you’re upgrading from 0.65.x
or below.
The linked battery sensor isn’t recognized
Try removing the entity from HomeKit and then adding it again. If you are adding this configuration option to an existing entity in HomeKit, any changes you make to this entity’s configuration options won’t appear until the accessory is removed from HomeKit and then re-added. See resetting accessories.
My media player is not showing up as a television accessory
Media Player entities with device_class: tv
will show up as Television accessories on devices running iOS 12.2/macOS 10.14.4 or later. If needed, try removing the entity from HomeKit and then adding it again, especially if the media_player
was previously exposed as a series of switches. Any changes, including changed supported features, made to an existing accessory won’t appear until the accessory is removed from HomeKit and then re-added. See resetting accessories.
Can’t control volume of your TV media player?
The volume and play/pause controls will show up on the Remote app or Control Center. If your TV supports volume control through Open Peer Power, you will be able to control the volume using the side volume buttons on the device while having the remote selected on screen.
Resetting accessories
On Open Peer Power 0.97.x
or later, you may use the service homekit.reset_accessory
with one or more entity_ids to reset accessories whose configuration may have changed. This can be useful when changing a media_player’s device class to tv
, linking a battery, or whenever Open Peer Power adds support for new HomeKit features to existing entities.
On earlier versions of Open Peer Power, you can reset accessories by removing the entity from HomeKit (via filter) and then re-adding the accessory.
With either strategy, the accessory will behave as if it’s the first time the accessory has been set up, so you will need to restore the name, group, room, scene, and/or automation settings.