[hdpowerview] Add support for Generation 3

[andrewfg]

Resolves #12678

Background

This PR adds support for Hunter Douglas Generation 3 hubs into the binding (which currently only supports Generation 1 & 2 hubs).

Note: the binding code in this PR automatically defaults to Generation 1/2 functionality unless a Generation 3 hub is pro-actively detected. Therefore the JAR resulting from this PR should run perfectly on Generation 1/2 hubs.

Specifics of Changes

The following classes have been added or modified for Generation 3 support..

New DTO Classes

• 'Info.java' provides information about Generation 3 gateways.
• 'Scene.java' provides information about Generation 3 scenes.
• 'Shade.java' provides information about Generation 3 shades.
• 'ShadePosition.java' provides information about Generation 3 shade positions.
• 'ShadeEvent.java' provides information about Generation 3 SSE events for shades.
• 'SceneEvent.java' provides information about Generation 3 SSE events for shades.

Note that some of these DTO classes have the same class names as already existing Gen 1/2 DTO classes.

New Handler Classes

• 'GatewayBridgeHandler.java' is a new bridge handler for Generation 3 gateways.
• 'ShadeThingHandler.java' is a new thing handler for Generation 3 shades.

New Discovery Classes

• 'GatewayDiscoveryParticipant.java' is an mDNS discover participant to discover Generation 3 gateways.
• 'ShadeDiscoveryService.java' is a discovery service to discover shades within a Generation 3 gateway.

Other New Classes

• 'GatewayWebTargets.java' provides the interface to Generation 3 API endpoints in the gateway, and SSE callbacks.
• A Junit test class added for the Generation 3 DTOs
• Respective JSON test files have been added too.

Changes to Existing Classes

• 'HDPowerViewHandlerFactory.java' has been extended to add support for 'GatewayBridgeHandler.java' and 'ShadeThingHandler.java'.
• 'HDPowerViewBindingConstants.java' has been extended with new Generation 3 constants.
• 'HDPowerViewCommandExtension.java' has been extended to also support Generation 3 gateways.
• 'ReadMe.md' has been extended to describe Generation 3 features.

JAR Files for Testing

You can download the current binding JAR files HERE

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

[jlaur]

Awesome, @andrewfg, this looks really good and clean to me - good job! I already added a few initial comments, but will need more time for going into the nitty gritty details.

How progressed is it, did you have a chance to test it with actual Gen 3 equipment through VPN?

Regarding the structure:

• I believe you can remove the "3" suffix from all DTO classes as there are no namespace conflicts.
• I'm in doubt whether I like all Gen 3 classes being in a completely separate tree as opposed to existing alongside the old classes. See below.

With the new hierarchy a lot of classes seems "hidden". So I would consider instead of:

• api/responses/shade
• discovery/HDPowerViewDeviceDiscoveryService
• handler/HDPowerViewHubHandler
• • gen3/discovery/HDPowerViewDeviceDiscoveryService3
• • gen3/handler/HDPowerViewHubHandler3

to have it flattened like this:

• dto/responses/Scenes
• dto/responses/Shade
• • dto/gen3/Shade
• • dto/gen3/Scene
• discovery/HDPowerViewDeviceDiscoveryService
• discovery/HDPowerViewDeviceDiscoveryService3
• handler/HDPowerViewHubHandler
• handler/HDPowerViewHubHandler3

[andrewfg]

How progressed is it, did you have a chance to test it with actual Gen 3 equipment through VPN?

No. Unfortunately @vves seems to have other priorities at the moment. => ???

[jlk]

@andrewfg if it helps, I have a new gen3 install that I'm willing to alpha test with. 😃

[andrewfg]

I have a new gen3 install that I'm willing to alpha test with

@jlaur for me my next step will be to confirm that Gen1/2 is not broken.

[jlaur]

@andrewfg if it helps, I have a new gen3 install that I'm willing to alpha test with. 😃

That's good to know, thanks! However, I'm afraid that the API is not finalized/published yet, so I don't think it will be possible to test with your firmware just yet. @andrewfg - for transparency, perhaps the PR should be marked as draft for now?

[andrewfg]

you can remove the "3" suffix from all DTO classes as there are no namespace conflicts.
I'm in doubt whether I like all Gen 3 classes being in a completely separate tree as opposed to existing alongside the old classes.

@jlaur before I rename any classes, and/or move them to other folders, I would like to make 100% sure we are in agreement on the approach. So can you please confirm the following from your side?

