##########
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 selected 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 selected flash size).

start
^^^^^
Starts the Zigbee stack again, if it was stopped by calling ``stop()``.

.. code-block:: arduino

    void start();


stop
^^^^
Stops the Zigbee stack. This can be used after calling ``begin()`` to stop the Zigbee stack.
Usage example is to save power or when you need the radio to be available for other tasks.

.. code-block:: arduino

    void stop();

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: 30000 ms)

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``)

onGlobalDefaultResponse
^^^^^^^^^^^^^^^^^^^^^^^

Sets a global callback for default response messages.

.. code-block:: arduino

    void onGlobalDefaultResponse(void (*callback)(zb_cmd_type_t resp_to_cmd, esp_zb_zcl_status_t status, uint8_t endpoint, uint16_t cluster));

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

This callback will be called for all endpoints when a default response is received.

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.
