feat(matter): adds temperature controlled cabinet matter endpoint

Author: SuGlider

CMakeLists.txt

@@ -191,6 +191,7 @@ set(ARDUINO_LIBRARY_Matter_SRCS
   libraries/Matter/src/MatterEndpoints/MatterEnhancedColorLight.cpp
   libraries/Matter/src/MatterEndpoints/MatterFan.cpp
   libraries/Matter/src/MatterEndpoints/MatterTemperatureSensor.cpp
+  libraries/Matter/src/MatterEndpoints/MatterTemperatureControlledCabinet.cpp
   libraries/Matter/src/MatterEndpoints/MatterHumiditySensor.cpp
   libraries/Matter/src/MatterEndpoints/MatterContactSensor.cpp
   libraries/Matter/src/MatterEndpoints/MatterPressureSensor.cpp

docs/en/matter/ep_temperature_controlled_cabinet.rst

@@ -0,0 +1,293 @@
+#######################################
+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, optional step control, or temperature level support.
+
+**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.
+
+**Features:**
+* Two initialization modes:
+  * **Temperature Number Mode** (``begin(tempSetpoint, minTemp, maxTemp, step)``): Temperature setpoint control with min/max limits and optional step
+  * **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)
+* Optional temperature step control (temperature_number mode)
+* 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
+
+**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`` - Temperature step value in Celsius for step control feature (default: 0.50, disabled if 0)
+
+This function will return ``true`` if successful, ``false`` otherwise.
+
+**Note:** The implementation stores temperature with 1/100th degree Celsius precision internally. If step is greater than 0, the temperature_step feature will be enabled.
+
+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 (Optional)
+***********************************
+
+setStep
+^^^^^^^
+
+Sets the temperature step value. This enables the temperature_step feature.
+
+**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 requires the temperature_number feature to be enabled. 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.
+
+.. 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, allowing Matter controllers to observe real-time changes.
+
+See ``MatterTemperatureControlledCabinetLevels`` example for the temperature level mode implementation.
+

docs/en/matter/matter.rst

@@ -130,6 +130,8 @@ The library provides specialized endpoint classes for different device types. Ea
 
 **Control Endpoints:**
 
+* ``MatterTemperatureControlledCabinet``: Temperature controlled cabinet (setpoint control with min/max limits)
+
 * ``MatterFan``: Fan with speed and mode control
 * ``MatterThermostat``: Thermostat with temperature control and setpoints
 * ``MatterOnOffPlugin``: On/off plugin unit (power outlet/relay)