MatterWindowCovering

#################### MatterWindowCovering ####################

About

The MatterWindowCovering class provides a window covering endpoint for Matter networks. This endpoint implements the Matter window covering standard for motorized blinds, shades, and other window coverings with lift and tilt control.

Features:

• Lift position and percentage control (0-100%, Matter: 0 = open, 100 = closed)
• Lift and tilt percent100ths control (0-10000, direct Matter attribute mapping)
• Local motor calibration for physical-unit to percentage conversion
• Multiple window covering types support
• Callback support for open, close, lift, tilt, and stop commands
• Integration with Apple HomeKit, Amazon Alexa, and Google Home
• Matter standard compliance

Supported Window Covering Types:

• ROLLERSHADE - Lift support
• ROLLERSHADE_2_MOTOR - Lift support
• ROLLERSHADE_EXTERIOR - Lift support
• ROLLERSHADE_EXTERIOR_2_MOTOR - Lift support
• DRAPERY - Lift support
• AWNING - Lift support
• SHUTTER - Tilt support
• BLIND_TILT_ONLY - Tilt support
• BLIND_LIFT_AND_TILT - Lift and Tilt support
• PROJECTOR_SCREEN - Lift support

Use Cases:

• Motorized blinds
• Automated shades
• Smart window coverings
• Projector screens
• Awnings and drapes

API Reference

Constructor

MatterWindowCovering ^^^^^^^^^^^^^^^^^^^^

Creates a new Matter window covering endpoint.

.. code-block:: arduino

MatterWindowCovering();

Initialization

begin ^^^^^

Initializes the Matter window covering endpoint with optional initial positions, covering type, and local motor calibration.

.. code-block:: arduino

bool begin(
  uint8_t liftPercent = 0,
  uint8_t tiltPercent = 0,
  WindowCoveringType_t coveringType = ROLLERSHADE,
  const PositionCalibration *liftCalibration = nullptr,
  const PositionCalibration *tiltCalibration = nullptr
);

• liftPercent - Initial lift percentage (0-100, default: 0 = fully open)
• tiltPercent - Initial tilt percentage (0-100, default: 0 = fully open)
• coveringType - Window covering type (default: ROLLERSHADE). This determines which features (lift, tilt, or both) are enabled.
• liftCalibration - Optional local motor range for lift (open/closed physical units). Not exposed as a Matter attribute in ESP-Matter 1.5.
• tiltCalibration - Optional local motor range for tilt. Not exposed as a Matter attribute in ESP-Matter 1.5.

This function will return true if successful, false otherwise.

Note: Matter percentage semantics apply throughout this API: 0 = fully open, 100 = fully closed. The covering type must be specified during initialization to ensure the correct features (lift and/or tilt) are enabled.

PositionCalibration ^^^^^^^^^^^^^^^^^^^

Local motor range used to convert between physical motor units and Matter percentages. This is stored in firmware only and is not published as a Matter cluster attribute in ESP-Matter 1.5.

.. code-block:: arduino

struct PositionCalibration {
  uint16_t open = 0;
  uint16_t closed = 65534;
};

end ^^^

Stops processing Matter window covering events.

.. code-block:: arduino

void end();

Lift Position Control

setLiftPosition ^^^^^^^^^^^^^^^

Sets the window covering lift position in local motor units. Converts to Matter percent100ths using the local motor calibration range.

.. code-block:: arduino

bool setLiftPosition(uint16_t liftPosition);

• liftPosition - Lift position in local motor units (e.g. centimeters)

This function will return true if successful, false otherwise.

getLiftPosition ^^^^^^^^^^^^^^^

Gets the current lift position.

.. code-block:: arduino

uint16_t getLiftPosition();

This function will return the current lift position.

setLiftPercentage ^^^^^^^^^^^^^^^^^

Sets the window covering lift position as a percentage. This method updates the CurrentPositionLiftPercent100ths attribute, which reflects the device's actual position. The TargetPositionLiftPercent100ths attribute is set by Matter commands/apps when a new target is requested.

.. code-block:: arduino

bool setLiftPercentage(uint8_t liftPercent);

• liftPercent - Lift percentage (0-100, where 0 is fully open, 100 is fully closed)

