feat(zigbee): Add multistate endpoint support

CMakeLists.txt

@@ -306,6 +306,7 @@ set(ARDUINO_LIBRARY_Zigbee_SRCS
   libraries/Zigbee/src/ep/ZigbeeBinary.cpp
   libraries/Zigbee/src/ep/ZigbeePowerOutlet.cpp
   libraries/Zigbee/src/ep/ZigbeeFanControl.cpp
+  libraries/Zigbee/src/ep/ZigbeeMultistate.cpp
   )
 
 set(ARDUINO_LIBRARY_BLE_SRCS

libraries/Zigbee/examples/Zigbee_Multistate_Input_Output/README.md

@@ -0,0 +1,90 @@
+# Arduino-ESP32 Zigbee Multistate Input Output Example
+
+This example shows how to configure the Zigbee end device and use it as a Home Automation (HA) multistate input/output device.
+
+# Supported Targets
+
+Currently, this example supports the following targets.
+
+| Supported Targets | ESP32-C6 | ESP32-H2 |
+| ----------------- | -------- | -------- |
+
+## Multistate Device Functions
+
+This example demonstrates two different multistate devices:
+
+1. **Standard Multistate Device** (`zbMultistateDevice`): Uses predefined application states from the Zigbee specification
+   - Application Type 0: Fan states (Off, On, Auto)
+   - Application Type 7: Light states (High, Normal, Low)
+
+2. **Custom Multistate Device** (`zbMultistateDeviceCustom`): Uses user-defined custom states
+   - Custom fan states: Off, On, UltraSlow, Slow, Fast, SuperFast
+
+* After this board first starts up, it will be configured as two multistate devices with different state configurations.
+* By clicking the button (BOOT) on this board, the devices will cycle through their respective states and report the changes to the network.
+
+## Hardware Required
+
+* A USB cable for power supply and programming
+
+### Configure the Project
+
+Set the Button GPIO by changing the `button` variable. By default, it's the pin `BOOT_PIN` (BOOT button on ESP32-C6 and ESP32-H2).
+
+The example creates two multistate devices:
+- **Endpoint 1**: Standard multistate device using predefined Zigbee application types
+- **Endpoint 2**: Custom multistate device using user-defined states
+
+You can modify the state names and configurations by changing the following variables:
+- `multistate_custom_state_names[]`: Array of custom state names
+- Application type and lenght macros: `ZB_MULTISTATE_APPLICATION_TYPE_X_STATE_NAMES`, 
+`ZB_MULTISTATE_APPLICATION_TYPE_X_NUM_STATES`, `ZB_MULTISTATE_APPLICATION_TYPE_X_INDEX`
+- Device descriptions and application types in the setup() function
+
+#### Using Arduino IDE
+
+To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits).
+
+* Before Compile/Verify, select the correct board: `Tools -> Board`.
+* Select the End device Zigbee mode: `Tools -> Zigbee mode: Zigbee ED (end device)`
+* Select Partition Scheme for Zigbee: `Tools -> Partition Scheme: Zigbee 4MB with spiffs`
+* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port.
+* Optional: Set debug level to verbose to see all logs from Zigbee stack: `Tools -> Core Debug Level: Verbose`.
+
+## Troubleshooting
+
+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.
+You can do the following:
+
+* In the Arduino IDE go to the Tools menu and set `Erase All Flash Before Sketch Upload` to `Enabled`.
+* Add to the sketch `Zigbee.factoryReset();` to reset the device and Zigbee stack.
+
+By default, the coordinator network is closed after rebooting or flashing new firmware.
+To open the network you have 2 options:
+
+* Open network after reboot by setting `Zigbee.setRebootOpenNetwork(time);` before calling `Zigbee.begin();`.
+* In application you can anytime call `Zigbee.openNetwork(time);` to open the network for devices to join.
+
+***Important: Make sure you are using a good quality USB cable and that you have a reliable power source***
+
+* **LED not blinking:** Check the wiring connection and the IO selection.
+* **Programming Fail:** If the programming/flash procedure fails, try reducing the serial connection speed.
+* **COM port not detected:** Check the USB cable and the USB to Serial driver installation.
+
+If the error persists, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute).
+
+## Contribute
+
+To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst)
+
+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!
+
+Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else.
+
+## Resources
+
+* Official ESP32 Forum: [Link](https://esp32.com)
+* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32)
+* ESP32-C6 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c6_datasheet_en.pdf)
+* ESP32-H2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-h2_datasheet_en.pdf)
+* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com)

