Any Version Update ?

[kingy444]

Great work to date - will be very helpful for HomeAssistant integration and was pointed this way by the OpenHAB dev.

Just wanted to touch base as i am updating our internal databases if you had any new updates (we do)

Would be happy to share here but pdf is not really the format for us to be able to raise pull requests to you

[jlaur]

Hi @kingy444, thanks for reaching out. I have at least one update not incorporated into the document yet: openhab/openhab-addons#12761. I would need to recheck if I missed others. I'm aware that the distribution format is not PR friendly, so I'm only using this repository as a distribution channel. If you send me your updates in some kind of "instruction format", I'll be happy to add them. For example: "Page 27, ShadeType: Add ShadeType 38 with description "Silhouette Duolite" and ShadeCapabilities 9"

It might be a good idea to extract these tables from the document into some md file or the like as "source format", although the PDF also has the advantage that everything is self-contained. I'll think about it, maybe it would make sense to do both, i.e. open up for PR's maintaining the tables, and then recompile the PDF from time to time.

[jlaur]

@kingy444 - btw, you might also be interested in openhab/openhab-addons#12678.

[kingy444]

Thanks - hopefully the keep the api the same - a md table and the pdf is a good idea - the table is the thing that is likely to change the most

Could i query the highlighted below - I would expect a 'Tilt Only' to not have a primary rail
Hard for us to confirm at the moment as we only get the info from JSON commands and we havent found any for Type 4 or Type 5 - have you seen them ?

EDIT: actually translating this to an internal db now
think you have type 1 wrong - it can only tilt on closed

[jlaur]

@kingy444 - these tables were actually provided by @andrewfg. :) @andrewfg, will you be able to verify this and/or check the source of the information?

[jlaur]

@kingy444 - "Title on Closed" for capabilities 1 was already fixed by openhab/openhab-addons#12237. I'm updating the table/documentation now according to our last few pull requests.

[kingy444]

This will likely help - it is from andrew

withblackoutshade indicates secondary shade reversed so might need another column

[jlaur]

@kingy444 - document is now updated according to latest code changes in openHAB. Blackout shade support is still missing though.

[kingy444]

@kingy444 - document is now updated according to latest code changes in openHAB. Blackout shade support is still missing though.

BlackoutShade is special - i misspoke above - it is not secondary shade reversed it only has one motor - but it accepts poskind2 and the values of position2 need to be inverted as i understand (0 is open and 65k is closed)

[andrewfg]

@jlaur / @kingy444 just to confirm that I think the OH code base reflects the current latest state of knowledge, and @jlaur 's document should indeed be updated to reflect that.

But shutter support is still work-in-progress: @kingy444 has a user request to add support for it in HA; once we have the shade JSON information from the user I will also add support for it in OH; I opened this Issue as a placeholder; my very strong guess is that the user's JSON will show that shutters are Capabilities 5; this means they are implicitly already in OH, but probably not explicitly validated.

BlackoutShade is special

Indeed. It has one motor but supports both a primary and secondary rail position; the motor basically unwinds the first rail cables to lower the rail until it reaches its end stop, and then it continues to unwind the cables for the second rail. For this reason these have special interlocking logic in the code to allow for the physical limitations in the possible positions of the primary and secondary rails.

[andrewfg]

but it accepts poskind2 and the values of position2 need to be inverted as i understand (0 is open and 65k is closed)

To be more specific;

• The position1/posKind1 JSON element may contain either a primary position or a secondary position
• If it contains a primary position then it is de-facto the case that the secondary rail is fully up
• If it contains a secondary position then it is de-facto the case that the primary rail is fully down
• So in other words providing just one position1/posKind1 JSON element is sufficient to define two rail positions

Blackout shade support is still missing though.

So in @jlaur 's document the table for Capabilities 8 and 9 should have a "yes" in both the primary and the secondary rail columns. Note: Capabilities 9 shades also have a separate additional tilt anywhere motor, so they provide a position2/posKind2 JSON element as well.

[andrewfg]

... so I think the final table is this (???) ..

[andrewfg]

^
Perhaps the critical thing as far as the documentation is concerned is that shades can have one/two/three dimensions of motion (primary rail, secondary rail, vanes), and the usage position1/posKind1 resp. position2/posKind2 differs as follows..

1. Shades with one dimension of motion simply just use position1/posKind1
2. Some shades with two dimensions of motion are physically so constructed so that position1/posKind1 provides sufficient data to describe BOTH of the position values uniquely at all times
3. Other shades with two dimensions of motion do actually require both position1/posKind1 and position2/posKind2 to uniquely describe the positions at all times
4. Shades with three dimensions of motion always require both position1/posKind1 and position2/posKind2 to uniquely describe the positions at all times

[jlaur]

@andrewfg - you have added "yes" to Secondary Rail for capabilities 8 and 9, but in the openHAB code this is not the case:

            new Capabilities(8).primary()                                     .text("Duolite Lift")             .withBlackoutShade(),
            new Capabilities(9).primary().tiltAnywhere()                      .text("Duolite Lift and Tilt 90°").withBlackoutShade(),

Should this be fixed in the code?

[andrewfg]

Should this be fixed in the code?

No. It works fine as it is. The only issue is one of nomenclature: these shades DO have both a primary and a secondary rail, but the rails are both driven tightly interlocked by one motor. So strictly they have a secondary rail but not an INDEPENDENT secondary rail.

[andrewfg]

^
Perhaps I should refactor the method name 'withBlackoutShade' to something like 'withInterlockedSecondary' ?? Or something like that..

[jlaur]

@andrewfg - at least some direct mapping between table and code would be preferable. So what does "Secondary Rail" mean in the table vs. what does this mean in the openHAB code when defining capabilities:

        protected Capabilities secondary() {
            supportsSecondary = true;
            return this;
        }

If "withBlackoutShade" would be added to the table, should 8 and 9 still be marked with "Secondary Rail"?

[andrewfg]

^
I think the analog is ‘tiltOnClosed’ (tightly interlocked) vs. ‘tiltAnywhere’ (fully independent). Both map to the same motion dimension and UI elements I.e. vane/tilt but have different logic.

.. so yes, probably an extra column in the table would be the correct approach.

[andrewfg]

tightly interlocked vs. fully independent

@jlaur I was thinking about this further overnight...

There are two known types of shade that have two rails: a) top down bottom up, and b) Duolite blackout shades. In neither case are the primary and secondary fully independent. In both cases they are supported as a secondary roller shutter in the UI. But in each case they are differently interlocked. And in each case they are differently encoded in the JSON.

Top Down Bottom Up

• Interlock: top (secondary) rail cannot go below the bottom (primary) rail; and vice-versa
• Encoding: primary encoded in position1/posKind1; secondary encoded in position2/posKind2; (or vice versa)
• UI: both primary and secondary are supported as roller shutter controls

Duolite Blackout

• Interlock: blackout shade (secondary) secondary cant close until front shade (primary) is closed; primary cant open until secondary is open
• Encoding: both primary and secondary encoded in position1/posKind1
• UI: both primary and secondary are supported as roller shutter controls

Now, the actual code of the binding does de-facto exactly as described above. So for me the only questions are..

1. How to better describe the above in your API annexe? In the table? In the words?
2. Do we need a better description in the ReadMe?
3. Shall we refactor the OH code (e.g. method names) -- without changing the functionality -- so that the code "reads" similarly to the descriptions in 1. and 2. above?

[kingy444]

• Interlock: blackout shade (secondary) secondary cant close until front shade (primary) is closed; primary cant open until secondary is open

@andrewfg
Every time I think I understand these ones 🤷‍♂️

I had the inverse in my head - the rear shade couldn’t move until the front was open

but from the quoted I read that now that the rear shade needs to be treated as the priority (not sure you saw my post on other thread about using 1 slider) but would this equate to
posKind2 65k(closed) and 0 on slider (closed position)
PosKind 2 35k being 25% on slider
Poskind2 0 and 50% on slider
Poskind1 also being 50% on slider but 65k
Poskind 1 35k and 75% on slider
Poskind1 being 0 at 100% on the slider (open position)

Do I have that right now ?

[andrewfg]

@kingy444 have a look at the pictures in this post

[jlaur]

@andrewfg - sorry for getting back late. I have not been able to fully catch up and read/understand all what has been posted here and in sander76/aio-powerview-api#16. Maybe I need a simplified version. :-)

We have some concrete shade types involved, having some additional complexity:

• Top Down Bottom Up (two motors)
• Duolite (one motor)

I have seen front panel and back panel mentioned. Not sure exactly what it refers to, just mentioning as part of finding best terminology.

Then we have the current table mentioning primary rail and secondary rail. So far I have understood rail as connected to a motor.

And last blackout shade has been mentioned. Is that the same as back panel?

Also, we might distinguish between physical attributes like number of motors and logical attributes like whether a back/secondary panel or rail (?) exists, whether it is controlled by motor (or rail?) 1 or 2.

The shade type description can contain product names, but probably the attributes should not. So I would refrain from using "Duolite" when describing shade attributes/capabilities.

To simplify the table:

• Would it make sense to merge some columns or would it complicate things? Like: "Primary Rail: Yes/Reversed" (merging Primary Rail and Primary Reversed
• Which terminology makes most sense for the columns current named Primary Rail, Secondary Rail and (in code) Blackout Shade? For me some more understanding would be needed (from questions above).

[andrewfg]

@jlaur some pictures..

---

---

---

---

---

[andrewfg]

refrain from using "Duolite" when describing shade attributes/capabilities.

Ok. The I would suggest to call it 'secondaryOverlapped' (see below..)

Would it make sense to merge some columns or would it complicate things? Like: "Primary Rail: Yes/Reversed" (merging Primary Rail and Primary Reversed

Either way is fine for me.

Which terminology makes most sense for the columns current named Primary Rail, Secondary Rail and (in code) Blackout Shade? For me some more understanding would be needed (from questions above).

• primary = Primary Bottom Up = single motor = posKind1==1
• primaryInverted = Primary Top Down = single motor = posKind1==1
• secondary = Secondary Top Down = requires extra motor in addition to the primary motor = posKind1==1 && posKind2==2
• secondaryOverlapped = Duolite, blackout etc. = does not require extra motor posKind1==1 || posKind1==2

[andrewfg]

Here is the file with my images..

Rail Positions.pptx

[andrewfg]

[jlaur]

New document uploaded with capabilities table updated. @kingy444 - if you still have something to add, feel free to post comments here. I'll close the issue though as specific table change requests should have been done now.

[kingy444]

@andrewfg @jlaur

Little pedantic but im trying to code HA inline with the naming here so OH and HA is similar. This is both the capability info and classes.

Every other class we describe them as 'Bottom up', 'Top Down', 'Tilt Only 180' etc - basically their functionality
But the type 8 and 9 we have named them after the shade type

Could i suggest we change them to 'Dual Shade Interlocked' and 'Dual Shade Interlocked Tilt 90' ?
(no need to do that right now but i would like to agree on something so we can be consistent)

Also we have listed as tiltanywhere - I am still working with someone with type 38 (type 9) but their description would indicate they arent tiltAnywhere or tiltOnClosed
He has described them as back shade opne / front shade fully closed to tilt
Will update once i have some more info (waiting for their response of running some move commands)

[andrewfg]

Dual Shade Interlocked

I would suggest Dual Shade Overlapped .. (but otherwise agreed)

[kingy444]

Dual Shade Interlocked

I would suggest Dual Shade Overlapped

Guess I’ll explain my thinking and see how you feel then

my thinking was more around how they function here and not how they look

the movement is interlocked in that they cannot move independently and require the other to be in a predetermined position before moving

and I guess this goes back to the table too - perhaps overlapped isn’t the right word their either

I see Overlapped as more of a description of how they look than the way they function

ie we refer to Silhoutte as ‘Bottom up tilt 90’ not ‘sheer blind with vanes’

[andrewfg]

Interlocked is not the correct word. TDBU shades are also interlocked. But their rails are in the same plane (not overlapped) so their interlocking is different than for overlapped shades.

[andrewfg]

PS tilt on closed shades are also interlocked..

[kingy444]

This led me to look into some definitions - looks like interlocked is related to overlapping as well

With your comments re other shades having interlocking relationship what about dropping the second word all together

Dual Shade
Dual Shade Tilt 90

side note: looks like the guy flicked you the details for the palm beach shutters on HA forum - could you PM them to me too. Annoyingly hasn’t sent them on yet - not sure why he didn’t just post on the forum

[andrewfg]

I'm on the road today and tomorrow, but will forward the pms when I am back. There is a lot of stuff so I need to sort it out first.

[kingy444]

No worries - im happy for it in raw format and i can try and digest if that makes it easier.