Window Covering

A HomeKit Window Covering accessory.

Type	Device Type
45	Window Covering

Window Covering was introduced in firmware version 0.9.0

The following configuration is available for window coverings:

Section	Key	Description
Actions	"0", "1" etc.	The actions performed by the accessory
Digital Inputs	"b"	GPIOs that invoke specific actions
Accessory Notifications	"m"	Notifications to send to another accessory
State & Status Inputs	"f[n]" & "g[n]"	Inputs that manage accessory state
Actions on Boot	"xa"	Enable / Disable execution of accessory actions on boot
Wildcard Actions	"y[n]"	Perform an action when an accessory reaches a target value
Covering Type	"w"	Type of covering
Opening Time	"o"	Time for accessory to completely open
Closing Time	"c"	Time for accessory to completely close
Correction Value	"f"	Non-linear correction value for
Margin	"m"	Percentage margin to sync cover when fully open / close

Window Covering Example

{
  "c": { "l": 0, "b": [{ "g": 2, "p": 0, "t": 5 }], "0": { "r": [{ "g": 16 }] } },
  "a": [{
    "t": 45,
    "o": 18,
    "c": 14,
    "f": 70,
    "0": { "r": [{ "g": 15, "v": 1 }, { "g": 4 }] },
    "1": { "r": [{ "g": 15 }, { "g": 4, "v": 1 }] },
    "2": { "r": [{ "g": 15 }, { "g": 4 }] },
    "3": { "r": [{ "g": 15, "i": 0.2 }, { "g": 4 }] },
    "4": { "r": [{ "g": 15 }, { "g": 4, "i": 0.2 }] },
    "f0": [{ "g": 5, "i": 1, "p": 0, "t":0 }],
    "f1": [{ "g": 13, "i": 1, "p": 0, "t":0 }],
    "f2": [{ "g": 5 }, { "g": 13 }]
  }]
}

The above example defines a Shelly 2.5 Window Covering driver with external switches and a status LED "c": { "l": 0, "b": [{ "g": 2, "p": 0, "t": 5 }], "0": { "r": [{ "g": 16 }] } }. The opening time is defined as 18 seconds "o": 18. The closing time is defined as 14 seconds "c": 14. A non-linear correction of 70% has also been set "f": 70.

Actions

A window covering has a number of actions as documented below:

Key	Action	Description
"0"	Close, from stop	Close the window covering from the stopped state
"1"	Open, from stop	Open the window covering from the stopped state
"2"	Stop	Stop the window covering opening or closing
"3"	Close, from opening	Action a close while window covering is opening
"4"	Open, from closing	Action an open while window covering is closing
"5"	Stop, from closing	Stop the window covering while it is closing
"6"	Stop, from opening	Stop the window covering while it is opening
"7"	Obstruction removed
"8"	Obstruction detected

The Digital Outputs "r": [{}] for each should be configured to attain the desired state.

Covering Type

The covering type is defined by the "w" key contained within the accessory object.

Key	Value	Description
"w"	0	*Window covering (default)* e.g. a roller blind
	1	Window e.g. a motorized window
	2	Door e.g. a motorized door

This option specifies the type of covering. Refer to the HomeKit specifications to see details on the differences between these device types.

Opening Time

Opening time is defined by the "o" key contained within the accessory object.

Key	Value	Description
"o"	15	*Accessory opening time (default)*
	1 - 65535	Integer value specifying number of seconds

This option specifies the time the accessory takes to open completely. It is an integer (no decimals).

Closing Time

Closing time is defined by the "c" key contained within the accessory object.

Key	Value	Description
"c"	15	*Accessory closing time (default)*
	1 - 65535	Integer value specifying number of seconds

This option specifies the time the accessory takes to close completely. It is an integer (no decimals).

Correction Value

Correction value is defined by the "f" key contained within the accessory object.

Key	Value	Description
"f"	0	Non-linear correction value (_default)
	0 - 100	Percentage value

Some window coverings may require a correction factor to determine their real position with respect to open or closing state. This may be due to the it being a roller shutter for instance. Where the amount the covering opens accelerates as it opens due to the drum of the shutter.

You can modify how the position of the shutter is calculated by providing a non-linear correction value.

When a correction value is provided the position of the accessory is calculated as follows:

HomeKit Position = motorPosition / (1 + ((100 - motorPosition) * correctionValue * 0.0002))

This option specifies a percentage. It is an integer between 0 and 100.

Margin

Margin is defined by the "m" key contained within the accessory object.

Key	Value	Description
"m"	15	*Percentage margin (default)*
	1 - 100	Integer value specifying percentage

This option specifies the margin used to determine whether a cover is fully open or fully closed e.g. setting the margin to 10 results in the accessory stopping when it is closed 90% or more or when it is open 10% or less. It is an integer (no decimals) specifying the percentage.

Accessory Notifications

The list of notifications "m" supported by a window covering are as follows:

Value	Notification
-2	Obstruction removed
-1	Obstruction detected
0 - 100	Set window covering to specified open percentage
101	It will stop the window covering opening or closing

See the general Accessory Notifications section for details of how to configure these notifications.

Digital Inputs

Digital Inputs "b" are supported by this accessory.

See Digital Inputs for details on how to define this mandatory option.

State and Status Inputs

State inputs "f[n]" & Status Inputs "g[n]" are supported by this accessory. The supported list is:

Key	Required State
"f0"	Close window covering
"f1"	Open window covering
"f2"	Stop window covering opening or closing
"f3"	Toggle between closing and stop
"f4"	Toggle between opening and stop
"f5"	Indicates that there is no obstruction
"f6"	Indicates that there is an obstruction