########
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.

setVersion
^^^^^^^^^^

Sets the application version for the endpoint. The value is stored in the endpoint config and added to the Basic cluster (Application Version attribute). Must be called before ``Zigbee.begin()``.

.. code-block:: arduino

    void setVersion(uint8_t version);

* ``version`` - Application version (0-255)

setHardwareVersion
^^^^^^^^^^^^^^^^^^

Sets the hardware version for the endpoint. The value is added to the Basic cluster (Hardware Version attribute). Must be called before ``Zigbee.begin()``.

.. code-block:: arduino

    void setHardwareVersion(uint8_t version);

* ``version`` - Hardware version (0-255)

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<esp_zb_binding_info_t> 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 100 mV 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 100 mV units (e.g., 35 for 3.5 V)

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

onDefaultResponse
^^^^^^^^^^^^^^^^^

Sets a callback for default response messages for this endpoint.

.. code-block:: arduino

    void onDefaultResponse(void (*callback)(zb_cmd_type_t resp_to_cmd, esp_zb_zcl_status_t status));

* ``callback`` - Function pointer to the callback function

This callback will be called when a default response is received for this specific endpoint.

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_*
