Skip to content

Commit db0bbad

Browse files
hennikulP-R-O-C-H-Ypre-commit-ci-lite[bot]
authored
Created Zigbee Endpoint for Window Covering. (#10914)
* feat(zigbee): Added Endpoint for Window Covering (#10913) * Added example Sketch. * Added window covering to CMakeLists.txt. * feat(zigbee): Window covering tilt support and fixes * fix(zigbee): Fix typos * ci(pre-commit): Apply automatic fixes * fix(ci): Fixes of typos --------- Co-authored-by: Jan Procházka <[email protected]> Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
1 parent 6a11276 commit db0bbad

File tree

9 files changed

+757
-1
lines changed

9 files changed

+757
-1
lines changed

‎CMakeLists.txt

+1
Original file line numberDiff line numberDiff line change
@@ -292,6 +292,7 @@ set(ARDUINO_LIBRARY_Zigbee_SRCS
292292
libraries/Zigbee/src/ep/ZigbeeCarbonDioxideSensor.cpp
293293
libraries/Zigbee/src/ep/ZigbeeContactSwitch.cpp
294294
libraries/Zigbee/src/ep/ZigbeeDoorWindowHandle.cpp
295+
libraries/Zigbee/src/ep/ZigbeeWindowCovering.cpp
295296
)
296297

297298
set(ARDUINO_LIBRARY_BLE_SRCS

‎libraries/Zigbee/examples/Zigbee_Window_Covering/README.md

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Arduino-ESP32 Window Covering Example
2+
3+
This example shows how to configure the Zigbee end device and use it as a Home Automation (HA) window covering device.
4+
5+
To see if the communication with your Zigbee network works, use the Serial monitor and watch for output there.
6+
7+
# Supported Targets
8+
9+
Currently, this example supports the following targets.
10+
11+
| Supported Targets | ESP32-C6 | ESP32-H2 |
12+
| ----------------- | -------- | -------- |
13+
14+
## Hardware Required
15+
16+
* A USB cable for power supply and programming
17+
* Board (ESP32-H2 or ESP32-C6) as Zigbee end device and upload the Zigbee_Window_Covering example
18+
* Zigbee network / coordinator (Other board with switch examples or Zigbee2mqtt or ZigbeeHomeAssistant like application)
19+
20+
### Configure the Project
21+
22+
#### Using Arduino IDE
23+
24+
To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits).
25+
26+
* Before Compile/Verify, select the correct board: `Tools -> Board`.
27+
* Select the End device Zigbee mode: `Tools -> Zigbee mode: Zigbee ED (end device)`
28+
* Select Tools / USB CDC On Boot: "Enabled"
29+
* Select Partition Scheme for Zigbee: `Tools -> Partition Scheme: Zigbee 4MB with spiffs`
30+
* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port.
31+
* Optional: Set debug level to verbose to see all logs from Zigbee stack: `Tools -> Core Debug Level: Verbose`.
32+
33+
## Troubleshooting
34+
35+
If the End device flashed with this example is not connecting to the coordinator, erase the flash of the End device before flashing the example to the board. It is recommended to do this if you re-flash the coordinator.
36+
You can do the following:
37+
38+
* In the Arduino IDE go to the Tools menu and set `Erase All Flash Before Sketch Upload` to `Enabled`.
39+
* Add to the sketch `Zigbee.factoryReset();` to reset the device and Zigbee stack.
40+
41+
By default, the coordinator network is closed after rebooting or flashing new firmware.
42+
To open the network you have 2 options:
43+
44+
* Open network after reboot by setting `Zigbee.setRebootOpenNetwork(time);` before calling `Zigbee.begin();`.
45+
* In application you can anytime call `Zigbee.openNetwork(time);` to open the network for devices to join.
46+
47+
***Important: Make sure you are using a good quality USB cable and that you have a reliable power source***
48+
49+
* **LED not blinking:** Check the wiring connection and the IO selection.
50+
* **Programming Fail:** If the programming/flash procedure fails, try reducing the serial connection speed.
51+
* **COM port not detected:** Check the USB cable and the USB to Serial driver installation.
52+
53+
If the error persists, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute).
54+
55+
## Contribute
56+
57+
To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst)
58+
59+
If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome!
60+
61+
Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else.
62+
63+
## Resources
64+
65+
* Official ESP32 Forum: [Link](https://esp32.com)
66+
* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32)
67+
* ESP32-C6 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c6_datasheet_en.pdf)
68+
* ESP32-H2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-h2_datasheet_en.pdf)
69+
* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com)

