You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat(matter_docs): Enhance README with callback usage details
Clarify the importance of calling setLiftPercentage() and setTiltPercentage() in callbacks to update CurrentPosition attributes. Expand on callback flow and provide details on target position callbacks.
Copy file name to clipboardExpand all lines: libraries/Matter/examples/MatterWindowCovering/README.md
+19-7Lines changed: 19 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -148,9 +148,14 @@ For production use with a motorized window covering:
148
148
- Use encoders or limit switches to provide position feedback
149
149
- For lift: Update `currentLift` (cm) based on actual motor position
150
150
- For tilt: Update `currentTiltPercent` (rotation percentage) based on actual motor rotation
151
-
- Call `setLiftPercentage()` and `setTiltPercentage()`to update `CurrentPosition` attributes (these methods update the device's actual position, not the target)
151
+
-**Important**: Call `setLiftPercentage()` and `setTiltPercentage()`in your `onGoToLiftPercentage()` or `onGoToTiltPercentage()` callbacks to update `CurrentPosition` attributes when the physical device actually moves. This will trigger the `onChange()` callback if registered.
152
152
- Call `setOperationalState(LIFT, STALL)` or `setOperationalState(TILT, STALL)` when movement is complete to indicate the device has reached the target position
153
153
- Configure installed limits using `setInstalledOpenLimitLift()`, `setInstalledClosedLimitLift()`, `setInstalledOpenLimitTilt()`, and `setInstalledClosedLimitTilt()` to define the physical range of your window covering
154
+
155
+
**Callback Flow:**
156
+
- Matter command → `TargetPosition` changes → `onGoToLiftPercentage()`/`onGoToTiltPercentage()` called
157
+
- Your callback moves the motor → When movement completes, call `setLiftPercentage()`/`setTiltPercentage()`
158
+
-`setLiftPercentage()`/`setTiltPercentage()` update `CurrentPosition` → `onChange()` called (if registered)
154
159
155
160
3.**Window Covering Type**:
156
161
- Pass the covering type to `begin()` to configure the appropriate type (e.g., `BLIND_LIFT_AND_TILT`, `ROLLERSHADE`, etc.)
@@ -198,12 +203,18 @@ The MatterWindowCovering example consists of the following main components:
198
203
2.**`loop()`**: Checks the Matter commissioning state, handles button input for manual lift control and factory reset, and allows the Matter stack to process events.
199
204
200
205
3.**Callbacks**:
201
-
-`fullOpen()`: Handles open command - moves window covering to fully open (100% lift), updates `CurrentPosition`, and sets operational state to `STALL`
202
-
-`fullClose()`: Handles close command - moves window covering to fully closed (0% lift), updates `CurrentPosition`, and sets operational state to `STALL`
203
-
-`goToLiftPercentage()`: Handles lift percentage changes (0-100%), calculates absolute position (cm) based on installed limits, updates `CurrentPosition`, and sets operational state to `STALL` when movement is complete
204
-
-`goToTiltPercentage()`: Handles tilt rotation percentage changes (0-100%), updates `CurrentPosition`, and sets operational state to `STALL` when movement is complete
205
-
-`stopMotor()`: Handles stop command - stops any ongoing movement, updates `CurrentPosition` for both lift and tilt, and sets operational state to `STALL` for both
206
-
-`visualizeWindowBlinds()`: Updates RGB LED to reflect current lift and tilt positions
206
+
207
+
**Target Position Callbacks** (called when `TargetPosition` attributes change):
208
+
-`fullOpen()`: Registered with `onOpen()` - called when `UpOrOpen` command is received. Moves window covering to fully open (100% lift), calls `setLiftPercentage()` to update `CurrentPosition`, and sets operational state to `STALL`
209
+
-`fullClose()`: Registered with `onClose()` - called when `DownOrClose` command is received. Moves window covering to fully closed (0% lift), calls `setLiftPercentage()` to update `CurrentPosition`, and sets operational state to `STALL`
210
+
-`goToLiftPercentage()`: Registered with `onGoToLiftPercentage()` - called when `TargetPositionLiftPercent100ths` changes (from commands, `setTargetLiftPercent100ths()`, or direct attribute writes). Calculates absolute position (cm) based on installed limits, calls `setLiftPercentage()` to update `CurrentPosition`, and sets operational state to `STALL` when movement is complete
211
+
-`goToTiltPercentage()`: Registered with `onGoToTiltPercentage()` - called when `TargetPositionTiltPercent100ths` changes. Calls `setTiltPercentage()` to update `CurrentPosition`, and sets operational state to `STALL` when movement is complete
212
+
-`stopMotor()`: Registered with `onStop()` - called when `StopMotion` command is received. Stops any ongoing movement, calls `setLiftPercentage()` and `setTiltPercentage()` to update `CurrentPosition` for both, and sets operational state to `STALL` for both
213
+
214
+
**Current Position Callback** (called when `CurrentPosition` attributes change):
215
+
-`onChange()`: Registered with `onChange()` - called when `CurrentPositionLiftPercent100ths` or `CurrentPositionTiltPercent100ths` change (after `setLiftPercentage()` or `setTiltPercentage()` are called). Updates RGB LED visualization to reflect current positions
216
+
217
+
**Note:** The Target Position callbacks (`fullOpen()`, `fullClose()`, `goToLiftPercentage()`, `goToTiltPercentage()`, `stopMotor()`) call `setLiftPercentage()` or `setTiltPercentage()` to update the `CurrentPosition` attributes. This triggers the `onChange()` callback, which updates the visualization.
207
218
208
219
## Troubleshooting
209
220
@@ -225,3 +236,4 @@ The MatterWindowCovering example consists of the following main components:
225
236
## License
226
237
227
238
This example is licensed under the Apache License, Version 2.0.
0 commit comments