[hdpowerview] PowerView Gen 3 support

[jlaur]

This issue is created as a placeholder for gathering information about the new PowerView Gen 3 and discussing how to support it. I have requested API documentation from Hunter Douglas. They have responded: "This information has not been released to the general public yet, we are working in beta with selected groups as needed."

What we know so far:

• Proprietary RF communication will be replaced by standards-based Bluetooth Low Energy (BLE) protocol.
• The new protocol offers instant two-way synchronization and improved reliability and range.
• A new PowerView Gen 3 Gateway will be introduced, probably similar to PowerView Gen 2 Hub, but communicating over BLE with shades and accessories.
• A new PowerView Pebble Remote will be introduced, communicating over BLE.

Open questions:

• Will the PowerView Gen 3 Gateway support the proprietary RF communication for backwards compatibility with legacy shades and accessories?
• Will the PowerView Gen 3 Gateway remain open for integrators like the PowerView Gen 2 Hub?
• Will the PowerView Gen 3 Gateway implement a new API and/or support the existing API?
• Will the PowerView Gen 3 Gateway support the Matter standard at some point?

Sources:

• https://restechtoday.com/hunter-douglas-debuts-powerview-gen-3-automation/
• https://www.cepro.com/control/motorized-shades/hunter-douglas-powerview-gen-3-series/

[jlaur]

@andrewfg, @arroyoj - FYI.

[kingy444]

The fact they havent released the api is not a great sign for any backwards compatability

but fingers crossed for the new hub to support the old protocol - be nice if shades automatically updated their postion with the hub when finished moving

[andrewfg]

The fact they havent released the api is not a great sign for any backwards compatability

Or it might mean that the API did not change :)

[kingy444]

Likely some bad news unfortunately

https://community.home-assistant.io/t/hunter-douglas-powerview-gen-3-integration/424836/3

[andrewfg]

The current (older) API uses plain text over HTTP with no encryption and no authentication. So it is pretty archaic. Therefore my guess is that they will have moved to HTTPS and some form of authentication (perhaps password based or token based).

{ Note: I had the exact same experience in the last month with the Heatmiser Neohub where the manufacturer migrated from plain text HTTP to a token based web socket connection instead https://github.com/openhab/openhab-addons/pull/12915#issuecomment-1152413274 and in this case, they kept support for the legacy plain text HTTP but now it requires the user to explicitly switch it on in the App }

[kingy444]

Yea that makes sense - would be good if they added it via firmware to the old hubs too tbh - just make it optional

[andrewfg]

Yeah. In the Heatmiser App, it is as simple as this..

[andrewfg]

would be good if they added it via firmware to the old hubs

PS in my App there is an option 'Receive Early Access Updates' (Opt in to receive early access to firmware updates before official release) ... however I am extremely nervous about whether or not to enable it ...

[jlaur]

PS in my App there is an option 'Receive Early Access Updates' (Opt in to receive early access to firmware updates before official release) ... however I am extremely nervous about whether or not to enable it ...

IMHO you should try it. :laughing:

[jlaur]

Btw, in the linked thread a port scan was made, and port 443 wasn't open.

[andrewfg]

you should try it

LOL

[andrewfg]

@jlaur here is another article that answers some of your questions about Gen 2 vs Gen 3 inter-operation..

https://www.slashgear.com/850488/hunter-douglas-smart-blinds-embrace-bluetooth-why-thats-a-big-deal/

[andrewfg]

@jlaur someone made the following post on the HA forum; it's not definitive, but the guy sounds like he knows something..

https://community.home-assistant.io/t/hunter-douglas-powerview-gen-3-integration/424836/17?u=andrewfg

[andrewfg]

@jlaur I found the following link, which implies that some commercial companies have developed integrations for Gen3 hubs. The web page has an email link, and I have already emailed them asking for information about the Gen 3 API. I will keep you informed if I get any response.

https://controlconcepts.net/manufacturers-modules-and-drivers/hunter-douglas/

[andrewfg]

@jlaur the response was as follows..

Do you have access to a Gen 3 Gateway and shades? The Gen 3 API documentation lives on the Gateway itself using Swagger. Swagger also allows for easy testing of the REST API, showing command structure and results.

By default, Swagger is disabled on Gateways as it does utilize system resources and is only needed during integration development. http://powerview-g3.local/gateway/swagger?enable=true will enable Swagger. Note that Swagger must be re-enabled after each Gateway power cycle.

To get to Swagger once enabled, use http://powerview-g3.local:3002/

[vves]

@andrewfg @jlaur Hi, I wanted to introduce myself. I am the product architect for Gen3 can provide some unofficial guidance and support for this integration. Cheers and Code On! @jlaur is correct that the starting point for the integration is the Gateway Swagger docs listed above.

[jlaur]

@andrewfg @jlaur Hi, I wanted to introduce myself. I am the product architect for Gen3 can provide some unofficial guidance and support for this integration. Cheers and Code On! @jlaur is correct that the starting point for the integration is the Gateway Swagger docs listed above.

Thanks for stepping in and offering support, @vves. For supporting the Gen 3 gateway we currently lack documentation and/or users (in order to get hands on), since we are currently not in procession of the new gateway. I recently added new TDBU shades to my setup, so I now have 11 shades on a Gen 2 Hub, so for me personally I'm unfortunately nowhere near a Gen 3 upgrade.

[andrewfg]

@vves I would also like to thank you for your support; perhaps the best is if you can send us the swagger data (presumably a yaml file?); however alternatively perhaps you can expose one of your hubs via a port forwarding, or vpn connection, so we can talk to it ourselves?

[kingy444]

Thanks for reaching out @vves

I do Dev work on the HomeAssistant side and have been working with @andrewfg closely over the last couple of months (great to see collaboration between ‘competing’ platforms)

As Andrew suggested if we could get access to the api doco in some alternative way that would be great.

While offline development without a hub isn’t great (blindly hoping your code logic works) our only other option is to hope another ‘developer’ gets a gen3 hub installed - I couldn’t afford to spring for new blinds just to help the community out 😂

Again really appreciate the response - I’d personally tried to reach out to Hunter Douglas and had no response.

Not sure if you have seen some of our other conversations but one thing that would be insanely helpful is the definition of your shade capability and types. Everything we currently have is community driven and relies solely on someone providing their json output to us.

Even just a listing of shades and their capability type would be great for aesthetics but really would be great if some of our ‘guesses’ on capability were substantiated.

[vves]

My preference is to use the Gateway Swagger endpoint as the HD dev team is still making minor tweaks to the API. That said, I'll provide static swagger doc here but first I need to cull some private data from swagger. Expect an update by end-of-week.

[andrewfg]

@vves many thanks for your support; much appreciated.

[andrewfg]

@jlaur as "homework" for this integration, you may want to take a look at the tado binding which uses Swagger CodeGen to parse the Swagger 'yaml' file and auto- generate the respective Java classes for the DTOs and the web service.

[andrewfg]

FWIW a Home Assistant user kindly did a screen capture from their Gen 3 hub (see below). It is interesting, but I am still hoping that @vves can post us the yaml file :)

