Skip to content

Commit 3c587c0

Browse files
authored
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.
1 parent af00cc7 commit 3c587c0

File tree

1 file changed

+19
-7
lines changed
  • libraries/Matter/examples/MatterWindowCovering

1 file changed

+19
-7
lines changed

libraries/Matter/examples/MatterWindowCovering/README.md

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -148,9 +148,14 @@ For production use with a motorized window covering:
148148
- Use encoders or limit switches to provide position feedback
149149
- For lift: Update `currentLift` (cm) based on actual motor position
150150
- 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.
152152
- Call `setOperationalState(LIFT, STALL)` or `setOperationalState(TILT, STALL)` when movement is complete to indicate the device has reached the target position
153153
- 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)
154159

155160
3. **Window Covering Type**:
156161
- 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:
198203
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.
199204

200205
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.
207218

208219
## Troubleshooting
209220

@@ -225,3 +236,4 @@ The MatterWindowCovering example consists of the following main components:
225236
## License
226237

227238
This example is licensed under the Apache License, Version 2.0.
239+

0 commit comments

Comments
 (0)