Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit c3f9513

Browse files
Merge pull request #11560 from espressif/feaz/zigbee-binary-output
feat(zigbee): Add Binary Output support
2 parents 35dffda + 7d37b7d commit c3f9513

File tree

6 files changed

+358
-37
lines changed

6 files changed

+358
-37
lines changed

‎docs/en/zigbee/ep_binary.rst

Lines changed: 114 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,7 @@ About
77

88
The ``ZigbeeBinary`` class provides an endpoint for binary input/output sensors in Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for binary sensors, supporting various application types for HVAC, security, and general binary sensing.
99
Binary Input (BI) is meant to be used for sensors that provide a binary signal, such as door/window sensors, motion detectors, etc. to be sent to the network.
10-
11-
.. note::
12-
13-
Binary Output (BO) is not supported yet.
10+
Binary Output (BO) is used for controlling binary devices such as relays, switches, or actuators that can be turned on/off remotely.
1411

1512
API Reference
1613
-------------
@@ -63,6 +60,33 @@ Security Application Types
6360
#define BINARY_INPUT_APPLICATION_TYPE_SECURITY_HEAT_DETECTION 0x01000008
6461
#define BINARY_INPUT_APPLICATION_TYPE_SECURITY_OTHER 0x0100FFFF
6562
63+
Binary Output Application Types
64+
*******************************
65+
66+
HVAC Application Types
67+
^^^^^^^^^^^^^^^^^^^^^^
68+
69+
.. code-block:: arduino
70+
71+
#define BINARY_OUTPUT_APPLICATION_TYPE_HVAC_BOILER 0x00000003
72+
#define BINARY_OUTPUT_APPLICATION_TYPE_HVAC_CHILLER 0x0000000D
73+
#define BINARY_OUTPUT_APPLICATION_TYPE_HVAC_FAN 0x00000022
74+
#define BINARY_OUTPUT_APPLICATION_TYPE_HVAC_HEATING_VALVE 0x0000002C
75+
#define BINARY_OUTPUT_APPLICATION_TYPE_HVAC_HUMIDIFIER 0x00000033
76+
#define BINARY_OUTPUT_APPLICATION_TYPE_HVAC_PREHEAT 0x00000034
77+
#define BINARY_OUTPUT_APPLICATION_TYPE_HVAC_OTHER 0x0000FFFF
78+
79+
Security Application Types
80+
^^^^^^^^^^^^^^^^^^^^^^^^^^
81+
82+
.. code-block:: arduino
83+
84+
#define BINARY_OUTPUT_APPLICATION_TYPE_SECURITY_ARM_DISARM_COMMAND 0x01000000
85+
#define BINARY_OUTPUT_APPLICATION_TYPE_SECURITY_OCCUPANCY_CONTROL 0x01000001
86+
#define BINARY_OUTPUT_APPLICATION_TYPE_SECURITY_ENABLE_CONTROL 0x01000002
87+
#define BINARY_OUTPUT_APPLICATION_TYPE_SECURITY_ACCESS_CONTROL 0x01000003
88+
#define BINARY_OUTPUT_APPLICATION_TYPE_SECURITY_OTHER 0x0100FFFF
89+
6690
API Methods
6791
***********
6892

@@ -127,11 +151,94 @@ Manually reports the current binary input value.
127151
128152
This function will return ``true`` if successful, ``false`` otherwise.
129153

