User Tools

Site Tools


Sidebar

supported_hardware:homekit

Home Kit

The XTension Home Kit plugin is currently in public beta testing. Not all device types are implemented and there remain some issues see below:

The Home Kit plugin shares your selected units to Apple’s Home Kit making them available for control via Siri or the Apple ‘Home’ app.

Requirements:

The Home Kit plugin absolutely requires Python 3.7 or newer. As of MacOS 10.14 this is not included in the standard software like Python 2.7 is. You must install it separately. The easiest way to do this is via one of the binary installers available from Python.org Releases As of this writing the latest release version is 3.7.2. I would not recommend installing alpha or beta releases. Please use the 64-bit installer and not the combined 64/32 bit installer since XTension does not support 32 bit only hardware anymore anyway.

If you use the above installer then the binary positions will be correct and you can ignore this paragraph. If you already have Python3 installed or decide to instead build from source please make sure that the python3 binary file, or a symbolic link to it, is available at /usr/local/bin/python3 or the plugin will not be able to find it to execute itself.

The plugin itself and all necessary dependencies are included in the current XTension distribution so no further installs are required once you have completed the Python3 install.

Setup:

Setup Dialog

Open the Interface List window and click the “New Interface” button. Select “Home Kit” from the Device popup and you’ll be presented with the Home Kit settings dialog:

As with any other plugin instance give it a descriptive name.

The Bridge Name must be unique compared to any other Home Kit Accessories on your local network.

The Port should be left at the default unless you wish to run more than one instance of the plugin at the same time. In which case you’ll have to choose a different unique port for each one. Note that at this moment Home Kit doesn’t seem to connect properly if you change this port number or try to create more than one instance of a bridge on the same machine.

The “Update Config” button asks any paired Home Kit apps to reload the configuration. After adding new units or if you change the settings or names of those units you may have to click this button to force the new units or changes to appear in the Home Kit apps. At this time Apple’s home kit app does not seem to load any changes to any existing units at all. If you need to change the name of a unit in Home Kit you’ll need to do it from the Home Kit app itself as these changes don’t reliably get loaded into the App. Adding new units is no problem however, click the Update Config button and the changes will show up. Also if you add units while the interface is not enabled they may not show up when you enable it unless you click this button. This button is disabled unless the plugin is enabled.

The “Reset Bridge” button will unpair any paired Home Kit apps and reset all the settings. After resetting the bridge the plugin will quit and be restarted by XTension 5 seconds later to finish the reset. After it restarts the QR Linking Code and pin-code will change and you can re-add the bridge to your Home App.

Once you complete the initial setup you can link this Bridge to your iOS or other Home Kit app. If using the iOS app you can simply point the camera at the displayed QR code. Otherwise you can link via the pin code displayed to the right of the QR code. If you have removed the bridge from the iOS app to get it to recognize changes to the units you may get a “accessory already added” error in which case you’ll need to use the “Reset Bridge” button and then try again.

The QR code and Pin will be blank if the plugin is not enabled. You cannot link to this plugin until you enable the plugin.

Database Sharing Settings:

I would not recommend sharing everything to Home Kit unless you have a very small database. There are limitations about removing things later without removing the entire bridge from Home Kit which will require you to re-add everything. Better to add units as you go so that you can be sure things are working the way you wish at each step.

Click the “Select Items To Share” button to bring down the sharing selection sheet. Here you can select lists of units that you wish to make available to Home Kit. If necessary you can create a new List from this window and then add any units that you wish to share to the list. When you’ve selected all the lists you want to share click Save to close the window and return to the Home Kit plugin setup window.

As of this first beta version only sharing of units is supported though the release version will also add the sharing of scripts.

Unit Sharing Settings:

Because XTension doesn’t have intrinsic types of units that can be automatically mapped to Home Kit’s accessory definition you must tell the plugin what Accessory type is should tell Home Kit the unit represents. By clicking the “Configure Sharing” button you’ll be shown a list of all the units that you have selected to share. Go down the list and select a Home Kit Accessory type from the “Share As” popup menu.

NOTE: Home Kit does not seem to properly support changing the type of an Accessory after it’s first added. Nor will it simply let you remove and re-add the Accessory. In order to make such a change you’ll have to remove the entire bridge, use the Reset Bridge button and then re-add everything to iOS re-setting all the room assignments and assignments to any scenes or shortcuts. Add only the units that you’re ready to work with. Any others you can set to “None” to keep them from being shared until you’re ready to set them.

You do not need to add all your units at this time. Home Kit does allow you to add more Accessories to the bridge later. Drag more units into a shared list, or add another list to the sharing selection sheet window. If the interface is already running those units will not be shared until you re-visit this window and select an Accessory type for them. If the interface is enabled then as you configure each unit they will be added to Home Kit but they will not be visible to any clients until you complete the unit sharing setup and click the “Update Config” button on the main interface screen.

Accessory Types

As of the first beta release XTension supports the following Access types:

  • Contact Closure
  • Garage Door (see below)
  • Humidity Sensor
  • Light Sensor
  • Door Lock (see below)
  • Motion Sensor
  • Occupancy Sensor
  • Outlet
  • Smoke Detector
  • Switch (see below)
  • Temperature Sensor (see below)

The rest of the Accessory types as defined by Home Kit will be available before version 1 is complete.

Garage Door

The Garage Door Accessory has built into it both monitoring the state and controlling the door. In this beta build there is no way to link a separate unit to the state of the door vs the control of the door. A future version will allow the setting of 2 separate units those 2 separate functions.

Door Lock

Like the Garage Door Accessory this will eventually allow you to select a separate unit for the control of the door lock vs displaying it’s locked status.

Switch

In XTension the Switch type handles both the non dimmable “Switch” accessory as well as the “Lightbulb” accessory type for dimmable devices. For either type of lighting unit just select “Switch” and XTension will create the correct Accessory type based on the unit’s dimmable or non-dimmable setting.

Temperature Sensor

Since XTension only knows the value of these units and not the scale used you must tell the plugin if the value in XTension is in C or F if you wish it to be displayed properly in Home Kit. If the Value in XTension is in F then select “Temperature Sensor in F” and if in C select “Temperature Sensor in C.” This has no impact on how the values are displayed in Home Kit as that is configured in your iOS settings. This just makes sure that the value is properly displayed in Home Kit.

Color and Color Temperature Support

If the XTension device that you are sharing supports color or color temperature settings select “Switch” as its device type and the color or color temperature will be automatically enabled for this unit in Home Kit. As of this first beta this works, but can be a bit finicky as the Home Kit interface tends to jump around a bit while you’re changing the colors. Changes to the color in XTension do show properly in the current color display in Home Kit.

Known Issues

As of this first beta changing the Accessory type of a unit does not seem to ever be reflected in the Home Kit database. If you wish to do this you’ll have to remove the bridge from Home Kit and then use the Reset Bridge button to rebuild the pairing keys and then re-pair. This has the effect of removing all the shared units as well and any settings, scenes or shortcuts that you’ve created in home kit using them. I can see that the new information is properly broadcast to Home Kit but the App does not reflect the changes. I believe this is a bug, or an intrinsic limitation in the Home app or in Home Kit itself.

Changing the name of a unit in XTension also is not reliably reflected in Home Kit. Sometimes the name change will show up in it’s display some hours or even days later, sometimes never. I can see that the information is properly sent to Home Kit but the App rarely changes what it thinks it knows about a bridged accessory. If you need to change the name of a unit as far as Home Kit is concerned you can do so directly from the Home Kit app itself by using a 3D touch tap on the unit and clicking it’s “settings” button. There is no need for an Accessory in Home Kit to have the same name as it does in XTension. You may wish to keep your XTension named “Master Bedroom Overhead” but to change the name in Home Kit just to “my room” or something similar. That works fine.

There seems no way to remove a bridged accessory from Home Kit either. If you remove a unit from a shared list it will stay forever in home kit showing the “not responding” error. If anyone knows how to delete a bridged accessory from Home Kit please let me know.

As of this moment Home Kit doesn’t seem to support running more than one bridge plugin instance on the same machine. Additional instances fail to pair properly.

Any battery operated device currently reports a low battery status all the time to Home Kit and not just when the battery is low. This will be sorted out in the next release for now ignore the low battery flags.

History

  • The first beta of the Home Kit plugin was included in XTension version 9.4.16 in Feb of 2019
supported_hardware/homekit.txt · Last modified: 2019/02/23 18:15 by James Sentman