-
Notifications
You must be signed in to change notification settings - Fork 7.7k
feat(matter): new Matter Endpoint for Thermostat #10755
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
me-no-dev
merged 10 commits into
espressif:master
from
SuGlider:matter_thermostat_endpoint
Jan 7, 2025
+872
−0
Merged
Changes from all commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
c484f14
feat(matter): add new matter endpoint for thermostat
SuGlider bcf884b
Merge branch 'master' into matter_thermostat_endpoint
SuGlider f1eca7d
fix(matter): not used variable from log_e() message
SuGlider 102dfc6
feat(matter): adds specifc type name for thermostat auto mode enabled
SuGlider 60d674b
Merge branch 'master' into matter_thermostat_endpoint
SuGlider f708865
fix(matter): suggested changes in pr review
SuGlider 1d4e150
feat(matter): added the whole list of thermostat operational modes
SuGlider 10b42ee
fix(matter): fixed type in thermostat operational modes
SuGlider 4cd8751
ci(pre-commit): Apply automatic fixes
pre-commit-ci-lite[bot] 6ec7207
fix(matter): typos caught by CI codespell
SuGlider File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
243 changes: 243 additions & 0 deletions
243
libraries/Matter/examples/MatterThermostat/MatterThermostat.ino
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,243 @@ | ||
// Copyright 2024 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 <Matter.h> | ||
#include <WiFi.h> | ||
|
||
// List of Matter Endpoints for this Node | ||
// Matter Thermostat Endpoint | ||
MatterThermostat SimulatedThermostat; | ||
|
||
// WiFi is manually set and started | ||
const char *ssid = "your-ssid"; // Change this to your WiFi SSID | ||
const char *password = "your-password"; // Change this to your WiFi password | ||
|
||
// set your board USER BUTTON pin here - decommissioning button | ||
const uint8_t buttonPin = BOOT_PIN; // Set your pin here. Using BOOT Button. | ||
|
||
// Button control - decommision the Matter Node | ||
uint32_t button_time_stamp = 0; // debouncing control | ||
bool button_state = false; // false = released | true = pressed | ||
const uint32_t decommissioningTimeout = 5000; // keep the button pressed for 5s, or longer, to decommission | ||
|
||
// 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 | ||
pinMode(buttonPin, INPUT_PULLUP); | ||
|
||
Serial.begin(115200); | ||
|
||
// Manually connect to WiFi | ||
WiFi.begin(ssid, password); | ||
// Wait for connection | ||
while (WiFi.status() != WL_CONNECTED) { | ||
delay(500); | ||
Serial.print("."); | ||
} | ||
Serial.println(); | ||
|
||
// 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(); | ||
|
||
// Check Matter Accessory Commissioning state, which may change during execution of loop() | ||
if (!Matter.isDeviceCommissioned()) { | ||
Serial.println(""); | ||
Serial.println("Matter Node is not commissioned yet."); | ||
Serial.println("Initiate the device discovery in your Matter environment."); | ||
Serial.println("Commission it to your Matter hub with the manual pairing code or QR code"); | ||
Serial.printf("Manual pairing code: %s\r\n", Matter.getManualPairingCode().c_str()); | ||
Serial.printf("QR code URL: %s\r\n", Matter.getOnboardingQRCodeUrl().c_str()); | ||
// waits for Matter Thermostat Commissioning. | ||
uint32_t timeCount = 0; | ||
while (!Matter.isDeviceCommissioned()) { | ||
delay(100); | ||
if ((timeCount++ % 50) == 0) { // 50*100ms = 5 sec | ||
Serial.println("Matter Node not commissioned yet. Waiting for commissioning."); | ||
} | ||
} | ||
Serial.println("Matter Node is commissioned and connected to Wi-Fi. Ready for use."); | ||
|
||
// after commissioning, set initial thermostat parameters | ||
// start the thermostat in AUTO mode | ||
SimulatedThermostat.setMode(MatterThermostat::THERMOSTAT_MODE_AUTO); | ||
// cooling setpoint must be lower than heating setpoint by at least 2.5C (deadband), in auto mode | ||
SimulatedThermostat.setCoolingHeatingSetpoints(20.0, 23.00); // the target cooler and heating setpoint | ||
// 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 | ||
// Initial local temperature is 10C as defined in getSimulatedTemperature() function | ||
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() { | ||
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" | ||
); | ||
} | ||
// Check if the button has been pressed | ||
if (digitalRead(buttonPin) == LOW && !button_state) { | ||
// deals with button debouncing | ||
button_time_stamp = millis(); // record the time while the button is pressed. | ||
button_state = true; // pressed. | ||
} | ||
|
||
if (digitalRead(buttonPin) == HIGH && button_state) { | ||
button_state = false; // released | ||
} | ||
|
||
// Onboard User Button is kept pressed for longer than 5 seconds in order to decommission matter node | ||
uint32_t time_diff = millis() - button_time_stamp; | ||
if (button_state && time_diff > decommissioningTimeout) { | ||
Serial.println("Decommissioning the Light Matter Accessory. It shall be commissioned again."); | ||
Matter.decommission(); | ||
button_time_stamp = millis(); // avoid running decommissining again, reboot takes a second or so | ||
} | ||
|
||
delay(500); | ||
} |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
{ | ||
"fqbn_append": "PartitionScheme=huge_app", | ||
"requires": [ | ||
"CONFIG_SOC_WIFI_SUPPORTED=y", | ||
"CONFIG_ESP_MATTER_ENABLE_DATA_MODEL=y" | ||
] | ||
} |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
370 changes: 370 additions & 0 deletions
370
libraries/Matter/src/MatterEndpoints/MatterThermostat.cpp
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,370 @@ | ||
// Copyright 2024 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. | ||
|
||
#include <sdkconfig.h> | ||
#ifdef CONFIG_ESP_MATTER_ENABLE_DATA_MODEL | ||
|
||
#include <Matter.h> | ||
#include <MatterEndpoints/MatterThermostat.h> | ||
|
||
using namespace esp_matter; | ||
using namespace esp_matter::endpoint; | ||
using namespace chip::app::Clusters; | ||
|
||
// string helper for the THERMOSTAT MODE | ||
const char *MatterThermostat::thermostatModeString[5] = {"OFF", "AUTO", "UNKNOWN", "COOL", "HEAT"}; | ||
|
||
// endpoint for color light device | ||
namespace esp_matter { | ||
using namespace cluster; | ||
namespace endpoint { | ||
namespace multi_mode_thermostat { | ||
typedef struct config { | ||
cluster::descriptor::config_t descriptor; | ||
cluster::identify::config_t identify; | ||
cluster::scenes_management::config_t scenes_management; | ||
cluster::groups::config_t groups; | ||
cluster::thermostat::config_t thermostat; | ||
} config_t; | ||
|
||
uint32_t get_device_type_id() { | ||
return ESP_MATTER_THERMOSTAT_DEVICE_TYPE_ID; | ||
} | ||
|
||
uint8_t get_device_type_version() { | ||
return ESP_MATTER_THERMOSTAT_DEVICE_TYPE_VERSION; | ||
} | ||
|
||
esp_err_t add(endpoint_t *endpoint, config_t *config) { | ||
if (!endpoint) { | ||
log_e("Endpoint cannot be NULL"); | ||
return ESP_ERR_INVALID_ARG; | ||
} | ||
esp_err_t err = add_device_type(endpoint, get_device_type_id(), get_device_type_version()); | ||
if (err != ESP_OK) { | ||
log_e("Failed to add device type id:%" PRIu32 ",err: %d", get_device_type_id(), err); | ||
return err; | ||
} | ||
|
||
descriptor::create(endpoint, &(config->descriptor), CLUSTER_FLAG_SERVER); | ||
identify::create(endpoint, &(config->identify), CLUSTER_FLAG_SERVER); | ||
groups::create(endpoint, &(config->groups), CLUSTER_FLAG_SERVER); | ||
uint32_t thermostatFeatures = 0; | ||
switch (config->thermostat.control_sequence_of_operation) { | ||
case MatterThermostat::THERMOSTAT_SEQ_OP_COOLING: | ||
case MatterThermostat::THERMOSTAT_SEQ_OP_COOLING_REHEAT: thermostatFeatures = cluster::thermostat::feature::cooling::get_id(); break; | ||
case MatterThermostat::THERMOSTAT_SEQ_OP_HEATING: | ||
case MatterThermostat::THERMOSTAT_SEQ_OP_HEATING_REHEAT: thermostatFeatures = cluster::thermostat::feature::heating::get_id(); break; | ||
case MatterThermostat::THERMOSTAT_SEQ_OP_COOLING_HEATING: | ||
case MatterThermostat::THERMOSTAT_SEQ_OP_COOLING_HEATING_REHEAT: | ||
thermostatFeatures = cluster::thermostat::feature::cooling::get_id() | cluster::thermostat::feature::heating::get_id(); | ||
break; | ||
} | ||
cluster::thermostat::create(endpoint, &(config->thermostat), CLUSTER_FLAG_SERVER, thermostatFeatures); | ||
return ESP_OK; | ||
} | ||
|
||
endpoint_t *create(node_t *node, config_t *config, uint8_t flags, void *priv_data) { | ||
endpoint_t *endpoint = endpoint::create(node, flags, priv_data); | ||
add(endpoint, config); | ||
return endpoint; | ||
} | ||
} // namespace multi_mode_thermostat | ||
} // namespace endpoint | ||
} // namespace esp_matter | ||
|
||
bool MatterThermostat::attributeChangeCB(uint16_t endpoint_id, uint32_t cluster_id, uint32_t attribute_id, esp_matter_attr_val_t *val) { | ||
bool ret = true; | ||
if (!started) { | ||
log_e("Matter Thermostat device has not begun."); | ||
return false; | ||
} | ||
log_d("Thermostat Attr update callback: endpoint: %u, cluster: %u, attribute: %u, val: %u", endpoint_id, cluster_id, attribute_id, val->val.u32); | ||
|
||
if (cluster_id == Thermostat::Id) { | ||
switch (attribute_id) { | ||
case Thermostat::Attributes::SystemMode::Id: | ||
if (_onChangeModeCB != NULL) { | ||
ret &= _onChangeModeCB((ThermostatMode_t)val->val.u8); | ||
} | ||
if (_onChangeCB != NULL) { | ||
ret &= _onChangeCB(); | ||
} | ||
if (ret == true) { | ||
currentMode = (ThermostatMode_t)val->val.u8; | ||
log_v("Thermostat Mode updated to %d", val->val.u8); | ||
} | ||
break; | ||
case Thermostat::Attributes::LocalTemperature::Id: | ||
if (_onChangeTemperatureCB != NULL) { | ||
ret &= _onChangeTemperatureCB((float)val->val.i16 / 100.00); | ||
} | ||
if (_onChangeCB != NULL) { | ||
ret &= _onChangeCB(); | ||
} | ||
if (ret == true) { | ||
localTemperature = val->val.i16; | ||
log_v("Local Temperature updated to %.01fC", (float)val->val.i16 / 100.00); | ||
} | ||
break; | ||
case Thermostat::Attributes::OccupiedCoolingSetpoint::Id: | ||
if (_onChangeCoolingSetpointCB != NULL) { | ||
ret &= _onChangeCoolingSetpointCB((float)val->val.i16 / 100.00); | ||
} | ||
if (_onChangeCB != NULL) { | ||
ret &= _onChangeCB(); | ||
} | ||
if (ret == true) { | ||
coolingSetpointTemperature = val->val.i16; | ||
log_v("Cooling Setpoint updated to %.01fC", (float)val->val.i16 / 100.00); | ||
} | ||
break; | ||
case Thermostat::Attributes::OccupiedHeatingSetpoint::Id: | ||
if (_onChangeHeatingSetpointCB != NULL) { | ||
ret &= _onChangeHeatingSetpointCB((float)val->val.i16 / 100.00); | ||
} | ||
if (_onChangeCB != NULL) { | ||
ret &= _onChangeCB(); | ||
} | ||
if (ret == true) { | ||
heatingSetpointTemperature = val->val.i16; | ||
log_v("Heating Setpoint updated to %.01fC", (float)val->val.i16 / 100.00); | ||
} | ||
break; | ||
default: log_w("Unhandled Thermostat Attribute ID: %u", attribute_id); break; | ||
} | ||
} | ||
return ret; | ||
} | ||
|
||
MatterThermostat::MatterThermostat() {} | ||
|
||
MatterThermostat::~MatterThermostat() { | ||
end(); | ||
} | ||
|
||
bool MatterThermostat::begin(ControlSequenceOfOperation_t _controlSequence, ThermostatAutoMode_t _autoMode) { | ||
ArduinoMatter::_init(); | ||
|
||
if (getEndPointId() != 0) { | ||
log_e("Matter Thermostat with Endpoint Id %d device has already been created.", getEndPointId()); | ||
return false; | ||
} | ||
|
||
// check if auto mode is allowed with the control sequence of operation - only allowed for Cooling & Heating | ||
if (_autoMode == THERMOSTAT_AUTO_MODE_ENABLED && _controlSequence != THERMOSTAT_SEQ_OP_COOLING_HEATING | ||
&& _controlSequence != THERMOSTAT_SEQ_OP_COOLING_HEATING_REHEAT) { | ||
log_e("Thermostat in Auto Mode requires a Cooling & Heating Control Sequence of Operation."); | ||
return false; | ||
} | ||
|
||
const int16_t _localTemperature = 2000; // initial value to be automatically changed by the Matter Thermostat | ||
const int16_t _coolingSetpointTemperature = 2400; // 24C cooling setpoint | ||
const int16_t _heatingSetpointTemperature = 1600; // 16C heating setpoint | ||
const ThermostatMode_t _currentMode = THERMOSTAT_MODE_OFF; | ||
|
||
multi_mode_thermostat::config_t thermostat_config; | ||
thermostat_config.thermostat.control_sequence_of_operation = (uint8_t)_controlSequence; | ||
thermostat_config.thermostat.cooling.occupied_cooling_setpoint = _coolingSetpointTemperature; | ||
thermostat_config.thermostat.heating.occupied_heating_setpoint = _heatingSetpointTemperature; | ||
thermostat_config.thermostat.system_mode = (uint8_t)_currentMode; | ||
thermostat_config.thermostat.local_temperature = _localTemperature; | ||
|
||
// endpoint handles can be used to add/modify clusters | ||
endpoint_t *endpoint = multi_mode_thermostat::create(node::get(), &thermostat_config, ENDPOINT_FLAG_NONE, (void *)this); | ||
if (endpoint == nullptr) { | ||
log_e("Failed to create Thermostat endpoint"); | ||
return false; | ||
} | ||
if (_autoMode == THERMOSTAT_AUTO_MODE_ENABLED) { | ||
cluster_t *cluster = cluster::get(endpoint, Thermostat::Id); | ||
thermostat_config.thermostat.auto_mode.min_setpoint_dead_band = kDefaultDeadBand; // fixed by default to 2.5C | ||
cluster::thermostat::feature::auto_mode::add(cluster, &thermostat_config.thermostat.auto_mode); | ||
} | ||
|
||
controlSequence = _controlSequence; | ||
autoMode = _autoMode; | ||
coolingSetpointTemperature = _coolingSetpointTemperature; | ||
heatingSetpointTemperature = _heatingSetpointTemperature; | ||
localTemperature = _localTemperature; | ||
currentMode = _currentMode; | ||
|
||
setEndPointId(endpoint::get_id(endpoint)); | ||
log_i("Thermostat created with endpoint_id %d", getEndPointId()); | ||
started = true; | ||
return true; | ||
} | ||
|
||
void MatterThermostat::end() { | ||
started = false; | ||
} | ||
|
||
bool MatterThermostat::setMode(ThermostatMode_t _mode) { | ||
if (!started) { | ||
log_e("Matter Thermostat device has not begun."); | ||
return false; | ||
} | ||
|
||
if (autoMode == THERMOSTAT_AUTO_MODE_DISABLED && _mode == THERMOSTAT_MODE_AUTO) { | ||
log_e("Thermostat can't set Auto Mode."); | ||
return false; | ||
} | ||
// check if the requested mode is valid based on the control sequence of operation | ||
// no restrictions for OFF mode | ||
if (_mode != THERMOSTAT_MODE_OFF) { | ||
// check HEAT, COOL and AUTO modes | ||
switch (controlSequence) { | ||
case THERMOSTAT_SEQ_OP_COOLING: | ||
case THERMOSTAT_SEQ_OP_COOLING_REHEAT: | ||
if (_mode == THERMOSTAT_MODE_HEAT || _mode == THERMOSTAT_MODE_AUTO) { | ||
break; | ||
} | ||
log_e("Invalid Thermostat Mode for Cooling Control Sequence of Operation."); | ||
return false; | ||
case THERMOSTAT_SEQ_OP_HEATING: | ||
case THERMOSTAT_SEQ_OP_HEATING_REHEAT: | ||
if (_mode == THERMOSTAT_MODE_COOL || _mode == THERMOSTAT_MODE_AUTO) { | ||
break; | ||
} | ||
log_e("Invalid Thermostat Mode for Heating Control Sequence of Operation."); | ||
return false; | ||
default: | ||
// compiler warning about not handling all enum values | ||
break; | ||
} | ||
} | ||
|
||
// avoid processing if there was no change | ||
if (currentMode == _mode) { | ||
return true; | ||
} | ||
|
||
esp_matter_attr_val_t modeVal = esp_matter_invalid(NULL); | ||
if (!getAttributeVal(Thermostat::Id, Thermostat::Attributes::SystemMode::Id, &modeVal)) { | ||
log_e("Failed to get Thermostat Mode Attribute."); | ||
return false; | ||
} | ||
if (modeVal.val.u8 != _mode) { | ||
modeVal.val.u8 = _mode; | ||
bool ret; | ||
ret = updateAttributeVal(Thermostat::Id, Thermostat::Attributes::SystemMode::Id, &modeVal); | ||
if (!ret) { | ||
log_e("Failed to update Thermostat Mode Attribute."); | ||
return false; | ||
} | ||
currentMode = _mode; | ||
} | ||
log_v("Thermostat Mode set to %d", _mode); | ||
|
||
return true; | ||
} | ||
|
||
bool MatterThermostat::setRawTemperature(int16_t _rawTemperature, uint32_t attribute_id, int16_t *internalValue) { | ||
if (!started) { | ||
log_e("Matter Thermostat device has not begun."); | ||
return false; | ||
} | ||
|
||
// avoid processing if there was no change | ||
if (*internalValue == _rawTemperature) { | ||
return true; | ||
} | ||
|
||
esp_matter_attr_val_t temperatureVal = esp_matter_invalid(NULL); | ||
if (!getAttributeVal(Thermostat::Id, attribute_id, &temperatureVal)) { | ||
log_e("Failed to get Thermostat Temperature or Setpoint Attribute."); | ||
return false; | ||
} | ||
if (temperatureVal.val.i16 != _rawTemperature) { | ||
temperatureVal.val.i16 = _rawTemperature; | ||
bool ret; | ||
ret = updateAttributeVal(Thermostat::Id, attribute_id, &temperatureVal); | ||
if (!ret) { | ||
log_e("Failed to update Thermostat Temperature or Setpoint Attribute."); | ||
return false; | ||
} | ||
*internalValue = _rawTemperature; | ||
} | ||
log_v("Temperature set to %.01fC", (float)_rawTemperature / 100.00); | ||
|
||
return true; | ||
} | ||
|
||
bool MatterThermostat::setCoolingHeatingSetpoints(double _setpointHeatingTemperature, double _setpointCollingTemperature) { | ||
// at least one of the setpoints must be valid | ||
bool settingCooling = _setpointCollingTemperature != (float)0xffff; | ||
bool settingHeating = _setpointHeatingTemperature != (float)0xffff; | ||
if (!settingCooling && !settingHeating) { | ||
log_e("Invalid Setpoints values. Set correctly at least one of them in Celsius."); | ||
return false; | ||
} | ||
int16_t _rawHeatValue = static_cast<int16_t>(_setpointHeatingTemperature * 100.0f); | ||
int16_t _rawCoolValue = static_cast<int16_t>(_setpointCollingTemperature * 100.0f); | ||
|
||
// check limits for the setpoints | ||
if (settingHeating && (_rawHeatValue < kDefaultMinHeatSetpointLimit || _rawHeatValue > kDefaultMaxHeatSetpointLimit)) { | ||
log_e( | ||
"Invalid Heating Setpoint value: %.01fC - valid range %d..%d", _setpointHeatingTemperature, kDefaultMinHeatSetpointLimit / 100, | ||
kDefaultMaxHeatSetpointLimit / 100 | ||
); | ||
return false; | ||
} | ||
if (settingCooling && (_rawCoolValue < kDefaultMinCoolSetpointLimit || _rawCoolValue > kDefaultMaxCoolSetpointLimit)) { | ||
log_e( | ||
"Invalid Cooling Setpoint value: %.01fC - valid range %d..%d", _setpointCollingTemperature, kDefaultMinCoolSetpointLimit / 100, | ||
kDefaultMaxCoolSetpointLimit / 100 | ||
); | ||
return false; | ||
} | ||
|
||
// AUTO mode requires both setpoints to be valid to each other and respect the deadband | ||
if (currentMode == THERMOSTAT_MODE_AUTO) { | ||
#if ARDUHAL_LOG_LEVEL >= ARDUHAL_LOG_LEVEL_ERROR | ||
float deadband = getDeadBand(); | ||
#endif | ||
// only setting Cooling Setpoint | ||
if (settingCooling && !settingHeating && _rawCoolValue < (heatingSetpointTemperature + (kDefaultDeadBand * 10))) { | ||
log_e( | ||
"AutoMode :: Invalid Cooling Setpoint value: %.01fC - must be higher or equal than %.01fC", _setpointCollingTemperature, getHeatingSetpoint() + deadband | ||
); | ||
return false; | ||
} | ||
// only setting Heating Setpoint | ||
if (!settingCooling && settingHeating && _rawHeatValue > (coolingSetpointTemperature - (kDefaultDeadBand * 10))) { | ||
log_e( | ||
"AutoMode :: Invalid Heating Setpoint value: %.01fC - must be lower or equal than %.01fC", _setpointHeatingTemperature, getCoolingSetpoint() - deadband | ||
); | ||
return false; | ||
} | ||
// setting both setpoints | ||
if (settingCooling && settingHeating && (_rawCoolValue <= _rawHeatValue || _rawCoolValue - _rawHeatValue < kDefaultDeadBand * 10.0)) { | ||
log_e( | ||
"AutoMode :: Error - Heating Setpoint %.01fC must be lower than Cooling Setpoint %.01fC with a minimum difference of %0.1fC", | ||
_setpointHeatingTemperature, _setpointCollingTemperature, deadband | ||
); | ||
return false; | ||
} | ||
} | ||
|
||
bool ret = true; | ||
if (settingCooling) { | ||
ret &= setRawTemperature(_rawCoolValue, Thermostat::Attributes::OccupiedCoolingSetpoint::Id, &coolingSetpointTemperature); | ||
} | ||
if (settingHeating) { | ||
ret &= setRawTemperature(_rawHeatValue, Thermostat::Attributes::OccupiedHeatingSetpoint::Id, &heatingSetpointTemperature); | ||
} | ||
return ret; | ||
} | ||
|
||
#endif /* CONFIG_ESP_MATTER_ENABLE_DATA_MODEL */ |
207 changes: 207 additions & 0 deletions
207
libraries/Matter/src/MatterEndpoints/MatterThermostat.h
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,207 @@ | ||
// Copyright 2024 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. | ||
|
||
#pragma once | ||
#include <sdkconfig.h> | ||
#ifdef CONFIG_ESP_MATTER_ENABLE_DATA_MODEL | ||
|
||
#include <Matter.h> | ||
#include <MatterEndPoint.h> | ||
#include <app-common/zap-generated/cluster-enums.h> | ||
|
||
using namespace chip::app::Clusters; | ||
|
||
class MatterThermostat : public MatterEndPoint { | ||
public: | ||
// clang-format off | ||
enum ControlSequenceOfOperation_t { | ||
THERMOSTAT_SEQ_OP_COOLING = (uint8_t) Thermostat::ControlSequenceOfOperationEnum::kCoolingOnly, | ||
THERMOSTAT_SEQ_OP_COOLING_REHEAT = (uint8_t) Thermostat::ControlSequenceOfOperationEnum::kCoolingWithReheat, | ||
THERMOSTAT_SEQ_OP_HEATING = (uint8_t) Thermostat::ControlSequenceOfOperationEnum::kHeatingOnly, | ||
THERMOSTAT_SEQ_OP_HEATING_REHEAT = (uint8_t) Thermostat::ControlSequenceOfOperationEnum::kHeatingWithReheat, | ||
THERMOSTAT_SEQ_OP_COOLING_HEATING = (uint8_t) Thermostat::ControlSequenceOfOperationEnum::kCoolingAndHeating, | ||
THERMOSTAT_SEQ_OP_COOLING_HEATING_REHEAT = (uint8_t) Thermostat::ControlSequenceOfOperationEnum::kCoolingAndHeatingWithReheat, | ||
}; | ||
|
||
enum ThermostatMode_t { | ||
THERMOSTAT_MODE_OFF = (uint8_t) Thermostat::SystemModeEnum::kOff, | ||
THERMOSTAT_MODE_AUTO = (uint8_t) Thermostat::SystemModeEnum::kAuto, | ||
THERMOSTAT_MODE_COOL = (uint8_t) Thermostat::SystemModeEnum::kCool, | ||
THERMOSTAT_MODE_HEAT = (uint8_t) Thermostat::SystemModeEnum::kHeat, | ||
THERMOSTAT_MODE_EMERGENCY_HEAT = (uint8_t) Thermostat::SystemModeEnum::kEmergencyHeat, | ||
THERMOSTAT_MODE_PRECOOLING = (uint8_t) Thermostat::SystemModeEnum::kPrecooling, | ||
THERMOSTAT_MODE_FAN_ONLY = (uint8_t) Thermostat::SystemModeEnum::kFanOnly, | ||
THERMOSTAT_MODE_DRY = (uint8_t) Thermostat::SystemModeEnum::kDry, | ||
THERMOSTAT_MODE_SLEEP = (uint8_t) Thermostat::SystemModeEnum::kSleep | ||
}; | ||
|
||
enum ThermostatAutoMode_t { | ||
THERMOSTAT_AUTO_MODE_DISABLED = (uint8_t) Thermostat::SystemModeEnum::kOff, | ||
THERMOSTAT_AUTO_MODE_ENABLED = (uint8_t) Thermostat::SystemModeEnum::kAuto, | ||
}; | ||
// clang-format on | ||
|
||
MatterThermostat(); | ||
~MatterThermostat(); | ||
// begin Matter Thermostat endpoint with initial Operation Mode | ||
bool begin(ControlSequenceOfOperation_t controlSequence = THERMOSTAT_SEQ_OP_COOLING, ThermostatAutoMode_t autoMode = THERMOSTAT_AUTO_MODE_DISABLED); | ||
// this will stop processing Thermostat Matter events | ||
void end(); | ||
|
||
// set the Thermostat Mode | ||
bool setMode(ThermostatMode_t mode); | ||
// get the Thermostat Mode | ||
ThermostatMode_t getMode() { | ||
return currentMode; | ||
} | ||
// returns a friendly string for the Fan Mode | ||
static const char *getThermostatModeString(uint8_t mode) { | ||
return thermostatModeString[mode]; | ||
} | ||
|
||
// get the Thermostat Control Sequence of Operation | ||
ControlSequenceOfOperation_t getControlSequence() { | ||
return controlSequence; | ||
} | ||
|
||
// get the minimum heating setpoint in 1/100th of a Celsio degree | ||
float getMinHeatSetpoint() { | ||
return (float)kDefaultMinHeatSetpointLimit / 100.00; | ||
} | ||
// get the maximum heating setpoint in 1/100th of a Celsio degree | ||
float getMaxHeatSetpoint() { | ||
return (float)kDefaultMaxHeatSetpointLimit / 100.00; | ||
} | ||
// get the minimum cooling setpoint in 1/100th of a Celsio degree | ||
float getMinCoolSetpoint() { | ||
return (float)kDefaultMinCoolSetpointLimit / 100.00; | ||
} | ||
// get the maximum cooling setpoint in 1/100th of a Celsio degree | ||
float getMaxCoolSetpoint() { | ||
return (float)kDefaultMaxCoolSetpointLimit / 100.00; | ||
} | ||
// get the deadband in 1/10th of a Celsio degree | ||
float getDeadBand() { | ||
return (float)kDefaultDeadBand / 10.00; | ||
} | ||
|
||
// generic function for setting the cooling and heating setpoints - checks if the setpoints are valid | ||
// it can be used to set both setpoints at the same time or only one of them, by setting the other to (float)0xffff | ||
// Heating Setpoint must be lower than Cooling Setpoint | ||
// When using AUTO mode the Cooling Setpoint must be higher than Heating Setpoint by at least the 2.5C (deadband) | ||
// Thermostat Matter Server will enforce those rules and the Max/Min setpoints limits as in the Matter Specification | ||
bool setCoolingHeatingSetpoints(double _setpointHeatingTemperature, double _setpointCollingTemperature); | ||
|
||
// set the heating setpoint in 1/100th of a Celsio degree | ||
bool setHeatingSetpoint(double _setpointHeatingTemperature) { | ||
return setCoolingHeatingSetpoints((double)0xffff, _setpointHeatingTemperature); | ||
} | ||
// get the heating setpoint in 1/100th of a Celsio degree | ||
double getHeatingSetpoint() { | ||
return heatingSetpointTemperature / 100.0; | ||
} | ||
// set the cooling setpoint in 1/100th of a Celsio degree | ||
bool setCoolingSetpoint(double _setpointCollingTemperature) { | ||
return setCoolingHeatingSetpoints(_setpointCollingTemperature, (double)0xffff); | ||
} | ||
// get the cooling setpoint in 1/100th of a Celsio degree | ||
double getCoolingSetpoint() { | ||
return coolingSetpointTemperature / 100.0; | ||
} | ||
|
||
// set the local Thermostat temperature in Celsio degrees | ||
bool setLocalTemperature(double temperature) { | ||
// stores up to 1/100th of a Celsio degree precision | ||
int16_t rawValue = static_cast<int16_t>(temperature * 100.0f); | ||
return setRawTemperature(rawValue, Thermostat::Attributes::LocalTemperature::Id, &localTemperature); | ||
} | ||
// returns the local Thermostat float temperature with 1/100th of a Celsio degree precision | ||
double getLocalTemperature() { | ||
return (double)localTemperature / 100.0; | ||
} | ||
|
||
// User Callback for whenever the Thermostat Mode is changed by the Matter Controller | ||
using EndPointModeCB = std::function<bool(ThermostatMode_t)>; | ||
void onChangeMode(EndPointModeCB onChangeCB) { | ||
_onChangeModeCB = onChangeCB; | ||
} | ||
|
||
// User Callback for whenever the Local Temperature is changed by the Matter Controller | ||
using EndPointTemperatureCB = std::function<bool(float)>; | ||
void onChangeLocalTemperature(EndPointTemperatureCB onChangeCB) { | ||
_onChangeTemperatureCB = onChangeCB; | ||
} | ||
|
||
// User Callback for whenever the Cooling or Heating Setpoint is changed by the Matter Controller | ||
using EndPointCoolingSetpointCB = std::function<bool(double)>; | ||
void onChangeCoolingSetpoint(EndPointCoolingSetpointCB onChangeCB) { | ||
_onChangeCoolingSetpointCB = onChangeCB; | ||
} | ||
|
||
// User Callback for whenever the Cooling or Heating Setpoint is changed by the Matter Controller | ||
using EndPointHeatingSetpointCB = std::function<bool(double)>; | ||
void onChangeHeatingSetpoint(EndPointHeatingSetpointCB onChangeCB) { | ||
_onChangeHeatingSetpointCB = onChangeCB; | ||
} | ||
|
||
// User Callback for whenever any parameter is changed by the Matter Controller | ||
// Main parameters are Thermostat Mode, Local Temperature, Cooling Setpoint and Heating Setpoint | ||
// Those can be obtained using getMode(), getTemperature(), getCoolingSetpoint() and getHeatingSetpoint() | ||
using EndPointCB = std::function<bool(void)>; | ||
void onChange(EndPointCB onChangeCB) { | ||
_onChangeCB = onChangeCB; | ||
} | ||
|
||
// this function is called by Matter internal event processor. It could be overwritten by the application, if necessary. | ||
bool attributeChangeCB(uint16_t endpoint_id, uint32_t cluster_id, uint32_t attribute_id, esp_matter_attr_val_t *val); | ||
|
||
protected: | ||
bool started = false; | ||
// implementation keeps temperature in 1/100th of a Celsio degree | ||
int16_t coolingSetpointTemperature = 2400; // 24C cooling setpoint | ||
int16_t localTemperature = 2000; // 20C local temperature | ||
int16_t heatingSetpointTemperature = 1600; // 16C heating setpoint | ||
|
||
ThermostatMode_t currentMode = THERMOSTAT_MODE_OFF; | ||
ControlSequenceOfOperation_t controlSequence = THERMOSTAT_SEQ_OP_COOLING; | ||
ThermostatAutoMode_t autoMode = THERMOSTAT_AUTO_MODE_DISABLED; | ||
|
||
EndPointModeCB _onChangeModeCB = NULL; | ||
EndPointTemperatureCB _onChangeTemperatureCB = NULL; | ||
EndPointCoolingSetpointCB _onChangeCoolingSetpointCB = NULL; | ||
EndPointHeatingSetpointCB _onChangeHeatingSetpointCB = NULL; | ||
EndPointCB _onChangeCB = NULL; | ||
|
||
// internal function to set the raw temperature value (Matter Cluster) | ||
bool setRawTemperature(int16_t _rawTemperature, uint32_t attribute_id, int16_t *internalValue); | ||
|
||
// clang-format off | ||
// Default Thermostat values - can't be changed - defined in the Thermostat Cluster Server code | ||
static const int16_t kDefaultAbsMinHeatSetpointLimit = 700; // 7C (44.5 F) | ||
static const int16_t kDefaultMinHeatSetpointLimit = 700; // 7C (44.5 F) | ||
static const int16_t kDefaultAbsMaxHeatSetpointLimit = 3000; // 30C (86 F) | ||
static const int16_t kDefaultMaxHeatSetpointLimit = 3000; // 30C (86 F) | ||
|
||
static const int16_t kDefaultAbsMinCoolSetpointLimit = 1600; // 16C (61 F) | ||
static const int16_t kDefaultMinCoolSetpointLimit = 1600; // 16C (61 F) | ||
static const int16_t kDefaultAbsMaxCoolSetpointLimit = 3200; // 32C (90 F) | ||
static const int16_t kDefaultMaxCoolSetpointLimit = 3200; // 32C (90 F) | ||
|
||
static const int8_t kDefaultDeadBand = 25; // 2.5C when in AUTO mode | ||
// clang-format on | ||
|
||
// string helper for the THERMOSTAT MODE | ||
static const char *thermostatModeString[5]; | ||
}; | ||
#endif /* CONFIG_ESP_MATTER_ENABLE_DATA_MODEL */ |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.