1. Can you confirm that in general you do not want to have the new classes in own gen3 specific folders?
2. Can you confirm that in general you do not want to have the new classes named by any gen 3 specific suffix (e.g. '3' suffix)?
3. Notwithstanding the above, apropos your point about DTO classes with '3' suffix; there are I think are two class name conflicts -- namely the Scene class embedded in the Scenes class, and the ShadePosition class; so in these cases the '3' suffix is probably inevitable. Do you agree to that exception to point 2 above?
4. For the handlers, discovery, and webTargets classes, so far I used the nomenclature 'HDPowerViewBlahBlah' => HDPowerViewBlahBlah3', which I think is inelegant, so I propose to name the gen3 versions of those classes more plainly as e.g. GatewayBridgeHandler, GatewayWebTargets, GatewayDiscoveryParticipant, GatewayShadeDiscoveryService, and GatewayShadeHandler, => Is that OK with you?
5. For info: there is another DTO class 'ScheduledEvent3' which potentially has a name conflict. However I think that we should probably delete that class because, unlike in gen1/2 such ScheduledEvents (aka Automations) the respective resources are read only in gen3, so there are no channels created in the gateway bridge thing for such resources, because there is actually nothing that OH could do with / do to, such resources. => Do you agree with this deletion?

[jlaur]

1. Can you confirm that in general you do not want to have the new classes in own gen3 specific folders?

In general I don't think a total segregation with two complete separate hierarchies will be useful. That would be almost like having two bindings in one, but actually I do think there will be some overlap and dependencies. The exception would be the DTO classes, which I think should be kept separate. Two reasons for that:

1. They represent different API's with different serialization/deserialization of different JSON structures, as previously discussed.
2. There are simply many of them, and they could also be structured in subfolders like we have for Gen 1/2: request, response, etc. where applicable.

2. Can you confirm that in general you do not want to have the new classes named by any gen 3 specific suffix (e.g. '3' suffix)?

In general, yes.

3. Notwithstanding the above, apropos your point about DTO classes with '3' suffix; there are I think are two class name conflicts -- namely the Scene class embedded in the Scenes class, and the ShadePosition class; so in these cases the '3' suffix is probably inevitable. Do you agree to that exception to point 2 above?

Not for this case. First, I don't think any Gen3 DTO class should include other DTO classes from Gen 1/2 and vice versa. This would break the separation. And also, in specific scenarios where we need to reference both, this shouldn't be a problem: We can just reference them by fully qualified namespaces. As an example, this might be needed in the console class being introduced with #13615.

4. For the handlers, discovery, and webTargets classes, so far I used the nomenclature 'HDPowerViewBlahBlah' => HDPowerViewBlahBlah3', which I think is inelegant, so I propose to name the gen3 versions of those classes more plainly as e.g. GatewayBridgeHandler, GatewayWebTargets, GatewayDiscoveryParticipant, GatewayShadeDiscoveryService, and GatewayShadeHandler, => Is that OK with you?

Yes, that seems reasonable. In a way we are lucky that Hub is now Gateway, as it resolves naming conflicts for us. :-)

5. For info: there is another DTO class 'ScheduledEvent3' which potentially has a name conflict. However I think that we should probably delete that class because, unlike in gen1/2 such ScheduledEvents (aka Automations) the respective resources are read only in gen3, so there are no channels created in the gateway bridge thing for such resources, because there is actually nothing that OH could do with / do to, such resources. => Do you agree with this deletion?

Yes. I suggested to Wes to add possibility in the API for enabling/disabling automations, but don't know the status. This is very useful for automating the automations. :-) See #11637. I would certainly miss this. Probably it would appear in some new form with new JSON structures, so we'll see.

[andrewfg]

@jlaur many thanks for the advice; I have renamed and moved the classes as you suggest; and for the DTO's it was indeed possible to use the same classes in gen 3 as in gen 1/2 by means of fully qualified references as you proposed.

In this last commit, I also extended your new console class, and did some extra work on the ReadMe..

[openhab-bot]

This pull request has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/hunter-douglas-luxaflex-powerview-generation-3-binding/146796/1

[openhab-bot]

This pull request has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/hunter-douglas-luxaflex-powerview-gen-3-3-4-0-0-4-0-0-0/146805/1

[jlaur]

Thanks for your contribution. The code looks good, I have added only a few comments.

[jlaur]

LGTM