diff --git a/docs/en/libraries.rst b/docs/en/libraries.rst index 525a5c4ba26..07f0978be68 100644 --- a/docs/en/libraries.rst +++ b/docs/en/libraries.rst @@ -91,3 +91,15 @@ The Arduino ESP32 offers some unique APIs, described in this section: :glob: api/* + +Zigbee APIs +----------- + +.. toctree:: + :maxdepth: 1 + :glob: + + zigbee/zigbee + zigbee/zigbee_core + zigbee/zigbee_ep + zigbee/ep_* diff --git a/docs/en/zigbee/ep_analog.rst b/docs/en/zigbee/ep_analog.rst new file mode 100644 index 00000000000..45740007881 --- /dev/null +++ b/docs/en/zigbee/ep_analog.rst @@ -0,0 +1,280 @@ +############ +ZigbeeAnalog +############ + +About +----- + +The ``ZigbeeAnalog`` class provides analog input and output endpoints for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for analog signal processing and control. +Analog Input (AI) is meant to be used for sensors that provide an analog signal, such as temperature, humidity, pressure to be sent to the coordinator. +Analog Output (AO) is meant to be used for actuators that require an analog signal, such as dimmers, valves, etc. to be controlled by the coordinator. + + +Common API +---------- + +Constructor +*********** + +ZigbeeAnalog +^^^^^^^^^^^^ + +Creates a new Zigbee analog endpoint. + +.. code-block:: arduino + + ZigbeeAnalog(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +Cluster Management +****************** + +addAnalogInput +^^^^^^^^^^^^^^ + +Adds analog input cluster to the endpoint. + +.. code-block:: arduino + + bool addAnalogInput(); + +This function will return ``true`` if successful, ``false`` otherwise. + +addAnalogOutput +^^^^^^^^^^^^^^^ + +Adds analog output cluster to the endpoint. + +.. code-block:: arduino + + bool addAnalogOutput(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Analog Input API +---------------- + +Configuration Methods +********************* + +setAnalogInputApplication +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sets the application type for the analog input. + +.. code-block:: arduino + + bool setAnalogInputApplication(uint32_t application_type); + +* ``application_type`` - Application type constant (see esp_zigbee_zcl_analog_input.h for values) + +This function will return ``true`` if successful, ``false`` otherwise. + +setAnalogInputDescription +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sets a custom description for the analog input. + +.. code-block:: arduino + + bool setAnalogInputDescription(const char *description); + +* ``description`` - Description string + +This function will return ``true`` if successful, ``false`` otherwise. + +setAnalogInputResolution +^^^^^^^^^^^^^^^^^^^^^^^^ + +Sets the resolution for the analog input. + +.. code-block:: arduino + + bool setAnalogInputResolution(float resolution); + +* ``resolution`` - Resolution value + +This function will return ``true`` if successful, ``false`` otherwise. + +setAnalogInputMinMax +^^^^^^^^^^^^^^^^^^^^ + +Sets the minimum and maximum values for the analog input. + +.. code-block:: arduino + + bool setAnalogInputMinMax(float min, float max); + +* ``min`` - Minimum value +* ``max`` - Maximum value + +This function will return ``true`` if successful, ``false`` otherwise. + +Value Control +************* + +setAnalogInput +^^^^^^^^^^^^^^ + +Sets the analog input value. + +.. code-block:: arduino + + bool setAnalogInput(float analog); + +* ``analog`` - Analog input value + +This function will return ``true`` if successful, ``false`` otherwise. + +Reporting Methods +***************** + +setAnalogInputReporting +^^^^^^^^^^^^^^^^^^^^^^^ + +Sets the reporting configuration for analog input. + +.. code-block:: arduino + + bool setAnalogInputReporting(uint16_t min_interval, uint16_t max_interval, float delta); + +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change in value to trigger a report + +This function will return ``true`` if successful, ``false`` otherwise. + +reportAnalogInput +^^^^^^^^^^^^^^^^^ + +Manually reports the current analog input value. + +.. code-block:: arduino + + bool reportAnalogInput(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Analog Output API +----------------- + +Configuration Methods +********************* + +setAnalogOutputApplication +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sets the application type for the analog output. + +.. code-block:: arduino + + bool setAnalogOutputApplication(uint32_t application_type); + +* ``application_type`` - Application type constant (see esp_zigbee_zcl_analog_output.h for values) + +This function will return ``true`` if successful, ``false`` otherwise. + +setAnalogOutputDescription +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sets a custom description for the analog output. + +.. code-block:: arduino + + bool setAnalogOutputDescription(const char *description); + +* ``description`` - Description string + +This function will return ``true`` if successful, ``false`` otherwise. + +setAnalogOutputResolution +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sets the resolution for the analog output. + +.. code-block:: arduino + + bool setAnalogOutputResolution(float resolution); + +* ``resolution`` - Resolution value + +This function will return ``true`` if successful, ``false`` otherwise. + +setAnalogOutputMinMax +^^^^^^^^^^^^^^^^^^^^^ + +Sets the minimum and maximum values for the analog output. + +.. code-block:: arduino + + bool setAnalogOutputMinMax(float min, float max); + +* ``min`` - Minimum value +* ``max`` - Maximum value + +This function will return ``true`` if successful, ``false`` otherwise. + +Value Control +************* + +setAnalogOutput +^^^^^^^^^^^^^^^ + +Sets the analog output value. + +.. code-block:: arduino + + bool setAnalogOutput(float analog); + +* ``analog`` - Analog output value + +This function will return ``true`` if successful, ``false`` otherwise. + +getAnalogOutput +^^^^^^^^^^^^^^^ + +Gets the current analog output value. + +.. code-block:: arduino + + float getAnalogOutput(); + +This function will return current analog output value. + +Reporting Methods +***************** + +reportAnalogOutput +^^^^^^^^^^^^^^^^^^ + +Manually reports the current analog output value. + +.. code-block:: arduino + + bool reportAnalogOutput(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Event Handling +************** + +onAnalogOutputChange +^^^^^^^^^^^^^^^^^^^^ + +Sets a callback function to be called when the analog output value changes. + +.. code-block:: arduino + + void onAnalogOutputChange(void (*callback)(float analog)); + +* ``callback`` - Function to call when analog output changes + +Example +------- + +Analog Input/Output +******************* + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Analog_Input_Output/Zigbee_Analog_Input_Output.ino + :language: arduino diff --git a/docs/en/zigbee/ep_binary.rst b/docs/en/zigbee/ep_binary.rst new file mode 100644 index 00000000000..950e20ef42b --- /dev/null +++ b/docs/en/zigbee/ep_binary.rst @@ -0,0 +1,137 @@ +############ +ZigbeeBinary +############ + +About +----- + +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. +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. + +.. note:: + + Binary Output (BO) is not supported yet. + +API Reference +------------- + +Constructor +*********** + +ZigbeeBinary +^^^^^^^^^^^^ + +Creates a new Zigbee binary sensor endpoint. + +.. code-block:: arduino + + ZigbeeBinary(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +Binary Input Application Types +****************************** + +HVAC Application Types +^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: arduino + + #define BINARY_INPUT_APPLICATION_TYPE_HVAC_BOILER_STATUS 0x00000003 + #define BINARY_INPUT_APPLICATION_TYPE_HVAC_CHILLER_STATUS 0x00000013 + #define BINARY_INPUT_APPLICATION_TYPE_HVAC_OCCUPANCY 0x00000031 + #define BINARY_INPUT_APPLICATION_TYPE_HVAC_FAN_STATUS 0x00000035 + #define BINARY_INPUT_APPLICATION_TYPE_HVAC_FILTER_STATUS 0x00000036 + #define BINARY_INPUT_APPLICATION_TYPE_HVAC_HEATING_ALARM 0x0000003E + #define BINARY_INPUT_APPLICATION_TYPE_HVAC_COOLING_ALARM 0x0000001D + #define BINARY_INPUT_APPLICATION_TYPE_HVAC_UNIT_ENABLE 0x00000090 + #define BINARY_INPUT_APPLICATION_TYPE_HVAC_OTHER 0x0000FFFF + +Security Application Types +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: arduino + + #define BINARY_INPUT_APPLICATION_TYPE_SECURITY_GLASS_BREAKAGE_DETECTION_0 0x01000000 + #define BINARY_INPUT_APPLICATION_TYPE_SECURITY_INTRUSION_DETECTION 0x01000001 + #define BINARY_INPUT_APPLICATION_TYPE_SECURITY_MOTION_DETECTION 0x01000002 + #define BINARY_INPUT_APPLICATION_TYPE_SECURITY_GLASS_BREAKAGE_DETECTION_1 0x01000003 + #define BINARY_INPUT_APPLICATION_TYPE_SECURITY_ZONE_ARMED 0x01000004 + #define BINARY_INPUT_APPLICATION_TYPE_SECURITY_GLASS_BREAKAGE_DETECTION_2 0x01000005 + #define BINARY_INPUT_APPLICATION_TYPE_SECURITY_SMOKE_DETECTION 0x01000006 + #define BINARY_INPUT_APPLICATION_TYPE_SECURITY_CARBON_DIOXIDE_DETECTION 0x01000007 + #define BINARY_INPUT_APPLICATION_TYPE_SECURITY_HEAT_DETECTION 0x01000008 + #define BINARY_INPUT_APPLICATION_TYPE_SECURITY_OTHER 0x0100FFFF + +API Methods +*********** + +addBinaryInput +^^^^^^^^^^^^^^ + +Adds a binary input cluster to the endpoint. + +.. code-block:: arduino + + bool addBinaryInput(); + +This function will return ``true`` if successful, ``false`` otherwise. + +setBinaryInputApplication +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sets the application type for the binary input. + +.. code-block:: arduino + + bool setBinaryInputApplication(uint32_t application_type); + +* ``application_type`` - Application type constant (see above) + +This function will return ``true`` if successful, ``false`` otherwise. + +setBinaryInputDescription +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Sets a custom description for the binary input. + +.. code-block:: arduino + + bool setBinaryInputDescription(const char *description); + +* ``description`` - Description string + +This function will return ``true`` if successful, ``false`` otherwise. + +setBinaryInput +^^^^^^^^^^^^^^ + +Sets the binary input value. + +.. code-block:: arduino + + bool setBinaryInput(bool input); + +* ``input`` - Binary value (true/false) + +This function will return ``true`` if successful, ``false`` otherwise. + +reportBinaryInput +^^^^^^^^^^^^^^^^^ + +Manually reports the current binary input value. + +.. code-block:: arduino + + bool reportBinaryInput(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Example +------- + +Binary Input Implementation +**************************** + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Binary_Input/Zigbee_Binary_Input.ino + :language: arduino diff --git a/docs/en/zigbee/ep_carbon_dioxide_sensor.rst b/docs/en/zigbee/ep_carbon_dioxide_sensor.rst new file mode 100644 index 00000000000..6f219a16fd0 --- /dev/null +++ b/docs/en/zigbee/ep_carbon_dioxide_sensor.rst @@ -0,0 +1,105 @@ +######################### +ZigbeeCarbonDioxideSensor +######################### + +About +----- + +The ``ZigbeeCarbonDioxideSensor`` class provides a CO2 sensor endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for carbon dioxide measurement devices. + +API Reference +------------- + +Constructor +*********** + +ZigbeeCarbonDioxideSensor +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee CO2 sensor endpoint. + +.. code-block:: arduino + + ZigbeeCarbonDioxideSensor(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +API Methods +*********** + +setCarbonDioxide +^^^^^^^^^^^^^^^^ + +Sets the CO2 concentration measurement value. + +.. code-block:: arduino + + bool setCarbonDioxide(float carbon_dioxide); + +* ``carbon_dioxide`` - CO2 concentration value in ppm + +This function will return ``true`` if successful, ``false`` otherwise. + +setMinMaxValue +^^^^^^^^^^^^^^ + +Sets the minimum and maximum measurement values. + +.. code-block:: arduino + + bool setMinMaxValue(float min, float max); + +* ``min`` - Minimum CO2 concentration value in ppm +* ``max`` - Maximum CO2 concentration value in ppm + +This function will return ``true`` if successful, ``false`` otherwise. + +setTolerance +^^^^^^^^^^^^ + +Sets the tolerance value for measurements. + +.. code-block:: arduino + + bool setTolerance(float tolerance); + +* ``tolerance`` - Tolerance value in ppm + +This function will return ``true`` if successful, ``false`` otherwise. + +setReporting +^^^^^^^^^^^^ + +Sets the reporting configuration for CO2 measurements. + +.. code-block:: arduino + + bool setReporting(uint16_t min_interval, uint16_t max_interval, uint16_t delta); + +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change required to trigger a report in ppm + +**Note:** Delta reporting is currently not supported by the carbon dioxide sensor. + +This function will return ``true`` if successful, ``false`` otherwise. + +report +^^^^^^ + +Manually reports the current CO2 concentration value. + +.. code-block:: arduino + + bool report(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Example +------- + +CO2 Sensor Implementation +************************* + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_CarbonDioxide_Sensor/Zigbee_CarbonDioxide_Sensor.ino + :language: arduino diff --git a/docs/en/zigbee/ep_color_dimmable_light.rst b/docs/en/zigbee/ep_color_dimmable_light.rst new file mode 100644 index 00000000000..b2fa6d0bf91 --- /dev/null +++ b/docs/en/zigbee/ep_color_dimmable_light.rst @@ -0,0 +1,223 @@ +######################## +ZigbeeColorDimmableLight +######################## + +About +----- + +The ``ZigbeeColorDimmableLight`` class provides an endpoint for color dimmable lights in Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for color lighting devices, supporting RGB color control, dimming, and scene management. + +**Features:** +* On/off control +* Brightness level control (0-100%) +* RGB color control +* HSV color support +* Scene and group support +* Automatic state restoration +* Integration with common endpoint features (binding, OTA, etc.) +* Zigbee HA standard compliance + +**Use Cases:** +* Smart RGB light bulbs +* Color-changing LED strips +* Mood lighting systems +* Entertainment lighting +* Architectural lighting +* Smart home color lighting + +API Reference +------------- + +Constructor +*********** + +ZigbeeColorDimmableLight +^^^^^^^^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee color dimmable light endpoint. + +.. code-block:: arduino + + ZigbeeColorDimmableLight(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +Callback Functions +****************** + +onLightChange +^^^^^^^^^^^^^ + +Sets the callback function for light state changes. + +.. code-block:: arduino + + void onLightChange(void (*callback)(bool, uint8_t, uint8_t, uint8_t, uint8_t)); + +* ``callback`` - Function pointer to the light change callback (state, red, green, blue, level) + +Control Methods +*************** + +setLightState +^^^^^^^^^^^^^ + +Sets the light on/off state. + +.. code-block:: arduino + + bool setLightState(bool state); + +* ``state`` - Light state (true = on, false = off) + +This function will return ``true`` if successful, ``false`` otherwise. + +setLightLevel +^^^^^^^^^^^^^ + +Sets the light brightness level. + +.. code-block:: arduino + + bool setLightLevel(uint8_t level); + +* ``level`` - Brightness level (0-100, where 0 is off, 100 is full brightness) + +This function will return ``true`` if successful, ``false`` otherwise. + +setLightColor (RGB) +^^^^^^^^^^^^^^^^^^^ + +Sets the light color using RGB values. + +.. code-block:: arduino + + bool setLightColor(uint8_t red, uint8_t green, uint8_t blue); + bool setLightColor(espRgbColor_t rgb_color); + +* ``red`` - Red component (0-255) +* ``green`` - Green component (0-255) +* ``blue`` - Blue component (0-255) +* ``rgb_color`` - RGB color structure + +This function will return ``true`` if successful, ``false`` otherwise. + +setLightColor (HSV) +^^^^^^^^^^^^^^^^^^^ + +Sets the light color using HSV values. + +.. code-block:: arduino + + bool setLightColor(espHsvColor_t hsv_color); + +* ``hsv_color`` - HSV color structure + +This function will return ``true`` if successful, ``false`` otherwise. + +setLight +^^^^^^^^ + +Sets all light parameters at once. + +.. code-block:: arduino + + bool setLight(bool state, uint8_t level, uint8_t red, uint8_t green, uint8_t blue); + +* ``state`` - Light state (true/false) +* ``level`` - Brightness level (0-100) +* ``red`` - Red component (0-255) +* ``green`` - Green component (0-255) +* ``blue`` - Blue component (0-255) + +This function will return ``true`` if successful, ``false`` otherwise. + +State Retrieval Methods +*********************** + +getLightState +^^^^^^^^^^^^^ + +Gets the current light state. + +.. code-block:: arduino + + bool getLightState(); + +This function will return current light state (true = on, false = off). + +getLightLevel +^^^^^^^^^^^^^ + +Gets the current brightness level. + +.. code-block:: arduino + + uint8_t getLightLevel(); + +This function will return current brightness level (0-100). + +getLightColor +^^^^^^^^^^^^^ + +Gets the current RGB color. + +.. code-block:: arduino + + espRgbColor_t getLightColor(); + +This function will return current RGB color structure. + +getLightRed +^^^^^^^^^^^ + +Gets the current red component. + +.. code-block:: arduino + + uint8_t getLightRed(); + +This function will return current red component (0-255). + +getLightGreen +^^^^^^^^^^^^^ + +Gets the current green component. + +.. code-block:: arduino + + uint8_t getLightGreen(); + +This function will return current green component (0-255). + +getLightBlue +^^^^^^^^^^^^ + +Gets the current blue component. + +.. code-block:: arduino + + uint8_t getLightBlue(); + +This function will return current blue component (0-255). + +Utility Methods +*************** + +restoreLight +^^^^^^^^^^^^ + +Restores the light to its last known state. + +.. code-block:: arduino + + void restoreLight(); + +Example +------- + +Color Dimmable Light Implementation +*********************************** + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Color_Dimmable_Light/Zigbee_Color_Dimmable_Light.ino + :language: arduino diff --git a/docs/en/zigbee/ep_color_dimmer_switch.rst b/docs/en/zigbee/ep_color_dimmer_switch.rst new file mode 100644 index 00000000000..720c5d8f5bf --- /dev/null +++ b/docs/en/zigbee/ep_color_dimmer_switch.rst @@ -0,0 +1,186 @@ +####################### +ZigbeeColorDimmerSwitch +####################### + +About +----- + +The ``ZigbeeColorDimmerSwitch`` class provides a color dimmer switch endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for advanced lighting control switches that can control both dimming and color of lights. + +**Features:** +* On/off control for bound lights +* Brightness level control (0-100%) +* Color control (RGB, HSV) +* Color temperature control +* Scene and group support +* Special effects and timed operations +* Integration with common endpoint features (binding, OTA, etc.) +* Zigbee HA standard compliance + +**Use Cases:** +* Smart lighting switches +* Color control remotes +* Advanced lighting controllers +* Smart home lighting automation +* Entertainment lighting control + +API Reference +------------- + +Constructor +*********** + +ZigbeeColorDimmerSwitch +^^^^^^^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee color dimmer switch endpoint. + +.. code-block:: arduino + + ZigbeeColorDimmerSwitch(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +Basic Control Commands +********************** + +lightToggle +^^^^^^^^^^^ + +Toggles the state of bound lights (on to off, or off to on). + +.. code-block:: arduino + + void lightToggle(); + void lightToggle(uint16_t group_addr); + void lightToggle(uint8_t endpoint, uint16_t short_addr); + void lightToggle(uint8_t endpoint, esp_zb_ieee_addr_t ieee_addr); + +* ``group_addr`` - Group address to control (optional) +* ``endpoint`` - Target device endpoint (optional) +* ``short_addr`` - Target device short address (optional) +* ``ieee_addr`` - Target device IEEE address (optional) + +lightOn +^^^^^^^ + +Turns on bound lights. + +.. code-block:: arduino + + void lightOn(); + void lightOn(uint16_t group_addr); + void lightOn(uint8_t endpoint, uint16_t short_addr); + void lightOn(uint8_t endpoint, esp_zb_ieee_addr_t ieee_addr); + +* ``group_addr`` - Group address to control (optional) +* ``endpoint`` - Target device endpoint (optional) +* ``short_addr`` - Target device short address (optional) +* ``ieee_addr`` - Target device IEEE address (optional) + +lightOff +^^^^^^^^ + +Turns off bound lights. + +.. code-block:: arduino + + void lightOff(); + void lightOff(uint16_t group_addr); + void lightOff(uint8_t endpoint, uint16_t short_addr); + void lightOff(uint8_t endpoint, esp_zb_ieee_addr_t ieee_addr); + +* ``group_addr`` - Group address to control (optional) +* ``endpoint`` - Target device endpoint (optional) +* ``short_addr`` - Target device short address (optional) +* ``ieee_addr`` - Target device IEEE address (optional) + +Dimmer Control Commands +*********************** + +setLightLevel +^^^^^^^^^^^^^ + +Sets the brightness level of bound lights. + +.. code-block:: arduino + + void setLightLevel(uint8_t level); + void setLightLevel(uint8_t level, uint16_t group_addr); + void setLightLevel(uint8_t level, uint8_t endpoint, uint16_t short_addr); + void setLightLevel(uint8_t level, uint8_t endpoint, esp_zb_ieee_addr_t ieee_addr); + +* ``level`` - Brightness level (0-100, where 0 is off, 100 is full brightness) +* ``group_addr`` - Group address to control (optional) +* ``endpoint`` - Target device endpoint (optional) +* ``short_addr`` - Target device short address (optional) +* ``ieee_addr`` - Target device IEEE address (optional) + +Color Control Commands +********************** + +setLightColor +^^^^^^^^^^^^^ + +Sets the color of bound lights using RGB values. + +.. code-block:: arduino + + void setLightColor(uint8_t red, uint8_t green, uint8_t blue); + void setLightColor(uint8_t red, uint8_t green, uint8_t blue, uint16_t group_addr); + void setLightColor(uint8_t red, uint8_t green, uint8_t blue, uint8_t endpoint, uint16_t short_addr); + void setLightColor(uint8_t red, uint8_t green, uint8_t blue, uint8_t endpoint, esp_zb_ieee_addr_t ieee_addr); + +* ``red`` - Red component (0-255) +* ``green`` - Green component (0-255) +* ``blue`` - Blue component (0-255) +* ``group_addr`` - Group address to control (optional) +* ``endpoint`` - Target device endpoint (optional) +* ``short_addr`` - Target device short address (optional) +* ``ieee_addr`` - Target device IEEE address (optional) + +Advanced Control Commands +************************* + +lightOffWithEffect +^^^^^^^^^^^^^^^^^^ + +Turns off lights with a specific effect. + +.. code-block:: arduino + + void lightOffWithEffect(uint8_t effect_id, uint8_t effect_variant); + +* ``effect_id`` - Effect identifier +* ``effect_variant`` - Effect variant + +lightOnWithTimedOff +^^^^^^^^^^^^^^^^^^^ + +Turns on lights with automatic turn-off after specified time. + +.. code-block:: arduino + + void lightOnWithTimedOff(uint8_t on_off_control, uint16_t time_on, uint16_t time_off); + +* ``on_off_control`` - Control byte +* ``time_on`` - Time to stay on (in 1/10th seconds) +* ``time_off`` - Time to stay off (in 1/10th seconds) + +lightOnWithSceneRecall +^^^^^^^^^^^^^^^^^^^^^^ + +Turns on lights with scene recall. + +.. code-block:: arduino + + void lightOnWithSceneRecall(); + +Example +------- + +Color Dimmer Switch Implementation +********************************** + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Color_Dimmer_Switch/Zigbee_Color_Dimmer_Switch.ino + :language: arduino diff --git a/docs/en/zigbee/ep_contact_switch.rst b/docs/en/zigbee/ep_contact_switch.rst new file mode 100644 index 00000000000..f7f6dc15c66 --- /dev/null +++ b/docs/en/zigbee/ep_contact_switch.rst @@ -0,0 +1,95 @@ +################### +ZigbeeContactSwitch +################### + +About +----- + +The ``ZigbeeContactSwitch`` class provides a contact switch endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for door/window contact sensors and other binary contact devices. + +**Features:** +* Contact state detection (open/closed) +* Configurable application types +* Automatic reporting capabilities +* Integration with common endpoint features (binding, OTA, etc.) +* Zigbee HA standard compliance + +**Use Cases:** +* Door and window sensors +* Security system contacts +* Cabinet and drawer sensors +* Industrial contact monitoring +* Smart home security applications + +API Reference +------------- + +Constructor +*********** + +ZigbeeContactSwitch +^^^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee contact switch endpoint. + +.. code-block:: arduino + + ZigbeeContactSwitch(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +API Methods +*********** + +setClosed +^^^^^^^^^ + +Sets the contact switch to closed state. + +.. code-block:: arduino + + bool setClosed(); + +This function will return ``true`` if successful, ``false`` otherwise. + +setOpen +^^^^^^^ + +Sets the contact switch to open state. + +.. code-block:: arduino + + bool setOpen(); + +This function will return ``true`` if successful, ``false`` otherwise. + +setIASClientEndpoint +^^^^^^^^^^^^^^^^^^^^ + +Sets the IAS Client endpoint number (default is 1). + +.. code-block:: arduino + + void setIASClientEndpoint(uint8_t ep_number); + +* ``ep_number`` - IAS Client endpoint number + +report +^^^^^^ + +Manually reports the current contact state. + +.. code-block:: arduino + + bool report(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Example +------- + +Contact Switch Implementation +***************************** + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Contact_Switch/Zigbee_Contact_Switch.ino + :language: arduino diff --git a/docs/en/zigbee/ep_dimmable_light.rst b/docs/en/zigbee/ep_dimmable_light.rst new file mode 100644 index 00000000000..3eeec3a3308 --- /dev/null +++ b/docs/en/zigbee/ep_dimmable_light.rst @@ -0,0 +1,138 @@ +################### +ZigbeeDimmableLight +################### + +About +----- + +The ``ZigbeeDimmableLight`` class provides a dimmable light endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for dimmable lighting control with both on/off and brightness level control. + +**Features:** +* On/off control +* Brightness level control (0-100%) +* State and level change callbacks +* Integration with common endpoint features (binding, OTA, etc.) +* Zigbee HA standard compliance + +**Use Cases:** +* Dimmable smart bulbs +* LED strips with brightness control +* Any device requiring both on/off and dimming functionality + +API Reference +------------- + +Constructor +*********** + +ZigbeeDimmableLight +^^^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee dimmable light endpoint. + +.. code-block:: arduino + + ZigbeeDimmableLight(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +Light Control +************* + +setLightState +^^^^^^^^^^^^^ + +Sets only the light state (on or off) without changing the brightness level. + +.. code-block:: arduino + + bool setLightState(bool state); + +* ``state`` - ``true`` to turn on, ``false`` to turn off + +This function will return ``true`` if successful, ``false`` otherwise. + +setLightLevel +^^^^^^^^^^^^^ + +Sets only the brightness level (0-100) without changing the on/off state. + +.. code-block:: arduino + + bool setLightLevel(uint8_t level); + +* ``level`` - Brightness level (0-100, where 0 is off, 100 is full brightness) + +This function will return ``true`` if successful, ``false`` otherwise. + +setLight +^^^^^^^^ + +Sets both the light state and brightness level simultaneously. + +.. code-block:: arduino + + bool setLight(bool state, uint8_t level); + +* ``state`` - ``true`` to turn on, ``false`` to turn off +* ``level`` - Brightness level (0-100) + +This function will return ``true`` if successful, ``false`` otherwise. + +getLightState +^^^^^^^^^^^^^ + +Gets the current light state. + +.. code-block:: arduino + + bool getLightState(); + +This function will return current light state (``true`` = on, ``false`` = off). + +getLightLevel +^^^^^^^^^^^^^ + +Gets the current brightness level. + +.. code-block:: arduino + + uint8_t getLightLevel(); + +This function will return current brightness level (0-100). + +restoreLight +^^^^^^^^^^^^ + +Restores the light state and triggers any registered callbacks. + +.. code-block:: arduino + + void restoreLight(); + +Event Handling +************** + +onLightChange +^^^^^^^^^^^^^ + +Sets a callback function to be called when the light state or level changes. + +.. code-block:: arduino + + void onLightChange(void (*callback)(bool, uint8_t)); + +* ``callback`` - Function to call when light state or level changes + +**Callback Parameters:** +* ``bool state`` - New light state (true = on, false = off) +* ``uint8_t level`` - New brightness level (0-100) + +Example +------- + +Dimmable Light Implementation +***************************** + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Dimmable_Light/Zigbee_Dimmable_Light.ino + :language: arduino \ No newline at end of file diff --git a/docs/en/zigbee/ep_door_window_handle.rst b/docs/en/zigbee/ep_door_window_handle.rst new file mode 100644 index 00000000000..53203f463dd --- /dev/null +++ b/docs/en/zigbee/ep_door_window_handle.rst @@ -0,0 +1,95 @@ +###################### +ZigbeeDoorWindowHandle +###################### + +About +----- + +The ``ZigbeeDoorWindowHandle`` class provides a door/window handle endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for handle position sensors and other handle-related devices. + +**Features:** +* Handle position detection +* Multiple position states support +* Configurable application types +* Automatic reporting capabilities + + +API Reference +------------- + +Constructor +*********** + +ZigbeeDoorWindowHandle +^^^^^^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee door/window handle endpoint. + +.. code-block:: arduino + + ZigbeeDoorWindowHandle(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +API Methods +*********** + +setClosed +^^^^^^^^^ + +Sets the door/window handle to closed position. + +.. code-block:: arduino + + bool setClosed(); + +This function will return ``true`` if successful, ``false`` otherwise. + +setOpen +^^^^^^^ + +Sets the door/window handle to open position. + +.. code-block:: arduino + + bool setOpen(); + +This function will return ``true`` if successful, ``false`` otherwise. + +setTilted +^^^^^^^^^ + +Sets the door/window handle to tilted position. + +.. code-block:: arduino + + bool setTilted(); + +This function will return ``true`` if successful, ``false`` otherwise. + +setIASClientEndpoint +^^^^^^^^^^^^^^^^^^^^ + +Sets the IAS Client endpoint number (default is 1). + +.. code-block:: arduino + + void setIASClientEndpoint(uint8_t ep_number); + +* ``ep_number`` - IAS Client endpoint number + +report +^^^^^^ + +Manually reports the current handle position. + +.. code-block:: arduino + + bool report(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Example +------- + +*To be added* diff --git a/docs/en/zigbee/ep_electrical_measurement.rst b/docs/en/zigbee/ep_electrical_measurement.rst new file mode 100644 index 00000000000..11d86249f74 --- /dev/null +++ b/docs/en/zigbee/ep_electrical_measurement.rst @@ -0,0 +1,255 @@ +########################### +ZigbeeElectricalMeasurement +########################### + +About +----- + +The ``ZigbeeElectricalMeasurement`` class provides an endpoint for electrical measurement devices in Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for power monitoring and electrical measurement. + +**Features:** +* AC and DC electrical measurements +* Voltage, current, and power monitoring +* Power factor measurement +* Multi-phase support +* Configurable measurement ranges +* Automatic reporting capabilities +* Integration with common endpoint features (binding, OTA, etc.) +* Zigbee HA standard compliance + +**Use Cases:** +* Smart power meters +* Energy monitoring systems +* Industrial power monitoring +* Solar panel monitoring +* Battery monitoring systems +* Electrical load monitoring + +Common API +---------- + +Constructor +*********** + +ZigbeeElectricalMeasurement +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee electrical measurement endpoint. + +.. code-block:: arduino + + ZigbeeElectricalMeasurement(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +DC Electrical Measurement +************************* + +addDCMeasurement +^^^^^^^^^^^^^^^^ + +Adds a DC measurement type to the endpoint. + +.. code-block:: arduino + + bool addDCMeasurement(ZIGBEE_DC_MEASUREMENT_TYPE measurement_type); + +* ``measurement_type`` - DC measurement type constant (ZIGBEE_DC_MEASUREMENT_TYPE_VOLTAGE, ZIGBEE_DC_MEASUREMENT_TYPE_CURRENT, ZIGBEE_DC_MEASUREMENT_TYPE_POWER) + +This function will return ``true`` if successful, ``false`` otherwise. + +setDCMeasurement +^^^^^^^^^^^^^^^^ + +Sets the DC measurement value for a specific measurement type. + +.. code-block:: arduino + + bool setDCMeasurement(ZIGBEE_DC_MEASUREMENT_TYPE measurement_type, int16_t value); + +* ``measurement_type`` - DC measurement type constant (ZIGBEE_DC_MEASUREMENT_TYPE_VOLTAGE, ZIGBEE_DC_MEASUREMENT_TYPE_CURRENT, ZIGBEE_DC_MEASUREMENT_TYPE_POWER) +* ``value`` - Measurement value + +This function will return ``true`` if successful, ``false`` otherwise. + +setDCMinMaxValue +^^^^^^^^^^^^^^^^ + +Sets the minimum and maximum values for a DC measurement type. + +.. code-block:: arduino + + bool setDCMinMaxValue(ZIGBEE_DC_MEASUREMENT_TYPE measurement_type, int16_t min, int16_t max); + +* ``measurement_type`` - DC measurement type constant (ZIGBEE_DC_MEASUREMENT_TYPE_VOLTAGE, ZIGBEE_DC_MEASUREMENT_TYPE_CURRENT, ZIGBEE_DC_MEASUREMENT_TYPE_POWER) +* ``min`` - Minimum value +* ``max`` - Maximum value + +This function will return ``true`` if successful, ``false`` otherwise. + +setDCMultiplierDivisor +^^^^^^^^^^^^^^^^^^^^^^ + +Sets the multiplier and divisor for scaling DC measurements. + +.. code-block:: arduino + + bool setDCMultiplierDivisor(ZIGBEE_DC_MEASUREMENT_TYPE measurement_type, uint16_t multiplier, uint16_t divisor); + +* ``measurement_type`` - DC measurement type constant (ZIGBEE_DC_MEASUREMENT_TYPE_VOLTAGE, ZIGBEE_DC_MEASUREMENT_TYPE_CURRENT, ZIGBEE_DC_MEASUREMENT_TYPE_POWER) +* ``multiplier`` - Multiplier value +* ``divisor`` - Divisor value + +This function will return ``true`` if successful, ``false`` otherwise. + +setDCReporting +^^^^^^^^^^^^^^ + +Sets the reporting configuration for DC measurements. + +.. code-block:: arduino + + bool setDCReporting(ZIGBEE_DC_MEASUREMENT_TYPE measurement_type, uint16_t min_interval, uint16_t max_interval, int16_t delta); + +* ``measurement_type`` - DC measurement type constant (ZIGBEE_DC_MEASUREMENT_TYPE_VOLTAGE, ZIGBEE_DC_MEASUREMENT_TYPE_CURRENT, ZIGBEE_DC_MEASUREMENT_TYPE_POWER) +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change required to trigger a report + +This function will return ``true`` if successful, ``false`` otherwise. + +reportDC +^^^^^^^^ + +Manually reports a DC measurement value. + +.. code-block:: arduino + + bool reportDC(ZIGBEE_DC_MEASUREMENT_TYPE measurement_type); + +* ``measurement_type`` - DC measurement type constant (ZIGBEE_DC_MEASUREMENT_TYPE_VOLTAGE, ZIGBEE_DC_MEASUREMENT_TYPE_CURRENT, ZIGBEE_DC_MEASUREMENT_TYPE_POWER) + +This function will return ``true`` if successful, ``false`` otherwise. + +AC Electrical Measurement +************************* + +addACMeasurement +^^^^^^^^^^^^^^^^ + +Adds an AC measurement type for a specific phase. + +.. code-block:: arduino + + bool addACMeasurement(ZIGBEE_AC_MEASUREMENT_TYPE measurement_type, ZIGBEE_AC_PHASE_TYPE phase_type); + +* ``measurement_type`` - AC measurement type constant (ZIGBEE_AC_MEASUREMENT_TYPE_VOLTAGE, ZIGBEE_AC_MEASUREMENT_TYPE_CURRENT, ZIGBEE_AC_MEASUREMENT_TYPE_POWER, ZIGBEE_AC_MEASUREMENT_TYPE_POWER_FACTOR, ZIGBEE_AC_MEASUREMENT_TYPE_FREQUENCY) +* ``phase_type`` - Phase type constant (ZIGBEE_AC_PHASE_TYPE_NON_SPECIFIC, ZIGBEE_AC_PHASE_TYPE_A, ZIGBEE_AC_PHASE_TYPE_B, ZIGBEE_AC_PHASE_TYPE_C) + +This function will return ``true`` if successful, ``false`` otherwise. + +setACMeasurement +^^^^^^^^^^^^^^^^ + +Sets the AC measurement value for a specific measurement type and phase. + +.. code-block:: arduino + + bool setACMeasurement(ZIGBEE_AC_MEASUREMENT_TYPE measurement_type, ZIGBEE_AC_PHASE_TYPE phase_type, int32_t value); + +* ``measurement_type`` - AC measurement type constant (ZIGBEE_AC_MEASUREMENT_TYPE_VOLTAGE, ZIGBEE_AC_MEASUREMENT_TYPE_CURRENT, ZIGBEE_AC_MEASUREMENT_TYPE_POWER, ZIGBEE_AC_MEASUREMENT_TYPE_POWER_FACTOR, ZIGBEE_AC_MEASUREMENT_TYPE_FREQUENCY) +* ``phase_type`` - Phase type constant (ZIGBEE_AC_PHASE_TYPE_NON_SPECIFIC, ZIGBEE_AC_PHASE_TYPE_A, ZIGBEE_AC_PHASE_TYPE_B, ZIGBEE_AC_PHASE_TYPE_C) +* ``value`` - Measurement value + +This function will return ``true`` if successful, ``false`` otherwise. + +setACMinMaxValue +^^^^^^^^^^^^^^^^ + +Sets the minimum and maximum values for an AC measurement type and phase. + +.. code-block:: arduino + + bool setACMinMaxValue(ZIGBEE_AC_MEASUREMENT_TYPE measurement_type, ZIGBEE_AC_PHASE_TYPE phase_type, int32_t min, int32_t max); + +* ``measurement_type`` - AC measurement type constant (ZIGBEE_AC_MEASUREMENT_TYPE_VOLTAGE, ZIGBEE_AC_MEASUREMENT_TYPE_CURRENT, ZIGBEE_AC_MEASUREMENT_TYPE_POWER, ZIGBEE_AC_MEASUREMENT_TYPE_POWER_FACTOR, ZIGBEE_AC_MEASUREMENT_TYPE_FREQUENCY) +* ``phase_type`` - Phase type constant (ZIGBEE_AC_PHASE_TYPE_NON_SPECIFIC, ZIGBEE_AC_PHASE_TYPE_A, ZIGBEE_AC_PHASE_TYPE_B, ZIGBEE_AC_PHASE_TYPE_C) +* ``min`` - Minimum value +* ``max`` - Maximum value + +This function will return ``true`` if successful, ``false`` otherwise. + +setACMultiplierDivisor +^^^^^^^^^^^^^^^^^^^^^^ + +Sets the multiplier and divisor for scaling AC measurements. + +.. code-block:: arduino + + bool setACMultiplierDivisor(ZIGBEE_AC_MEASUREMENT_TYPE measurement_type, uint16_t multiplier, uint16_t divisor); + +* ``measurement_type`` - AC measurement type constant (ZIGBEE_AC_MEASUREMENT_TYPE_VOLTAGE, ZIGBEE_AC_MEASUREMENT_TYPE_CURRENT, ZIGBEE_AC_MEASUREMENT_TYPE_POWER, ZIGBEE_AC_MEASUREMENT_TYPE_POWER_FACTOR, ZIGBEE_AC_MEASUREMENT_TYPE_FREQUENCY) +* ``multiplier`` - Multiplier value +* ``divisor`` - Divisor value + +This function will return ``true`` if successful, ``false`` otherwise. + +setACPowerFactor +^^^^^^^^^^^^^^^^ + +Sets the power factor for a specific phase. + +.. code-block:: arduino + + bool setACPowerFactor(ZIGBEE_AC_PHASE_TYPE phase_type, int8_t power_factor); + +* ``phase_type`` - Phase type constant (ZIGBEE_AC_PHASE_TYPE_NON_SPECIFIC, ZIGBEE_AC_PHASE_TYPE_A, ZIGBEE_AC_PHASE_TYPE_B, ZIGBEE_AC_PHASE_TYPE_C) +* ``power_factor`` - Power factor value (-100 to 100) + +This function will return ``true`` if successful, ``false`` otherwise. + +setACReporting +^^^^^^^^^^^^^^ + +Sets the reporting configuration for AC measurements. + +.. code-block:: arduino + + bool setACReporting(ZIGBEE_AC_MEASUREMENT_TYPE measurement_type, ZIGBEE_AC_PHASE_TYPE phase_type, uint16_t min_interval, uint16_t max_interval, int32_t delta); + +* ``measurement_type`` - AC measurement type constant (ZIGBEE_AC_MEASUREMENT_TYPE_VOLTAGE, ZIGBEE_AC_MEASUREMENT_TYPE_CURRENT, ZIGBEE_AC_MEASUREMENT_TYPE_POWER, ZIGBEE_AC_MEASUREMENT_TYPE_POWER_FACTOR, ZIGBEE_AC_MEASUREMENT_TYPE_FREQUENCY) +* ``phase_type`` - Phase type constant (ZIGBEE_AC_PHASE_TYPE_NON_SPECIFIC, ZIGBEE_AC_PHASE_TYPE_A, ZIGBEE_AC_PHASE_TYPE_B, ZIGBEE_AC_PHASE_TYPE_C) +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change required to trigger a report + +This function will return ``true`` if successful, ``false`` otherwise. + +reportAC +^^^^^^^^ + +Manually reports an AC measurement value. + +.. code-block:: arduino + + bool reportAC(ZIGBEE_AC_MEASUREMENT_TYPE measurement_type, ZIGBEE_AC_PHASE_TYPE phase_type); + +* ``measurement_type`` - AC measurement type constant (ZIGBEE_AC_MEASUREMENT_TYPE_VOLTAGE, ZIGBEE_AC_MEASUREMENT_TYPE_CURRENT, ZIGBEE_AC_MEASUREMENT_TYPE_POWER, ZIGBEE_AC_MEASUREMENT_TYPE_POWER_FACTOR, ZIGBEE_AC_MEASUREMENT_TYPE_FREQUENCY) +* ``phase_type`` - Phase type constant (ZIGBEE_AC_PHASE_TYPE_NON_SPECIFIC, ZIGBEE_AC_PHASE_TYPE_A, ZIGBEE_AC_PHASE_TYPE_B, ZIGBEE_AC_PHASE_TYPE_C) + +This function will return ``true`` if successful, ``false`` otherwise. + +Example +------- + +DC Electrical Measurement +************************* + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Electrical_DC_Sensor/Zigbee_Electrical_DC_Sensor.ino + :language: arduino + +AC Electrical Measurement +************************* + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Electrical_AC_Sensor_MultiPhase/Zigbee_Electrical_AC_Sensor_MultiPhase.ino + :language: arduino diff --git a/docs/en/zigbee/ep_flow_sensor.rst b/docs/en/zigbee/ep_flow_sensor.rst new file mode 100644 index 00000000000..9423f321a5d --- /dev/null +++ b/docs/en/zigbee/ep_flow_sensor.rst @@ -0,0 +1,119 @@ +################ +ZigbeeFlowSensor +################ + +About +----- + +The ``ZigbeeFlowSensor`` class provides a flow sensor endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for liquid and gas flow measurement devices. + +**Features:** +* Flow rate measurement in m³/h +* Configurable measurement range +* Tolerance and reporting configuration +* Automatic reporting capabilities +* Integration with common endpoint features (binding, OTA, etc.) +* Zigbee HA standard compliance + +**Use Cases:** +* Water flow monitoring +* Gas flow measurement +* Industrial process monitoring +* Smart home water management +* HVAC system flow monitoring +* Agricultural irrigation systems + +API Reference +------------- + +Constructor +*********** + +ZigbeeFlowSensor +^^^^^^^^^^^^^^^^ + +Creates a new Zigbee flow sensor endpoint. + +.. code-block:: arduino + + ZigbeeFlowSensor(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +API Methods +*********** + +setFlow +^^^^^^^ + +Sets the flow rate measurement value. + +.. code-block:: arduino + + bool setFlow(float value); + +* ``value`` - Flow rate value in 0.1 m³/h + +This function will return ``true`` if successful, ``false`` otherwise. + +setMinMaxValue +^^^^^^^^^^^^^^ + +Sets the minimum and maximum measurement values. + +.. code-block:: arduino + + bool setMinMaxValue(float min, float max); + +* ``min`` - Minimum flow rate value in 0.1 m³/h +* ``max`` - Maximum flow rate value in 0.1 m³/h + +This function will return ``true`` if successful, ``false`` otherwise. + +setTolerance +^^^^^^^^^^^^ + +Sets the tolerance value for measurements. + +.. code-block:: arduino + + bool setTolerance(float tolerance); + +* ``tolerance`` - Tolerance value in 0.01 m³/h + +This function will return ``true`` if successful, ``false`` otherwise. + +setReporting +^^^^^^^^^^^^ + +Sets the reporting configuration for flow rate measurements. + +.. code-block:: arduino + + bool setReporting(uint16_t min_interval, uint16_t max_interval, float delta); + +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change required to trigger a report in 0.1 m³/h + +This function will return ``true`` if successful, ``false`` otherwise. + +report +^^^^^^ + +Manually reports the current flow rate value. + +.. code-block:: arduino + + bool report(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Example +------- + +Flow + PressureSensor Implementation +************************************ + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Pressure_Flow_Sensor/Zigbee_Pressure_Flow_Sensor.ino + :language: arduino diff --git a/docs/en/zigbee/ep_gateway.rst b/docs/en/zigbee/ep_gateway.rst new file mode 100644 index 00000000000..7afdab8ee35 --- /dev/null +++ b/docs/en/zigbee/ep_gateway.rst @@ -0,0 +1,35 @@ +############# +ZigbeeGateway +############# + +About +----- + +The ``ZigbeeGateway`` class provides a gateway endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for network coordination and gateway functionality. +Gateway is a device that can be used to bridge Zigbee network to other networks (e.g. WiFi, Ethernet, etc.). + +API Reference +------------- + +Constructor +*********** + +ZigbeeGateway +^^^^^^^^^^^^^ + +Creates a new Zigbee gateway endpoint. + +.. code-block:: arduino + + ZigbeeGateway(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +Example +------- + +Gateway Implementation +********************** + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Gateway/Zigbee_Gateway.ino + :language: arduino diff --git a/docs/en/zigbee/ep_illuminance_sensor.rst b/docs/en/zigbee/ep_illuminance_sensor.rst new file mode 100644 index 00000000000..1e627f7dfe9 --- /dev/null +++ b/docs/en/zigbee/ep_illuminance_sensor.rst @@ -0,0 +1,109 @@ +####################### +ZigbeeIlluminanceSensor +####################### + +About +----- + +The ``ZigbeeIlluminanceSensor`` class provides an endpoint for illuminance sensors in Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for light level measurement devices, supporting ambient light monitoring. + +**Features:** +* Illuminance measurement in lux +* Configurable measurement range +* Tolerance and reporting configuration +* Automatic reporting capabilities + +API Reference +------------- + +Constructor +*********** + +ZigbeeIlluminanceSensor +^^^^^^^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee illuminance sensor endpoint. + +.. code-block:: arduino + + ZigbeeIlluminanceSensor(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +API Methods +*********** + +setIlluminance +^^^^^^^^^^^^^^ + +Sets the illuminance measurement value. + +.. code-block:: arduino + + bool setIlluminance(uint16_t value); + +* ``value`` - Illuminance value in lux + +This function will return ``true`` if successful, ``false`` otherwise. + +setMinMaxValue +^^^^^^^^^^^^^^ + +Sets the minimum and maximum measurement values. + +.. code-block:: arduino + + bool setMinMaxValue(uint16_t min, uint16_t max); + +* ``min`` - Minimum illuminance value in lux +* ``max`` - Maximum illuminance value in lux + +This function will return ``true`` if successful, ``false`` otherwise. + +setTolerance +^^^^^^^^^^^^ + +Sets the tolerance value for measurements. + +.. code-block:: arduino + + bool setTolerance(uint16_t tolerance); + +* ``tolerance`` - Tolerance value in lux + +This function will return ``true`` if successful, ``false`` otherwise. + +setReporting +^^^^^^^^^^^^ + +Sets the reporting configuration for illuminance measurements. + +.. code-block:: arduino + + bool setReporting(uint16_t min_interval, uint16_t max_interval, uint16_t delta); + +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change required to trigger a report in lux + +This function will return ``true`` if successful, ``false`` otherwise. + +report +^^^^^^ + +Manually reports the current illuminance value. + +.. code-block:: arduino + + bool report(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Example +------- + +Illuminance Sensor Implementation +********************************* + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Illuminance_Sensor/Zigbee_Illuminance_Sensor.ino + :language: arduino diff --git a/docs/en/zigbee/ep_light.rst b/docs/en/zigbee/ep_light.rst new file mode 100644 index 00000000000..fb70320321b --- /dev/null +++ b/docs/en/zigbee/ep_light.rst @@ -0,0 +1,88 @@ +########### +ZigbeeLight +########### + +About +----- + +The ``ZigbeeLight`` class provides a simple on/off light endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for basic lighting control. + +**Features:** +* Simple on/off control +* State change callbacks + +API Reference +------------- + +Constructor +*********** + +ZigbeeLight +^^^^^^^^^^^ + +Creates a new Zigbee light endpoint. + +.. code-block:: arduino + + ZigbeeLight(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +Light Control +************* + +setLight +^^^^^^^^ + +Sets the light state (on or off). + +.. code-block:: arduino + + bool setLight(bool state); + +* ``state`` - ``true`` to turn on, ``false`` to turn off + +This function will return ``true`` if successful, ``false`` otherwise. + +getLightState +^^^^^^^^^^^^^ + +Gets the current light state. + +.. code-block:: arduino + + bool getLightState(); + +This function will return current light state (``true`` = on, ``false`` = off). + +restoreLight +^^^^^^^^^^^^ + +Restores the light state and triggers any registered callbacks. + +.. code-block:: arduino + + void restoreLight(); + +Event Handling +************** + +onLightChange +^^^^^^^^^^^^^ + +Sets a callback function to be called when the light state changes. + +.. code-block:: arduino + + void onLightChange(void (*callback)(bool)); + +* ``callback`` - Function to call when light state changes + +Example +------- + +Basic Light Implementation +************************** + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_On_Off_Light/Zigbee_On_Off_Light.ino + :language: arduino diff --git a/docs/en/zigbee/ep_occupancy_sensor.rst b/docs/en/zigbee/ep_occupancy_sensor.rst new file mode 100644 index 00000000000..7fe50d59ea4 --- /dev/null +++ b/docs/en/zigbee/ep_occupancy_sensor.rst @@ -0,0 +1,81 @@ +##################### +ZigbeeOccupancySensor +##################### + +About +----- + +The ``ZigbeeOccupancySensor`` class provides an endpoint for occupancy sensors in Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for occupancy detection devices, supporting various sensor types for detecting presence. + +**Features:** +* Occupancy detection (occupied/unoccupied) +* Multiple sensor type support (PIR, ultrasonic, etc.) +* Automatic reporting capabilities +* Integration with common endpoint features (binding, OTA, etc.) +* Zigbee HA standard compliance + +API Reference +------------- + +Constructor +*********** + +ZigbeeOccupancySensor +^^^^^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee occupancy sensor endpoint. + +.. code-block:: arduino + + ZigbeeOccupancySensor(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +API Methods +*********** + +setOccupancy +^^^^^^^^^^^^ + +Sets the occupancy state. + +.. code-block:: arduino + + bool setOccupancy(bool occupied); + +* ``occupied`` - Occupancy state (true = occupied, false = unoccupied) + +This function will return ``true`` if successful, ``false`` otherwise. + +setSensorType +^^^^^^^^^^^^^ + +Sets the sensor type. + +.. code-block:: arduino + + bool setSensorType(uint8_t sensor_type); + +* ``sensor_type`` - Sensor type identifier (see esp_zb_zcl_occupancy_sensing_occupancy_sensor_type_t) + +This function will return ``true`` if successful, ``false`` otherwise. + +report +^^^^^^ + +Manually reports the current occupancy state. + +.. code-block:: arduino + + bool report(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Example +------- + +Occupancy Sensor Implementation +******************************* + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Occupancy_Sensor/Zigbee_Occupancy_Sensor.ino + :language: arduino diff --git a/docs/en/zigbee/ep_pm25_sensor.rst b/docs/en/zigbee/ep_pm25_sensor.rst new file mode 100644 index 00000000000..2f1432f8224 --- /dev/null +++ b/docs/en/zigbee/ep_pm25_sensor.rst @@ -0,0 +1,109 @@ +################ +ZigbeePM25Sensor +################ + +About +----- + +The ``ZigbeePM25Sensor`` class provides a PM2.5 air quality sensor endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for particulate matter measurement devices. + +**Features:** +* PM2.5 concentration measurement in μg/m³ +* Configurable measurement range +* Tolerance and reporting configuration +* Automatic reporting capabilities + +API Reference +------------- + +Constructor +*********** + +ZigbeePM25Sensor +^^^^^^^^^^^^^^^^ + +Creates a new Zigbee PM2.5 sensor endpoint. + +.. code-block:: arduino + + ZigbeePM25Sensor(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +API Methods +*********** + +setPM25 +^^^^^^^ + +Sets the PM2.5 concentration measurement value. + +.. code-block:: arduino + + bool setPM25(float pm25); + +* ``pm25`` - PM2.5 concentration value in 0.1 μg/m³ + +This function will return ``true`` if successful, ``false`` otherwise. + +setMinMaxValue +^^^^^^^^^^^^^^ + +Sets the minimum and maximum measurement values. + +.. code-block:: arduino + + bool setMinMaxValue(float min, float max); + +* ``min`` - Minimum PM2.5 concentration value in 0.1 μg/m³ +* ``max`` - Maximum PM2.5 concentration value in 0.1 μg/m³ + +This function will return ``true`` if successful, ``false`` otherwise. + +setTolerance +^^^^^^^^^^^^ + +Sets the tolerance value for measurements. + +.. code-block:: arduino + + bool setTolerance(float tolerance); + +* ``tolerance`` - Tolerance value in 0.1 μg/m³ + +This function will return ``true`` if successful, ``false`` otherwise. + +setReporting +^^^^^^^^^^^^ + +Sets the reporting configuration for PM2.5 measurements. + +.. code-block:: arduino + + bool setReporting(uint16_t min_interval, uint16_t max_interval, float delta); + +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change required to trigger a report in 0.1 μg/m³ + +This function will return ``true`` if successful, ``false`` otherwise. + +report +^^^^^^ + +Manually reports the current PM2.5 concentration value. + +.. code-block:: arduino + + bool report(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Example +------- + +PM2.5 Sensor Implementation +*************************** + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_PM25_Sensor/Zigbee_PM25_Sensor.ino + :language: arduino diff --git a/docs/en/zigbee/ep_power_outlet.rst b/docs/en/zigbee/ep_power_outlet.rst new file mode 100644 index 00000000000..97b22cbbc2a --- /dev/null +++ b/docs/en/zigbee/ep_power_outlet.rst @@ -0,0 +1,88 @@ +################# +ZigbeePowerOutlet +################# + +About +----- + +The ``ZigbeePowerOutlet`` class provides a smart power outlet endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for power control, allowing remote on/off control of electrical devices. + +**Features:** +* On/off power control +* State change callbacks + +API Reference +------------- + +Constructor +*********** + +ZigbeePowerOutlet +^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee power outlet endpoint. + +.. code-block:: arduino + + ZigbeePowerOutlet(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +Power Control +************* + +setState +^^^^^^^^ + +Sets the power outlet state (on or off). + +.. code-block:: arduino + + bool setState(bool state); + +* ``state`` - ``true`` to turn on, ``false`` to turn off + +This function will return ``true`` if successful, ``false`` otherwise. + +getPowerOutletState +^^^^^^^^^^^^^^^^^^^ + +Gets the current power outlet state. + +.. code-block:: arduino + + bool getPowerOutletState(); + +This function will return current power state (``true`` = on, ``false`` = off). + +restoreState +^^^^^^^^^^^^ + +Restores the power outlet state and triggers any registered callbacks. + +.. code-block:: arduino + + void restoreState(); + +Event Handling +************** + +onPowerOutletChange +^^^^^^^^^^^^^^^^^^^ + +Sets a callback function to be called when the power outlet state changes. + +.. code-block:: arduino + + void onPowerOutletChange(void (*callback)(bool)); + +* ``callback`` - Function to call when power outlet state changes + +Example +------- + +Smart Power Outlet Implementation +********************************* + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Power_Outlet/Zigbee_Power_Outlet.ino + :language: arduino diff --git a/docs/en/zigbee/ep_pressure_sensor.rst b/docs/en/zigbee/ep_pressure_sensor.rst new file mode 100644 index 00000000000..5d857bb163e --- /dev/null +++ b/docs/en/zigbee/ep_pressure_sensor.rst @@ -0,0 +1,109 @@ +#################### +ZigbeePressureSensor +#################### + +About +----- + +The ``ZigbeePressureSensor`` class provides an endpoint for pressure sensors in Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for pressure measurement devices, supporting atmospheric pressure, barometric pressure, and other pressure measurements. + +**Features:** +* Pressure measurement in hPa (hectopascals) +* Configurable measurement range +* Tolerance and reporting configuration +* Automatic reporting capabilities + +API Reference +------------- + +Constructor +*********** + +ZigbeePressureSensor +^^^^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee pressure sensor endpoint. + +.. code-block:: arduino + + ZigbeePressureSensor(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +API Methods +*********** + +setPressure +^^^^^^^^^^^ + +Sets the pressure measurement value. + +.. code-block:: arduino + + bool setPressure(int16_t value); + +* ``value`` - Pressure value in hPa + +This function will return ``true`` if successful, ``false`` otherwise. + +setMinMaxValue +^^^^^^^^^^^^^^ + +Sets the minimum and maximum measurement values. + +.. code-block:: arduino + + bool setMinMaxValue(int16_t min, int16_t max); + +* ``min`` - Minimum pressure value in hPa +* ``max`` - Maximum pressure value in hPa + +This function will return ``true`` if successful, ``false`` otherwise. + +setTolerance +^^^^^^^^^^^^ + +Sets the tolerance value for measurements. + +.. code-block:: arduino + + bool setTolerance(uint16_t tolerance); + +* ``tolerance`` - Tolerance value in hPa + +This function will return ``true`` if successful, ``false`` otherwise. + +setReporting +^^^^^^^^^^^^ + +Sets the reporting configuration for pressure measurements. + +.. code-block:: arduino + + bool setReporting(uint16_t min_interval, uint16_t max_interval, uint16_t delta); + +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change required to trigger a report in hPa + +This function will return ``true`` if successful, ``false`` otherwise. + +report +^^^^^^ + +Manually reports the current pressure value. + +.. code-block:: arduino + + bool report(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Example +------- + +Pressure + Flow Sensor Implementation +************************************* + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Pressure_Flow_Sensor/Zigbee_Pressure_Flow_Sensor.ino + :language: arduino diff --git a/docs/en/zigbee/ep_range_extender.rst b/docs/en/zigbee/ep_range_extender.rst new file mode 100644 index 00000000000..9492ce9c8eb --- /dev/null +++ b/docs/en/zigbee/ep_range_extender.rst @@ -0,0 +1,34 @@ +################### +ZigbeeRangeExtender +################### + +About +----- + +The ``ZigbeeRangeExtender`` class provides a range extender endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for range extender devices that help extend the coverage of Zigbee networks by acting as repeaters. + +API Reference +------------- + +Constructor +*********** + +ZigbeeRangeExtender +^^^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee range extender endpoint. + +.. code-block:: arduino + + ZigbeeRangeExtender(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +Example +------- + +Range Extender Implementation +***************************** + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Range_Extender/Zigbee_Range_Extender.ino + :language: arduino \ No newline at end of file diff --git a/docs/en/zigbee/ep_switch.rst b/docs/en/zigbee/ep_switch.rst new file mode 100644 index 00000000000..e1847996cc2 --- /dev/null +++ b/docs/en/zigbee/ep_switch.rst @@ -0,0 +1,136 @@ +############ +ZigbeeSwitch +############ + +About +----- + +The ``ZigbeeSwitch`` class provides a switch endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for controlling other devices (typically lights) through on/off commands. + +**Features:** +* On/off control commands for bound devices +* Group control support +* Direct device addressing + +API Reference +------------- + +Constructor +*********** + +ZigbeeSwitch +^^^^^^^^^^^^ + +Creates a new Zigbee switch endpoint. + +.. code-block:: arduino + + ZigbeeSwitch(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +Basic Control Commands +********************** + +lightToggle +^^^^^^^^^^^ + +Toggles the state of bound lights (on to off, or off to on). + +.. code-block:: arduino + + void lightToggle(); + void lightToggle(uint16_t group_addr); + void lightToggle(uint8_t endpoint, uint16_t short_addr); + void lightToggle(uint8_t endpoint, esp_zb_ieee_addr_t ieee_addr); + +* ``group_addr`` - Group address to control (optional) +* ``endpoint`` - Target device endpoint (optional) +* ``short_addr`` - Target device short address (optional) +* ``ieee_addr`` - Target device IEEE address (optional) + +lightOn +^^^^^^^ + +Turns on bound lights. + +.. code-block:: arduino + + void lightOn(); + void lightOn(uint16_t group_addr); + void lightOn(uint8_t endpoint, uint16_t short_addr); + void lightOn(uint8_t endpoint, esp_zb_ieee_addr_t ieee_addr); + +* ``group_addr`` - Group address to control (optional) +* ``endpoint`` - Target device endpoint (optional) +* ``short_addr`` - Target device short address (optional) +* ``ieee_addr`` - Target device IEEE address (optional) + +lightOff +^^^^^^^^ + +Turns off bound lights. + +.. code-block:: arduino + + void lightOff(); + void lightOff(uint16_t group_addr); + void lightOff(uint8_t endpoint, uint16_t short_addr); + void lightOff(uint8_t endpoint, esp_zb_ieee_addr_t ieee_addr); + +* ``group_addr`` - Group address to control (optional) +* ``endpoint`` - Target device endpoint (optional) +* ``short_addr`` - Target device short address (optional) +* ``ieee_addr`` - Target device IEEE address (optional) + +Advanced Control Commands +************************* + +lightOffWithEffect +^^^^^^^^^^^^^^^^^^ + +Turns off lights with a specific effect. + +.. code-block:: arduino + + void lightOffWithEffect(uint8_t effect_id, uint8_t effect_variant); + +* ``effect_id`` - Effect identifier +* ``effect_variant`` - Effect variant + +lightOnWithTimedOff +^^^^^^^^^^^^^^^^^^^ + +Turns on lights with automatic turn-off after specified time. + +.. code-block:: arduino + + void lightOnWithTimedOff(uint8_t on_off_control, uint16_t time_on, uint16_t time_off); + +* ``on_off_control`` - Control byte +* ``time_on`` - Time to stay on (in 1/10th seconds) +* ``time_off`` - Time to stay off (in 1/10th seconds) + +lightOnWithSceneRecall +^^^^^^^^^^^^^^^^^^^^^^ + +Turns on lights by recalling a scene. + +.. code-block:: arduino + + void lightOnWithSceneRecall(); + +Example +------- + +Basic Switch Implementation +*************************** + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_On_Off_Switch/Zigbee_On_Off_Switch.ino + :language: arduino + +Multi Switch Implementation +*************************** + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_On_Off_MultiSwitch/Zigbee_On_Off_MultiSwitch.ino + :language: arduino diff --git a/docs/en/zigbee/ep_temperature_sensor.rst b/docs/en/zigbee/ep_temperature_sensor.rst new file mode 100644 index 00000000000..85c2147f1a1 --- /dev/null +++ b/docs/en/zigbee/ep_temperature_sensor.rst @@ -0,0 +1,184 @@ +################ +ZigbeeTempSensor +################ + +About +----- + +The ``ZigbeeTempSensor`` class provides a temperature and humidity sensor endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for environmental monitoring with configurable reporting intervals and thresholds. + +**Features:** +* Temperature measurement and reporting +* Optional humidity measurement +* Configurable reporting intervals +* Min/max value and tolerance settings + +API Reference +------------- + +Constructor +*********** + +ZigbeeTempSensor +^^^^^^^^^^^^^^^^ + +Creates a new Zigbee temperature sensor endpoint. + +.. code-block:: arduino + + ZigbeeTempSensor(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +Temperature Control +******************* + +setTemperature +^^^^^^^^^^^^^^ + +Sets the temperature value in 0.01°C resolution. + +.. code-block:: arduino + + bool setTemperature(float value); + +* ``value`` - Temperature value in degrees Celsius + +This function will return ``true`` if successful, ``false`` otherwise. + +setMinMaxValue +^^^^^^^^^^^^^^ + +Sets the minimum and maximum temperature values for the sensor. + +.. code-block:: arduino + + bool setMinMaxValue(float min, float max); + +* ``min`` - Minimum temperature value in degrees Celsius +* ``max`` - Maximum temperature value in degrees Celsius + +This function will return ``true`` if successful, ``false`` otherwise. + +setTolerance +^^^^^^^^^^^^ + +Sets the tolerance value for temperature reporting. + +.. code-block:: arduino + + bool setTolerance(float tolerance); + +* ``tolerance`` - Tolerance value in degrees Celsius + +This function will return ``true`` if successful, ``false`` otherwise. + +setReporting +^^^^^^^^^^^^ + +Sets the reporting interval for temperature measurements. + +.. code-block:: arduino + + bool setReporting(uint16_t min_interval, uint16_t max_interval, float delta); + +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change in temperature to trigger report (in 0.01°C) + +This function will return ``true`` if successful, ``false`` otherwise. + +reportTemperature +^^^^^^^^^^^^^^^^^ + +Manually reports the current temperature value. + +.. code-block:: arduino + + bool reportTemperature(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Humidity Control (Optional) +*************************** + +addHumiditySensor +^^^^^^^^^^^^^^^^^ + +Adds humidity measurement capability to the temperature sensor. + +.. code-block:: arduino + + void addHumiditySensor(float min, float max, float tolerance); + +* ``min`` - Minimum humidity value in percentage +* ``max`` - Maximum humidity value in percentage +* ``tolerance`` - Tolerance value in percentage + +setHumidity +^^^^^^^^^^^ + +Sets the humidity value in 0.01% resolution. + +.. code-block:: arduino + + bool setHumidity(float value); + +* ``value`` - Humidity value in percentage (0-100) + +This function will return ``true`` if successful, ``false`` otherwise. + +setHumidityReporting +^^^^^^^^^^^^^^^^^^^^ + +Sets the reporting interval for humidity measurements. + +.. code-block:: arduino + + bool setHumidityReporting(uint16_t min_interval, uint16_t max_interval, float delta); + +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change in humidity to trigger report (in 0.01%) + +This function will return ``true`` if successful, ``false`` otherwise. + +reportHumidity +^^^^^^^^^^^^^^ + +Manually reports the current humidity value. + +.. code-block:: arduino + + bool reportHumidity(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Combined Reporting +****************** + +report +^^^^^^ + +Reports both temperature and humidity values if humidity sensor is enabled. + +.. code-block:: arduino + + bool report(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Example +------- + +Temperature Sensor Implementation +********************************* + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Temperature_Sensor/Zigbee_Temperature_Sensor.ino + :language: arduino + +Temperature + Humidity Sleepy Sensor Implementation +*************************************************** + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Temp_Hum_Sensor_Sleepy/Zigbee_Temp_Hum_Sensor_Sleepy.ino + :language: arduino diff --git a/docs/en/zigbee/ep_thermostat.rst b/docs/en/zigbee/ep_thermostat.rst new file mode 100644 index 00000000000..b7c79254d0f --- /dev/null +++ b/docs/en/zigbee/ep_thermostat.rst @@ -0,0 +1,238 @@ +################ +ZigbeeThermostat +################ + +About +----- + +The ``ZigbeeThermostat`` class provides a thermostat endpoint for Zigbee networks that receives temperature data from temperature sensors. This endpoint implements the Zigbee Home Automation (HA) standard for thermostats that can bind to temperature sensors and receive temperature readings. + +**Features:** +* Automatic discovery and binding to temperature sensors +* Temperature data reception from bound sensors +* Configurable temperature reporting intervals +* Sensor settings retrieval (min/max temperature, tolerance) +* Multiple addressing modes (group, specific endpoint, IEEE address) + +API Reference +------------- + +Constructor +*********** + +ZigbeeThermostat +^^^^^^^^^^^^^^^^ + +Creates a new Zigbee thermostat endpoint. + +.. code-block:: arduino + + ZigbeeThermostat(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +Event Handling +************** + +onTempReceive +^^^^^^^^^^^^^ + +Sets a callback function for receiving temperature data. + +.. code-block:: arduino + + void onTempReceive(void (*callback)(float temperature)); + +* ``callback`` - Function to call when temperature data is received +* ``temperature`` - Temperature value in degrees Celsius + +onTempReceiveWithSource +^^^^^^^^^^^^^^^^^^^^^^^ + +Sets a callback function for receiving temperature data with source information. + +.. code-block:: arduino + + void onTempReceiveWithSource(void (*callback)(float temperature, uint8_t src_endpoint, esp_zb_zcl_addr_t src_address)); + +* ``callback`` - Function to call when temperature data is received +* ``temperature`` - Temperature value in degrees Celsius +* ``src_endpoint`` - Source endpoint that sent the temperature data +* ``src_address`` - Source address information + +onConfigReceive +^^^^^^^^^^^^^^^ + +Sets a callback function for receiving sensor configuration data. + +.. code-block:: arduino + + void onConfigReceive(void (*callback)(float min_temp, float max_temp, float tolerance)); + +* ``callback`` - Function to call when sensor configuration is received +* ``min_temp`` - Minimum temperature supported by the sensor +* ``max_temp`` - Maximum temperature supported by the sensor +* ``tolerance`` - Temperature tolerance of the sensor + +Temperature Data Retrieval +************************** + +getTemperature +^^^^^^^^^^^^^^ + +Requests temperature data from all bound sensors. + +.. code-block:: arduino + + void getTemperature(); + +getTemperature (Group) +^^^^^^^^^^^^^^^^^^^^^^ + +Requests temperature data from a specific group. + +.. code-block:: arduino + + void getTemperature(uint16_t group_addr); + +* ``group_addr`` - Group address to send the request to + +getTemperature (Endpoint + Short Address) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Requests temperature data from a specific endpoint using short address. + +.. code-block:: arduino + + void getTemperature(uint8_t endpoint, uint16_t short_addr); + +* ``endpoint`` - Target endpoint number +* ``short_addr`` - Short address of the target device + +getTemperature (Endpoint + IEEE Address) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Requests temperature data from a specific endpoint using IEEE address. + +.. code-block:: arduino + + void getTemperature(uint8_t endpoint, esp_zb_ieee_addr_t ieee_addr); + +* ``endpoint`` - Target endpoint number +* ``ieee_addr`` - IEEE address of the target device + +Sensor Settings Retrieval +************************* + +getSensorSettings +^^^^^^^^^^^^^^^^^ + +Requests sensor settings from all bound sensors. + +.. code-block:: arduino + + void getSensorSettings(); + +getSensorSettings (Group) +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Requests sensor settings from a specific group. + +.. code-block:: arduino + + void getSensorSettings(uint16_t group_addr); + +* ``group_addr`` - Group address to send the request to + +getSensorSettings (Endpoint + Short Address) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Requests sensor settings from a specific endpoint using short address. + +.. code-block:: arduino + + void getSensorSettings(uint8_t endpoint, uint16_t short_addr); + +* ``endpoint`` - Target endpoint number +* ``short_addr`` - Short address of the target device + +getSensorSettings (Endpoint + IEEE Address) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Requests sensor settings from a specific endpoint using IEEE address. + +.. code-block:: arduino + + void getSensorSettings(uint8_t endpoint, esp_zb_ieee_addr_t ieee_addr); + +* ``endpoint`` - Target endpoint number +* ``ieee_addr`` - IEEE address of the target device + +Temperature Reporting Configuration +*********************************** + +setTemperatureReporting +^^^^^^^^^^^^^^^^^^^^^^^ + +Configures temperature reporting for all bound sensors. + +.. code-block:: arduino + + void setTemperatureReporting(uint16_t min_interval, uint16_t max_interval, float delta); + +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change in temperature to trigger a report + +setTemperatureReporting (Group) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Configures temperature reporting for a specific group. + +.. code-block:: arduino + + void setTemperatureReporting(uint16_t group_addr, uint16_t min_interval, uint16_t max_interval, float delta); + +* ``group_addr`` - Group address to configure +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change in temperature to trigger a report + +setTemperatureReporting (Endpoint + Short Address) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Configures temperature reporting for a specific endpoint using short address. + +.. code-block:: arduino + + void setTemperatureReporting(uint8_t endpoint, uint16_t short_addr, uint16_t min_interval, uint16_t max_interval, float delta); + +* ``endpoint`` - Target endpoint number +* ``short_addr`` - Short address of the target device +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change in temperature to trigger a report + +setTemperatureReporting (Endpoint + IEEE Address) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Configures temperature reporting for a specific endpoint using IEEE address. + +.. code-block:: arduino + + void setTemperatureReporting(uint8_t endpoint, esp_zb_ieee_addr_t ieee_addr, uint16_t min_interval, uint16_t max_interval, float delta); + +* ``endpoint`` - Target endpoint number +* ``ieee_addr`` - IEEE address of the target device +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change in temperature to trigger a report + +Example +------- + +Thermostat Implementation +************************* + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Thermostat/Zigbee_Thermostat.ino + :language: arduino diff --git a/docs/en/zigbee/ep_vibration_sensor.rst b/docs/en/zigbee/ep_vibration_sensor.rst new file mode 100644 index 00000000000..896c4672c6d --- /dev/null +++ b/docs/en/zigbee/ep_vibration_sensor.rst @@ -0,0 +1,87 @@ +##################### +ZigbeeVibrationSensor +##################### + +About +----- + +The ``ZigbeeVibrationSensor`` class provides a vibration sensor endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for vibration detection devices. + +**Features:** +* Vibration detection and measurement +* Configurable sensitivity levels +* Multiple detection modes +* Automatic reporting capabilities +* Integration with common endpoint features (binding, OTA, etc.) +* Zigbee HA standard compliance + +**Use Cases:** +* Security system vibration detection +* Industrial equipment monitoring +* Structural health monitoring +* Smart home security applications +* Machine condition monitoring + +API Reference +------------- + +Constructor +*********** + +ZigbeeVibrationSensor +^^^^^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee vibration sensor endpoint. + +.. code-block:: arduino + + ZigbeeVibrationSensor(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +API Methods +*********** + +setVibration +^^^^^^^^^^^^ + +Sets the vibration detection state. + +.. code-block:: arduino + + bool setVibration(bool sensed); + +* ``sensed`` - Vibration state (true = sensed, false = not sensed) + +This function will return ``true`` if successful, ``false`` otherwise. + +setIASClientEndpoint +^^^^^^^^^^^^^^^^^^^^ + +Sets the IAS Client endpoint number (default is 1). + +.. code-block:: arduino + + void setIASClientEndpoint(uint8_t ep_number); + +* ``ep_number`` - IAS Client endpoint number + +report +^^^^^^ + +Manually reports the current vibration state. + +.. code-block:: arduino + + void report(); + +This function does not return a value. + +Example +------- + +Vibration Sensor Implementation +******************************* + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Vibration_Sensor/Zigbee_Vibration_Sensor.ino + :language: arduino diff --git a/docs/en/zigbee/ep_wind_speed_sensor.rst b/docs/en/zigbee/ep_wind_speed_sensor.rst new file mode 100644 index 00000000000..67c4958e37c --- /dev/null +++ b/docs/en/zigbee/ep_wind_speed_sensor.rst @@ -0,0 +1,119 @@ +##################### +ZigbeeWindSpeedSensor +##################### + +About +----- + +The ``ZigbeeWindSpeedSensor`` class provides a wind speed sensor endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for wind speed measurement devices. + +**Features:** +* Wind speed measurement in m/s +* Configurable measurement range +* Tolerance and reporting configuration +* Automatic reporting capabilities +* Integration with common endpoint features (binding, OTA, etc.) +* Zigbee HA standard compliance + +**Use Cases:** +* Weather stations +* Wind turbine monitoring +* Agricultural weather monitoring +* Marine applications +* Smart home weather systems +* Industrial wind monitoring + +API Reference +------------- + +Constructor +*********** + +ZigbeeWindSpeedSensor +^^^^^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee wind speed sensor endpoint. + +.. code-block:: arduino + + ZigbeeWindSpeedSensor(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +API Methods +*********** + +setWindSpeed +^^^^^^^^^^^^ + +Sets the wind speed measurement value. + +.. code-block:: arduino + + bool setWindSpeed(float value); + +* ``value`` - Wind speed value in 0.01 m/s + +This function will return ``true`` if successful, ``false`` otherwise. + +setMinMaxValue +^^^^^^^^^^^^^^ + +Sets the minimum and maximum measurement values. + +.. code-block:: arduino + + bool setMinMaxValue(float min, float max); + +* ``min`` - Minimum wind speed value in 0.01 m/s +* ``max`` - Maximum wind speed value in 0.01 m/s + +This function will return ``true`` if successful, ``false`` otherwise. + +setTolerance +^^^^^^^^^^^^ + +Sets the tolerance value for measurements. + +.. code-block:: arduino + + bool setTolerance(float tolerance); + +* ``tolerance`` - Tolerance value in 0.01 m/s + +This function will return ``true`` if successful, ``false`` otherwise. + +setReporting +^^^^^^^^^^^^ + +Sets the reporting configuration for wind speed measurements. + +.. code-block:: arduino + + bool setReporting(uint16_t min_interval, uint16_t max_interval, float delta); + +* ``min_interval`` - Minimum reporting interval in seconds +* ``max_interval`` - Maximum reporting interval in seconds +* ``delta`` - Minimum change required to trigger a report in 0.01 m/s + +This function will return ``true`` if successful, ``false`` otherwise. + +reportWindSpeed +^^^^^^^^^^^^^^^ + +Manually reports the current wind speed value. + +.. code-block:: arduino + + bool reportWindSpeed(); + +This function will return ``true`` if successful, ``false`` otherwise. + +Example +------- + +Wind Speed Sensor Implementation +******************************** + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Wind_Speed_Sensor/Zigbee_Wind_Speed_Sensor.ino + :language: arduino diff --git a/docs/en/zigbee/ep_window_covering.rst b/docs/en/zigbee/ep_window_covering.rst new file mode 100644 index 00000000000..ddfa03ae097 --- /dev/null +++ b/docs/en/zigbee/ep_window_covering.rst @@ -0,0 +1,233 @@ +#################### +ZigbeeWindowCovering +#################### + +About +----- + +The ``ZigbeeWindowCovering`` class provides a window covering endpoint for Zigbee networks. This endpoint implements the Zigbee Home Automation (HA) standard for motorized blinds, shades, and other window coverings. + +**Features:** +* Position control (lift and tilt) +* Multiple window covering types support +* Configurable operation modes and limits +* Status reporting and callbacks +* Safety features and limits + +**Supported Window Covering Types:** +* ROLLERSHADE - Lift support +* ROLLERSHADE_2_MOTOR - Lift support +* ROLLERSHADE_EXTERIOR - Lift support +* ROLLERSHADE_EXTERIOR_2_MOTOR - Lift support +* DRAPERY - Lift support +* AWNING - Lift support +* SHUTTER - Tilt support +* BLIND_TILT_ONLY - Tilt support +* BLIND_LIFT_AND_TILT - Lift and Tilt support +* PROJECTOR_SCREEN - Lift support + +API Reference +------------- + +Constructor +*********** + +ZigbeeWindowCovering +^^^^^^^^^^^^^^^^^^^^ + +Creates a new Zigbee window covering endpoint. + +.. code-block:: arduino + + ZigbeeWindowCovering(uint8_t endpoint); + +* ``endpoint`` - Endpoint number (1-254) + +Position Control +**************** + +setLiftPosition +^^^^^^^^^^^^^^^ + +Sets the window covering lift position in centimeters. + +.. code-block:: arduino + + bool setLiftPosition(uint16_t lift_position); + +* ``lift_position`` - Lift position in centimeters + +This function will return ``true`` if successful, ``false`` otherwise. + +setLiftPercentage +^^^^^^^^^^^^^^^^^ + +Sets the window covering lift position as a percentage. + +.. code-block:: arduino + + bool setLiftPercentage(uint8_t lift_percentage); + +* ``lift_percentage`` - Lift percentage (0-100, where 0 is fully closed, 100 is fully open) + +This function will return ``true`` if successful, ``false`` otherwise. + +setTiltPosition +^^^^^^^^^^^^^^^ + +Sets the window covering tilt position in degrees. + +.. code-block:: arduino + + bool setTiltPosition(uint16_t tilt_position); + +* ``tilt_position`` - Tilt position in degrees + +This function will return ``true`` if successful, ``false`` otherwise. + +setTiltPercentage +^^^^^^^^^^^^^^^^^ + +Sets the window covering tilt position as a percentage. + +.. code-block:: arduino + + bool setTiltPercentage(uint8_t tilt_percentage); + +* ``tilt_percentage`` - Tilt percentage (0-100) + +This function will return ``true`` if successful, ``false`` otherwise. + +Configuration +************* + +setCoveringType +^^^^^^^^^^^^^^^ + +Sets the window covering type. + +.. code-block:: arduino + + bool setCoveringType(ZigbeeWindowCoveringType covering_type); + +* ``covering_type`` - Window covering type (see supported types above) + +This function will return ``true`` if successful, ``false`` otherwise. + +setConfigStatus +^^^^^^^^^^^^^^^ + +Sets the window covering configuration status. + +.. code-block:: arduino + + bool setConfigStatus(bool operational, bool online, bool commands_reversed, bool lift_closed_loop, bool tilt_closed_loop, bool lift_encoder_controlled, bool tilt_encoder_controlled); + +* ``operational`` - Operational status +* ``online`` - Online status +* ``commands_reversed`` - Commands reversed flag +* ``lift_closed_loop`` - Lift closed loop flag +* ``tilt_closed_loop`` - Tilt closed loop flag +* ``lift_encoder_controlled`` - Lift encoder controlled flag +* ``tilt_encoder_controlled`` - Tilt encoder controlled flag + +This function will return ``true`` if successful, ``false`` otherwise. + +setMode +^^^^^^^ + +Sets the window covering operation mode. + +.. code-block:: arduino + + bool setMode(bool motor_reversed, bool calibration_mode, bool maintenance_mode, bool leds_on); + +* ``motor_reversed`` - Motor reversed flag +* ``calibration_mode`` - Calibration mode flag +* ``maintenance_mode`` - Maintenance mode flag +* ``leds_on`` - LEDs on flag + +This function will return ``true`` if successful, ``false`` otherwise. + +setLimits +^^^^^^^^^ + +Sets the motion limits for the window covering. + +.. code-block:: arduino + + bool setLimits(uint16_t installed_open_limit_lift, uint16_t installed_closed_limit_lift, uint16_t installed_open_limit_tilt, uint16_t installed_closed_limit_tilt); + +* ``installed_open_limit_lift`` - Installed open limit for lift +* ``installed_closed_limit_lift`` - Installed closed limit for lift +* ``installed_open_limit_tilt`` - Installed open limit for tilt +* ``installed_closed_limit_tilt`` - Installed closed limit for tilt + +This function will return ``true`` if successful, ``false`` otherwise. + +Event Handling +************** + +onOpen +^^^^^^ + +Sets a callback function to be called when the window covering opens. + +.. code-block:: arduino + + void onOpen(void (*callback)()); + +* ``callback`` - Function to call when window covering opens + +onClose +^^^^^^^ + +Sets a callback function to be called when the window covering closes. + +.. code-block:: arduino + + void onClose(void (*callback)()); + +* ``callback`` - Function to call when window covering closes + +onGoToLiftPercentage +^^^^^^^^^^^^^^^^^^^^ + +Sets a callback function to be called when lift percentage changes. + +.. code-block:: arduino + + void onGoToLiftPercentage(void (*callback)(uint8_t)); + +* ``callback`` - Function to call when lift percentage changes + +onGoToTiltPercentage +^^^^^^^^^^^^^^^^^^^^ + +Sets a callback function to be called when tilt percentage changes. + +.. code-block:: arduino + + void onGoToTiltPercentage(void (*callback)(uint8_t)); + +* ``callback`` - Function to call when tilt percentage changes + +onStop +^^^^^^ + +Sets a callback function to be called when window covering stops. + +.. code-block:: arduino + + void onStop(void (*callback)()); + +* ``callback`` - Function to call when window covering stops + +Example +------- + +Window Covering Implementation +****************************** + +.. literalinclude:: ../../../libraries/Zigbee/examples/Zigbee_Window_Covering/Zigbee_Window_Covering.ino + :language: arduino diff --git a/docs/en/zigbee/zigbee.rst b/docs/en/zigbee/zigbee.rst new file mode 100644 index 00000000000..2f4b2c152c2 --- /dev/null +++ b/docs/en/zigbee/zigbee.rst @@ -0,0 +1,159 @@ +###### +Zigbee +###### + +About +----- + +The Zigbee library provides support for creating Zigbee 3.0 compatible devices including: + +* Support for different Zigbee roles (Coordinator, Router, End Device) +* Network management (scanning, joining, commissioning) +* Multiple endpoint types for various device categories +* OTA (Over-The-Air) update support +* Power management for battery-powered devices +* Time synchronization +* Advanced binding and group management + +The Zigbee library is built on top of `ESP-ZIGBEE-SDK `_ and provides a high-level Arduino-style interface for creating Zigbee devices. + +Zigbee Network Topology +*********************** + +.. code-block:: text + + ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ + │ Coordinator │◄─────►│ Router │◄─────►│ Router │ + │ (Gateway) │ │ (Repeater) │ │ (Thermostat) │ + └─────────────────┘ └─────────────────┘ └─────────────────┘ + │ │ │ + │ ▼ │ + │ ┌─────────────────┐ │ + │ │ End Device │ │ + │ │ (Sensor) │ │ + │ └─────────────────┘ │ + │ │ + ▼ ▼ + ┌─────────────────┐ ┌─────────────────┐ + │ End Device │ │ End Device │ + │ (Sensor) │ │ (Sensor) │ + └─────────────────┘ └─────────────────┘ + + +**Device Roles** + +* **Coordinator**: Forms and manages the network, stores network information +* **Router**: Extends network range, routes messages, mains powered devices (typicaly lights, switches, etc.) +* **End Device**: Battery-powered devices that can sleep for extended periods (typicaly sensors) + +Zigbee Library Structure +------------------------ + +**The library is split into three main components:** + +* ``ZigbeeCore``: The main class that manages the Zigbee network +* ``ZigbeeEP``: The base class for all Zigbee endpoints, which provides common functionality for all endpoint types +* ``Specific endpoint classes``: The classes for all Zigbee endpoints, which provides the specific functionality for each endpoint type + +ZigbeeCore +********** + +The ``ZigbeeCore`` class is the main entry point for all Zigbee operations. It serves as the central coordinator that manages: + +* **Network Operations**: Starting, stopping, and managing the Zigbee network +* **Device Role Management**: Configuring the device as Coordinator, Router, or End Device +* **Endpoint Management**: Adding and managing multiple device endpoints +* **Network Discovery**: Scanning for and joining existing networks +* **OTA Updates**: Managing over-the-air firmware updates +* **Power Management**: Configuring sleep modes for battery-powered devices + +The ``ZigbeeCore`` class is implemented as a singleton, meaning there's only one instance available globally. You access it directly as ``Zigbee`` without creating an instance. + +.. toctree:: + :maxdepth: 3 + + zigbee_core + +ZigbeeEP +******** + +The ``ZigbeeEP`` class is the base class for all Zigbee endpoints. It provides common functionality for all endpoint types. + +* **Device Information**: Every endpoint can be configured with manufacturer and model information that helps identify the device on the network +* **Binding Management**: Binding allows endpoints to establish direct communication links with other devices. This enables automatic command transmission without requiring manual addressing +* **Power Management**: Endpoints can report their power source type and battery status, which helps the network optimize communication patterns +* **Time Synchronization**: Endpoints can synchronize with network time, enabling time-based operations and scheduling +* **OTA Support**: Endpoints can receive over-the-air firmware updates to add new features or fix bugs +* **Device Discovery**: Endpoints can read manufacturer and model information from other devices on the network + +.. toctree:: + :maxdepth: 2 + + zigbee_ep + +Specific endpoint classes +************************* + +Library provides the following endpoint classes from lights, switches, sensors, etc. Each endpoint class provides the specific functionality for each endpoint type and inherits from the ``ZigbeeEP`` class. + +.. toctree:: + :maxdepth: 1 + :glob: + + ep_* + + +Common Problems and Issues +-------------------------- + +Troubleshooting +--------------- + +Common Issues +************* + +**Device won't join network** + * Ensure the coordinator is in pairing mode + * Check that the device is configured with the correct role + * Verify the channel mask includes the coordinator's channel + +**OTA updates fail** + * Ensure the OTA server is properly configured + * Check that the device has sufficient memory for the update + * Verify network connectivity + +**Battery devices not working** + * Ensure proper power source configuration + * Check sleep/wake timing settings + * Verify parent device (router/coordinator) is always powered + +**Binding issues** + * Check that both devices support the required clusters + * Verify that binding is enabled on both devices + * Ensure devices are on the same network + +**Network connectivity problems** + * Check that devices are within range + * Verify that routers are properly configured + * Check for interference from other 2.4GHz devices + +Factory Reset +************* + +If you have problems with connecting to the network, you can try to factory reset the device. This will erase all the network settings and act as brand new device. + +.. code-block:: arduino + + Zigbee.factoryReset(true); // true = restart after reset + +Debug Mode +********** + +For better debugging, you can enable debug mode to get detailed information about network operations. Call debug mode before starting Zigbee. +Also selectiong zigbee mode with *debug* suffix is recommended. + +.. code-block:: arduino + + Zigbee.setDebugMode(true); + // Start Zigbee with debug output + Zigbee.begin(); \ No newline at end of file diff --git a/docs/en/zigbee/zigbee_core.rst b/docs/en/zigbee/zigbee_core.rst new file mode 100644 index 00000000000..819526c8be1 --- /dev/null +++ b/docs/en/zigbee/zigbee_core.rst @@ -0,0 +1,375 @@ +########## +ZigbeeCore +########## + +About +----- + +The ``ZigbeeCore`` class is the main entry point for all Zigbee operations. It serves as the central class that manages: + +* **Network Operations**: Starting, stopping, and managing the Zigbee network +* **Device Role Management**: Configuring the device as Coordinator, Router, or End Device +* **Endpoint Management**: Adding and managing multiple device endpoints +* **Network Discovery**: Scanning for and joining existing networks + +ZigbeeCore APIs +--------------- + +Network Initialization +********************** + +begin +^^^^^ + +Initializes the Zigbee stack and starts the network. + +.. code-block:: arduino + + bool begin(zigbee_role_t role = ZIGBEE_END_DEVICE, bool erase_nvs = false); + bool begin(esp_zb_cfg_t *role_cfg, bool erase_nvs = false); + +* ``role`` - Device role (default: ``ZIGBEE_END_DEVICE``) +* ``role_cfg`` - Custom role configuration structure +* ``erase_nvs`` - Whether to erase NVS storage (default: ``false``) + +This function will return ``true`` if initialization successful, ``false`` otherwise. + +**Available Roles:** + +* **ZIGBEE_COORDINATOR**: Network coordinator, forms and manages the network +* **ZIGBEE_ROUTER**: Network router, connects to existing network and extends network range and routes messages (if device is mains powered, always use this role) +* **ZIGBEE_END_DEVICE**: End device, connects to existing network (typically battery-powered which can sleep) + +.. note:: + + Depending on the Zigbee role, proper Zigbee mode and partition scheme must be set in the Arduino IDE. + + * **ZIGBEE_COORDINATOR** and **ZIGBEE_ROUTER**: + * Zigbee mode to ``Zigbee ZCZR (coordinator/router)``. + * Partition scheme to ``Zigbee ZCZR xMB with spiffs`` (where ``x`` is the number of MB of seleted flash size). + * **ZIGBEE_END_DEVICE**: + * Zigbee mode to ``Zigbee ED (end device)``. + * Partition scheme to ``Zigbee xMB with spiffs`` (where ``x`` is the number of MB of seleted flash size). + +Network Status +************** + +started +^^^^^^^ + +Checks if the Zigbee stack has been started. + +.. code-block:: arduino + + bool started(); + +This function will return ``true`` if Zigbee stack is running, ``false`` otherwise. + +connected +^^^^^^^^^ + +Checks if the device is connected to a Zigbee network. + +.. code-block:: arduino + + bool connected(); + +This function will return ``true`` if connected to network, ``false`` otherwise. + +getRole +^^^^^^^ + +Gets the current Zigbee device role. + +.. code-block:: arduino + + zigbee_role_t getRole(); + +This function will return current device role (``ZIGBEE_COORDINATOR``, ``ZIGBEE_ROUTER``, ``ZIGBEE_END_DEVICE``). + +Endpoint Management +******************* + +addEndpoint +^^^^^^^^^^^ + +Adds an endpoint to the Zigbee network. + +.. code-block:: arduino + + bool addEndpoint(ZigbeeEP *ep); + +* ``ep`` - Pointer to the endpoint object to add + +This function will return ``true`` if endpoint added successfully, ``false`` otherwise. + +Network Configuration +********************* + +setPrimaryChannelMask +^^^^^^^^^^^^^^^^^^^^^ + +Sets the primary channel mask for network scanning and joining. + +.. code-block:: arduino + + void setPrimaryChannelMask(uint32_t mask); + +* ``mask`` - Channel mask (default: all channels 11-26, mask 0x07FFF800) + +setScanDuration +^^^^^^^^^^^^^^^ + +Sets the scan duration for network discovery. + +.. code-block:: arduino + + void setScanDuration(uint8_t duration); + +* ``duration`` - Scan duration (1-4, where 1 is fastest, 4 is slowest) + +getScanDuration +^^^^^^^^^^^^^^^ + +Gets the current scan duration setting. + +.. code-block:: arduino + + uint8_t getScanDuration(); + +This function will return current scan duration (1-4). + +Power Management +**************** + +setRxOnWhenIdle +^^^^^^^^^^^^^^^ + +Sets whether the device keeps its receiver on when idle. + +.. code-block:: arduino + + void setRxOnWhenIdle(bool rx_on_when_idle); + +* ``rx_on_when_idle`` - ``true`` to keep receiver on, ``false`` to allow sleep + +getRxOnWhenIdle +^^^^^^^^^^^^^^^ + +Gets the current receiver idle setting. + +.. code-block:: arduino + + bool getRxOnWhenIdle(); + +This function will return current receiver idle setting. + +setTimeout +^^^^^^^^^^ + +Sets the timeout for network operations. + +.. code-block:: arduino + + void setTimeout(uint32_t timeout); + +* ``timeout`` - Timeout in milliseconds (default: 30000ms) + +Network Discovery +***************** + +scanNetworks +^^^^^^^^^^^^ + +Scans for available Zigbee networks. + +.. code-block:: arduino + + void scanNetworks(uint32_t channel_mask = ESP_ZB_TRANSCEIVER_ALL_CHANNELS_MASK, uint8_t scan_duration = 5); + +* ``channel_mask`` - Channels to scan (default: all channels) +* ``scan_duration`` - Scan duration (default: 5) + +scanComplete +^^^^^^^^^^^^ + +Checks if network scanning is complete. + +.. code-block:: arduino + + int16_t scanComplete(); + +This function will return: +* ``-2``: Scan failed or not started +* ``-1``: Scan running +* ``0``: No networks found +* ``>0``: Number of networks found + +getScanResult +^^^^^^^^^^^^^ + +Gets the scan results. + +.. code-block:: arduino + + zigbee_scan_result_t *getScanResult(); + +This function will return pointer to scan results, or ``NULL`` if no results. + +scanDelete +^^^^^^^^^^ + +Deletes the scan results from memory. + +.. code-block:: arduino + + void scanDelete(); + +Network Management (Coordinator only) +************************************* + +setRebootOpenNetwork +^^^^^^^^^^^^^^^^^^^^ + +Opens the network for joining after reboot for a specified time. + +.. code-block:: arduino + + void setRebootOpenNetwork(uint8_t time); + +* ``time`` - Time in seconds to keep network open after reboot + +openNetwork +^^^^^^^^^^^ + +Opens the network for device joining for a specified time. + +.. code-block:: arduino + + void openNetwork(uint8_t time); + +* ``time`` - Time in seconds to keep network open for device joining + +closeNetwork +^^^^^^^^^^^^ + +Closes the network to prevent new devices from joining. + +.. code-block:: arduino + + void closeNetwork(); + +Radio Configuration +******************* + +setRadioConfig +^^^^^^^^^^^^^^ + +Sets the radio configuration. + +.. code-block:: arduino + + void setRadioConfig(esp_zb_radio_config_t config); + +* ``config`` - Radio configuration structure + +getRadioConfig +^^^^^^^^^^^^^^ + +Gets the current radio configuration. + +.. code-block:: arduino + + esp_zb_radio_config_t getRadioConfig(); + +This function will return current radio configuration. + +Host Configuration +****************** + +setHostConfig +^^^^^^^^^^^^^ + +Sets the host configuration. + +.. code-block:: arduino + + void setHostConfig(esp_zb_host_config_t config); + +* ``config`` - Host configuration structure + +getHostConfig +^^^^^^^^^^^^^ + +Gets the current host configuration. + +.. code-block:: arduino + + esp_zb_host_config_t getHostConfig(); + +This function will return current host configuration. + +Debug and Utilities +******************* + +setDebugMode +^^^^^^^^^^^^ + +Enables or disables debug mode. + +.. code-block:: arduino + + void setDebugMode(bool debug); + +* ``debug`` - ``true`` to enable debug output, ``false`` to disable + +getDebugMode +^^^^^^^^^^^^ + +Gets the current debug mode setting. + +.. code-block:: arduino + + bool getDebugMode(); + +This function will return current debug mode setting. + +factoryReset +^^^^^^^^^^^^ + +Performs a factory reset, clearing all network settings. + +.. code-block:: arduino + + void factoryReset(bool restart = true); + +* ``restart`` - ``true`` to restart after reset (default: ``true``) + +Utility Functions +***************** + +formatIEEEAddress +^^^^^^^^^^^^^^^^^ + +Formats an IEEE address for display. + +.. code-block:: arduino + + static const char *formatIEEEAddress(const esp_zb_ieee_addr_t addr); + +* ``addr`` - IEEE address to format + +This function will return formatted address string. + +formatShortAddress +^^^^^^^^^^^^^^^^^^ + +Formats a short address for display. + +.. code-block:: arduino + + static const char *formatShortAddress(uint16_t addr); + +* ``addr`` - Short address to format + +This function will return formatted address string. diff --git a/docs/en/zigbee/zigbee_ep.rst b/docs/en/zigbee/zigbee_ep.rst new file mode 100644 index 00000000000..8e7c47ee572 --- /dev/null +++ b/docs/en/zigbee/zigbee_ep.rst @@ -0,0 +1,357 @@ +######## +ZigbeeEP +######## + +About +----- + +The ``ZigbeeEP`` class is the base class for all Zigbee endpoints. It provides common functionality for all endpoint types. + +* **Device Information**: Every endpoint can be configured with manufacturer and model information that helps identify the device on the network +* **Binding Management**: Binding allows endpoints to establish direct communication links with other devices. This enables automatic command transmission without requiring manual addressing +* **Power Management**: Endpoints can report their power source type and battery status, which helps the network optimize communication patterns +* **Time Synchronization**: Endpoints can synchronize with network time, enabling time-based operations and scheduling +* **OTA Support**: Endpoints can receive over-the-air firmware updates to add new features or fix bugs +* **Device Discovery**: Endpoints can read manufacturer and model information from other devices on the network + + +ZigbeeEP APIs +------------- + +Device Information +****************** + +setManufacturerAndModel +^^^^^^^^^^^^^^^^^^^^^^^ + +Sets the manufacturer name and model identifier for the device. + +.. code-block:: arduino + + bool setManufacturerAndModel(const char *name, const char *model); + +* ``name`` - Manufacturer name (max 32 characters) +* ``model`` - Model identifier (max 32 characters) + +This function will return ``true`` if set successfully, ``false`` otherwise. + +getEndpoint +^^^^^^^^^^^ + +Gets the endpoint number assigned to this device. + +.. code-block:: arduino + + uint8_t getEndpoint(); + +This function will return the endpoint number (1-254). + +Binding Management +****************** + +bound +^^^^^ + +Checks if the endpoint has any bound devices. + +.. code-block:: arduino + + bool bound(); + +This function will return ``true`` if the endpoint has bound devices, ``false`` otherwise. + +getBoundDevices +^^^^^^^^^^^^^^^ + +Gets the list of devices bound to this endpoint. + +.. code-block:: arduino + + std::vector getBoundDevices(); + +This function will return list of bound device parameters. + +printBoundDevices +^^^^^^^^^^^^^^^^^ + +Prints information about bound devices to Serial or a custom Print object. + +.. code-block:: arduino + + void printBoundDevices(Print &print = Serial); + +* ``print`` - Custom Print object (optional, defaults to Serial) + +allowMultipleBinding +^^^^^^^^^^^^^^^^^^^^ + +Enables or disables multiple device binding for this endpoint. + +.. code-block:: arduino + + void allowMultipleBinding(bool bind); + +* ``bind`` - ``true`` to allow multiple bindings, ``false`` for single binding only + +setManualBinding +^^^^^^^^^^^^^^^^ + +Enables or disables manual binding mode. Manual binding mode is supposed to be used when using ZHA or Z2M where you bind devices manually. + +.. code-block:: arduino + + void setManualBinding(bool bind); + +* ``bind`` - ``true`` for manual binding, ``false`` for automatic binding (default) + +clearBoundDevices +^^^^^^^^^^^^^^^^^ + +Removes all bound devices from this endpoint. + +.. code-block:: arduino + + void clearBoundDevices(); + +Binding Status +************** + +epAllowMultipleBinding +^^^^^^^^^^^^^^^^^^^^^^ + +Gets whether multiple device binding is allowed for this endpoint. + +.. code-block:: arduino + + bool epAllowMultipleBinding(); + +This function will return ``true`` if multiple bindings are allowed, ``false`` otherwise. + +epUseManualBinding +^^^^^^^^^^^^^^^^^^ + +Gets whether manual binding mode is enabled for this endpoint. + +.. code-block:: arduino + + bool epUseManualBinding(); + +This function will return ``true`` if manual binding is enabled, ``false`` otherwise. + +Power Management +**************** + +setPowerSource +^^^^^^^^^^^^^^ + +Sets the power source type for the endpoint. + +.. code-block:: arduino + + bool setPowerSource(uint8_t source, uint8_t percentage = 0xff, uint8_t voltage = 0xff); + +* ``source`` - Power source type (``ZB_POWER_SOURCE_MAINS``, ``ZB_POWER_SOURCE_BATTERY``, etc.) +* ``percentage`` - Battery percentage (0-100, default: 0xff) +* ``voltage`` - Battery voltage in 100mV units (default: 0xff) + +This function will return ``true`` if set successfully, ``false`` otherwise. + +setBatteryPercentage +^^^^^^^^^^^^^^^^^^^^ + +Sets the current battery percentage. + +.. code-block:: arduino + + bool setBatteryPercentage(uint8_t percentage); + +* ``percentage`` - Battery percentage (0-100) + +This function will return ``true`` if set successfully, ``false`` otherwise. + +setBatteryVoltage +^^^^^^^^^^^^^^^^^ + +Sets the battery voltage. + +.. code-block:: arduino + + bool setBatteryVoltage(uint8_t voltage); + +* ``voltage`` - Battery voltage in 100mV units (e.g., 35 for 3.5V) + +This function will return ``true`` if set successfully, ``false`` otherwise. + +reportBatteryPercentage +^^^^^^^^^^^^^^^^^^^^^^^ + +Reports the current battery percentage to the network. + +.. code-block:: arduino + + bool reportBatteryPercentage(); + +This function will return ``true`` if reported successfully, ``false`` otherwise. + +Time Synchronization +******************** + +addTimeCluster +^^^^^^^^^^^^^^ + +Adds time synchronization cluster to the endpoint. When you want to add a server cluster (have the time and GMT offset) fill the time structure with the current time and GMT offset. +For client cluster (get the time and GMT offset) keep the default parameters. + +.. code-block:: arduino + + bool addTimeCluster(tm time = {}, int32_t gmt_offset = 0); + +* ``time`` - Current time structure (default: empty) +* ``gmt_offset`` - GMT offset in seconds (default: 0) + +This function will return ``true`` if added successfully, ``false`` otherwise. + +setTime +^^^^^^^ + +Sets the current time for the endpoint. + +.. code-block:: arduino + + bool setTime(tm time); + +* ``time`` - Time structure to set + +This function will return ``true`` if set successfully, ``false`` otherwise. + +setTimezone +^^^^^^^^^^^ + +Sets the timezone offset for the endpoint. + +.. code-block:: arduino + + bool setTimezone(int32_t gmt_offset); + +* ``gmt_offset`` - GMT offset in seconds + +This function will return ``true`` if set successfully, ``false`` otherwise. + +getTime +^^^^^^^ + +Gets the current network time. + +.. code-block:: arduino + + struct tm getTime(uint8_t endpoint = 1, int32_t short_addr = 0x0000, esp_zb_ieee_addr_t ieee_addr = {}); + +* ``endpoint`` - Target endpoint (default: 1) +* ``short_addr`` - Target device short address (default: 0x0000) +* ``ieee_addr`` - Target device IEEE address (default: empty) + +This function will return network time structure. + +getTimezone +^^^^^^^^^^^ + +Gets the timezone offset. + +.. code-block:: arduino + + int32_t getTimezone(uint8_t endpoint = 1, int32_t short_addr = 0x0000, esp_zb_ieee_addr_t ieee_addr = {}); + +* ``endpoint`` - Target endpoint (default: 1) +* ``short_addr`` - Target device short address (default: 0x0000) +* ``ieee_addr`` - Target device IEEE address (default: empty) + +This function will return GMT offset in seconds. + +OTA Support +*********** + +addOTAClient +^^^^^^^^^^^^ + +Adds OTA client to the endpoint for firmware updates. + +.. code-block:: arduino + + bool addOTAClient(uint32_t file_version, uint32_t downloaded_file_ver, uint16_t hw_version, uint16_t manufacturer = 0x1001, uint16_t image_type = 0x1011, uint8_t max_data_size = 223); + +* ``file_version`` - Current firmware version +* ``downloaded_file_ver`` - Downloaded file version +* ``hw_version`` - Hardware version +* ``manufacturer`` - Manufacturer code (default: 0x1001) +* ``image_type`` - Image type code (default: 0x1011) +* ``max_data_size`` - Maximum data size for OTA transfer (default: 223) + +This function will return ``true`` if added successfully, ``false`` otherwise. + +requestOTAUpdate +^^^^^^^^^^^^^^^^ + +Requests OTA update from the server. + +.. code-block:: arduino + + void requestOTAUpdate(); + +Device Discovery +**************** + +readManufacturer +^^^^^^^^^^^^^^^^ + +Reads the manufacturer name from a remote device. + +.. code-block:: arduino + + char *readManufacturer(uint8_t endpoint, uint16_t short_addr, esp_zb_ieee_addr_t ieee_addr); + +* ``endpoint`` - Target endpoint number +* ``short_addr`` - Target device short address +* ``ieee_addr`` - Target device IEEE address + +This function will return pointer to manufacturer string, or ``NULL`` if read failed. + +readModel +^^^^^^^^^ + +Reads the model identifier from a remote device. + +.. code-block:: arduino + + char *readModel(uint8_t endpoint, uint16_t short_addr, esp_zb_ieee_addr_t ieee_addr); + +* ``endpoint`` - Target endpoint number +* ``short_addr`` - Target device short address +* ``ieee_addr`` - Target device IEEE address + +This function will return pointer to model string, or ``NULL`` if read failed. + +Event Handling +************** + +onIdentify +^^^^^^^^^^ + +Sets a callback function for identify events. + +.. code-block:: arduino + + void onIdentify(void (*callback)(uint16_t)); + +* ``callback`` - Function to call when identify event occurs +* ``time`` - Identify time in seconds + +Supported Endpoints +------------------- + +The Zigbee library provides specialized endpoint classes for different device types. Each endpoint type includes specific clusters and functionality relevant to that device category. + +.. toctree:: + :maxdepth: 1 + :glob: + + ep_*