@jlaur of immediate interest to me are the following..

• The urls in Gen 2 hubs like '/api/shades' seem to now be '/homes/shades' instead.
• There seem to be ten capabilities rather than nine ;)
• .. more no doubt to come ..

[vves]

@andrewfg Even better - I am putting a 'Getting Started with Integrations' document together. A deep integration only needs around 10 total calls. The rest of the API is for internal Hunter Douglas tools and will end up being redacted in the future.

[andrewfg]

putting a 'Getting Started with Integrations' document together

@vves please don't feel that you need to make that extra effort on account of us. We already have full integration for Gen 1 and Gen 2 hubs so (dare I say it) we are beyond the 'getting started' phase. All we need from you is the extra information concerning how Gen3 hubs differ from Gen 1/2 ones..

A deep integration only needs around 10 total calls

Yes. In fact our integration for the Gen 1/2 hubs goes a bit deeper than ten. We use seventeen calls as you can see from the HDPowerViewWebTargets.java code. Albeit some of these are GET/PUT variations on the same uri.

[vves]

@andrewfg there are some significant changes in Gen3 as all shade information is now live and event driven instead of requiring polling for shade and scene state. It's these changes that I want to highlight and provide best practices for all integrations - not just openHAB. Coming soon!

[andrewfg]

all shade information is now .. event driven

Ah yes. Had you not mentioned it, I would most probably have overlooked it. ;)

[andrewfg]

Some data from /home/shades :)

[
	{
		"id": 37,
		"type": 9,
		"name": "TGVmdA==",
		"ptName": "Left",
		"motion": null,
		"capabilities": 7,
		"powerType": 2,
		"batteryStatus": 3,
		"roomId": 1,
		"firmware": {
			"revision": 3,
			"subRevision": 0,
			"build": 359
		},
		"positions": {
			"primary": 1,
			"secondary": 0,
			"tilt": 0,
			"velocity": 9998
		},
		"signalStrength": -55,
		"bleName": "DUE:1D9E"
	}
]

[andrewfg]

@jlaur I made some preliminary experiments on implementing the gen 3 api on my branch below..

Basically I started creating two abstract classes ShadeData and ShadePosition with V1 and V3 implementations ShadeDataV1, ShadeDataV3, ShadePositionV1, ShadePositionV3. This means the binding code that depends on ShadeData and ShadePosition can essentially remain unchanged..

Next step is to also do the same thing with the WebTargets class..

https://github.com/andrewfg/openhab-addons/tree/hdpowerview-generation3/bundles/org.openhab.binding.hdpowerview

[jlaur]

@andrewfg - great that you are getting started. I didn't have time since our meeting to reflect much about the approach, except some initial thoughts.

Collaboration:

• If you are interested in discussing the design and approach to integrating Gen 3 into the existing binding, let's agree on some communication channel/format? I'm fine with this issue for starters, I guess we can extend if needed.
• Let's also sync expectations with each other and Wes about our timeline and effort we can put into this. Perhaps next meeting or PM.
• Pull request strategy: Some refactoring and preparations could be done before actually adding Gen 3 support, or at least it could be done in parallel and frequently rebased. A good strategy could help keeping the initial Gen 3 PR smaller and at the same time ease the maintenance and other work happening in the meantime.
• And of course practical coordination like who will do what.

Technical - as said, not much time for considerations yet:

• Namespace/structure: I would suggest to use dedicated subfolders for Gen 3 to avoid naming each individual class something like V3 or V1 (which is actually Gen1+Gen2 as they are almost identical).
• Naming: Perhaps we could use "Gen3" as a term. Not sure what to call Gen 1 and Gen 2 combined though. "Legacy" might be a bit ahead of time. :-)
• Bridge: What would you think about creating a new bridge type? Name is now "Gateway", not "Hub". Also it doesn't seem to have many similarities with Gen1/2, except hostname. Gen 3 might also have some kind of configuration for SSE (not sure yet).
• Things: So far I don't see any need to model things differently, so probably everything can be reused. Only the implementation would differ. What do you think?
• Controlling multiple shades: Not sure what is possible - do you know if it is somehow possible to implement/override/intercept handleCommand for a group? This could make it possible in the semantic model to iterate through children and create a single request for all shades in the group when using controls on the group.
• Much more to come, but let's start creating ideas. :-)