This function will return true if successful, false otherwise.

Note: When the device reaches the target position, call setOperationalState(LIFT, STALL) to indicate that movement is complete. Prefer setCurrentLiftPercent100ths() when sub-percent precision is needed.

getLiftPercentage ^^^^^^^^^^^^^^^^^

Gets the current lift percentage.

.. code-block:: arduino

uint8_t getLiftPercentage();

This function will return the current lift percentage (0-100, Matter semantics).

setCurrentLiftPercent100ths ^^^^^^^^^^^^^^^^^^^^^^^^^^^

Sets the current lift position using Matter percent100ths (0-10000). This is the primary API for reporting actual position to commissioners.

.. code-block:: arduino

bool setCurrentLiftPercent100ths(uint16_t liftPercent100ths);

• liftPercent100ths - Current lift position (0 = open, 10000 = closed)

getCurrentLiftPercent100ths ^^^^^^^^^^^^^^^^^^^^^^^^^^^

Gets the current lift position in percent100ths.

.. code-block:: arduino

uint16_t getCurrentLiftPercent100ths();

Tilt Position Control

setTiltPosition ^^^^^^^^^^^^^^^

Sets the window covering tilt position. Note that tilt is a rotation, not a linear measurement. This method converts the absolute position to percentage using the installed limits.

.. code-block:: arduino

bool setTiltPosition(uint16_t tiltPosition);

• tiltPosition - Tilt position value (absolute value for conversion, not a physical unit)

This function will return true if successful, false otherwise.

getTiltPosition ^^^^^^^^^^^^^^^

Gets the current tilt position. Note that tilt is a rotation, not a linear measurement.

.. code-block:: arduino

uint16_t getTiltPosition();

This function will return the current tilt position (absolute value for conversion, not a physical unit).

setTiltPercentage ^^^^^^^^^^^^^^^^^

Sets the window covering tilt position as a percentage. This method updates the CurrentPositionTiltPercent100ths attribute, which reflects the device's actual position. The TargetPositionTiltPercent100ths attribute is set by Matter commands/apps when a new target is requested.

.. code-block:: arduino

bool setTiltPercentage(uint8_t tiltPercent);

• tiltPercent - Tilt percentage (0-100, where 0 is fully open, 100 is fully closed)

This function will return true if successful, false otherwise.

Note: When the device reaches the target position, call setOperationalState(TILT, STALL) to indicate that movement is complete. Prefer setCurrentTiltPercent100ths() when sub-percent precision is needed.

getTiltPercentage ^^^^^^^^^^^^^^^^^

Gets the current tilt percentage.

.. code-block:: arduino

uint8_t getTiltPercentage();

This function will return the current tilt percentage (0-100, Matter semantics).

setCurrentTiltPercent100ths ^^^^^^^^^^^^^^^^^^^^^^^^^^^

Sets the current tilt position using Matter percent100ths (0-10000).

.. code-block:: arduino

bool setCurrentTiltPercent100ths(uint16_t tiltPercent100ths);

getCurrentTiltPercent100ths ^^^^^^^^^^^^^^^^^^^^^^^^^^^

Gets the current tilt position in percent100ths.

.. code-block:: arduino

uint16_t getCurrentTiltPercent100ths();

Window Covering Type

setCoveringType ^^^^^^^^^^^^^^^

Sets the window covering type.

.. code-block:: arduino

bool setCoveringType(WindowCoveringType_t coveringType);

• coveringType - Window covering type (see Window Covering Types enum)

This function will return true if successful, false otherwise.

getCoveringType ^^^^^^^^^^^^^^^

Gets the current window covering type.

.. code-block:: arduino

WindowCoveringType_t getCoveringType();

This function will return the current window covering type.

Installed Limit Control

These methods configure local motor calibration for converting between physical motor units and Matter percentages. They are not exposed as Matter cluster attributes in ESP-Matter 1.5. Prefer setLiftCalibration() / setTiltCalibration() or pass PositionCalibration to begin().

setLiftCalibration ^^^^^^^^^^^^^^^^^^

Sets the local lift motor calibration range.

.. code-block:: arduino

bool setLiftCalibration(const PositionCalibration &calibration);