libraries/Zigbee/examples/Zigbee_Multistate_Input_Output/Zigbee_Multistate_Input_Output.ino

@@ -0,0 +1,188 @@
+// Copyright 2025 Espressif Systems (Shanghai) PTE LTD
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * @brief This example demonstrates Zigbee multistate input / output device.
+ *
+ * The example demonstrates how to use Zigbee library to create a end device multistate device.
+ * In the example, we have two multistate devices:
+ * - zbMultistateDevice: uses defined application states from Zigbee specification
+ * - zbMultistateDeviceCustom: uses custom application states (user defined)
+ * 
+ * Proper Zigbee mode must be selected in Tools->Zigbee mode
+ * and also the correct partition scheme must be selected in Tools->Partition Scheme.
+ *
+ * Please check the README.md for instructions and more detailed description.
+ *
+ * Created by Jan Procházka (https://github.com/P-R-O-C-H-Y/)
+ * Modified by Pat Clay
+ */
+
+#ifndef ZIGBEE_MODE_ZCZR
+#error "Zigbee coordinator/router device mode is not selected in Tools->Zigbee mode"
+#endif
+
+#include "Zigbee.h"
+
+/* Zigbee multistate device configuration */
+#define MULTISTATE_DEVICE_ENDPOINT_NUMBER 1
+
+uint8_t button = BOOT_PIN;
+
+// zbMultistateDevice will use defined application states
+ZigbeeMultistate zbMultistateDevice = ZigbeeMultistate(MULTISTATE_DEVICE_ENDPOINT_NUMBER);
+
+// zbMultistateDeviceCustom will use custom application states (user defined)
+ZigbeeMultistate zbMultistateDeviceCustom = ZigbeeMultistate(MULTISTATE_DEVICE_ENDPOINT_NUMBER + 1);
+
+const char* multistate_custom_state_names[6] = {"Off", "On", "UltraSlow", "Slow", "Fast", "SuperFast"};
+
+void onStateChange(uint16_t state) {
+  // print the state
+  Serial.printf("Received state change: %d\r\n", state);
+  // print the state name using the stored state names
+  const char* const* state_names = zbMultistateDevice.getMultistateOutputStateNames();
+  if (state_names && state < zbMultistateDevice.getMultistateOutputStateNamesLength()) {
+    Serial.printf("State name: %s\r\n", state_names[state]);
+  }
+  // print state index of possible options
+  Serial.printf("State index: %d / %d\r\n", state, zbMultistateDevice.getMultistateOutputStateNamesLength() - 1);
+}
+
+void onStateChangeCustom(uint16_t state) {
+  // print the state
+  Serial.printf("Received state change: %d\r\n", state);
+  // print the state name using the stored state names
+  const char* const* state_names = zbMultistateDeviceCustom.getMultistateOutputStateNames();
+  if (state_names && state < zbMultistateDeviceCustom.getMultistateOutputStateNamesLength()) {
+    Serial.printf("State name: %s\r\n", state_names[state]);
+  }
+  // print state index of possible options
+  Serial.printf("State index: %d / %d\r\n", state, zbMultistateDevice.getMultistateOutputStateNamesLength() - 1);
+
+  Serial.print("Changing to fan mode to: ");
+  switch (state) {
+    case 0:
+      Serial.println("Off");
+      break;
+    case 1:
+      Serial.println("On");
+      break;
+    case 2:
+      Serial.println("Slow");
+      break;
+    case 3:
+      Serial.println("Medium");
+      break;
+    case 4:
+      Serial.println("Fast");
+      break;
+    default:
+      Serial.println("Invalid state");
+      break;
+  }
+}
+
+void setup() {
+  Serial.begin(115200);
+
+  // Init button switch
+  pinMode(button, INPUT_PULLUP);
+
+  // Optional: set Zigbee device name and model
+  zbMultistateDevice.setManufacturerAndModel("Espressif", "ZigbeeMultistateDevice");
+
+  // Set up analog input
+  zbMultistateDevice.addMultistateInput();
+  zbMultistateDevice.setMultistateInputApplication(ZB_MULTISTATE_APPLICATION_TYPE_0_INDEX);
+  zbMultistateDevice.setMultistateInputDescription("Fan (on/off/auto)");
+  zbMultistateDevice.setMultistateInputStates(ZB_MULTISTATE_APPLICATION_TYPE_0_STATE_NAMES, ZB_MULTISTATE_APPLICATION_TYPE_0_NUM_STATES);
+
+  // Set up analog output
+  zbMultistateDevice.addMultistateOutput();
+  zbMultistateDevice.setMultistateOutputApplication(ZB_MULTISTATE_APPLICATION_TYPE_7_INDEX);
+  zbMultistateDevice.setMultistateOutputDescription("Light (high/normal/low)");
+  zbMultistateDevice.setMultistateOutputStates(ZB_MULTISTATE_APPLICATION_TYPE_7_STATE_NAMES, ZB_MULTISTATE_APPLICATION_TYPE_7_NUM_STATES);
+
+  // Set up custom output
+  zbMultistateDeviceCustom.addMultistateOutput();
+  zbMultistateDeviceCustom.setMultistateOutputApplication(ZB_MULTISTATE_APPLICATION_TYPE_OTHER_INDEX);
+  zbMultistateDeviceCustom.setMultistateOutputDescription("Fan (on/off/slow/medium/fast)");
+  zbMultistateDeviceCustom.setMultistateOutputStates(multistate_custom_state_names, 5);
+
+  // Set callback function for multistate output change 
+  zbMultistateDevice.onMultistateOutputChange(onStateChange);
+  zbMultistateDeviceCustom.onMultistateOutputChange(onStateChangeCustom);
+
+  // Add endpoints to Zigbee Core
+  Zigbee.addEndpoint(&zbMultistateDevice);
+  Zigbee.addEndpoint(&zbMultistateDeviceCustom);
+
+  Serial.println("Starting Zigbee...");
+  // When all EPs are registered, start Zigbee in Router Device mode
+  if (!Zigbee.begin(ZIGBEE_ROUTER)) {
+    Serial.println("Zigbee failed to start!");
+    Serial.println("Rebooting...");
+    ESP.restart();
+  } else {
+    Serial.println("Zigbee started successfully!");
+  }
+  Serial.println("Connecting to network");
+  while (!Zigbee.connected()) {
+    Serial.print(".");
+    delay(100);
+  }
+  Serial.println("Connected");
+}
+
+void loop() {
+  static uint32_t timeCounter = 0;
+
+  // Checking button for factory reset and reporting
+  if (digitalRead(button) == LOW) {  // Push button pressed
+    // Key debounce handling
+    delay(100);
+    int startTime = millis();
+    while (digitalRead(button) == LOW) {
+      delay(50);
+      if ((millis() - startTime) > 3000) {
+        // If key pressed for more than 3secs, factory reset Zigbee and reboot
+        Serial.println("Resetting Zigbee to factory and rebooting in 1s.");
+        delay(1000);
+        Zigbee.factoryReset();
+      }
+    }
+    // For demonstration purposes, increment the multistate output/input value by 1
+    if (zbMultistateDevice.getMultistateOutput() < zbMultistateDevice.getMultistateOutputStateNamesLength() - 1) {
+      zbMultistateDevice.setMultistateOutput(zbMultistateDevice.getMultistateOutput() + 1);
+      zbMultistateDevice.reportMultistateOutput();
+      zbMultistateDevice.setMultistateInput(zbMultistateDevice.getMultistateOutput());
+      zbMultistateDevice.reportMultistateInput();
+    } else {
+      zbMultistateDevice.setMultistateOutput(0);
+      zbMultistateDevice.reportMultistateOutput();
+      zbMultistateDevice.setMultistateInput(zbMultistateDevice.getMultistateOutput());
+      zbMultistateDevice.reportMultistateInput();
+    }
+
+    if (zbMultistateDeviceCustom.getMultistateOutput() < zbMultistateDeviceCustom.getMultistateOutputStateNamesLength() - 1) {
+      zbMultistateDeviceCustom.setMultistateOutput(zbMultistateDeviceCustom.getMultistateOutput() + 1);
+      zbMultistateDeviceCustom.reportMultistateOutput();
+    } else {
+      zbMultistateDeviceCustom.setMultistateOutput(0);
+      zbMultistateDeviceCustom.reportMultistateOutput();
+    }
+  }
+  delay(100);
+}

libraries/Zigbee/examples/Zigbee_Multistate_Input_Output/ci.json

@@ -0,0 +1,6 @@
+{
+  "fqbn_append": "PartitionScheme=zigbee_zczr,ZigbeeMode=zczr",
+  "requires": [
+    "CONFIG_ZB_ENABLED=y"
+  ]
+}

libraries/Zigbee/keywords.txt

@@ -26,6 +26,7 @@ ZigbeeFlowSensor	KEYWORD1
 ZigbeeGateway	KEYWORD1
 ZigbeeIlluminanceSensor	KEYWORD1
 ZigbeeLight	KEYWORD1
+ZigbeeMultistate	KEYWORD1
 ZigbeeOccupancySensor	KEYWORD1
 ZigbeePM25Sensor	KEYWORD1
 ZigbeePowerOutlet	KEYWORD1
@@ -222,6 +223,27 @@ getFanMode	KEYWORD2
 getFanModeSequence	KEYWORD2
 onFanModeChange	KEYWORD2
 
+# ZigbeeMultistate
+addMultistateInput	KEYWORD2
+addMultistateOutput	KEYWORD2
+onMultistateOutputChange	KEYWORD2
+setMultistateInput	KEYWORD2
+getMultistateInput	KEYWORD2
+setMultistateOutput	KEYWORD2
+getMultistateOutput	KEYWORD2
+reportMultistateInput	KEYWORD2
+reportMultistateOutput	KEYWORD2
+setMultistateInputApplication	KEYWORD2
+setMultistateInputDescription	KEYWORD2
+setMultistateInputStates	KEYWORD2
+setMultistateOutputApplication	KEYWORD2
+setMultistateOutputDescription	KEYWORD2
+setMultistateOutputStates	KEYWORD2
+getMultistateInputStateNames	KEYWORD2
+getMultistateInputStateNamesLength	KEYWORD2
+getMultistateOutputStateNames	KEYWORD2
+getMultistateOutputStateNamesLength	KEYWORD2
+
 #######################################
 # Constants (LITERAL1)
 #######################################
@@ -236,3 +258,42 @@ ZIGBEE_DEFAULT_RADIO_CONFIG	LITERAL1
 ZIGBEE_DEFAULT_UART_RCP_RADIO_CONFIG	LITERAL1
 ZIGBEE_DEFAULT_HOST_CONFIG	LITERAL1
 ZB_ARRAY_LENGHT	LITERAL1
+
+# ZigbeeMultistate
+ZB_MULTISTATE_APPLICATION_TYPE_0_INDEX	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_0_NUM_STATES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_0_STATE_NAMES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_1_INDEX	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_1_NUM_STATES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_1_STATE_NAMES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_2_INDEX	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_2_NUM_STATES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_2_STATE_NAMES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_3_INDEX	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_3_NUM_STATES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_3_STATE_NAMES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_4_INDEX	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_4_NUM_STATES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_4_STATE_NAMES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_5_INDEX	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_5_NUM_STATES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_5_STATE_NAMES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_6_INDEX	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_6_NUM_STATES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_6_STATE_NAMES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_7_INDEX	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_7_NUM_STATES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_7_STATE_NAMES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_8_INDEX	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_8_NUM_STATES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_8_STATE_NAMES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_9_INDEX	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_9_NUM_STATES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_9_STATE_NAMES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_10_INDEX	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_10_NUM_STATES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_10_STATE_NAMES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_11_INDEX	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_11_NUM_STATES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_11_STATE_NAMES	LITERAL1
+ZB_MULTISTATE_APPLICATION_TYPE_OTHER_INDEX	LITERAL1

libraries/Zigbee/src/Zigbee.h

@@ -28,6 +28,7 @@
 #include "ep/ZigbeeElectricalMeasurement.h"
 #include "ep/ZigbeeFlowSensor.h"
 #include "ep/ZigbeeIlluminanceSensor.h"
+#include "ep/ZigbeeMultistate.h"
 #include "ep/ZigbeeOccupancySensor.h"
 #include "ep/ZigbeePM25Sensor.h"
 #include "ep/ZigbeePressureSensor.h"