ContextQMD
Back to Arduino Esp32

MatterThermostat

docs/en/matter/ep_thermostat.rst

3.3.86.2 KB
Original Source

################ MatterThermostat ################

About

The MatterThermostat class provides a thermostat endpoint for Matter networks with temperature control, setpoints, and multiple operating modes. This endpoint implements the Matter thermostat standard.

Features:

  • Multiple operating modes (OFF, HEAT, COOL, AUTO, etc.)
  • Heating and cooling setpoint control
  • Local temperature reporting
  • Automatic temperature regulation
  • Deadband control for AUTO mode
  • Callback support for mode, temperature, and setpoint changes
  • Integration with Apple HomeKit, Amazon Alexa, and Google Home
  • Matter standard compliance

Use Cases:

  • HVAC systems
  • Smart thermostats
  • Temperature control systems
  • Climate control automation
  • Energy management systems

API Reference

Constructor

MatterThermostat ^^^^^^^^^^^^^^^^

Creates a new Matter thermostat endpoint.

.. code-block:: arduino

MatterThermostat();

Initialization

begin ^^^^^

Initializes the Matter thermostat endpoint with control sequence and auto mode settings.

.. code-block:: arduino

bool begin(ControlSequenceOfOperation_t controlSequence = THERMOSTAT_SEQ_OP_COOLING, ThermostatAutoMode_t autoMode = THERMOSTAT_AUTO_MODE_DISABLED);
  • controlSequence - Control sequence of operation (default: THERMOSTAT_SEQ_OP_COOLING)
  • autoMode - Auto mode enabled/disabled (default: THERMOSTAT_AUTO_MODE_DISABLED)

This function will return true if successful, false otherwise.

end ^^^

Stops processing Matter thermostat events.

.. code-block:: arduino

void end();

Control Sequences

ControlSequenceOfOperation_t ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Control sequence enumeration:

  • THERMOSTAT_SEQ_OP_COOLING - Cooling only
  • THERMOSTAT_SEQ_OP_COOLING_REHEAT - Cooling with reheat
  • THERMOSTAT_SEQ_OP_HEATING - Heating only
  • THERMOSTAT_SEQ_OP_HEATING_REHEAT - Heating with reheat
  • THERMOSTAT_SEQ_OP_COOLING_HEATING - Cooling and heating
  • THERMOSTAT_SEQ_OP_COOLING_HEATING_REHEAT - Cooling and heating with reheat

Thermostat Modes

ThermostatMode_t ^^^^^^^^^^^^^^^^

Thermostat mode enumeration:

  • THERMOSTAT_MODE_OFF - Off
  • THERMOSTAT_MODE_AUTO - Auto mode
  • THERMOSTAT_MODE_COOL - Cooling mode
  • THERMOSTAT_MODE_HEAT - Heating mode
  • THERMOSTAT_MODE_EMERGENCY_HEAT - Emergency heat
  • THERMOSTAT_MODE_PRECOOLING - Precooling
  • THERMOSTAT_MODE_FAN_ONLY - Fan only
  • THERMOSTAT_MODE_DRY - Dry mode
  • THERMOSTAT_MODE_SLEEP - Sleep mode

Mode Control

setMode ^^^^^^^

Sets the thermostat mode.

.. code-block:: arduino

bool setMode(ThermostatMode_t mode);

getMode ^^^^^^^

Gets the current thermostat mode.

.. code-block:: arduino

ThermostatMode_t getMode();

getThermostatModeString ^^^^^^^^^^^^^^^^^^^^^^^

Gets a friendly string for the thermostat mode.

.. code-block:: arduino

static const char *getThermostatModeString(uint8_t mode);

Temperature Control

setLocalTemperature ^^^^^^^^^^^^^^^^^^^

Sets the local temperature reading.

.. code-block:: arduino

bool setLocalTemperature(double temperature);
  • temperature - Temperature in Celsius

getLocalTemperature ^^^^^^^^^^^^^^^^^^^

Gets the current local temperature.

.. code-block:: arduino

double getLocalTemperature();

Setpoint Control

setCoolingHeatingSetpoints ^^^^^^^^^^^^^^^^^^^^^^^^^^

Sets both cooling and heating setpoints.

.. code-block:: arduino

bool setCoolingHeatingSetpoints(double _setpointHeatingTemperature, double _setpointCoolingTemperature);
  • _setpointHeatingTemperature - Heating setpoint in Celsius (or 0xffff to keep current)
  • _setpointCoolingTemperature - Cooling setpoint in Celsius (or 0xffff to keep current)

Note: Heating setpoint must be lower than cooling setpoint. In AUTO mode, cooling setpoint must be at least 2.5°C higher than heating setpoint (deadband).

setHeatingSetpoint ^^^^^^^^^^^^^^^^^^

Sets the heating setpoint.

.. code-block:: arduino

bool setHeatingSetpoint(double _setpointHeatingTemperature);

getHeatingSetpoint ^^^^^^^^^^^^^^^^^^

Gets the heating setpoint.

.. code-block:: arduino

double getHeatingSetpoint();

setCoolingSetpoint ^^^^^^^^^^^^^^^^^^

Sets the cooling setpoint.

.. code-block:: arduino

bool setCoolingSetpoint(double _setpointCoolingTemperature);

getCoolingSetpoint ^^^^^^^^^^^^^^^^^^

Gets the cooling setpoint.

.. code-block:: arduino

double getCoolingSetpoint();

Setpoint Limits

getMinHeatSetpoint ^^^^^^^^^^^^^^^^^^

Gets the minimum heating setpoint limit.

.. code-block:: arduino

float getMinHeatSetpoint();

getMaxHeatSetpoint ^^^^^^^^^^^^^^^^^^

Gets the maximum heating setpoint limit.

.. code-block:: arduino

float getMaxHeatSetpoint();

getMinCoolSetpoint ^^^^^^^^^^^^^^^^^^

Gets the minimum cooling setpoint limit.

.. code-block:: arduino

float getMinCoolSetpoint();

getMaxCoolSetpoint ^^^^^^^^^^^^^^^^^^

Gets the maximum cooling setpoint limit.

.. code-block:: arduino

float getMaxCoolSetpoint();

getDeadBand ^^^^^^^^^^^

Gets the deadband value (minimum difference between heating and cooling setpoints in AUTO mode).

.. code-block:: arduino

float getDeadBand();

Event Handling

onChange ^^^^^^^^

Sets a callback for when any parameter changes.

.. code-block:: arduino

void onChange(EndPointCB onChangeCB);

onChangeMode ^^^^^^^^^^^^

Sets a callback for mode changes.

.. code-block:: arduino

void onChangeMode(EndPointModeCB onChangeCB);

onChangeLocalTemperature ^^^^^^^^^^^^^^^^^^^^^^^^^

Sets a callback for local temperature changes.

.. code-block:: arduino

void onChangeLocalTemperature(EndPointTemperatureCB onChangeCB);

onChangeCoolingSetpoint ^^^^^^^^^^^^^^^^^^^^^^^

Sets a callback for cooling setpoint changes.

.. code-block:: arduino

void onChangeCoolingSetpoint(EndPointCoolingSetpointCB onChangeCB);

onChangeHeatingSetpoint ^^^^^^^^^^^^^^^^^^^^^^^

Sets a callback for heating setpoint changes.

.. code-block:: arduino

void onChangeHeatingSetpoint(EndPointHeatingSetpointCB onChangeCB);

Example

Thermostat

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