Window Covering

A HomeKit Window Covering service.

Type	Service 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 service
Digital Inputs	"b"	GPIOs that invoke specific actions
Service Notifications	"m"	Notifications to send to another service
Initial Lock State	"ks"	Lock state at boot
State & Status Inputs	"f[n]" & "g[n]"	Inputs that manage service state
Actions on Boot	"xa"	Enable / Disable execution of service actions on boot
Wildcard Actions	"y[n]"	Perform an action when a service reaches a target value
Covering Type	"w"	Type of covering
Opening Time	"o"	Time for service to completely open
Closing Time	"c"	Time for service to completely close
Correction Value	"f"	Non-linear correction value for
Margin	"m"	Percentage margin to sync cover when fully open / close
Virtual Stop	"vs"	Simulates stop function from Home App
Historical Data Characteristics

Window Covering Example

{
  "c": { "l": 0, "b": [{ "g": 2, "p": 0, "t": 5 }], "0": { "r": [{ "g": 15 }, { "g": 16 }] } },
  "a": [{
    "t": 45,
    "o": 18,
    "c": 14,
    "f": 70,
    "cd": 2,
    "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 service 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 service object.

Key	Value	Description
"o"	15	*Service opening time (default)*
	float	Value specifying number of seconds

This option specifies the time the service takes to open completely. Decimals can be used.

Closing Time

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

Key	Value	Description
"c"	15	*Service closing time (default)*
	float	Value specifying number of seconds

This option specifies the time the service takes to close completely. Decimals can be used.

Correction Value

Correction value is defined by the "f" key contained within the service 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 service 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 service object.

Key	Value	Description
"m"	15	*Percentage margin (default)*
	0 - 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 service 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.

Virtual Stop

When enabled, it simulates stop function from Home App when window covering is moving and service is triggered again from Apple Home App, instead changing movement direction.

Key	Value	Description
"vs"	0	*Virtual Stop disabled (default)*
	1	Virtual Stop enabled

Service 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 Service Notifications section for details of how to configure these notifications.

Digital Inputs

Digital Inputs "b" are supported by this service.

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 service. 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