##################################
MatterTemperatureControlledCabinet
##################################

About
-----

The ``MatterTemperatureControlledCabinet`` class provides a temperature controlled cabinet endpoint for Matter networks. This endpoint implements the Matter temperature control standard for managing temperature setpoints with min/max limits, step control (always enabled), or temperature level support.

**Features:**

* Two initialization modes:

   - **Temperature Number Mode** (``begin(tempSetpoint, minTemp, maxTemp, step)``): Temperature setpoint control with min/max limits and step control
   - **Temperature Level Mode** (``begin(supportedLevels, levelCount, selectedLevel)``): Temperature level control with array of supported levels

* 1/100th degree Celsius precision (for temperature_number mode)
* Min/max temperature limits with validation (temperature_number mode)
* Temperature step control (temperature_number mode, always enabled)
* Temperature level array support (temperature_level mode)
* Automatic setpoint validation against limits
* Feature validation - methods return errors if called with wrong feature mode
* Integration with Apple HomeKit, Amazon Alexa, and Google Home
* Matter standard compliance

**Important:** The ``temperature_number`` and ``temperature_level`` features are **mutually exclusive**. Only one can be enabled at a time. Use ``begin(tempSetpoint, minTemp, maxTemp, step)`` for temperature_number mode or ``begin(supportedLevels, levelCount, selectedLevel)`` for temperature_level mode.

**Use Cases:**

* Refrigerators and freezers
* Wine coolers
* Medical storage cabinets
* Laboratory equipment
* Food storage systems
* Temperature-controlled storage units

API Reference
-------------

Constructor
***********

MatterTemperatureControlledCabinet
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Creates a new Matter temperature controlled cabinet endpoint.

.. code-block:: arduino

    MatterTemperatureControlledCabinet();

Initialization
**************

begin
^^^^^

Initializes the Matter temperature controlled cabinet endpoint with **temperature_number** feature mode. This enables temperature setpoint control with min/max limits and optional step.

**Note:** This mode is mutually exclusive with temperature_level mode. Use ``begin(supportedLevels, levelCount, selectedLevel)`` for temperature level control.

.. code-block:: arduino

    bool begin(double tempSetpoint = 0.00, double minTemperature = -10.0, double maxTemperature = 32.0, double step = 0.50);

* ``tempSetpoint`` - Initial temperature setpoint in Celsius (default: 0.00)
* ``minTemperature`` - Minimum allowed temperature in Celsius (default: -10.0)
* ``maxTemperature`` - Maximum allowed temperature in Celsius (default: 32.0)
* ``step`` - Initial temperature step value in Celsius (default: 0.50)

This function will return ``true`` if successful, ``false`` otherwise.

**Note:** The implementation stores temperature with 1/100th degree Celsius precision internally. The temperature_step feature is always enabled for temperature_number mode, allowing ``setStep()`` to be called later even if step is not provided in ``begin()``.

begin (overloaded)
^^^^^^^^^^^^^^^^^^

Initializes the Matter temperature controlled cabinet endpoint with **temperature_level** feature mode. This enables temperature level control with an array of supported levels.

**Note:** This mode is mutually exclusive with temperature_number mode. Use ``begin(tempSetpoint, minTemp, maxTemp, step)`` for temperature setpoint control.

.. code-block:: arduino

    bool begin(uint8_t *supportedLevels, uint16_t levelCount, uint8_t selectedLevel = 0);

* ``supportedLevels`` - Pointer to array of temperature level values (uint8_t, 0-255)
* ``levelCount`` - Number of levels in the array (maximum: 16)
* ``selectedLevel`` - Initial selected temperature level (default: 0)

This function will return ``true`` if successful, ``false`` otherwise.

**Note:** The maximum number of supported levels is 16 (defined by ``temperature_control::k_max_temp_level_count``). The array is copied internally, so it does not need to remain valid after the function returns. This method uses a custom endpoint implementation that properly supports the temperature_level feature.

end
^^^

Stops processing Matter temperature controlled cabinet events.

.. code-block:: arduino

    void end();

Temperature Setpoint Control
****************************

setTemperatureSetpoint
^^^^^^^^^^^^^^^^^^^^^^^

Sets the temperature setpoint value. The setpoint will be validated against min/max limits.

**Requires:** temperature_number feature mode (use ``begin()``)

.. code-block:: arduino

    bool setTemperatureSetpoint(double temperature);

* ``temperature`` - Temperature setpoint in Celsius

This function will return ``true`` if successful, ``false`` otherwise (e.g., if temperature is out of range or wrong feature mode).

**Note:** Temperature is stored with 1/100th degree Celsius precision. The setpoint must be within the min/max temperature range. This method will return ``false`` and log an error if called when using temperature_level mode.

getTemperatureSetpoint
^^^^^^^^^^^^^^^^^^^^^^

