[hdpowerview] Support activation of scene collections

[jlaur]

The Hunter Douglas PowerView Hub supports two different scene concepts:

• Scenes
• Scene Collections

A scene collection is a collection of scenes and can be used to group multiple scenes and activate them all with a single click or automation.

Currently the binding supports only scenes, but not scene collections.

Note: Hunter Douglas has removed scene collections from the app, but they are still supported by the hub. Any user already having scene collections will be able to still trigger them - also from the app. In order to implement #11516 without filtering scene collections, this issue is still relevant, although a bit late.

[jlaur]

@andrewfg - just received this response from Hunter Douglas (only relevant part quoted):

Thank you for contacting Hunter Douglas. I am sorry we did get rid of the scene groups.

[jlaur]

@andrewfg - good news, I just managed to manually create a new scene collection, so it's still supported by the hub. I compared how scenes are created/fetched with how scene collections are fetched and deducted from this how scene collections are created (as I could no longer trace it because app doesn't support it anymore):

POST /api/sceneCollections/
Request:

{
	"sceneCollection": {
		"name": "QsO4cm4gaSBzZW5n",
		"colorId": 12,
		"iconId": 17,
		"id": -1,
		"order": 0,
		"hkAssist": false
	}
}

Response:

{
    "sceneCollection": {
        "name": "QsO4cm4gaSBzZW5n",
        "colorId": 12,
        "iconId": 17,
        "id": 16820,
        "order": 0,
        "hkAssist": false
    }
}

Using this returned id and some known id's from existing scenes, sent two additional requests to link the scene collection with these two scenes:

POST /api/scenecollectionmembers/

{
	"sceneCollectionMember": {
		"sceneCollectionId": 16820,
		"sceneId": 19165
	}
}

POST /api/scenecollectionmembers/

{
	"sceneCollectionMember": {
		"sceneCollectionId": 16820,
		"sceneId": 7829
	}
}

After this, the scene group shows up in the app and can of course also be triggered from openHAB with #11534. Once the scene group is created, it can even be edited within the app.

[andrewfg]

Cool

[andrewfg]

sent two additional requests to link the scene collection with these two scenes

Just wondering how you would DELETE a scene from a scene collection, (via the REST API)..?

[jlaur]

@andrewfg - it can be deleted through the API, also from the app.

[andrewfg]

it can be deleted through the API

What is the JSON POST payload to delete a scene from a collection? The examples you showed above are only for adding a scene to a collection..

[jlaur]

@andrewfg - I'll trace it in the evening, will post update.

[jlaur]

@andrewfg - okay, that was pretty straight-forward:

DELETE /api/scenecollections/16820 HTTP/1.1
User-Agent: PowerView/3.0.2 5433 (OnePlus IN2013 da_DK)
Host: 192.168.0.239
Connection: Keep-Alive
Accept-Encoding: gzip

HTTP/1.1 204 No Content
X-Powered-By: Express
Content-Type: application/json
Date: Mon, 15 Nov 2021 16:00:10 GMT
Connection: keep-alive

[jlaur]

@andrewfg - oh, wait, I deleted the scene collection, you asked about removal of a scene from a scene collection. I can try that later, will need to create a new scene collection again. That's really going into details, only use-case is probably it someone would write a new app/client, it's not something we'll really need for the binding or even for testing the binding. To get same result as deleting a scene from a scene collection, the scene collection could simply be created from scratch without adding the scene.

[andrewfg]

Interesting (but obvious) to use HTTP DELETE method. However I guess that method deletes the whole scene collection, rather than deleting one scene from a collection. Or??

[jlaur]

@andrewfg - okay, got it:
DELETE /api/scenecollectionmembers?sceneCollectionId=16328&sceneId=19165 HTTP/1.1

Note that from the app you cannot delete 2nd last scene, as you need at least two scenes in a scene collection.

And to update a scene collection:
PUT /api/scenecollections/16328 HTTP/1.1