getLiftCalibration ^^^^^^^^^^^^^^^^^^

Gets the local lift motor calibration range.

.. code-block:: arduino

PositionCalibration getLiftCalibration();

setTiltCalibration ^^^^^^^^^^^^^^^^^^

Sets the local tilt motor calibration range.

.. code-block:: arduino

bool setTiltCalibration(const PositionCalibration &calibration);

getTiltCalibration ^^^^^^^^^^^^^^^^^^

Gets the local tilt motor calibration range.

.. code-block:: arduino

PositionCalibration getTiltCalibration();

setInstalledOpenLimitLift ^^^^^^^^^^^^^^^^^^^^^^^^^

Sets the local open limit for lift motor calibration (physical units when fully open).

.. code-block:: arduino

bool setInstalledOpenLimitLift(uint16_t openLimit);

• openLimit - Open limit position in your motor units (e.g. centimeters)

This function will return true if successful, false otherwise.

getInstalledOpenLimitLift ^^^^^^^^^^^^^^^^^^^^^^^^^^

Gets the local open limit for lift motor calibration.

.. code-block:: arduino

uint16_t getInstalledOpenLimitLift();

This function will return the open limit for lift motor calibration.

setInstalledClosedLimitLift ^^^^^^^^^^^^^^^^^^^^^^^^^^^

Sets the local closed limit for lift motor calibration (physical units when fully closed).

.. code-block:: arduino

bool setInstalledClosedLimitLift(uint16_t closedLimit);

• closedLimit - Closed limit position in your motor units (e.g. centimeters)

This function will return true if successful, false otherwise.

getInstalledClosedLimitLift ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Gets the local closed limit for lift motor calibration.

.. code-block:: arduino

uint16_t getInstalledClosedLimitLift();

This function will return the closed limit for lift motor calibration.

setInstalledOpenLimitTilt ^^^^^^^^^^^^^^^^^^^^^^^^^

Sets the local open limit for tilt motor calibration.

.. code-block:: arduino

bool setInstalledOpenLimitTilt(uint16_t openLimit);

• openLimit - Open limit value for tilt conversion

This function will return true if successful, false otherwise.

Note: Tilt is a rotation, not a linear measurement. These limits are used for local position conversion only.

getInstalledOpenLimitTilt ^^^^^^^^^^^^^^^^^^^^^^^^^^

Gets the local open limit for tilt motor calibration.

.. code-block:: arduino

uint16_t getInstalledOpenLimitTilt();

This function will return the open limit for tilt motor calibration.

setInstalledClosedLimitTilt ^^^^^^^^^^^^^^^^^^^^^^^^^^^

Sets the local closed limit for tilt motor calibration.

.. code-block:: arduino

bool setInstalledClosedLimitTilt(uint16_t closedLimit);

• closedLimit - Closed limit value for tilt conversion

This function will return true if successful, false otherwise.

Note: Tilt is a rotation, not a linear measurement. These limits are used for local position conversion only.

getInstalledClosedLimitTilt ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Gets the local closed limit for tilt motor calibration.

.. code-block:: arduino

uint16_t getInstalledClosedLimitTilt();

This function will return the closed limit for tilt motor calibration.

Target Position Control

setTargetLiftPercent100ths ^^^^^^^^^^^^^^^^^^^^^^^^^^

Sets the target lift position in percent100ths (0-10000, where 0 is fully open, 10000 is fully closed).

.. code-block:: arduino

bool setTargetLiftPercent100ths(uint16_t liftPercent100ths);

• liftPercent100ths - Target lift position in percent100ths (0-10000)

This function will return true if successful, false otherwise.

Note: This sets the target position that the device should move towards. The actual position should be updated using setLiftPercentage().

getTargetLiftPercent100ths ^^^^^^^^^^^^^^^^^^^^^^^^^^

Gets the current target lift position in percent100ths.

.. code-block:: arduino

uint16_t getTargetLiftPercent100ths();

This function will return the current target lift position in percent100ths (0-10000).

setTargetTiltPercent100ths ^^^^^^^^^^^^^^^^^^^^^^^^^^^

Sets the target tilt position in percent100ths (0-10000, where 0 is fully open, 10000 is fully closed).

.. code-block:: arduino