Gets the current temperature setpoint value.

.. code-block:: arduino

    double getTemperatureSetpoint();

This function will return the temperature setpoint in Celsius with 1/100th degree precision.

Min/Max Temperature Control
****************************

setMinTemperature
^^^^^^^^^^^^^^^^^

Sets the minimum allowed temperature.

**Requires:** temperature_number feature mode (use ``begin()``)

.. code-block:: arduino

    bool setMinTemperature(double temperature);

* ``temperature`` - Minimum temperature in Celsius

This function will return ``true`` if successful, ``false`` otherwise. Will return ``false`` and log an error if called when using temperature_level mode.

getMinTemperature
^^^^^^^^^^^^^^^^^

Gets the minimum allowed temperature.

.. code-block:: arduino

    double getMinTemperature();

This function will return the minimum temperature in Celsius with 1/100th degree precision.

setMaxTemperature
^^^^^^^^^^^^^^^^^

Sets the maximum allowed temperature.

**Requires:** temperature_number feature mode (use ``begin()``)

.. code-block:: arduino

    bool setMaxTemperature(double temperature);

* ``temperature`` - Maximum temperature in Celsius

This function will return ``true`` if successful, ``false`` otherwise. Will return ``false`` and log an error if called when using temperature_level mode.

getMaxTemperature
^^^^^^^^^^^^^^^^^

Gets the maximum allowed temperature.

.. code-block:: arduino

    double getMaxTemperature();

This function will return the maximum temperature in Celsius with 1/100th degree precision.

Temperature Step Control
*************************

setStep
^^^^^^^

Sets the temperature step value.

**Requires:** temperature_number feature mode (use ``begin()``)

.. code-block:: arduino

    bool setStep(double step);

* ``step`` - Temperature step value in Celsius

This function will return ``true`` if successful, ``false`` otherwise.

**Note:** The temperature_step feature is always enabled when using temperature_number mode, so this method can be called at any time to set or change the step value, even if step was not provided in ``begin()``. This method will return ``false`` and log an error if called when using temperature_level mode.

getStep
^^^^^^^

Gets the current temperature step value.

.. code-block:: arduino

    double getStep();

This function will return the temperature step in Celsius with 1/100th degree precision.

Temperature Level Control (Optional)
*************************************

setSelectedTemperatureLevel
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Sets the selected temperature level.

**Requires:** temperature_level feature mode (use ``begin(supportedLevels, levelCount, selectedLevel)``)

.. code-block:: arduino

    bool setSelectedTemperatureLevel(uint8_t level);

* ``level`` - Temperature level (0-255)

This function will return ``true`` if successful, ``false`` otherwise.

**Note:** Temperature level and temperature number features are mutually exclusive. This method will return ``false`` and log an error if called when using temperature_number mode.

getSelectedTemperatureLevel
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Gets the current selected temperature level.

.. code-block:: arduino

    uint8_t getSelectedTemperatureLevel();

This function will return the selected temperature level (0-255).

setSupportedTemperatureLevels
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Sets the supported temperature levels array.

**Requires:** temperature_level feature mode (use ``begin(supportedLevels, levelCount, selectedLevel)``)

.. code-block:: arduino

    bool setSupportedTemperatureLevels(uint8_t *levels, uint16_t count);

* ``levels`` - Pointer to array of temperature level values (array is copied internally)
* ``count`` - Number of levels in the array (maximum: 16)

This function will return ``true`` if successful, ``false`` otherwise.

**Note:** The maximum number of supported levels is 16. The array is copied internally, so it does not need to remain valid after the function returns. This method will return ``false`` and log an error if called when using temperature_number mode or if count exceeds the maximum.

getSupportedTemperatureLevelsCount
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Gets the count of supported temperature levels.

.. code-block:: arduino

    uint16_t getSupportedTemperatureLevelsCount();

This function will return the number of supported temperature levels.

Example
-------

Temperature Controlled Cabinet
******************************

The example demonstrates the temperature_number mode with dynamic temperature updates. The temperature setpoint automatically cycles between the minimum and maximum limits every 1 second using the configured step value, allowing Matter controllers to observe real-time changes. The example also monitors and logs when the initial setpoint is reached or overpassed in each direction.

.. literalinclude:: ../../../libraries/Matter/examples/MatterTemperatureControlledCabinet/MatterTemperatureControlledCabinet.ino
    :language: arduino

Temperature Controlled Cabinet (Level Mode)
********************************************

A separate example demonstrates the temperature_level mode with dynamic level updates. The temperature level automatically cycles through all supported levels every 1 second in both directions (increasing and decreasing), allowing Matter controllers to observe real-time changes. The example also monitors and logs when the initial level is reached or overpassed in each direction.

See ``MatterTemperatureControlledCabinetLevels`` example for the temperature level mode implementation.
