Package: homekit
HomeKit PythonWith this code it is possible to implement either a HomeKit Accessory or simulate a
HomeKit Controller.The code presented in this repository was created based on release R1 from 2017-06-07.Contributorsjc2kCommitsquarckoCommitsmjg59CommitsmrstegemanCommitsnetmanchrisCommitslimkevinkuanCommitstleegaardCommitsbenasseCommitsPaulMcMillanCommitselmoplCommits(The contributors are not listed in any particular order!)InstallationInstallation for IP based accessoriesSimply usepip3to install the package:pip3install--userhomekit[IP]This installation only for IP based accessories can be done without any operating system level installations and should
also work on operating systems other than linux (Mac OS X, Windows, ...).Installation for Bluetooth LE based accessoriesThis variant requires some packages on operating systems for the access onto Bluetooth LE via dbus. These can be
installed on Debian based operating systems via:aptinstall-ylibgirepository1.0-devgcclibcairo2-devpkg-configpython3-devgir1.2-gtk-3.0libdbus-1-devAfter that, usingpip3is sufficient again:pip3install--userhomekit[BLE]Installation for both type of accessoriesIn this case, install the packages for your operating system and afterwards usepip3:pip3install--userhomekit[IP,BLE]HomeKit AccessoryThis package helps in creating a custom HomeKit Accessory.The demonstration uses this JSON in~/.homekit/demoserver.json:{"name":"DemoAccessory","host_ip":"$YOUR IP","host_port":8080,"accessory_pairing_id":"12:00:00:00:00:00","accessory_pin":"031-45-154","peers":{},"unsuccessful_tries":0,"c#":0,"category":"Lightbulb"}Now let's spawn a simple light bulb accessory as demonstration:#!/usr/bin/env python3importos.pathfromhomekitimportAccessoryServerfromhomekit.modelimportAccessory,LightBulbServiceif__name__=='__main__':try:httpd=AccessoryServer(os.path.expanduser('~/.homekit/demoserver.json'))accessory=Accessory('test_light','homekit_python','Demoserver','0001','0.1')lightService=LightBulbService()accessory.services.append(lightService)httpd.accessories.add_accessory(accessory)httpd.publish_device()print('published device and start serving')httpd.serve_forever()exceptKeyboardInterrupt:print('unpublish device')httpd.unpublish_device()If everything went properly, you should be able to add this accessory to your home on your iOS device.HomeKit ControllerThe following tools help to access HomeKit Accessories.init_controller_storageThis tool initializes the HomeKit controller's storage file.Usage:python3-mhomekit.init_controller_storage-f${PAIRINGDATAFILE}The option-fspecifies the name of the file to contain the controller's data.discoverThis tool will list all available HomeKit IP Accessories within the local network.Usage:python3-mhomekit.discover[-t${TIMEOUT}][-u][--log${LOGLEVEL}]The option-tspecifies the timeout for the inquiry. This is optional and 10s are the default.The option-uactivates a filter to show only unpaired devices. This is optional and deactivated by default.The option--logspecifies the log level for the command. This is optional. UseDEBUGto get more output.Output:Name: smarthomebridge3._hap._tcp.local.
Url: http://192.168.178.21:51827
Configuration number (c#): 2
Feature Flags (ff): Paired (Flag: 0)
Device ID (id): 12:34:56:78:90:05
Model Name (md): Bridge
Protocol Version (pv): 1.0
State Number (s#): 1
Status Flags (sf): 0
Category Identifier (ci): Other (Id: 1)Hints:Some devices like the Koogeek P1EU Plug need bluetooth to set up wireless (e.g. join the wireless network) before.
Use your phone or the proper app to perform thispaired devices should not show updiscover_bleThis tool will list all available HomeKit BLE Accessories within range of the Bluetooth LE device.Usage:python3-mhomekit.discover_ble[-t${TIMEOUT}][-u][--adapter${ADAPTER}][--log${LOGLEVEL}]The option-tspecifies the timeout for the inquiry. This is optional and 10s are the default.The option-uactivates a filter to show only unpaired devices. This is optional and deactivated by default.The option--adapterspecifies which Bluetooth device to use. This is optional andhci0is the default.The option--logspecifies the log level for the command. This is optional. UseDEBUGto get more output.Output:Name: Koogeek-DW1-8ca86c
MAC: c6:cc:4d:a7:7c:5e
Configuration number (cn): 1
Device ID (id): B8:D1:29:61:A1:B0
Compatible Version (cv): 2
Global State Number (s#): 2
Status Flags (sf): The accessory has been paired with a controllers. (Flag: 0)
Category Identifier (ci): Sensor (Id: 10)identifyThis tool will use the Identify Routine of a HomeKit Accessory. It has 3 modes of operation.identify unpaired Homekit IP AccessoryUsage:python3-mhomekit.identify-d${DEVICEID}[--log${LOGLEVEL}]The option-dspecifies the device id of the accessory to identify. Can be obtained viadiscovery.The option--logspecifies the log level for the command. This is optional. UseDEBUGto get more output.identify unpaired Homekit BLE AccessoryUsage:python3-mhomekit.identify-m${MACADDRESS}[--adapter${ADAPTER}][--log${LOGLEVEL}]The option-mspecifies the Bluetooth LE mac id of the accessory to identify. Can be obtained viadiscovery_ble.The option--adapterspecifies which Bluetooth device to use. This is optional andhci0is the default.The option--logspecifies the log level for the command. This is optional. UseDEBUGto get more output.identify paired Homekit AccessoryUsage:python3-mhomekit.identify-f${PAIRINGDATAFILE}-a${ALIAS}[--adapter${ADAPTER}][--log${LOGLEVEL}]The option-fspecifies the file that contains the pairing data.The option-aspecifies the alias for the device.The option--adapterspecifies which Bluetooth device to use. This is optional andhci0is the default and is only
used if the paired device is using Bluetooth LE.The option--logspecifies the log level for the command. This is optional. UseDEBUGto get more output.pairThis tool will perform a pairing to a new IP accessory.Usage:python3-mhomekit.pair-d${DEVICEID}-p${SETUPCODE}-f${PAIRINGDATAFILE}-a${ALIAS}[--log${LOGLEVEL}]The option-dspecifies the device id of the accessory to pair. Can be obtained via discovery.The option-pspecifies the HomeKit Setup Code. Can be obtained from the accessory. This must look likeXXX-XX-XXX(X is a single digit and the dashes are important).The option-fspecifies the file that contains the pairing data.The option-aspecifies the alias for the device.The option--logspecifies the log level for the command. This is optional. UseDEBUGto get more output.The file with the pairing data will be required to send any additional commands to the accessory.pair_bleThis tool will perform a pairing to a new Bluetooth LE accessory.Usage:python3-mhomekit.pair-m${MACADDRESS}-p${SETUPCODE}-f${PAIRINGDATAFILE}-a${ALIAS}[--adapter${ADAPTER}][--log${LOGLEVEL}]The option-mspecifies the device id of the accessory to pair. Can be obtained via discovery.The option-pspecifies the HomeKit Setup Code. Can be obtained from the accessory.The option-fspecifies the file that contains the pairing data.The option-aspecifies the alias for the device.The option--adapterspecifies which Bluetooth device to use. This is optional andhci0is the default and is only
used if the paired device is using Bluetooth LE.The option--logspecifies the log level for the command. This is optional. UseDEBUGto get more output.The file with the pairing data will be required to send any additional commands to the accessory.list_pairingsThis tool will perform a query to list all pairings of an accessory. The
controller that performs the query must be registered asAdmin. If this is
not the case, no pairings are listed.Usage:python3-mhomekit.list_pairings-f${PAIRINGDATAFILE}-a${ALIAS}[--adapter${ADAPTER}][--log${LOGLEVEL}]The option-fspecifies the file that contains the pairing data.The option-aspecifies the alias for the device.The option--adapterspecifies which Bluetooth device to use. This is optional andhci0is the default and is only
used if the paired device is using Bluetooth LE.The option--logspecifies the log level for the command. This is optional. UseDEBUGto get more output.This will print information for each controller that is paired with the accessory:Pairing Id: 3d65d692-90bb-41c2-9bd0-2cb7a3a5dd18
        Public Key: 0xed93c78f80e7bc8bce4fb548f1a6681284f952d37ffcb439d21f7a96c87defaf
        Permissions: 1 (admin user)The information contains the pairing id, the public key of the device and permissions of the controller.prepare_add_remote_pairingThis tool will prepare data required for theadd_additional_pairingcommand.Usage:python3-mhomekit.prepare_add_remote_pairing-f${PAIRINGDATAFILE}-a${ALIAS}\[--log${LOGLEVEL}]The option-fspecifies the file that contains the pairing data.The option-aspecifies the alias for the device to be added.The option--logspecifies the log level for the command. This is optional.
UseDEBUGto get more output.This will print information to be fed intohomekit.add_additional_pairing(via a second channel):Please add this to homekit.add_additional_pairing:
    -i cec11edd-7363-42c4-8d13-aeb06b608ffc -k 0cbfd3abc377f6c3bfd3b4c119c1c5ff0c840ef1f9530e0f99c68b1f531dd66aadd_additional_pairingThis tool is used to tell a HomeKit Accessory accept a new pairing for an
additional controller.Usage:python3-mhomekit.add_additional_pairing-f${PAIRINGDATAFILE}-a${ALIAS}\-i${PAIRINGID}-k${PUBLIC_KEY}-p${LEVEL}[--log${LOGLEVEL}]The option-fspecifies the file that contains the pairing data.The option-aspecifies the alias for the device to be added.The option-ispecifies the additional controller's pairing id.The option-kspecifies the additional controller's public key.The option-pspecifies the additional controller's access privileges, this can beUserorAdminfor a pairing
with higher privileges.The option--logspecifies the log level for the command. This is optional.
UseDEBUGto get more output.This will print information to be fed intohomekit.finish_add_remote_pairing(via a second channel):Please add this to homekit.finish_add_remote_pairing:
    -c BLE -i D0:CA:1E:56:13:AA -m cb:e0:b0:c9:e8:72 -k a07c471e12682b161034b91c0d016201516eb51d9bf1071b6dcf0e3be71e9269finish_add_remote_pairingThis tool finalizes the addition of a pairing to a HomeKit Accessory.Usage:python3-mhomekit.finish_add_remote_pairing-f${PAIRINGDATAFILE}-a${ALIAS}\-c${CONNECTIONTYPE}-i${DEVICEID}-k${DEVICEPUBLICKEY}\[-m${MACADDRESS}][--log${LOGLEVEL}]The option-fspecifies the file that contains the pairing data.The option-aspecifies the alias for the device to be added.The option-cspecifies the type of connection for the accessory (values are
IP and BLE).The option-ispecifies the accessory's device id.The option-kspecifies the accessory's public key.The option-mspecifies the accessory's mac address for Bluetooth Low Energy
accessories. This is not required for IP accessories.The option--logspecifies the log level for the command. This is optional.
UseDEBUGto get more output.remove_pairingThis tool will remove a pairing from an accessory.Usage:python-mhomekit.remove_pairing-f${PAIRINGDATAFILE}-a${ALIAS}[-i${PAIRINGID}][--adapter${ADAPTER}][--log${LOGLEVEL}]The option-fspecifies the file that contains the pairing data.The option-aspecifies the alias for the device.The option-ispecifies the controller pairing id to remove. This is optional. If left out, the calling controller's
pairing id is used and the controller looses the ability to controll the device. See the output oflist_pairingshow to get the controller's pairing id.Important: this is not the accessory's device id.The option--adapterspecifies which Bluetooth device to use. This is optional andhci0is the default and is only
used if the paired device is using Bluetooth LE.The option--logspecifies the log level for the command. This is optional. UseDEBUGto get more output.get_accessoriesThis tool will read the accessory attribute database.Usage:python3-mhomekit.get_accessories-f${PAIRINGDATAFILE}-a${ALIAS}[-o{json,compact}][--adapter${ADAPTER}][--log${LOGLEVEL}]The option-fspecifies the file that contains the pairing data.The option-aspecifies the alias for the device.The option-ospecifies the format of the output:jsondisplays the result as pretty printed JSONcompactreformats the output to get more on one screenThe option--adapterspecifies which Bluetooth device to use. This is optional andhci0is the default and is only
used if the paired device is using Bluetooth LE.The option--logspecifies the log level for the command. This is optional. UseDEBUGto get more output.Using thecompactoutput the result will look like:1.1: >accessory-information<
  1.2: Koogeek-P1-770D90 () >name< [pr]
  1.3: Koogeek () >manufacturer< [pr]
  1.4: P1EU () >model< [pr]
  1.5: EUCP031715001435 () >serial-number< [pr]
  1.6:  () >identify< [pw]
  1.37: 1.2.9 () >firmware.revision< [pr]
1.7: >outlet<
  1.8: False () >on< [pr,pw,ev]
  1.9: True () >outlet-in-use< [pr,ev]
  1.10: Outlet () >name< [pr]get_characteristicThis tool will read values from one or more characteristics.Usage:python3-mhomekit.get_characteristic-f${PAIRINGDATAFILE}-a${ALIAS}-c${CHARACTERISTICS}[-m][-p][-t][-e]\[--adapter${ADAPTER}][--log${LOGLEVEL}]The option-fspecifies the file that contains the pairing data.The option-aspecifies the alias for the device.The option-cspecifies the characteristics to read. The format is<aid>.<cid>. This option can be repeated to
retrieve multiple characteristics with one call (e.g.-c 1.9 -c 1.8).The option-mspecifies if the meta data should be read as well.The option-pspecifies if the permissions should be read as well.The option-tspecifies if the type information should be read as well.The option-especifies if the event data should be read as well.The option--adapterspecifies which Bluetooth device to use. This is optional andhci0is the default and is only
used if the paired device is using Bluetooth LE.The option--logspecifies the log level for the command. This is optional. UseDEBUGto get more output.For example, this command reads 2 characteristics of a Koogeek P1EU Plug:python3 -m homekit.get_characteristic -f koogeek.json -a koogeek -c 1.8 -c 1.9The result will be a json with data for each requested characteristic:{"1.8":{"value":false},"1.9":{"value":true}}put_characteristicThis tool will write values to one or more characteristics.Usage:python3-mhomekit.put_characteristic-f${PAIRINGDATAFILE}-a${ALIAS}-c${Characteristics}${value}\[--adapter${ADAPTER}][--log${LOGLEVEL}]The option-fspecifies the file that contains the pairing data.The option-aspecifies the alias for the device.The option-cspecifies the characteristics to change. The format is<aid>.<cid> <value>. This option can be
repeated to change multiple characteristics with one call  (e.g.-c 1.9 On -c 1.8 22.3) . If the value is complex or
some longer chunk of data, it can be read from a file e.g.-c 1.9 @somefilewith the file containing the value.The option--adapterspecifies which Bluetooth device to use. This is optional andhci0is the default and is only
used if the paired device is using Bluetooth LE.The option--logspecifies the log level for the command. This is optional. UseDEBUGto get more output.For example, this command turns of a Koogeek P1EU Plug:python3 -m homekit.put_characteristic -f koogeek.json -a koogeek -c 1.8 falseNo output is given on successful operation or a error message is displayed.get_events!!Not yet implemented for Bluetooth LE Accessories!!This tool will register with an accessory and listen to the events send back from it.Usagepython3-mhomekit.get_events-f${PAIRINGDATAFILE}-a${ALIAS}-c${Characteristics}\[--adapter${ADAPTER}][--log${LOGLEVEL}]The option-fspecifies the file that contains the pairing data.The option-aspecifies the alias for the device.The option-cspecifies the characteristics to change. The format is<aid>.<cid>. This
option can be repeated to listen to multiple characteristics with one call.The option--adapterspecifies which Bluetooth device to use. This is optional andhci0is the default and is
only used if the paired device is using Bluetooth LE.The option--logspecifies the log level for the command. This is optional. UseDEBUGto get more output.For example, you can listen to characteristics 1.8 (on characteristic), 1.22 (1 REALTIME_ENERGY) and
1.23 (2 CURRENT_HOUR_DATA) of the Koogeek P1EU Plug with:python3-mhomekit.get_events-fkoogeek.json-akoogeek-c1.8-c1.22-c1.23This results inevent for 1.8: True
event for 1.22: 6.0
event for 1.23: 0.01666
event for 1.22: 17.0
event for 1.23: 0.06388
event for 1.23: 0.11111
event for 1.22: 18.0
event for 1.23: 0.16111
event for 1.8: Falsedebug_proxyTo assist the adoption of new accessories, there is a debug proxy. Seeits documentationfor more details.HomeKit AccessoryDevices Reported to workThe code was tested with the following devices by the author:Koogeek P1EU Plug (IP) (Vendor)Koogeek DW1 (BLE)  (Vendor)OSRAM SMART+ Classic E27 Multicolor (BLE) (Vendor)Users have tried (and succeeded, not checked by the author) to use the following devices:Ikea TRÅDFRI (IP) (Issue #13)Philips Hue (IP) (Issue #13)Leviton DH6HD-1BZ (IP) (Issue #16)Lutron Caseta (IP) (Smart Bridge 2 /Issue #17)iHome iSP5 (IP) (Issue #18)Xiaomi Mi Bedside Lamp 2 (IP) (Issue #116)