Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 792297f

Browse files
SuGliderCopilotpre-commit-ci-lite[bot]
authored
feat(matter): adds temperature controlled cabinet ep (#12104)
* feat(matter): adds temperature controlled cabinet matter endpoint * feat(matter): fixes step attibute issue from esp-matter * feat(matter): organize examples, keywords and fix init error * fix(matter): typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(matter): typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(matter): improves commentaries Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(matter): typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(matter): typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * feat(matter): checks level to verify that it is valid Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * feat(matter): checks level to verify that it is valid Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(matter_docs): rst formatting * fix(matter): typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(matter): typo Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(matter): removes redundant code Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(docs): identation and allignment * fix(docs): identation and allignment * fix(docs): identation and allignment * fix(docs): reorganization of the text Reinstate important note about mutually exclusive features for temperature control modes. * ci(pre-commit): Apply automatic fixes * fix(matter_example): bad ci.yml content * ci(pre-commit): Apply automatic fixes * fix(matter): bad content in source file Refactor MatterTemperatureControlledCabinet to support both temperature_number and temperature_level features. Introduce new methods for handling temperature levels and update existing methods to accommodate the new structure. --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: pre-commit-ci-lite[bot] <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com>
1 parent 9b3364c commit 792297f

File tree

13 files changed

+2044
-1
lines changed

13 files changed

+2044
-1
lines changed

‎CMakeLists.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -191,6 +191,7 @@ set(ARDUINO_LIBRARY_Matter_SRCS
191191
libraries/Matter/src/MatterEndpoints/MatterEnhancedColorLight.cpp
192192
libraries/Matter/src/MatterEndpoints/MatterFan.cpp
193193
libraries/Matter/src/MatterEndpoints/MatterTemperatureSensor.cpp
194+
libraries/Matter/src/MatterEndpoints/MatterTemperatureControlledCabinet.cpp
194195
libraries/Matter/src/MatterEndpoints/MatterHumiditySensor.cpp
195196
libraries/Matter/src/MatterEndpoints/MatterContactSensor.cpp
196197
libraries/Matter/src/MatterEndpoints/MatterWaterLeakDetector.cpp
Lines changed: 296 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
1+
##################################
2+
MatterTemperatureControlledCabinet
3+
##################################
4+
5+
About
6+
-----
7+
8+
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.
9+
10+
**Features:**
11+
12+
* Two initialization modes:
13+
14+
- **Temperature Number Mode** (``begin(tempSetpoint, minTemp, maxTemp, step)``): Temperature setpoint control with min/max limits and step control
15+
- **Temperature Level Mode** (``begin(supportedLevels, levelCount, selectedLevel)``): Temperature level control with array of supported levels
16+
17+
* 1/100th degree Celsius precision (for temperature_number mode)
18+
* Min/max temperature limits with validation (temperature_number mode)
19+
* Temperature step control (temperature_number mode, always enabled)
20+
* Temperature level array support (temperature_level mode)
21+
* Automatic setpoint validation against limits
22+
* Feature validation - methods return errors if called with wrong feature mode
23+
* Integration with Apple HomeKit, Amazon Alexa, and Google Home
24+
* Matter standard compliance
25+
26+
**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.
27+
28+
**Use Cases:**
29+
30+
* Refrigerators and freezers
31+
* Wine coolers
32+
* Medical storage cabinets
33+
* Laboratory equipment
34+
* Food storage systems
35+
* Temperature-controlled storage units
36+
37+
API Reference
38+
-------------
39+
40+
Constructor
41+
***********
42+
43+
MatterTemperatureControlledCabinet
44+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
45+
46+
Creates a new Matter temperature controlled cabinet endpoint.
47+
48+
.. code-block:: arduino
49+
50+
MatterTemperatureControlledCabinet();
51+
52+
Initialization
53+
**************
54+
55+
begin
56+
^^^^^
57+
58+
Initializes the Matter temperature controlled cabinet endpoint with **temperature_number** feature mode. This enables temperature setpoint control with min/max limits and optional step.
59+
60+
**Note:** This mode is mutually exclusive with temperature_level mode. Use ``begin(supportedLevels, levelCount, selectedLevel)`` for temperature level control.
61+
62+
.. code-block:: arduino
63+
64+
bool begin(double tempSetpoint = 0.00, double minTemperature = -10.0, double maxTemperature = 32.0, double step = 0.50);
65+
66+
* ``tempSetpoint`` - Initial temperature setpoint in Celsius (default: 0.00)
67+
* ``minTemperature`` - Minimum allowed temperature in Celsius (default: -10.0)
68+
* ``maxTemperature`` - Maximum allowed temperature in Celsius (default: 32.0)
69+
* ``step`` - Initial temperature step value in Celsius (default: 0.50)
70+
71+
This function will return ``true`` if successful, ``false`` otherwise.
72+
73+
**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()``.
74+
75+
begin (overloaded)
76+
^^^^^^^^^^^^^^^^^^
77+
78+
Initializes the Matter temperature controlled cabinet endpoint with **temperature_level** feature mode. This enables temperature level control with an array of supported levels.
79+
80+
**Note:** This mode is mutually exclusive with temperature_number mode. Use ``begin(tempSetpoint, minTemp, maxTemp, step)`` for temperature setpoint control.
81+
82+
.. code-block:: arduino
83+
84+
bool begin(uint8_t *supportedLevels, uint16_t levelCount, uint8_t selectedLevel = 0);
85+
86+
* ``supportedLevels`` - Pointer to array of temperature level values (uint8_t, 0-255)
87+
* ``levelCount`` - Number of levels in the array (maximum: 16)
88+
* ``selectedLevel`` - Initial selected temperature level (default: 0)
89+
90+
This function will return ``true`` if successful, ``false`` otherwise.
91+
92+
**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.
93+
94+
end
95+
^^^
96+
97+
Stops processing Matter temperature controlled cabinet events.
98+
99+
.. code-block:: arduino
100+
101+
void end();
102+
103+
Temperature Setpoint Control
104+
****************************
105+
106+
setTemperatureSetpoint
107+
^^^^^^^^^^^^^^^^^^^^^^^
108+
109+
Sets the temperature setpoint value. The setpoint will be validated against min/max limits.
110+
111+
**Requires:** temperature_number feature mode (use ``begin()``)
112+
113+
.. code-block:: arduino
114+
115+
bool setTemperatureSetpoint(double temperature);
116+
117+
* ``temperature`` - Temperature setpoint in Celsius
118+
119+
This function will return ``true`` if successful, ``false`` otherwise (e.g., if temperature is out of range or wrong feature mode).
120+
121+
**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.
122+
123+
getTemperatureSetpoint
124+
^^^^^^^^^^^^^^^^^^^^^^
125+
126+
Gets the current temperature setpoint value.
127+
128+
.. code-block:: arduino
129+
130+
double getTemperatureSetpoint();
131+
132+
This function will return the temperature setpoint in Celsius with 1/100th degree precision.
133+
134+
Min/Max Temperature Control
135+
****************************
136+
137+
setMinTemperature
138+
^^^^^^^^^^^^^^^^^
139+
140+
Sets the minimum allowed temperature.
141+
142+
**Requires:** temperature_number feature mode (use ``begin()``)
143+
144+
.. code-block:: arduino
145+
146+
bool setMinTemperature(double temperature);
147+
148+
* ``temperature`` - Minimum temperature in Celsius
149+
150+
This function will return ``true`` if successful, ``false`` otherwise. Will return ``false`` and log an error if called when using temperature_level mode.
151+
152+
getMinTemperature
153+
^^^^^^^^^^^^^^^^^
154+
155+
Gets the minimum allowed temperature.
156+
157+
.. code-block:: arduino
158+
159+
double getMinTemperature();
160+
161+
This function will return the minimum temperature in Celsius with 1/100th degree precision.
162+
163+
setMaxTemperature
164+
^^^^^^^^^^^^^^^^^
165+
166+
Sets the maximum allowed temperature.
167+
168+
**Requires:** temperature_number feature mode (use ``begin()``)
169+
170+
.. code-block:: arduino
171+
172+
bool setMaxTemperature(double temperature);
173+
174+
* ``temperature`` - Maximum temperature in Celsius
175+
176+
This function will return ``true`` if successful, ``false`` otherwise. Will return ``false`` and log an error if called when using temperature_level mode.
177+
178+
getMaxTemperature
179+
^^^^^^^^^^^^^^^^^
180+
181+
Gets the maximum allowed temperature.
182+
183+
.. code-block:: arduino
184+
185+
double getMaxTemperature();
186+
187+
This function will return the maximum temperature in Celsius with 1/100th degree precision.
188+
189+
Temperature Step Control
190+
*************************
191+
192+
setStep
193+
^^^^^^^
194+
195+
Sets the temperature step value.
196+
197+
**Requires:** temperature_number feature mode (use ``begin()``)
198+
199+
.. code-block:: arduino
200+
201+
bool setStep(double step);
202+
203+
* ``step`` - Temperature step value in Celsius
204+
205+
This function will return ``true`` if successful, ``false`` otherwise.
206+
207+
**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.
208+
209+
getStep
210+
^^^^^^^
211+
212+
Gets the current temperature step value.
213+
214+
.. code-block:: arduino
215+
216+
double getStep();
217+
218+
This function will return the temperature step in Celsius with 1/100th degree precision.
219+
220+
Temperature Level Control (Optional)
221+
*************************************
222+
223+
setSelectedTemperatureLevel
224+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
225+
226+
Sets the selected temperature level.
227+
228+
**Requires:** temperature_level feature mode (use ``begin(supportedLevels, levelCount, selectedLevel)``)
229+
230+
.. code-block:: arduino
231+
232+
bool setSelectedTemperatureLevel(uint8_t level);
233+
234+
* ``level`` - Temperature level (0-255)
235+
236+
This function will return ``true`` if successful, ``false`` otherwise.
237+
238+
**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.
239+
240+
getSelectedTemperatureLevel
241+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
242+
243+
Gets the current selected temperature level.
244+
245+
.. code-block:: arduino
246+
247+
uint8_t getSelectedTemperatureLevel();
248+
249+
This function will return the selected temperature level (0-255).
250+
251+
setSupportedTemperatureLevels
252+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
253+
254+
Sets the supported temperature levels array.
255+
256+
**Requires:** temperature_level feature mode (use ``begin(supportedLevels, levelCount, selectedLevel)``)
257+
258+
.. code-block:: arduino
259+
260+
bool setSupportedTemperatureLevels(uint8_t *levels, uint16_t count);
261+
262+
* ``levels`` - Pointer to array of temperature level values (array is copied internally)
263+
* ``count`` - Number of levels in the array (maximum: 16)
264+
265+
This function will return ``true`` if successful, ``false`` otherwise.
266+
267+
**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.
268+
269+
getSupportedTemperatureLevelsCount
270+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
271+
272+
Gets the count of supported temperature levels.
273+
274+
.. code-block:: arduino
275+
276+
uint16_t getSupportedTemperatureLevelsCount();
277+
278+
This function will return the number of supported temperature levels.
279+
280+
Example
281+
-------
282+
283+
Temperature Controlled Cabinet
284+
******************************
285+
286+
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.
287+
288+
.. literalinclude:: ../../../libraries/Matter/examples/MatterTemperatureControlledCabinet/MatterTemperatureControlledCabinet.ino
289+
:language: arduino
290+
291+
Temperature Controlled Cabinet (Level Mode)
292+
********************************************
293+
294+
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.
295+
296+
See ``MatterTemperatureControlledCabinetLevels`` example for the temperature level mode implementation.

‎docs/en/matter/matter.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,8 @@ The library provides specialized endpoint classes for different device types. Ea
133133

134134
**Control Endpoints:**
135135

136+
* ``MatterTemperatureControlledCabinet``: Temperature controlled cabinet (setpoint control with min/max limits)
137+
136138
* ``MatterFan``: Fan with speed and mode control
137139
* ``MatterThermostat``: Thermostat with temperature control and setpoints
138140
* ``MatterOnOffPlugin``: On/off plugin unit (power outlet/relay)

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /