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.

As of version 9.4.40 a separate python install is no longer required. No other work is needed to run the homekit plugin. If you are working with a version prior to 9.4.40 the install instructions are preserved below:

The Home Kit plugin requires that Python 3.7 be installed on the host machine. It does not have to be the default python version in use if you have multiple installs and it can coexist happily with multiple python versions if you are using the environment management systems. If you use an installer from python.org the default install location will be in /Library/Frameworks/Python.framework/Versions/3.7 which is what is needed for this plugin to work properly. Download Python 3.7 from the Python.org Releases page. Please download the 64 bit only version as 32 bit apps will not continue to run on newer OS versions.

Xtension versions prior to 9.4.35 required python 3.7 be the “active” version of python meaning that typing “python3” from the command line would bring up the python 3.7 version even if others were installed. Versions 9.4.35 and later only require that the install be present in the default location but do not need it to be the default version on the system anymore.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Some folks have had problems with duplicate Accessory ID’s. I have never been able to fully duplicate the issue but I believe I have located and fixed the timing issue that caused it to get out of sync with the master database in XTension 9.5.1. There are also 3 scripting commands you can run to help to trouble shoot the problem should you have it and to fix it if you do. The plugin will validate the stored AID’s for the units as they are loaded and will log in red if there are any duplicates. It will not try to fix the problem at this point as it is important to NOT reset the one that is actually the correct Unit that Home Kit thinks it is, and only the one that is not that.

To get a list of all shared units from the plugin and their current AIDs:

tell xInterface “name of your Home Kit Interface” to listAIDs()

That will write the name of every unit shared through this interface along with it’s AID to the log. To Verify that they are all different please use the verifyAIDs() command.

tell xInterface “name of your Home Kit Interface” to verifyAIDs()

will write similar output to list aids but if 2 units have the same AID there will be a red log line giving you the name of both of them. You can then decide which one to perform a reset on vis the resetAID() command. If you perform this on a Unit that is working properly it will break it’s association with home kit in a way that might require a reset of the interface and rebuilding of all the sharing info so please pick the unit that is NOT the correct unit as far as your home kit settings are concerned.

tell xInterface “name of your Home Kit Interface” to resetAID( “name of the problem unit”)

A new AID will be selected and assigned to the Unit and the interface will restart. After that you may have to re-assign its sharing setup and also click the “Update Config” button in the Interface setup dialog. That will bring the unit back to life for sharing.

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.

• The first beta of the Home Kit plugin was included in XTension version 9.4.16 in Feb of 2019
• As of XTension 9.4.35 it was no longer necessary that Python 3.7 was the “active” version on the system but it still requires that 3.7 be installed in the default /Library/Frameworks location in MacOS. See the Requirements section above for more info.
• As of XTension 9.4.40 a separate python version install is no longer required.