[homekit.binding] New HomeKit client binding

[andrewfg]

Resolves #14094

There is an existing HomeKit system integration addon which allows exporting OH Items into the HomeKit eco- system.
This is a new HomeKit client binding addon which allows importing OH Things and Channels from the HomeKit eco- system.

There are three types of Things supported:

• accessory: This integrates a single HomeKit accessory, which has its own LAN connection.
  Its services appear as channel groups, and their respective characteristics appear as channels.
• bridged-accessory: This integrates a single HomeKit accessory, which does NOT have its own LAN connection.
  It has the same functionality as an accessory, except that its communication is done via a bridge (see below).
• bridge: This integrates a HomeKit bridge accessory, which has its own LAN connection.
  It does not have any own channels.
  Instead it contains multiple bridged-accessory Things (see above).

Things of type bridge and accessory both communicate directly with their HomeKit device over the LAN. Whereas bridged-accessory Things communicate via their respective bridge Thing.

The JAR files for testing purposes are here:

• org.openhab.binding.homekit-5.1.0-SNAPSHOT.zip
• org.openhab.binding.homekit-5.0.3-SNAPSHOT.zip (note: this no longer tracks all the latest commits)

See Apple HomeKit Specification.pdf for reference.

Notes:

1. This binding uses a clone of the code in my Light State Model PR here for the time being. Note that once that PR will have been merged, the clone in this binding can be deleted and instead linked to use that library.
2. I did make contact with @kgoderis since he has also a huge HomeKit project that is also work-in-progress. However he told me that he has no time to make further progress on his work. So I decided to make a clean re-start from scratch.

Signed-off-by: Andrew Fiddian-Green software@whitebear.ch

Todos (all done)

• State options for enums
• Convert 2 step enums to Switch/Contact
• Adopt discovery PR from @jlaur
• Rollershutter instead of Dimmer, with up/down
• Add 'aid' to make thing labels unique
• Add intricate test cases for Velux Json dump
• Check arc degree usage
• Implement light state machine (see State machine to model lights in Thing handlers openhab-core#4995)
• Add code to reconnect if socket gets dropped
• Rollershutter add stop (position hold) override
• Implement button trigger channels
• i18n on thing status messages
• Support event subscription and notification
• Fix the disposition of On/Off derived from B part of OH HSB command
• i18n on channel labels
• i18n on state option labels
• Implement thing action for pairing
• Implement addon suggestion finder
• Unique channel type and group type ids

Issues that will NOT be addressed

• Coalesce target and current channels
• Identify device

[andrewfg]

@ThomasM102 I think you successfully integrated your own Hue bridge via this binding? That actually was a surprise for me since my own Hue bridges (a white v2 and a black v3) did not appear in my Inbox.

However on December 8th Philips/Signify announced a new firmware roll out and miracolo miracoli both of them appeared -- for a very short time -- in my Inbox :) However unfortunately before I could try to pair with them, they both equally suddenly disappeared from the Inbox again :(

So I am wondering if you used some special "magic" to discover your bridges and/or to pair them?

[ThomasM102]

Yes, really, this takes magic (and maybe an iPhone too; I haven't tested it with Android):

1. Delete any existing pairings in the Hue app.
2. Start the HomeKit pairing process in the Hue app, but only until the app says: "3 LEDs are now lit." Don't go any further, otherwise it will pair with your local HomeKit.
3. Press the pairing button on the Hue device. It should now be blinking.
4. Then start the scan with your binding.

This is how the discovery process worked for me with your binding.

[andrewfg]

maybe an iPhone too; I haven't tested it with Android

Aha. The Android app doesnt even mention an Apple Home option. But fortunately I do also have an iPad so I will try that..

Is it the case that the bridge only appears in the mDNS discovery after your step 3 in the app?

Also which of the two Thing Actions in the binding did you use?

[ThomasM102]

Is it the case that the bridge only appears in the mDNS discovery after your step 3 in the app?

Yes, it looks like multicasting needs to be activated through the app and the hardware first. It took a lot of trial and error to find this solution. There might be an easier way, but this is how it worked for me.
If you delete the pairing and the bridge, you then have a few minutes to perform a new scan/pairing. Only after a certain amount of time does it need to be reactivated via the app and the button. At least that's been my experience.

Also which of the two Thing Actions in the binding did you use?

I just tested both again. Everything works. Pairing works without the "With External Authentication" switch.

[jlaur]

I had a look at your latest commits, and they LGTM. The README needs a small update after that. I had a quick look at all files changed within the last week or so, and added two ultra-minor comments.

When the README is updated, we can merge. I expect to do that sometime tomorrow (and if you are not available before then, I'll just commit that README update).

Thanks for the massive effort put into this. This is going to be a major new feature in 5.1.

[jlaur]

LGTM

[lsiepel]

@andrewfg if you can fix the conflicts due to the merge of other new bindings, we can finally merge this awesome contribution.

[andrewfg]

fix the conflicts due to the merge of other new bindings

@lsiepel done.

[lsiepel]

As @jlaur did the extensive review and Approved and the conflict is now resolved and reviewed LGTM.
Next step is to add the binding's logo.

[lsiepel]

Thanks for all the hard work on this binding @andrewfg !

[andrewfg]

Next step is to add the binding's logo.

There is already a Homekit logo for org.openhab.io.homekit and we (myself and @jlaur) think that org.openhab.binding.homekit will therefore pull in that same logo. But @lsiepel can you please check it?

[lsiepel]

Next step is to add the binding's logo.

There is already a Homekit logo for org.openhab.io.homekit and we (myself and @jlaur) think that org.openhab.binding.homekit will therefore pull in that same logo. But @lsiepel can you please check it?

I think you two are right. Let's see after the snapshot build. We can always add the logo th enext week during feature freeze

[jlaur]

I think you two are right. Let's see after the snapshot build. We can always add the logo th enext week during feature freeze

We can also replace it with a new SVG logo. It seems the logo changed over the years - is this the latest logo?

If the logo will automatically be picked up as expected, we have a small issue further down the road: If we will ever have two bindings with the same name in different categories (binding/persistence/io ec.), it seems it's currently not possible to use fully qualified names and thus use different logos (if desired). Maybe fully or partially qualified names are already supported, I haven't checked, but there are no examples to prove it. 😉

[andrewfg]

Do you want me to make a PR replacing the old homekit.png with the new homekit.svg ?

EDIT done here

[jlaur]

Let's see after the snapshot build.

It works: https://next.openhab.org/addons/bindings/homekit/

[andrewfg]

But we still need to merge openhab/openhab-docs#2608