bool setTargetTiltPercent100ths(uint16_t tiltPercent100ths);

• tiltPercent100ths - Target tilt position in percent100ths (0-10000)

This function will return true if successful, false otherwise.

Note: This sets the target position that the device should move towards. The actual position should be updated using setTiltPercentage().

getTargetTiltPercent100ths ^^^^^^^^^^^^^^^^^^^^^^^^^^

Gets the current target tilt position in percent100ths.

.. code-block:: arduino

uint16_t getTargetTiltPercent100ths();

This function will return the current target tilt position in percent100ths (0-10000).

Operational Status Control

setOperationalStatus ^^^^^^^^^^^^^^^^^^^^

Sets the full operational status bitmap.

.. code-block:: arduino

bool setOperationalStatus(uint8_t operationalStatus);

• operationalStatus - Full operational status bitmap value

This function will return true if successful, false otherwise.

Note: It is recommended to use setOperationalState() to set individual field states instead of setting the full bitmap directly.

getOperationalStatus ^^^^^^^^^^^^^^^^^^^^

Gets the full operational status bitmap.

.. code-block:: arduino

uint8_t getOperationalStatus();

This function will return the current operational status bitmap value.

setOperationalState ^^^^^^^^^^^^^^^^^^^

Sets the operational state for a specific field (LIFT or TILT). The GLOBAL field is automatically updated based on priority (LIFT > TILT).

.. code-block:: arduino

bool setOperationalState(OperationalStatusField_t field, OperationalState_t state);

• field - Field to set (LIFT or TILT). GLOBAL cannot be set directly.
• state - Operational state (STALL, MOVING_UP_OR_OPEN, or MOVING_DOWN_OR_CLOSE)

This function will return true if successful, false otherwise.

Note: Only LIFT and TILT fields can be set directly. The GLOBAL field is automatically updated based on the active field (LIFT has priority over TILT).

getOperationalState ^^^^^^^^^^^^^^^^^^^

Gets the operational state for a specific field.

.. code-block:: arduino

OperationalState_t getOperationalState(OperationalStatusField_t field);

• field - Field to get (GLOBAL, LIFT, or TILT)

This function will return the operational state for the specified field (STALL, MOVING_UP_OR_OPEN, or MOVING_DOWN_OR_CLOSE).

Event Handling

The MatterWindowCovering class automatically detects Matter commands and calls the appropriate callbacks when registered. There are two types of callbacks:

Target Position Callbacks (triggered when TargetPosition attributes change):

• onOpen() - called when UpOrOpen command is received (sets target to 0% = fully open)
• onClose() - called when DownOrClose command is received (sets target to 100% = fully closed)
• onStop() - called when StopMotion command is received (sets target to current position)
• onGoToLiftPercentage() - called when TargetPositionLiftPercent100ths changes (from any command, setTargetLiftPercent100ths(), or direct attribute write)
• onGoToTiltPercentage() - called when TargetPositionTiltPercent100ths changes (from any command, setTargetTiltPercent100ths(), or direct attribute write)

Current Position Callback (triggered when CurrentPosition attributes change):

• onChange() - called when CurrentPositionLiftPercent100ths or CurrentPositionTiltPercent100ths change (after setLiftPercentage()/setTiltPercentage() are called or when a Matter controller updates these attributes directly)

Important: onChange() is not automatically called when Matter commands are executed. Commands modify TargetPosition, not CurrentPosition. To trigger onChange(), your onGoToLiftPercentage() or onGoToTiltPercentage() callback must call setLiftPercentage() or setTiltPercentage() when the physical device actually moves.

Note: All callbacks are optional. If a specific callback is not registered, only the generic onGoToLiftPercentage() or onGoToTiltPercentage() callbacks will be called (if registered).

onOpen ^^^^^^

Sets a callback function to be called when the UpOrOpen command is received from a Matter controller. This command sets the target position to 0% (fully open).

.. code-block:: arduino

void onOpen(EndPointOpenCB onChangeCB);

• onChangeCB - Function to call when UpOrOpen command is received

The callback signature is:

.. code-block:: arduino

bool onChangeCallback();

onClose ^^^^^^^

Sets a callback function to be called when the DownOrClose command is received from a Matter controller. This command sets the target position to 100% (fully closed).

