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 Home Assistant, Apple Home, 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.

MatterThermostat();

Initialization

begin

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

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.

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.

bool setMode(ThermostatMode_t mode);

getMode

Gets the current thermostat mode.

ThermostatMode_t getMode();

getControlSequence

Gets the Control Sequence of Operation set at begin().

ControlSequenceOfOperation_t getControlSequence();

getThermostatModeString

Gets a friendly string for the thermostat SystemMode value, including EMERGENCY_HEAT, PRECOOLING, FAN_ONLY, DRY, and SLEEP. Returns UNKNOWN for the unused enum value 2 and for any out-of-range mode.

static const char *getThermostatModeString(uint8_t mode);

Temperature Control

setLocalTemperature

Sets the local temperature reading.

bool setLocalTemperature(double temperature);

temperature - Temperature in Celsius

getLocalTemperature

Gets the current local temperature.

double getLocalTemperature();

Setpoint Control

setCoolingHeatingSetpoints

Sets both cooling and heating setpoints.

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.

bool setHeatingSetpoint(double _setpointHeatingTemperature);

getHeatingSetpoint

Gets the heating setpoint.

double getHeatingSetpoint();

setCoolingSetpoint

Sets the cooling setpoint.

bool setCoolingSetpoint(double _setpointCoolingTemperature);

getCoolingSetpoint

Gets the cooling setpoint.

double getCoolingSetpoint();

Setpoint Limits

getMinHeatSetpoint

Gets the minimum heating setpoint limit.

float getMinHeatSetpoint();

getMaxHeatSetpoint

Gets the maximum heating setpoint limit.

float getMaxHeatSetpoint();

getMinCoolSetpoint

Gets the minimum cooling setpoint limit.

float getMinCoolSetpoint();

getMaxCoolSetpoint

Gets the maximum cooling setpoint limit.

float getMaxCoolSetpoint();

getDeadBand

Gets the AUTO MinSetpointDeadBand in Celsius (cluster stores tenths of a degree). Reads the attribute when Auto is enabled; otherwise returns the default 2.5 °C.

float getDeadBand();

Event Handling

onChange

Sets a callback for when any parameter changes.

void onChange(EndPointCB onChangeCB);

onChangeMode

Sets a callback for mode changes.

void onChangeMode(EndPointModeCB onChangeCB);

onChangeLocalTemperature

Sets a callback for local temperature changes.

void onChangeLocalTemperature(EndPointTemperatureCB onChangeCB);

onChangeCoolingSetpoint

Sets a callback for cooling setpoint changes.

void onChangeCoolingSetpoint(EndPointCoolingSetpointCB onChangeCB);

onChangeHeatingSetpoint

Sets a callback for heating setpoint changes.

void onChangeHeatingSetpoint(EndPointHeatingSetpointCB onChangeCB);

Example

Thermostat

// Copyright 2025 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

/*
   This example is an example code that will create a Matter Device which can be
   commissioned and controlled from a Matter Environment APP.
   Additionally the ESP32 will send debug messages indicating the Matter activity.
   Turning DEBUG Level ON may be useful to following Matter Accessory and Controller messages.
*/

// Matter Manager
#include <Arduino.h>
#include <Matter.h>
// List of Matter Endpoints for this Node
// Matter Thermostat Endpoint
MatterThermostat SimulatedThermostat;

// Wi-Fi credentials for this sketch. Fill these in when the board cannot
// commission over BLE (Arduino prebuild on ESP32 / ESP32-S2): the sketch
// joins the AP itself. When Matter commissions over BLE (CHIPoBLE), the
// hub sends SSID and password — leave the placeholders; they are unused.
#define WIFI_SSID     "your-ssid"
#define WIFI_PASSWORD "your-password"

// set your board USER BUTTON pin here - decommissioning button
const uint8_t buttonPin = BOOT_PIN;  // Set your pin here. Using BOOT Button.
MatterButton button;

