Virtual Garage Door integration with HKLS

Posted on
Sun Dec 18, 2022 6:51 pm
papamac offline
User avatar
Posts: 131
Joined: Jan 29, 2014

Virtual Garage Door integration with HKLS

Hi Glenn! My name is David Krause (aka papamac). I am the author of the Virtual Garage Door (VGD) plugin (see Indigo Plugin Store, papamac's plugin forum, and https://github.com/papamac/VirtualGarageDoor).

Like many other Indigo users, I want to thank you for writing the HKLS plugin... it is truly a joy to use :)

I upgraded to HKLS from HomeKit Bridge effortlessly, and am now using it successfully in my home automation system with 74 devices, including two VGD devices. I can ask Siri to open, close, and check the garage doors. The HomeKit app works as well; it opens and closes the doors and shows the open/close status in the display. All of this is done using the onOffState of the VGD device which has two values ( False/off/0 -> open and True,/on/ 1 -> closed,).

The Apple HimeKit framework permits 5 door states values (see https://developer.apple.com/documentation/homekit/hmcharacteristicvaluedoorstate). These are: 0 -> open, 1 -> closed, 2 -> opening, 3 -> closing, and 4 -> stopped. The first four are obvious. The fifth (stopped) is an interrupted (perhaps obstructed) state during door opening. There is no corresponding state in the framework for interrupted (or obstructed) closing. Nevertheless, the framework includes an "ObstructionDetected" characteristic which presumably applies for both opening and closing. My desire is to modify the VGD and HKLS plugins to utilize these additional state values and characteristics. The goal is to have the HomeKit app additionally display opening and closing states and "ObstructionDetected".

I have modified the VGD plugin to include a new integer state variable named "doorState". Its values are the five HomeKit state values and an additional state value (5 -> reversing) to indicate interrupted (or obstructed) closing. It retains the same onOffState for compatibility with existing software. This versions not yet released in either GitHub or the Indigo PluginStore. It is available as the current master branch in GitHub should you want to look at it.

I have also modified a local copy of your HKLS plugin (v0.5.9) to recognize the new VGD doorState and set the GarageDoor accessory characteristics accordingly. My modified version looks for the doorState first, then if not present, the onOffState, and finally the binaryInput1 for Insteon. This should maintain compatibility with other GarageDoor devices/plugins. It then sets three GarageDoor accessory characteristics ( CurrentDoorState, TargetDoorState, and ObstructionDetected) based on rules that I determined empirically.

I have tested the modified HKLS version with my modified VGD plugin and the combination seems to work well with the HomeKit app for both normal and interrupted door operations. Nevertheless, my knowledge of the HomeKit framework is limited and I'm not sure that I captured all the subtleties of the interaction between the TargetDoorState and the CurrentDoorState. If you can help, please look at my assignment rules for the GarageDoor characteristics and let me know what you think. As I said, they work In my limited tests... but who knows if there are any side effects?

There are 5 small segments of code that changed in my modified HLKS version. Because there are so few changes, I am including them in this post for your review. Line numbers are referenced to your current GitHub version (v0.5.10). If you wish, I can provide these as a formal GitHub pull request.

Segment 1: HomeKitDevices.py, class GarageDoor, __init__ method, lines 1464-1466; remove the comment tag from these lines and correct spelling in "ObstructionDetected"

Code: Select all
        self.char_obstruction_detected = serv_garage_door.configure_char(
            "ObstructionDetected", value=False
        )


Segment 2: HomeKitDevices.py, class GarageDoor, _set_chars method; insert the following commented debug code after line 1509

Code: Select all
            # (VGD) debug code for papamac's Virtual Garage Door (VGD) changes
            # (VGD) currentDoorState = self.char_current_state.get_value()
            # (VGD) targetDoorState = self.char_target_state.get_value()
            # (VGD) obstructionDetected = int(self.char_obstruction_detected.get_value())
            # (VGD) chars = (currentDoorState, targetDoorState, obstructionDetected)
            # (VGD) logger.warning('GarageDoor characteristics changed by HK: (c, t, o) {}'.format(chars))


Segment 3: plugin.py; insert debug method after line 1423, just before the deviceUpdated method

Code: Select all
    # (VGD) debug method for papamac's Virtual Garage Door (VGD) changes
    @staticmethod
    def _getGarageDoorCharacteristics(accessory):
        currentDoorState = accessory.char_current_state.get_value()
        targetDoorState = accessory.char_target_state.get_value()
        obstructionDetected = int(accessory.char_obstruction_detected.get_value())
        return currentDoorState, targetDoorState, obstructionDetected


Segment 4: plugin.py, deviceUpdated method; replace the elif clause at line 1799 with

Code: Select all
                elif str(updateddevice_subtype) == "GarageDoor":
                    for stateName in ("doorState", "onOffState", "binaryInput1"):  # ordered by preference
                        # doorState:    0 -> open, 1 -> closed, 2 -> opening, 3 -> closing, 4 -> stopped, 5 -> reversing
                        # onOffState:   0 -> open, 1 -> closed
                        # binaryInput1: 0 -> open, 1 -> closed
                        if stateName in updated_device.states:  # choose the first match
                            oldstate = original_device.states[stateName]
                            newstate = updated_device.states[stateName]
                            if newstate != oldstate:  # state has changed

                                # Log Indigo device state change.

                                # (VGD) debug code for papamac's Virtual Garage Door (VGD) changes
                                # (VGD) self.logger.warning('Indigo device "{}" {} changed: {} --> {}'.format(updated_device.name, stateName, oldstate, newstate))
                                if self.debug2:
                                    self.logger.debug("NewState of Device:{} & State: {} ".format(updated_device.name, newstate))
                                if this_is_debug_device:
                                    self.logger.warning("NewState of Device:{} & State: {} ".format(updated_device.name, newstate))
                                accessory = self.device_list_internal[checkindex]["accessory"]
                                # (VGD) oldChars = self._getGarageDoorCharacteristics(accessory)

                                # Update GarageDoor characteristics based on Indigo device state change.

                                # CurrentDoorState must be 0 -> open, 1 -> closed, 2 -> opening, or 3 -> closing.
                                currentDoorState = (0, 1, 2, 3, 0, 2)[newstate]
                                accessory.char_current_state.set_value(currentDoorState)

                                # TargetDoorState must be 0 -> open or 1 -> closed
                                targetDoorState = (0, 1, 0, 1, 0, 0)[newstate]
                                accessory.char_target_state.set_value(targetDoorState)

                                # ObstructionDetected must be 0 -> False or 1 -> True
                                obstructionDetected = (None, 0, None, 0, 1, 1)[newstate]
                                if obstructionDetected is not None:
                                    accessory.char_obstruction_detected.set_value(obstructionDetected)

                                # (VGD) newChars = self._getGarageDoorCharacteristics(accessory)
                                # (VGD) self.logger.warning('GarageDoor characteristics changed by HKLS (c, t, o): {} --> {}'.format(oldChars, newChars))
                            break
                    return


Segment 5: plugin.py, Plugin_getter_callback method; replace the elif clause at line 2406 with

Code: Select all
            elif statetoGet == "garageDoorState":
                for stateName in ("doorState", "onOffState", "binaryInput1"):  # ordered by preference
                    if stateName in indigodevice.states:  # choose the first match
                        if self.debug4:
                            self.logger.debug("Found {} using that..".format(stateName))
                        return indigodevice.states[stateName]


So, thanks for listening to my story. My ask is that you review and evaluate my changes to your HKLS plugin, change them as you see fit, and incorporate their functionality into a future release of HKLS. If you have any concerns, or want to run additional test cases in my environment, please let me know. I will continue to work on an updated VGD release. My new release will work (in a limited way) without the HKLS changes, so we can work on this asynchronously. I hope that you view my suggestions positively as a win-win-win for HKLS, VGS, and Indigo users. Thanks again for your consideration.

David

Posted on
Sun Dec 18, 2022 7:40 pm
GlennNZ offline
User avatar
Posts: 1555
Joined: Dec 07, 2014
Location: Central Coast, Australia

Virtual Garage Door integration with HKLS

Thanks, for the comments and suggestions.

Looks good at first review.

There may be sequence issue which will double check - often HomeKit requires a certain order of setting. But if you have tested and functions - probably not a big issue. Occasionally Homekit wishes one item set, before another particularly if entering a error like state - which Obstructed may be….

But as said, looks good. I’m away for a bit at the moment, but when back in a week or so, will have a look and update/incorporate.

Glenn


Sent from my iPad using Tapatalk

Posted on
Sun Dec 18, 2022 10:48 pm
papamac offline
User avatar
Posts: 131
Joined: Jan 29, 2014

Re: Virtual Garage Door integration with HKLS

Thanks for the quick reply. I'll look forward to hearing from you when. you return.

David

Posted on
Sun Dec 18, 2022 11:23 pm
GlennNZ offline
User avatar
Posts: 1555
Joined: Dec 07, 2014
Location: Central Coast, Australia

Re: Virtual Garage Door integration with HKLS

Thanks David,

Looks good -the main aspect being handling the deviceUpdate, and updating obstruction char.

I would just add-in your support and update HKLS version number, but have already started, and changed quite a bit trying to support adaptive Lighting. The basics for adaptive lightning are there - and HomeKit App comes up with a new “Adaptive Lighting supported by your devices”.

But the actual code implementation of that control is unfortunately most of the work - it uses a strange TLS low-level encoding for registering various aspects, and also seems to need a constantly running thread managing the light changes. So basically - all lights appear to support Adaptive Lighting currently, but nothing happens! I have to wind that bit back, add your changes and push a new release. (Something that ideally need to be home for)

Thanks


Sent from my iPad using Tapatalk

Posted on
Mon Dec 19, 2022 11:32 am
papamac offline
User avatar
Posts: 131
Joined: Jan 29, 2014

Re: Virtual Garage Door integration with HKLS

No worries! There's no need to hurry. I have my modified HKLS version that I am using in my personal system. I will continue running it as an extended soak test. You should proceed with your development/release schedule.

As long as I know that you intend to include the VGD integration changes in your next release, I will proceed with a new dual capability VGD release. The new VGD release will provide the current onOffState capability with your current HKLS release, and the enhanced doorState capability with your next HLKS release, whenever it arrives

Thanks again,

David

Posted on
Thu Dec 22, 2022 8:19 pm
GlennNZ offline
User avatar
Posts: 1555
Joined: Dec 07, 2014
Location: Central Coast, Australia

Re: Virtual Garage Door integration with HKLS

Hi

Had a couple of hours before madness descends and have pushed 0.5.10 to code base (just download Code button to install)

Adding most of your changes (debug stuff had left out currently)

Hard to completely test - have a go and see what make of it!

Glenn

Posted on
Sun Dec 25, 2022 4:37 pm
papamac offline
User avatar
Posts: 131
Joined: Jan 29, 2014

Re: Virtual Garage Door integration with HKLS

Merry Christmas Glenn!

I just noticed your latest post... perhaps I should subscribe.

Thank you for adding my VGD changes to your HKLS interim v0.5.10. If you wish, you can clean up the code even more by deleting the remaining development/debug comments in your next release. I recommend deleting lines 1773-1774, 1780, and 1796-1798 in plugin.py. In HomeKitDevices.py, delete lines 1508-1512.

I will run tests in the next few days to ensure that the HKLS v0.5.10 and VGD v1.1.0 work together as expected, and also that the other combinations of versions work with limited capability. I will test the following version combinations:

1. HKLS release 0.5.2 with VGD release 1.0.6
2. HKLS release 0.5.2 with VGD interim 1.1.0
3. HKLS interim 0.5.10 with VDS release 1.0.6
4. HKLS interim 0.5.10 with VDS interim 1.1.0

I'll report the test results sometime this week

Thanks again.

David

Posted on
Sun Dec 25, 2022 4:48 pm
GlennNZ offline
User avatar
Posts: 1555
Joined: Dec 07, 2014
Location: Central Coast, Australia

Re: Virtual Garage Door integration with HKLS

No problem.

Agree - can delete the debug stuff before release.

Thanks!


Sent from my iPad using Tapatalk

Posted on
Wed Dec 28, 2022 6:25 pm
papamac offline
User avatar
Posts: 131
Joined: Jan 29, 2014

Re: Virtual Garage Door integration with HKLS

Hi Glenn,

I have completed my tests and all combinations of versions worked as expected. The following table summarizes the capabilities that were verified:

Image

Also, I discovered an error in my code that I'd like you to fix in your next update. Please change line 1793 in v0.5.10 plugin.py from
Code: Select all
obstructionDetected = (None, 0, None, 0, 1, 1)[newstate]

to
Code: Select all
obstructionDetected = (None, 0, None, None, 1, 1)[newstate]

This will maintain the "obstructionDegected" characteristic during closing until the door is fully closed. It is not urgent because it is not visible in Home App displays, but may be useful to anyone testing the characteristic. Please change it at your next planned update.

I will continue to update the VGD wiki and will release a documented VGD 1.1.1 in a week or so.

Thanks for all your help.

David

Posted on
Mon Jan 09, 2023 1:31 pm
papamac offline
User avatar
Posts: 131
Joined: Jan 29, 2014

Re: Virtual Garage Door integration with HKLS

Hi Glenn,

I have completed a draft of the VGD release v1.1.1 wiki that describes the changes that we made. Before I formally release it, I'd like you to look at the sections that are relevant to HKLS. Please let me know if I have misrepresented anything about your plugin. The sections for your review are in the VGD Design wiki (https://github.com/papamac/VirtualGarageDoor/wiki/3.-Design),
Sections 3.1.1-3.1.5.

Also, please tell me if there is anything else about HKLS that you would like to include in my wiki (relevant new/planned features, planned release dates, et al). I will include any suggestions that you may have.

Thanks again for working with me on this. It has been a real pleasure.

David

Posted on
Mon Jan 09, 2023 5:53 pm
GlennNZ offline
User avatar
Posts: 1555
Joined: Dec 07, 2014
Location: Central Coast, Australia

Re: Virtual Garage Door integration with HKLS

Hi David

I really have very little to say as you have covered it, and then some! Only thing I could think of was -
Could you do all my documentation???

(Joking!)

Away for a bit - back again in a couple of weeks!

Best of luck

Glenn


Sent from my iPhone using Tapatalk

Posted on
Mon Jan 23, 2023 12:59 am
papamac offline
User avatar
Posts: 131
Joined: Jan 29, 2014

Re: Virtual Garage Door integration with HKLS

Today, I officially released VGD v1.1.1 on GitHub and the Indigo Plugin Store. VGD is ready for the next release of HKLS.

David

Page 1 of 1

Who is online

Users browsing this forum: No registered users and 0 guests