.. code-block:: arduino

void onClose(EndPointCloseCB onChangeCB);

• onChangeCB - Function to call when DownOrClose command is received

The callback signature is:

.. code-block:: arduino

bool onChangeCallback();

onGoToLiftPercentage ^^^^^^^^^^^^^^^^^^^^

Sets a callback function to be called when TargetPositionLiftPercent100ths changes. This is triggered by:

• Matter commands: UpOrOpen, DownOrClose, StopMotion, GoToLiftPercentage
• Calling setTargetLiftPercent100ths()
• Direct attribute writes to TargetPositionLiftPercent100ths

This callback is always called when the target lift position changes, regardless of which command or method was used to change it.

Note: This callback receives the target position. To update the current position (which triggers onChange()), call setLiftPercentage() when the physical device actually moves.

.. code-block:: arduino

void onGoToLiftPercentage(EndPointLiftCB onChangeCB);

• onChangeCB - Function to call when target lift percentage changes

The callback signature is:

.. code-block:: arduino

bool onChangeCallback(uint8_t liftPercent);

• liftPercent - Target lift percentage (0-100, where 0 is fully open, 100 is fully closed)

onGoToTiltPercentage ^^^^^^^^^^^^^^^^^^^^

Sets a callback function to be called when TargetPositionTiltPercent100ths changes. This is triggered by:

• Matter commands: UpOrOpen, DownOrClose, StopMotion, GoToTiltPercentage
• Calling setTargetTiltPercent100ths()
• Direct attribute writes to TargetPositionTiltPercent100ths

This callback is always called when the target tilt position changes, regardless of which command or method was used to change it.

Note: This callback receives the target position. To update the current position (which triggers onChange()), call setTiltPercentage() when the physical device actually moves.

.. code-block:: arduino

void onGoToTiltPercentage(EndPointTiltCB onChangeCB);

• onChangeCB - Function to call when target tilt percentage changes

The callback signature is:

.. code-block:: arduino

bool onChangeCallback(uint8_t tiltPercent);

• tiltPercent - Target tilt percentage (0-100, where 0 is fully open, 100 is fully closed)

onStop ^^^^^^

Sets a callback function to be called when the StopMotion command is received from a Matter controller. This command sets the target position to the current position, effectively stopping any movement.

.. code-block:: arduino

void onStop(EndPointStopCB onChangeCB);

• onChangeCB - Function to call when StopMotion command is received

The callback signature is:

.. code-block:: arduino

bool onChangeCallback();

onChange ^^^^^^^^

Sets a callback function to be called when CurrentPositionLiftPercent100ths or CurrentPositionTiltPercent100ths attributes change. This is different from onGoToLiftPercentage() and onGoToTiltPercentage(), which are called when TargetPosition attributes change.

When onChange() is called:

• When CurrentPositionLiftPercent100ths changes (after setLiftPercentage() is called or when a Matter controller updates this attribute directly)
• When CurrentPositionTiltPercent100ths changes (after setTiltPercentage() is called or when a Matter controller updates this attribute directly)

Important: onChange() is not automatically called when Matter commands are executed. Commands modify TargetPosition attributes, which trigger onGoToLiftPercentage() or onGoToTiltPercentage() callbacks instead. To trigger onChange() after a command, your onGoToLiftPercentage() or onGoToTiltPercentage() callback must call setLiftPercentage() or setTiltPercentage() to update the CurrentPosition attributes when the physical device actually moves.

.. code-block:: arduino

void onChange(EndPointCB onChangeCB);

• onChangeCB - Function to call when current position attributes change

The callback signature is:

.. code-block:: arduino

bool onChangeCallback(uint8_t liftPercent, uint8_t tiltPercent);

• liftPercent - Current lift percentage (0-100)
• tiltPercent - Current tilt percentage (0-100)

updateAccessory ^^^^^^^^^^^^^^^

Updates the state of the window covering using the current Matter internal state.

.. code-block:: arduino

void updateAccessory();

This function will call the registered callback with the current state.

Example

Window Covering

.. literalinclude:: ../../../libraries/Matter/examples/MatterWindowCovering/MatterWindowCovering.ino :language: arduino