‎libraries/Zigbee/examples/Zigbee_Window_Covering/Zigbee_Window_Covering.ino

+198
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
// Copyright 2025 Espressif Systems (Shanghai) PTE LTD
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
/**
16+
* @brief This example demonstrates Zigbee Window Covering.
17+
*
18+
* The example demonstrates how to use Zigbee library to create a end device window covering device.
19+
* The window covering is a Zigbee end device, which is moving the blinds (lift+tilt) and reporting
20+
* its current position to the Zigbee network.
21+
*
22+
* Use setCoveringType() to set the type of covering (blind, shade, etc.).
23+
*
24+
* The example also demonstrates how to use the button to manually control the lift position.
25+
*
26+
* Proper Zigbee mode must be selected in Tools->Zigbee mode
27+
* and also the correct partition scheme must be selected in Tools->Partition Scheme.
28+
*
29+
* Please check the README.md for instructions and more detailed description.
30+
*
31+
* Created by hennikul and Jan Procházka (https://github.com/P-R-O-C-H-Y/)
32+
*/
33+
34+
#ifndef ZIGBEE_MODE_ED
35+
#error "Zigbee end device mode is not selected in Tools->Zigbee mode"
36+
#endif
37+
38+
#include "ZigbeeCore.h"
39+
#include "ep/ZigbeeWindowCovering.h"
40+
41+
#define ZIGBEE_COVERING_ENDPOINT 10
42+
#define BUTTON_PIN 9 // ESP32-C6/H2 Boot button
43+
44+
#define MAX_LIFT 200 // centimeters from open position (0-900)
45+
#define MIN_LIFT 0
46+
47+
#define MAX_TILT 40 // centimeters from open position (0-900)
48+
#define MIN_TILT 0
49+
50+
uint16_t currentLift = MAX_LIFT;
51+
uint8_t currentLiftPercentage = 100;
52+
53+
uint16_t currentTilt = MAX_TILT;
54+
uint8_t currentTiltPercentage = 100;
55+
56+
ZigbeeWindowCovering zbCovering = ZigbeeWindowCovering(ZIGBEE_COVERING_ENDPOINT);
57+
58+
void setup() {
59+
Serial.begin(115200);
60+
61+
// Init button for factory reset
62+
pinMode(BUTTON_PIN, INPUT_PULLUP);
63+
64+
// Optional: set Zigbee device name and model
65+
zbCovering.setManufacturerAndModel("Espressif", "WindowBlinds");
66+
67+
// Set proper covering type, it defines which attributes are available
68+
zbCovering.setCoveringType(BLIND_LIFT_AND_TILT);
69+
70+
// Set configuration: operational, online, not commands_reversed, lift / tilt closed_loop, lift / tilt encoder_controlled
71+
zbCovering.setConfigStatus(true, true, false, true, true, true, true);
72+
73+
// Set mode: not motor_reversed, calibration_mode, not maintenance_mode, not leds_on
74+
zbCovering.setMode(false, true, false, false);
75+
76+
// Set limits of motion
77+
zbCovering.setLimits(MIN_LIFT, MAX_LIFT, MIN_TILT, MAX_TILT);
78+
79+
// Set callback function for open, close, filt and tilt change, stop
80+
zbCovering.onOpen(fullOpen);
81+
zbCovering.onClose(fullClose);
82+
zbCovering.onGoToLiftPercentage(goToLiftPercentage);
83+
zbCovering.onGoToTiltPercentage(goToTiltPercentage);
84+
zbCovering.onStop(stopMotor);
85+
86+
// Add endpoint to Zigbee Core
87+
Serial.println("Adding ZigbeeWindowCovering endpoint to Zigbee Core");
88+
Zigbee.addEndpoint(&zbCovering);
89+
90+
// When all EPs are registered, start Zigbee. By default acts as ZIGBEE_END_DEVICE
91+
Serial.println("Calling Zigbee.begin()");
92+
if (!Zigbee.begin()) {
93+
Serial.println("Zigbee failed to start!");
94+
Serial.println("Rebooting...");
95+
ESP.restart();
96+
}
97+
Serial.println("Connecting to network");
98+
while (!Zigbee.connected()) {
99+
Serial.print(".");
100+
delay(100);
101+
}
102+
Serial.println();
103+
104+
// Set initial position
105+
zbCovering.setLiftPercentage(currentLiftPercentage);
106+
zbCovering.setTiltPercentage(currentTiltPercentage);
107+
}
108+
109+
void loop() {
110+
// Checking button for factory reset
111+
if (digitalRead(BUTTON_PIN) == LOW) { // Push button pressed
112+
// Key debounce handling
113+
delay(100);
114+
int startTime = millis();
115+
while (digitalRead(BUTTON_PIN) == LOW) {
116+
delay(50);
117+
if ((millis() - startTime) > 3000) {
118+
// If key pressed for more than 3secs, factory reset Zigbee and reboot
119+
Serial.printf("Resetting Zigbee to factory settings, reboot.\n");
120+
Zigbee.factoryReset();
121+
delay(30000);
122+
}
123+
}
124+
// Manual lift control simulation by pressing button
125+
manualControl();
126+
}
127+
delay(500);
128+
}
129+
130+
void fullOpen() {
131+
/* This is where you would trigger your motor to go to full open state, currentLift should
132+
be updated until full open has been reached in order to provide feedback to controller of actual position
133+
The stop can be always called, so the movement can be stopped at any time */
134+
135+
// Our cover updates instantly!
136+
currentLift = MAX_LIFT;
137+
currentLiftPercentage = 100;
138+
Serial.println("Opening cover");
139+
// Update the current position
140+
zbCovering.setLiftPercentage(currentLiftPercentage);
141+
}
142+
143+
void fullClose() {
144+
/* This is where you would trigger your motor to go to full close state, currentLift should
145+
be updated until full close has been reached in order to provide feedback to controller of actual position
146+
The stop can be always called, so the movement can be stopped at any time */
147+
148+
// Our cover updates instantly!
149+
currentLift = MIN_LIFT;
150+
currentLiftPercentage = 0;
151+
Serial.println("Closing cover");
152+
// Update the current position
153+
zbCovering.setLiftPercentage(currentLiftPercentage);
154+
}
155+
156+
void goToLiftPercentage(uint8_t liftPercentage) {
157+
/* This is where you would trigger your motor to go towards liftPercentage, currentLift should
158+
be updated until liftPercentage has been reached in order to provide feedback to controller */
159+
160+
// Our simulated cover updates instantly!
161+
currentLift = (liftPercentage * MAX_LIFT) / 100;
162+
currentLiftPercentage = liftPercentage;
163+
Serial.printf("New requested lift from Zigbee: %d (%d)\n", currentLift, liftPercentage);
164+
165+
// Update the current position
166+
zbCovering.setLiftPercentage(currentLiftPercentage); //or setLiftPosition()
167+
}
168+
169+
void goToTiltPercentage(uint8_t tiltPercentage) {
170+
/* This is where you would trigger your motor to go towards tiltPercentage, currentTilt should
171+
be updated until tiltPercentage has been reached in order to provide feedback to controller */
172+
173+
// Our simulated cover updates instantly!
174+
currentTilt = (tiltPercentage * MAX_TILT) / 100;
175+
currentTiltPercentage = tiltPercentage;
176+
Serial.printf("New requested tilt from Zigbee: %d (%d)\n", currentTilt, tiltPercentage);
177+
178+
// Update the current position
179+
zbCovering.setTiltPercentage(currentTiltPercentage); //or setTiltPosition()
180+
}
181+
182+
void stopMotor() {
183+
// Motor can be stopped while moving cover toward current target, when stopped the actual position should be updated
184+
Serial.println("Stopping motor");
185+
// Update the current position of both lift and tilt
186+
zbCovering.setLiftPercentage(currentLiftPercentage);
187+
zbCovering.setTiltPercentage(currentTiltPercentage);
188+
}
189+
190+
void manualControl() {
191+
// Simulate lift percentage move by increasing it by 20% each time
192+
currentLiftPercentage += 20;
193+
if (currentLiftPercentage > 100) {
194+
currentLiftPercentage = 0;
195+
}
196+
zbCovering.setLiftPercentage(currentLiftPercentage);
197+
// Also setLiftPosition() can be used to set the exact position instead of percentage
198+
}

‎libraries/Zigbee/examples/Zigbee_Window_Covering/ci.json

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"fqbn_append": "PartitionScheme=zigbee,ZigbeeMode=ed",
3+
"requires": [
4+
"CONFIG_SOC_IEEE802154_SUPPORTED=y"
5+
]
6+
}

‎libraries/Zigbee/src/Zigbee.h

+1
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,4 @@
2020
#include "ep/ZigbeeCarbonDioxideSensor.h"
2121
#include "ep/ZigbeeContactSwitch.h"
2222
#include "ep/ZigbeeDoorWindowHandle.h"
23+
#include "ep/ZigbeeWindowCovering.h"

‎libraries/Zigbee/src/ZigbeeEP.h

+1-1
Original file line numberDiff line numberDiff line change
@@ -115,8 +115,8 @@ class ZigbeeEP {
115115
virtual void zbAttributeRead(uint16_t cluster_id, const esp_zb_zcl_attribute_t *attribute) {};
116116
virtual void zbReadBasicCluster(const esp_zb_zcl_attribute_t *attribute); //already implemented
117117
virtual void zbIdentify(const esp_zb_zcl_set_attr_value_message_t *message);
118+
virtual void zbWindowCoveringMovementCmd(const esp_zb_zcl_window_covering_movement_message_t *message) {};
118119
virtual void zbReadTimeCluster(const esp_zb_zcl_attribute_t *attribute); //already implemented
119-
120120
virtual void zbIASZoneStatusChangeNotification(const esp_zb_zcl_ias_zone_status_change_notification_message_t *message) {};
121121
virtual void zbIASZoneEnrollResponse(const esp_zb_zcl_ias_zone_enroll_response_message_t *message) {};
122122

‎libraries/Zigbee/src/ZigbeeHandlers.cpp

+26
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ static esp_err_t zb_configure_report_resp_handler(const esp_zb_zcl_cmd_config_re
1212
static esp_err_t zb_cmd_ias_zone_status_change_handler(const esp_zb_zcl_ias_zone_status_change_notification_message_t *message);
1313
static esp_err_t zb_cmd_ias_zone_enroll_response_handler(const esp_zb_zcl_ias_zone_enroll_response_message_t *message);
1414
static esp_err_t zb_cmd_default_resp_handler(const esp_zb_zcl_cmd_default_resp_message_t *message);
15+
static esp_err_t zb_window_covering_movement_resp_handler(const esp_zb_zcl_window_covering_movement_message_t *message);
1516

1617
// Zigbee action handlers
1718
[[maybe_unused]]
@@ -28,6 +29,9 @@ static esp_err_t zb_action_handler(esp_zb_core_action_callback_id_t callback_id,
2829
case ESP_ZB_CORE_IAS_ZONE_ENROLL_RESPONSE_VALUE_CB_ID:
2930
ret = zb_cmd_ias_zone_enroll_response_handler((esp_zb_zcl_ias_zone_enroll_response_message_t *)message);
3031
break;
32+
case ESP_ZB_CORE_WINDOW_COVERING_MOVEMENT_CB_ID:
33+
ret = zb_window_covering_movement_resp_handler((esp_zb_zcl_window_covering_movement_message_t *)message);
34+
break;
3135
case ESP_ZB_CORE_CMD_DEFAULT_RESP_CB_ID: ret = zb_cmd_default_resp_handler((esp_zb_zcl_cmd_default_resp_message_t *)message); break;
3236
default: log_w("Receive unhandled Zigbee action(0x%x) callback", callback_id); break;
3337
}
@@ -198,4 +202,26 @@ static esp_err_t zb_cmd_default_resp_handler(const esp_zb_zcl_cmd_default_resp_m
198202
return ESP_OK;
199203
}
200204

205+
static esp_err_t zb_window_covering_movement_resp_handler(const esp_zb_zcl_window_covering_movement_message_t *message) {
206+
if (!message) {
207+
log_e("Empty message");
208+
}
209+
if (message->info.status != ESP_ZB_ZCL_STATUS_SUCCESS) {
210+
log_e("Received message: error status(%d)", message->info.status);
211+
}
212+
213+
log_v(
214+
"Received message: endpoint(%d), cluster(0x%x), command(0x%x), payload(%d)", message->info.dst_endpoint, message->info.cluster, message->command,
215+
message->payload
216+
);
217+
218+
// List through all Zigbee EPs and call the callback function, with the message
219+
for (std::list<ZigbeeEP *>::iterator it = Zigbee.ep_objects.begin(); it != Zigbee.ep_objects.end(); ++it) {
220+
if (message->info.dst_endpoint == (*it)->getEndpoint()) {
221+
(*it)->zbWindowCoveringMovementCmd(message); //method zbWindowCoveringMovementCmd must be implemented in specific EP class
222+
}
223+
}
224+
return ESP_OK;
225+
}
226+
201227
#endif //SOC_IEEE802154_SUPPORTED && CONFIG_ZB_ENABLED

0 commit comments

Comments
 (0)