// Simulate a system that will activate heating/cooling in addition to a temperature sensor - add your preferred code here
float getSimulatedTemperature(bool isHeating, bool isCooling) {
  // read sensor temperature and apply heating/cooling
  float simulatedTempHWSensor = SimulatedThermostat.getLocalTemperature();

  if (isHeating) {
    // it will increase to simulate a heating system
    simulatedTempHWSensor = simulatedTempHWSensor + 0.5;
  }
  if (isCooling) {
    // it will decrease to simulate a colling system
    simulatedTempHWSensor = simulatedTempHWSensor - 0.5;
  }
  // otherwise, it will keep the temperature stable
  return simulatedTempHWSensor;
}

void setup() {
  // Initialize the USER BUTTON (Boot button) that will be used to decommission the Matter Node
  button.begin(buttonPin);

  Serial.begin(115200);

// CONFIG_ENABLE_CHIPOBLE=n: sketch starts Wi-Fi here; with CHIPoBLE the hub delivers credentials.
#if !CONFIG_ENABLE_CHIPOBLE
  matterConnectWiFi(WIFI_SSID, WIFI_PASSWORD);
#endif

  // Simulated Thermostat in COOLING and HEATING mode with Auto Mode to keep the temperature between setpoints
  // Auto Mode can only be used when the control sequence of operation is Cooling & Heating
  SimulatedThermostat.begin(MatterThermostat::THERMOSTAT_SEQ_OP_COOLING_HEATING, MatterThermostat::THERMOSTAT_AUTO_MODE_ENABLED);

  // Matter beginning - Last step, after all EndPoints are initialized
  Matter.begin();
  matterWaitUntilReady();

  // start the thermostat in AUTO mode
  SimulatedThermostat.setMode(MatterThermostat::THERMOSTAT_MODE_AUTO);
  // Heating 20 C, cooling 23 C (cooling must stay at least deadband above heating in auto mode)
  SimulatedThermostat.setCoolingHeatingSetpoints(20.0, 23.00);
  // set the local temperature sensor in Celsius
  SimulatedThermostat.setLocalTemperature(12.50);

  Serial.println();
  Serial.printf(
    "Initial Setpoints are %.01fC to %.01fC with a minimum 2.5C difference\r\n", SimulatedThermostat.getHeatingSetpoint(),
    SimulatedThermostat.getCoolingSetpoint()
  );
  Serial.printf("Auto mode is ON. Initial Temperature of %.01fC \r\n", SimulatedThermostat.getLocalTemperature());
  Serial.println("Local Temperature Sensor will be simulated every 10 seconds and changed by a simulated heater and cooler to move in between setpoints.");
}

// This will simulate the thermostat control system (heating and cooling)
// User can set a local temperature using the Serial input (type a number and press Enter)
// New temperature can be an positive or negative temperature in Celsius, between -50C and 50C
// After commissioning, local temperature starts at 12.5 C (see setup()).
void readSerialForNewTemperature() {
  static String newTemperatureStr;

  while (Serial.available()) {
    char c = Serial.read();
    if (c == '\n' || c == '\r') {
      if (newTemperatureStr.length() > 0) {
        // convert the string to a float value
        float newTemperature = newTemperatureStr.toFloat();
        // check if the new temperature is valid
        if (newTemperature >= -50.0 && newTemperature <= 50.0) {
          // set the new temperature
          SimulatedThermostat.setLocalTemperature(newTemperature);
          Serial.printf("New Temperature is %.01fC\r\n", newTemperature);
        } else {
          Serial.println("Invalid Temperature value. Please type a number between -50 and 50");
        }
        newTemperatureStr = "";
      }
    } else {
      if (c == '+' || c == '-' || (c >= '0' && c <= '9') || c == '.') {
        newTemperatureStr += c;
      } else {
        Serial.println("Invalid character. Please type a number between -50 and 50");
        newTemperatureStr = "";
      }
    }
  }
}

