A HomeKit Window Covering service.

Window Covering was introduced in firmware version 0.9.0

The following configuration is available for window coverings:

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

The above example defines a Shelly 2.5 Window Covering driver with external switches and a status LED "c": { "l": 0, "b": [ [2,5] ] }. 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.

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

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

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

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

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

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

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

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

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

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

This option specifies the additional working time when a cover is set to fully open or fully closed to recalibrate its position. For example, if opening working time is 18 seconds, and margin is 10% (meaning 10% of 18s = 1.8s), when cover is set to fully open, stop action will exec after 1.8s cover is fully open to ensure that it is at target position. It is an integer (no decimals) specifying the percentage.

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.

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

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

Binary Inputs "b" are supported by this service.

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

State inputs "f[n]" are supported by this service. The supported list is:

Refer to State Inputs for more detail and examples.

The Initial Lock State about Service and Physical controls.

Actions on Boot "xa" are supported by this service.

See Execution of Actions on Boot for details on how to define this mandatory option.

Wildcard Actions "y[n]" are supported by this service. The supported list is:

The position of the window covering is expressed as a percentage e.g. {"y0":[{"v": 20, "0"{...}}]}

Refer to Wildcard Actions for more detail.