154+
addBinaryOutput
155+
^^^^^^^^^^^^^^^
156+
157+
Adds a binary output cluster to the endpoint.
158+
159+
.. code-block:: arduino
160+
161+
bool addBinaryOutput();
162+
163+
This function will return ``true`` if successful, ``false`` otherwise.
164+
165+
setBinaryOutputApplication
166+
^^^^^^^^^^^^^^^^^^^^^^^^^^
167+
168+
Sets the application type for the binary output.
169+
170+
.. code-block:: arduino
171+
172+
bool setBinaryOutputApplication(uint32_t application_type);
173+
174+
* ``application_type`` - Application type constant (see Binary Output Application Types above)
175+
176+
This function will return ``true`` if successful, ``false`` otherwise.
177+
178+
setBinaryOutputDescription
179+
^^^^^^^^^^^^^^^^^^^^^^^^^^
180+
181+
Sets a custom description for the binary output.
182+
183+
.. code-block:: arduino
184+
185+
bool setBinaryOutputDescription(const char *description);
186+
187+
* ``description`` - Description string
188+
189+
This function will return ``true`` if successful, ``false`` otherwise.
190+
191+
onBinaryOutputChange
192+
^^^^^^^^^^^^^^^^^^^^^
193+
194+
Sets a callback function to be called when the binary output value changes.
195+
196+
.. code-block:: arduino
197+
198+
void onBinaryOutputChange(void (*callback)(bool binary_output));
199+
200+
* ``callback`` - Function pointer to callback that receives the new binary output value
201+
202+
setBinaryOutput
203+
^^^^^^^^^^^^^^^
204+
205+
Sets the binary output value.
206+
207+
.. code-block:: arduino
208+
209+
bool setBinaryOutput(bool output);
210+
211+
* ``output`` - Binary value (true/false)
212+
213+
This function will return ``true`` if successful, ``false`` otherwise.
214+
215+
getBinaryOutput
216+
^^^^^^^^^^^^^^^
217+
218+
Gets the current binary output value.
219+
220+
.. code-block:: arduino
221+
222+
bool getBinaryOutput();
223+
224+
This function returns the current binary output state.
225+
226+
reportBinaryOutput
227+
^^^^^^^^^^^^^^^^^^
228+
229+
Manually reports the current binary output value.
230+
231+
.. code-block:: arduino
232+
233+
bool reportBinaryOutput();
234+
235+
This function will return ``true`` if successful, ``false`` otherwise.
236+
130237
Example
131238
-------
132239

133-
Binary Input Implementation
134-
****************************
240+
Binary Input and Output Implementation
241+
**************************************
135242

136-
.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Binary_Input/Zigbee_Binary_Input.ino
243+
.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Binary_Input_Output/Zigbee_Binary_Input_Output.ino
137244
:language: arduino

‎libraries/Zigbee/examples/Zigbee_Binary_Input/README.md renamed to ‎libraries/Zigbee/examples/Zigbee_Binary_Input_Output/README.md

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Arduino-ESP32 Zigbee Binary Input Example
1+
# Arduino-ESP32 Zigbee Binary Input Output Example
22

3-
This example shows how to configure the Zigbee end device and use it as a Home Automation (HA) binary input device with two different applications: HVAC fan status and security zone armed status.
3+
This example shows how to configure the Zigbee end device and use it as a Home Automation (HA) binary input/output device with multiple applications: HVAC fan status/control, security zone armed status, and HVAC humidifier control.
44

55
# Supported Targets
66

@@ -9,12 +9,17 @@ Currently, this example supports the following targets.
99
| Supported Targets | ESP32-C6 | ESP32-H2 |
1010
| ----------------- | -------- | -------- |
1111

12-
## Binary Input Functions
13-
14-
* The example implements two binary inputs:
15-
- HVAC Fan Status: Reports the current state of a fan
16-
- Security Zone Armed: Reports the armed state of a security zone
17-
* By clicking the button (BOOT) on this board, it will toggle both binary inputs and immediately send a report of their states to the network.
12+
## Binary Input/Output Functions
13+
14+
* The example implements three binary devices:
15+
- **Binary Fan Device (Endpoint 1)**:
16+
- Binary Input: HVAC Fan Status - Reports the current state of a fan
17+
- Binary Output: HVAC Fan - Controls the fan switch with callback function
18+
- **Binary Zone Device (Endpoint 2)**:
19+
- Binary Input: Security Zone Armed - Reports the armed state of a security zone
20+
- **Binary Humidifier Device (Endpoint 3)**:
21+
- Binary Output: HVAC Humidifier - Controls the humidifier switch with callback function
22+
* By clicking the button (BOOT) on this board, it will toggle all binary inputs/outputs and immediately send a report of their states to the network.
1823
* Holding the button for more than 3 seconds will trigger a factory reset of the Zigbee device.
1924

2025
## Hardware Required

‎libraries/Zigbee/examples/Zigbee_Binary_Input/Zigbee_Binary_Input.ino renamed to ‎libraries/Zigbee/examples/Zigbee_Binary_Input_Output/Zigbee_Binary_Input_Output.ino

Lines changed: 42 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,9 @@
1313
// limitations under the License.
1414

1515
/**
16-
* @brief This example demonstrates Zigbee binary input device.
16+
* @brief This example demonstrates Zigbee binary input/output device.
1717
*
18-
* The example demonstrates how to use Zigbee library to create an end device binary sensor device.
18+
* The example demonstrates how to use Zigbee library to create an end device binary sensor/switch device.
1919
*
2020
* Proper Zigbee mode must be selected in Tools->Zigbee mode
2121
* and also the correct partition scheme must be selected in Tools->Partition Scheme.
@@ -34,13 +34,24 @@
3434
/* Zigbee binary sensor device configuration */
3535
#define BINARY_DEVICE_ENDPOINT_NUMBER 1
3636