// loop will simulate the thermostat control system
// User can set a local temperature using the Serial input (type a number and press Enter)
// User can change the thermostat mode using the Matter APP (smartphone)
// The loop will simulate a heating and cooling system and the associated local temperature change
void loop() {
  matterRestartIfNoFabric();

  static uint32_t timeCounter = 0;

  // Simulate the heating and cooling systems
  static bool isHeating = false;
  static bool isCooling = false;

  // check if a new temperature is typed in the Serial Monitor
  readSerialForNewTemperature();

  // simulate thermostat with heating/cooling system and the associated local temperature change, every 10s
  if (!(timeCounter++ % 20)) {  // delaying for 500ms x 20 = 10s
    float localTemperature = getSimulatedTemperature(isHeating, isCooling);
    // Print the current thermostat local temperature value
    Serial.printf("Current Local Temperature is %.01fC\r\n", localTemperature);
    SimulatedThermostat.setLocalTemperature(localTemperature);  // publish the new temperature value

    // Simulate the thermostat control system - User has 4 modes: OFF, HEAT, COOL, AUTO
    switch (SimulatedThermostat.getMode()) {
      case MatterThermostat::THERMOSTAT_MODE_OFF:
        // turn off the heating and cooling systems
        isHeating = false;
        isCooling = false;
        break;
      case MatterThermostat::THERMOSTAT_MODE_AUTO:
        // User APP has set the thermostat to AUTO mode -- keeping the tempeature between both setpoints
        // check if the heating system should be turned on or off
        if (localTemperature < SimulatedThermostat.getHeatingSetpoint() + SimulatedThermostat.getDeadBand()) {
          // turn on the heating system and turn off the cooling system
          isHeating = true;
          isCooling = false;
        }
        if (localTemperature > SimulatedThermostat.getCoolingSetpoint() - SimulatedThermostat.getDeadBand()) {
          // turn off the heating system and turn on the cooling system
          isHeating = false;
          isCooling = true;
        }
        break;
      case MatterThermostat::THERMOSTAT_MODE_HEAT:
        // Simulate the heating system - User has turned the heating system ON
        isHeating = true;
        isCooling = false;  // keep the cooling system off as it is in heating mode
        // when the heating system is in HEATING mode, it will be turned off as soon as the local temperature is above the setpoint
        if (localTemperature > SimulatedThermostat.getHeatingSetpoint()) {
          // turn off the heating system
          isHeating = false;
        }
        break;
      case MatterThermostat::THERMOSTAT_MODE_COOL:
        // Simulate the cooling system - User has turned the cooling system ON
        if (SimulatedThermostat.getMode() == MatterThermostat::THERMOSTAT_MODE_COOL) {
          isCooling = true;
          isHeating = false;  // keep the heating system off as it is in cooling mode
          // when the cooling system is in COOLING mode, it will be turned off as soon as the local temperature is bellow the setpoint
          if (localTemperature < SimulatedThermostat.getCoolingSetpoint()) {
            // turn off the cooling system
            isCooling = false;
          }
        }
        break;
      default: log_e("Invalid Thermostat Mode %d", SimulatedThermostat.getMode());
    }
    // Reporting Heating and Cooling status
    Serial.printf(
      "\tThermostat Mode: %s >>> Heater is %s -- Cooler is %s\r\n", MatterThermostat::getThermostatModeString(SimulatedThermostat.getMode()),
      isHeating ? "ON" : "OFF", isCooling ? "ON" : "OFF"
    );
  }
  matterButtonEvent_t ev;
  while ((ev = button.poll()) != MATTER_BUTTON_NONE) {
    if (ev == MATTER_BUTTON_LONG_HOLD) {
      Serial.println("Decommissioning Thermostat Matter Accessory. It shall be commissioned again.");
      Matter.decommission();
    }
  }

  delay(500);
}