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 35dffda

Browse files
Merge pull request #11609 from espressif/feat/zigbee-multistate
feat(zigbee): Add multistate endpoint support
2 parents 63418e7 + f650c06 commit 35dffda

File tree

9 files changed

+1339
-0
lines changed

9 files changed

+1339
-0
lines changed

‎CMakeLists.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -315,6 +315,7 @@ set(ARDUINO_LIBRARY_Zigbee_SRCS
315315
libraries/Zigbee/src/ep/ZigbeeBinary.cpp
316316
libraries/Zigbee/src/ep/ZigbeePowerOutlet.cpp
317317
libraries/Zigbee/src/ep/ZigbeeFanControl.cpp
318+
libraries/Zigbee/src/ep/ZigbeeMultistate.cpp
318319
)
319320

320321
set(ARDUINO_LIBRARY_BLE_SRCS

‎docs/en/zigbee/ep_multistate.rst

Lines changed: 346 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,346 @@
1+
################
2+
ZigbeeMultistate
3+
################
4+
5+
About
6+
-----
7+
8+
The ``ZigbeeMultistate`` class provides multistate input and output endpoints for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for multistate signal processing and control.
9+
Multistate Input (MI) is meant to be used for sensors that provide discrete state values, such as fan speed settings, HVAC modes, or security states to be sent to the coordinator.
10+
Multistate Output (MO) is meant to be used for actuators that require discrete state control, such as fan controllers, HVAC systems, or security devices to be controlled by the coordinator.
11+
12+
.. note::
13+
14+
HomeAssistant ZHA does not support multistate input and output clusters yet.
15+
16+
Common API
17+
----------
18+
19+
Constructor
20+
***********
21+
22+
ZigbeeMultistate
23+
^^^^^^^^^^^^^^^^
24+
25+
Creates a new Zigbee multistate endpoint.
26+
27+
.. code-block:: arduino
28+
29+
ZigbeeMultistate(uint8_t endpoint);
30+
31+
* ``endpoint`` - Endpoint number (1-254)
32+
33+
Multistate Application Types
34+
****************************
35+
36+
The ZigbeeMultistate class supports predefined application types with specific state configurations:
37+
38+
.. code-block:: arduino
39+
40+
// Application Type 0: Fan states (Off, On, Auto)
41+
#define ZB_MULTISTATE_APPLICATION_TYPE_0_INDEX 0x0000
42+
#define ZB_MULTISTATE_APPLICATION_TYPE_0_NUM_STATES 3
43+
#define ZB_MULTISTATE_APPLICATION_TYPE_0_STATE_NAMES (const char* const[]){"Off", "On", "Auto"}
44+
45+
// Application Type 1: Fan speed states (Off, Low, Medium, High)
46+
#define ZB_MULTISTATE_APPLICATION_TYPE_1_INDEX 0x0001
47+
#define ZB_MULTISTATE_APPLICATION_TYPE_1_NUM_STATES 4
48+
#define ZB_MULTISTATE_APPLICATION_TYPE_1_STATE_NAMES (const char* const[]){"Off", "Low", "Medium", "High"}
49+
50+
// Application Type 2: HVAC modes (Auto, Heat, Cool, Off, Emergency Heat, Fan Only, Max Heat)
51+
#define ZB_MULTISTATE_APPLICATION_TYPE_2_INDEX 0x0002
52+
#define ZB_MULTISTATE_APPLICATION_TYPE_2_NUM_STATES 7
53+
#define ZB_MULTISTATE_APPLICATION_TYPE_2_STATE_NAMES (const char* const[]){"Auto", "Heat", "Cool", "Off", "Emergency Heat", "Fan Only", "Max Heat"}
54+
55+
// Application Type 3: Occupancy states (Occupied, Unoccupied, Standby, Bypass)
56+
#define ZB_MULTISTATE_APPLICATION_TYPE_3_INDEX 0x0003
57+
#define ZB_MULTISTATE_APPLICATION_TYPE_3_NUM_STATES 4
58+
#define ZB_MULTISTATE_APPLICATION_TYPE_3_STATE_NAMES (const char* const[]){"Occupied", "Unoccupied", "Standby", "Bypass"}
59+
60+
// Application Type 4: Control states (Inactive, Active, Hold)
61+
#define ZB_MULTISTATE_APPLICATION_TYPE_4_INDEX 0x0004
62+
#define ZB_MULTISTATE_APPLICATION_TYPE_4_NUM_STATES 3
63+
#define ZB_MULTISTATE_APPLICATION_TYPE_4_STATE_NAMES (const char* const[]){"Inactive", "Active", "Hold"}
64+
65+
// Application Type 5: Water system states (Auto, Warm-up, Water Flush, Autocalibration, Shutdown Open, Shutdown Closed, Low Limit, Test and Balance)
66+
#define ZB_MULTISTATE_APPLICATION_TYPE_5_INDEX 0x0005
67+
#define ZB_MULTISTATE_APPLICATION_TYPE_5_NUM_STATES 8
68+
#define ZB_MULTISTATE_APPLICATION_TYPE_5_STATE_NAMES (const char* const[]){"Auto", "Warm-up", "Water Flush", "Autocalibration", "Shutdown Open", "Shutdown Closed", "Low Limit", "Test and Balance"}
69+
70+
// Application Type 6: HVAC system states (Off, Auto, Heat Cool, Heat Only, Cool Only, Fan Only)
71+
#define ZB_MULTISTATE_APPLICATION_TYPE_6_INDEX 0x0006
72+
#define ZB_MULTISTATE_APPLICATION_TYPE_6_NUM_STATES 6
73+
#define ZB_MULTISTATE_APPLICATION_TYPE_6_STATE_NAMES (const char* const[]){"Off", "Auto", "Heat Cool", "Heat Only", "Cool Only", "Fan Only"}
74+
75+
// Application Type 7: Light states (High, Normal, Low)
76+
#define ZB_MULTISTATE_APPLICATION_TYPE_7_INDEX 0x0007
77+
#define ZB_MULTISTATE_APPLICATION_TYPE_7_NUM_STATES 3
78+
#define ZB_MULTISTATE_APPLICATION_TYPE_7_STATE_NAMES (const char* const[]){"High", "Normal", "Low"}
79+
80+
// Application Type 8: Occupancy control states (Occupied, Unoccupied, Startup, Shutdown)
81+
#define ZB_MULTISTATE_APPLICATION_TYPE_8_INDEX 0x0008
82+
#define ZB_MULTISTATE_APPLICATION_TYPE_8_NUM_STATES 4
83+
#define ZB_MULTISTATE_APPLICATION_TYPE_8_STATE_NAMES (const char* const[]){"Occupied", "Unoccupied", "Startup", "Shutdown"}
84+
85+
// Application Type 9: Time states (Night, Day, Hold)
86+
#define ZB_MULTISTATE_APPLICATION_TYPE_9_INDEX 0x0009
87+
#define ZB_MULTISTATE_APPLICATION_TYPE_9_NUM_STATES 3
88+
#define ZB_MULTISTATE_APPLICATION_TYPE_9_STATE_NAMES (const char* const[]){"Night", "Day", "Hold"}
89+
90+
// Application Type 10: HVAC control states (Off, Cool, Heat, Auto, Emergency Heat)
91+
#define ZB_MULTISTATE_APPLICATION_TYPE_10_INDEX 0x000A
92+
#define ZB_MULTISTATE_APPLICATION_TYPE_10_NUM_STATES 5
93+
#define ZB_MULTISTATE_APPLICATION_TYPE_10_STATE_NAMES (const char* const[]){"Off", "Cool", "Heat", "Auto", "Emergency Heat"}
94+
95+
// Application Type 11: Water control states (Shutdown Closed, Shutdown Open, Satisfied, Mixing, Cooling, Heating, Suppl Heat)
96+
#define ZB_MULTISTATE_APPLICATION_TYPE_11_INDEX 0x000B
97+
#define ZB_MULTISTATE_APPLICATION_TYPE_11_NUM_STATES 7
98+
#define ZB_MULTISTATE_APPLICATION_TYPE_11_STATE_NAMES (const char* const[]){"Shutdown Closed", "Shutdown Open", "Satisfied", "Mixing", "Cooling", "Heating", "Suppl Heat"}
99+
100+
// Custom application type for user-defined states
101+
#define ZB_MULTISTATE_APPLICATION_TYPE_OTHER_INDEX 0xFFFF
102+
103+
Cluster Management
104+
******************
105+
106+
addMultistateInput
107+
^^^^^^^^^^^^^^^^^^
108+
109+
Adds multistate input cluster to the endpoint.
110+
111+
.. code-block:: arduino
112+
113+
bool addMultistateInput();
114+
115+
This function will return ``true`` if successful, ``false`` otherwise.
116+
117+
addMultistateOutput
118+
^^^^^^^^^^^^^^^^^^^
119+
120+
Adds multistate output cluster to the endpoint.
121+
122+
.. code-block:: arduino
123+
124+
bool addMultistateOutput();
125+
126+
This function will return ``true`` if successful, ``false`` otherwise.
127+
128+
Multistate Input API
129+
--------------------
130+
131+
Configuration Methods
132+
*********************
133+
134+
setMultistateInputApplication
135+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
136+
137+
Sets the application type for the multistate input.
138+
139+
.. code-block:: arduino
140+
141+
bool setMultistateInputApplication(uint32_t application_type);
142+
143+
* ``application_type`` - Application type constant (see Multistate Application Types above)
144+
145+
This function will return ``true`` if successful, ``false`` otherwise.
146+
147+
setMultistateInputDescription
148+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
149+
150+
Sets a custom description for the multistate input.
151+
152+
.. code-block:: arduino
153+
154+
bool setMultistateInputDescription(const char *description);
155+
156+
* ``description`` - Description string
157+
158+
This function will return ``true`` if successful, ``false`` otherwise.
159+
160+
setMultistateInputStates
161+
^^^^^^^^^^^^^^^^^^^^^^^^
162+
163+
Sets the number of states for the multistate input.
164+
165+
.. code-block:: arduino
166+
167+
bool setMultistateInputStates(uint16_t number_of_states);
168+
169+
* ``number_of_states`` - Number of discrete states (1-65535)
170+
171+
This function will return ``true`` if successful, ``false`` otherwise.
172+
173+
Value Control
174+
*************
175+
176+
setMultistateInput
177+
^^^^^^^^^^^^^^^^^^
178+
179+
Sets the multistate input value.
180+
181+
.. code-block:: arduino
182+
183+
bool setMultistateInput(uint16_t state);
184+
185+
* ``state`` - State index (0 to number_of_states-1)
186+
187+
This function will return ``true`` if successful, ``false`` otherwise.
188+
189+
getMultistateInput
190+
^^^^^^^^^^^^^^^^^^
191+
192+
Gets the current multistate input value.
193+
194+
.. code-block:: arduino
195+
196+
uint16_t getMultistateInput();
197+
198+
This function returns the current multistate input state.
199+
200+
Reporting Methods
201+
*****************
202+
203+
reportMultistateInput
204+
^^^^^^^^^^^^^^^^^^^^^
205+
206+
Manually reports the current multistate input value.
207+
208+
.. code-block:: arduino
209+
210+
bool reportMultistateInput();
211+
212+
This function will return ``true`` if successful, ``false`` otherwise.
213+
214+
Multistate Output API
215+
---------------------
216+
217+
Configuration Methods
218+
*********************
219+
220+
setMultistateOutputApplication
221+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
222+
223+
Sets the application type for the multistate output.
224+
225+
.. code-block:: arduino
226+
227+
bool setMultistateOutputApplication(uint32_t application_type);
228+
229+
* ``application_type`` - Application type constant (see Multistate Application Types above)
230+
231+
This function will return ``true`` if successful, ``false`` otherwise.
232+
233+
setMultistateOutputDescription
234+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
235+
236+
Sets a custom description for the multistate output.
237+
238+
.. code-block:: arduino
239+
240+
bool setMultistateOutputDescription(const char *description);
241+
242+
* ``description`` - Description string
243+
244+
This function will return ``true`` if successful, ``false`` otherwise.
245+
246+
setMultistateOutputStates
247+
^^^^^^^^^^^^^^^^^^^^^^^^^
248+
249+
Sets the number of states for the multistate output.
250+
251+
.. code-block:: arduino
252+
253+
bool setMultistateOutputStates(uint16_t number_of_states);
254+
255+
* ``number_of_states`` - Number of discrete states (1-65535)
256+
257+
This function will return ``true`` if successful, ``false`` otherwise.
258+
259+
Value Control
260+
*************
261+
262+
setMultistateOutput
263+
^^^^^^^^^^^^^^^^^^^^
264+
265+
Sets the multistate output value.
266+
267+
.. code-block:: arduino
268+
269+
bool setMultistateOutput(uint16_t state);
270+
271+
* ``state`` - State index (0 to number_of_states-1)
272+
273+
This function will return ``true`` if successful, ``false`` otherwise.
274+
275+
getMultistateOutput
276+
^^^^^^^^^^^^^^^^^^^
277+
278+
Gets the current multistate output value.
279+
280+
.. code-block:: arduino
281+
282+
uint16_t getMultistateOutput();
283+
284+
This function returns the current multistate output state.
285+
286+
State Information
287+
*****************
288+
289+
getMultistateInputStateNamesLength
290+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
291+
292+
Gets the number of state names for multistate input.
293+
294+
.. code-block:: arduino
295+
296+
uint16_t getMultistateInputStateNamesLength();
297+
298+
This function returns the number of state names configured for multistate input.
299+
300+
getMultistateOutputStateNamesLength
301+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
302+
303+
Gets the number of state names for multistate output.
304+
305+
.. code-block:: arduino
306+
307+
uint16_t getMultistateOutputStateNamesLength();
308+
309+
This function returns the number of state names configured for multistate output.
310+
311+
Reporting Methods
312+
*****************
313+
314+
reportMultistateOutput
315+
^^^^^^^^^^^^^^^^^^^^^^^
316+
317+
Manually reports the current multistate output value.
318+
319+
.. code-block:: arduino
320+
321+
bool reportMultistateOutput();
322+
323+
This function will return ``true`` if successful, ``false`` otherwise.
324+
325+
Event Handling
326+
**************
327+
328+
onMultistateOutputChange
329+
^^^^^^^^^^^^^^^^^^^^^^^^
330+
331+
Sets a callback function to be called when the multistate output value changes.
332+
333+
.. code-block:: arduino
334+
335+
void onMultistateOutputChange(void (*callback)(uint16_t state));
336+
337+
* ``callback`` - Function to call when multistate output changes, receives the new state value
338+
339+
Example
340+
-------
341+
342+
Multistate Input/Output
343+
***********************
344+
345+
.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Multistate_Input_Output/Zigbee_Multistate_Input_Output.ino
346+
:language: arduino

0 commit comments

Comments
(0)

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