37-
uint8_t binaryPin = A0;
3837
uint8_t button = BOOT_PIN;
3938

4039
ZigbeeBinary zbBinaryFan = ZigbeeBinary(BINARY_DEVICE_ENDPOINT_NUMBER);
4140
ZigbeeBinary zbBinaryZone = ZigbeeBinary(BINARY_DEVICE_ENDPOINT_NUMBER + 1);
41+
ZigbeeBinary zbBinaryHumidifier = ZigbeeBinary(BINARY_DEVICE_ENDPOINT_NUMBER + 2);
4242

43-
bool binaryStatus = false;
43+
bool zoneStatus = false;
44+
45+
void fanSwitch(bool state) {
46+
Serial.println("Fan switch changed to: " + String(state));
47+
// Switch Fan status input signaling the fan status has changed
48+
zbBinaryFan.setBinaryInput(state);
49+
zbBinaryFan.reportBinaryInput();
50+
}
51+
52+
void humidifierSwitch(bool state) {
53+
Serial.println("Humidifier switch changed to: " + String(state));
54+
}
4455

4556
void setup() {
4657
Serial.begin(115200);
@@ -55,19 +66,33 @@ void setup() {
5566
// Optional: set Zigbee device name and model
5667
zbBinaryFan.setManufacturerAndModel("Espressif", "ZigbeeBinarySensor");
5768

58-
// Set up binary fan status input (HVAC)
69+
// Set up binary fan status input + switch output (HVAC)
5970
zbBinaryFan.addBinaryInput();
6071
zbBinaryFan.setBinaryInputApplication(BINARY_INPUT_APPLICATION_TYPE_HVAC_FAN_STATUS);
6172
zbBinaryFan.setBinaryInputDescription("Fan Status");
6273

74+
zbBinaryFan.addBinaryOutput();
75+
zbBinaryFan.setBinaryOutputApplication(BINARY_OUTPUT_APPLICATION_TYPE_HVAC_FAN);
76+
zbBinaryFan.setBinaryOutputDescription("Fan Switch");
77+
78+
zbBinaryFan.onBinaryOutputChange(fanSwitch);
79+
6380
// Set up binary zone armed input (Security)
6481
zbBinaryZone.addBinaryInput();
6582
zbBinaryZone.setBinaryInputApplication(BINARY_INPUT_APPLICATION_TYPE_SECURITY_ZONE_ARMED);
6683
zbBinaryZone.setBinaryInputDescription("Zone Armed");
6784

85+
// Set up binary humidifier output (HVAC)
86+
zbBinaryHumidifier.addBinaryOutput();
87+
zbBinaryHumidifier.setBinaryOutputApplication(BINARY_OUTPUT_APPLICATION_TYPE_HVAC_HUMIDIFIER);
88+
zbBinaryHumidifier.setBinaryOutputDescription("Humidifier Switch");
89+
90+
zbBinaryHumidifier.onBinaryOutputChange(humidifierSwitch);
91+
6892
// Add endpoints to Zigbee Core
6993
Zigbee.addEndpoint(&zbBinaryFan);
7094
Zigbee.addEndpoint(&zbBinaryZone);
95+
Zigbee.addEndpoint(&zbBinaryHumidifier);
7196

7297
Serial.println("Starting Zigbee...");
7398
// When all EPs are registered, start Zigbee in End Device mode
@@ -101,12 +126,19 @@ void loop() {
101126
Zigbee.factoryReset();
102127
}
103128
}
104-
// Toggle binary input
105-
binaryStatus = !binaryStatus;
106-
zbBinaryFan.setBinaryInput(binaryStatus);
107-
zbBinaryZone.setBinaryInput(binaryStatus);
108-
zbBinaryFan.reportBinaryInput();
129+
130+
// Toggle fan
131+
zbBinaryFan.setBinaryOutput(!zbBinaryFan.getBinaryOutput());
132+
zbBinaryFan.reportBinaryOutput();
133+
134+
// Toggle zone
135+
zoneStatus = !zoneStatus;
136+
zbBinaryZone.setBinaryInput(zoneStatus);
109137
zbBinaryZone.reportBinaryInput();
138+
139+
// Toggle humidifier
140+
zbBinaryHumidifier.setBinaryOutput(!zbBinaryHumidifier.getBinaryOutput());
141+
zbBinaryHumidifier.reportBinaryOutput();
110142
}
111143
delay(100);
112144
}

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /