[homekit] New HomeKit client binding

[andrewfg]

=== WORK IN PROGRESS ===

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

There are two types of Things supported:

• accessory: This integrates a single HomeKit accessory, whereby its services appear as channel groups and the respective service- characteristics appear as channels.
• bridge: This integrates a HomeKit bridge accessory containing multiple child accessory Things.
  So Things of type accessory either represent a stand-alone accessories or a child of a bridge Thing.

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

See Apple HomeKit Specification.pdf

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

Todos:

• 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
• Resolve where to coalesce target and current channels; and implement that
• Support event subscription and notification
• i18n on binding messages
• Identify device (not top priority since there is little point in the identify function after the device is discovered).

[andrewfg]

@lsiepel and @jimtng -- this addon is far from ready yet; it has not been tested at all, and there are still many areas work-in-progress -- however I am putting this up here as I think you guys may get some joy from it ;)

Note I did make contact with @kgoderis since he has also a huge HomeKit project that is also work-in-progress. I did take a look at your code, but eventually I found it easier to make a clean re-start on my own. (Sorry for that). One notable thing missing from my code is the HomeKit proxy server (which allows HomeKit accessories to be imported and also re-exported). However since we already have the HomeKit server io addon combined with this HomeKit client binding, I think that the proxy is not really required..

[lsiepel]

fyi @ccutrer

[andrewfg]

@ThomasM102 many thanks for your Json dump. I just created a stub JUnit test case based on it. However I still need to write the intricate detail tests for it..

[ThomasM102]

You marked my topic about the reversed roller shutters as solved. I only partially agree:
The target position is still reversed. So, clicking the UP icon lowers the roller shutters.

It would also be nice to have text in the position state, if possible. Here's my input:
position state: 0->moving down, 1->moving up, 2->stop

[andrewfg]

But for the most part, I think it maps best onto the openHAB model to combine both characteristics into a single channel, and just not show the state of the target characteristic. Perhaps include the state of the target characteristic as a separate advanced channel? I just worry it will cause user confusion if lots of accessories end up with two channels, and users get confused why they have to send a command to one channel, but read the state on the other side

@ccutrer OK I am slowly starting to come around to your way of thinking. A few points..

1. I think we agree that thermostats must have different channels for setpoint and actual values.
2. I think the same logic applies for humidity controllers.
3. I see the logic of merging setpoint and actual values of positional controller devices such as shades, windows and doors; (or to be more precise hiding the setpoint behind an abstraction layer). I think this applies to all percent type analog (now Rollershutter) channels and can fairly easily be handled via the binding getter and setter code. => @ThomasM102 and @jlaur perhaps you can give your thoughts based on the Velux use case?
4. However I am really struggling with non analog enum setpoint and actual characteristics like say Fan State Target (which maps to a 2 state auto-manual switch) and Fan State Current (which maps to 3 possible state description option enum conditions). I don't see any possible logical way to merge or hide one or other of these two characteristics. So I think we should leave these as separate channels. Or??

[andrewfg]

The target position is still reversed. So, clicking the UP icon lowers the roller shutters.

I agree your point. I had overlooked that. But see my post above this one concerning the merging of setpoint and actual characteristics, which will probably also resolve this issue.

It would also be nice to have text in the position state, if possible.
Here's my input: position state: 0->moving down, 1->moving up, 2->stop

Hmm. Nice to have. (IMHO). Such texts are not provided by the hardware. They are only available in the Apple specification PDF. There are 128 characteristics in the spec, and about half of them have 2 or more texts in the PDF. So there is a lot of work to extract the texts and create i18n property files and whatever. Personally I want to focus on functionality rather than cosmetics, so I suggest to postpone that text extraction work to a later PR.

[ThomasM102]

thoughts based on the Velux use case

With Velux roller shutters, it's possible that the actual value may not reach the target value. When the window is open, my roller shutters close to a maximum of 80% to prevent damage. I would prefer two variables.

Edit: The same applies to the window when the rain sensor is active.

[jlaur]

3. I see the logic of merging setpoint and actual values of positional controller devices such as shades, windows and doors; (or to be more precise hiding the setpoint behind an abstraction layer). I think this applies to all percent type analog (now Rollershutter) channels and can fairly easily be handled via the binding getter and setter code. => @ThomasM102 and @jlaur perhaps you can give your thoughts based on the Velux use case?

I think it would make a lot of sense to merge this into a single channel, similar to how other bindings map shades etc.

With Velux roller shutters, it's possible that the actual value may not reach the target value. When the window is open, my roller shutters close to a maximum of 80% to prevent damage. I would prefer two variables.

Having only a single channel could then disregard (veto) that target position. So if you start at 0%, then send a command with 100%, the final state will then become 80%. What is gained by having a separate channel for keeping the 100% you tried to command? It's not like a setpoint, where the window will then try to reach 100% over time. It's immediately rejected/corrected to 80%, and you have to send another command to try again (also in case of rain).

[jlaur]

Having only a single channel could then disregard (veto) that target position. So if you start at 0%, then send a command with 100%, the final state will then become 80%. What is gained by having a separate channel for keeping the 100% you tried to command? It's not like a setpoint, where the window will then try to reach 100% over time. It's immediately rejected/corrected to 80%, and you have to send another command to try again (also in case of rain).

I'll just add that currently when a window is initially closed, both channels are 100%. If I then use the Velux app (or physical button) to open the window a little bit, both channels change state to the new position, e.g. 80%. That seems counter-intuitive.

[andrewfg]

the stop button does not work

Indeed. It is on the TODO list in the top post.

EDIT: @ThomasM102 perhaps you can give some more input on this? There are actually three channels for this; the position current and position target channels as discussed above for the percent open position; plus the position hold channel for the stop command. We have argued to keep current and target as seperate channels. Which kind of argues that position hold should also be separate. => WDYT?

[ccutrer]

4. However I am really struggling with non analog enum setpoint and actual characteristics like say Fan State Target (which maps to a 2 state auto-manual switch) and Fan State Current (which maps to 3 possible state description option enum conditions). I don't see any possible logical way to merge or hide one or other of these two characteristics. So I think we should leave these as separate channels. Or??

Yes, I very much agree that any current/target that are enums with different valid values should be separate channels. Things like thermostat current/target mode (current can be idle, which is missing from target), security system current/target state (current can be triggered, which is missing from target), fan mode (target is just manual/auto, but current is inactive/idle/blowing).