with body as when creating, except that id is obviously included:
{"sceneCollection":{"colorId":12,"iconId":17,"order":0,"id":16328,"name":"QsO4cm4gaSBzZW5n"}}

[andrewfg]

Ah cool. For posterity, perhaps it would be helpful if you would add a description of those method's syntax (say) somewhere in the class that implements the other REST API calls for scene collections? Just an idea..

[jlaur]

@andrewfg - I'll try to see if I can figure how who maintains this document: Hunter Douglas PowerView® Hub API
for Home Automation Integration and if it can be extended with this additional information. IMHO it would be more useful to extend some documentation to be usable for everyone than to hide it within some code in openHAB where it's not actively used. But of course - also more difficult, but challenge accepted. :-) @arroyoj, do you know who maintains this document or maybe the origin?

[arroyoj]

@jlaur, sorry, I don't know the origin of the API document. I found the link to it in a previous issue. I tried to find a version on the Hunter Douglas website, but it doesn't seem to be there any more.

[andrewfg]

I'll try to see if I can figure how who maintains this document

@jlaur did you have any luck with this? (reason: for Issue #11557 I would like to contact them to learn the meaning of the shade's capabilities JSON element..)

PS I found a newer version of the PowerView API PowerView-Hub-REST-API-v2.pdf but unfortunately that also does not include the answer to my question..

[jlaur]

@andrewfg - no luck so far, but I also was in possession of that v2 document already which I found in some forum. Didn't realize the difference. Now searched for it and found this guy who may know something - I'll try to reach out to him in the upcoming weekend: https://community.hubitat.com/badges/2/member?username=sstretchh

If I don't find any document maintainer, I'll create an appendix document myself so we'll have documentation also for the findings from my reverse engineering, i.e. scene group (scene collection) update/deletion and automations (scheduled events).

[jlaur]

@andrewfg - okay, I'm pretty sure the document is from Hunter Douglas, so when I find the time I'll create an appendix. Btw, do you have a V1 or V2 hub? And you, @arroyoj?

[andrewfg]

do you have a V1 or V2 hub?

Mine is a V2 hub.

If I don't find any document maintainer

I discovered this address 'david(dot)flynn(at)hunterdouglas(dot)com' -- but I sent him a mail a week ago, and did not get any response yet.

when I find the time I'll create an appendix

Perhaps you could add these shade type and shade capabilities data to the appendix as well? :)

Shade Types and Capabilities.xlsx
.

[arroyoj]

@jlaur, I also have a V2 hub.

[andrewfg]

I don't find any document maintainer

A couple of further pieces of information that might relate to this..

• I came across a guy who was an HD product manager (see this post) who might perhaps be able to point you to a successor.
• I talked yesterday to my HD PowerView product installer, who told me that HD just closed a factory in Birmingham, UK (and reduced their staff from 350 people to 35 people (the latter being the ones in sales and marketing)). Apparently they moved the manufacturing to a 'robotic' factory in Poland (where they employ fewer (and cheaper) people). So perhaps this firing and hiring could explain a some lack of responsiveness to more complex queries (??)

[jlaur]

@andrewfg - I haven't forgotten about documenting the reverse engineered findings, it just didn't make it high enough on my TODO list yet. However, a few days ago I managed to come up with a small draft, so early sharing:
PowerView-Hub-REST-API-appendix.pdf

@arroyoj - for your information also.

I still need to add more and make all links work etc. and find a way to embed your document Shade.Types.and.Capabilities.xlsx.

[andrewfg]

^
Wow. That looks fantastic. Do you have the original in Word (or other editable RTF format)? If so then I would be happy to add my own findings and post it back to you for final publication.

[jlaur]

@andrewfg - not sure if you received my mail with the documents. Otherwise please let me know.

[andrewfg]

@jlaur yes I got your documents, many thanks; and I plan to start work on it tomorrow...

[jlaur]

For anyone reading this issue with interest in the API documentation, and for you @andrewfg: Without further ado, the document is now published: PowerView-Hub-REST-API-v2-appendix.pdf. Thanks for collaborating on this!