HomeKit Controller API

This page will describe the stable API for working as a Homekit controller with this python module.

Use Cases

The HomeKit Controller Api will cover the following use cases:

1. discover HomeKit enabled devices
2. identify unpaired and paired HomeKit devices
3. pair HomeKit devices
4. read out the HomeKit accessories of a device
5. read out one or more characteristics of a accessory
6. write back one or more characteristics of a accessory
7. register for events send back by the accessory
8. remove the pairing with a device

Wifi only at the moment!

Implementation

The use cases are split onto two main classes. These are shown in the class diagram below:

To make handling of paired accessories easier, pairings will have an alias as a shortcut.

homekit.Controller

This class replaces the iOS Device acting as Controller in the typical scenario.

homekit.Controller.discover

This method uses Bonjour / Zeroconf technology to gather HomeKit Accessories from within the same IP network.

Parameters

1. max_seconds (default: 10): how many seconds is the inquiry running. After that time the result is prepared and returned.

Result

The method returns a list of the discovered devices. The devices are represented by dicts that contain the following keys:

• name: the Bonjour name of the HomeKit accessory (i.e. Testsensor1._hap._tcp.local.)
• address: the IP address of the accessory
• port: the used IP port
• c#: the configuration number
• ff / flags: the numerical and human readable version of the feature flags (supports pairing or not, see table 5-8 page 69 or homekit.model.FeatureFlags)
• id: the accessory's pairing id
• md: the model name of the accessory
• pv: the protocol version
• s#: the current state number
• sf: the status flag (see table 5-9 page 70)
• ci / category: the category identifier in numerical and human readable form. For more information see table 12-3 page 254 or homekit.model.Categories

homekit.Controller.identify

This method is used to trigger the identification of an unpaired HomeKit Accessory. It is depending on the device how this call is handled.

Parameters

1. accessory_id: the HomeKit accessory's pairing id (field id of the results of discover)

Result

This method does not return anything but raises a AccessoryNotFoundException if no device could be looked up via Bonjour.

homekit.Controller.load_data

This method loads previously stored data about the pairings known to this controller. Should be performed after all methods that change pairing information (perform_pairing and remove_pairing).

Parameters

1. filename: The file that should be loaded.

Result

This method does not return anything but raises ConfigLoadingException on any error while loading the data.

homekit.Controller.save_data

This method saves data about the pairings known to this controller to a file. Should be performed at the beginning of a program that uses the controller.

Parameters

1. filename: The file that should be saved.

Result

This method does not return anything but raises ConfigSavingException on any error while loading the data.

homekit.Controller.get_pairings

Parameters

Result

homekit.Controller.perform_pairing

Parameters

Result

homekit.Controller.remove_pairing

Parameters

Result

homekit.Pairing

This class represents the pairing between the controller and a HomeKit accessory.

homekit.Pairing.get_accessories

Parameters

Result