feat(matter): New Matter Fan endpoint

CMakeLists.txt

@@ -173,6 +173,7 @@ set(ARDUINO_LIBRARY_Matter_SRCS
   libraries/Matter/src/MatterEndpoints/MatterDimmableLight.cpp
   libraries/Matter/src/MatterEndpoints/MatterColorTemperatureLight.cpp
   libraries/Matter/src/MatterEndpoints/MatterColorLight.cpp
+  libraries/Matter/src/MatterEndpoints/MatterFan.cpp
   libraries/Matter/src/MatterEndpoints/MatterEnhancedColorLight.cpp
   libraries/Matter/src/Matter.cpp)
 

libraries/Matter/examples/MatterFan/MatterFan.ino

@@ -0,0 +1,174 @@
+// 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.
+
+// Matter Manager
+#include <Matter.h>
+#include <WiFi.h>
+
+// List of Matter Endpoints for this Node
+// Fan Endpoint - On/Off control + Speed Percent Control + Fan Modes
+MatterFan Fan;
+
+// set your board USER BUTTON pin here - used for toggling on/off
+const uint8_t buttonPin = 0;  // Set your pin here. Using BOOT Button. C6/C3 use GPIO9.
+
+// set your board Analog Pin here - used for changing the Fan speed
+const uint8_t analogPin = A0; // Analog Pin depends on each board
+
+// 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
+
+void setup() {
+  // Initialize the USER BUTTON (Boot button) GPIO that will toggle the Fan (on/off)
+  pinMode(buttonPin, INPUT_PULLUP);
+  // Initialize the Analog Pin A0 used to read input voltage and to set the Fan speed accordingly
+  pinMode(analogPin, INPUT);
+  analogReadResolution(10); // 10 bits resolution reading 0..1023
+
+  Serial.begin(115200);
+  while (!Serial) {
+    delay(100);
+  }
+
+  // We start by connecting to a WiFi network
+  Serial.print("Connecting to ");
+  Serial.println(ssid);
+  // enable IPv6
+  WiFi.enableIPv6(true);
+  // Manually connect to WiFi
+  WiFi.begin(ssid, password);
+  // Wait for connection
+  while (WiFi.status() != WL_CONNECTED) {
+    delay(500);
+    Serial.print(".");
+  }
+  Serial.println("\r\nWiFi connected");
+  Serial.println("IP address: ");
+  Serial.println(WiFi.localIP());
+  delay(500);
+
+  // On Boot or Reset, Fan is set at 0% speed, OFF, changing between OFF, ON, SMART and HIGH
+  Fan.begin(0, MatterFan::FAN_MODE_OFF, MatterFan::FAN_MODE_SEQ_OFF_HIGH);
+
+  // callback functions would control Fan motor
+  // the Matter Controller will send new data whenver the User APP or Automation request 
+
+  // single feature callbacks take place before the generic (all features) callback
+  // This callback will be executed whenever the speed percent matter attribute is updated
+  Fan.onChangeSpeedPercent([](uint8_t speedPercent) {
+    // setting speed to Zero, while the Fan is ON, shall turn the Fan off
+    if (speedPercent == 0 && Fan.getMode() != MatterFan::FAN_MODE_OFF) {
+      // ATTR_SET do not update the attribute, just set it to avoid inifinite loop
+      return Fan.setOnOff(false, Fan.ATTR_SET);
+    }
+    // changing the speed to higher than Zero, while the Fan is OFF, shall turn the Fan on
+    if (speedPercent > 0 && Fan.getMode() == MatterFan::FAN_MODE_OFF) {
+      // ATTR_SET do not update the attribute, just set it to avoid inifinite loop
+      return Fan.setOnOff(true, Fan.ATTR_SET);
+    }
+    // for other case, just return true 
+    return true;
+  });
+
+  // This callback will be executed whenever the fan mode matter attribute is updated
+  // This will take action when user APP starts the Fan by changing the mode
+  Fan.onChangeMode([](MatterFan::FanMode_t fanMode) {
+    // when the Fan is turned on using Mode Selection, while it is OFF, shall start it by setting the speed to 50%
+    if (Fan.getSpeedPercent() == 0 && fanMode != MatterFan::FAN_MODE_OFF) {
+      Serial.printf("Fan set to %s mode -- speed percentage will go to 50%%\r\n", Fan.getFanModeString(fanMode));
+      // ATTR_SET do not update the attribute, just set it to avoid inifinite loop
+      return Fan.setSpeedPercent(50, Fan.ATTR_SET);
+    }
+    return true;
+  });
+
+  // Generic callback will be executed as soon as a single feature callback is done
+  // In this example, it will just print status messages
+  Fan.onChange([](MatterFan::FanMode_t fanMode, uint8_t speedPercent) {
+    // just report state
+    Serial.printf("Fan State: Mode %s | %d%% speed.\r\n", Fan.getFanModeString(fanMode), speedPercent);
+    // returns success
+    return true;
+  });
+
+  // Matter beginning - Last step, after all EndPoints are initialized
+  Matter.begin();
+  // This may be a restart of a already commissioned Matter accessory
+  if (Matter.isDeviceCommissioned()) {
+    Serial.println("Matter Node is commissioned and connected to Wi-Fi. Ready for use.");
+  }
+}
+
+// Builtin Button control
+uint32_t button_time_stamp = 0;                 // debouncing control
+bool button_state = false;                      // false = released | true = pressed
+const uint32_t debouceTime = 250;               // button debouncing time (ms)
+const uint32_t decommissioningTimeout = 10000;  // keep the button pressed for 10s to decommission the Matter Fabric
+
+void loop() {
+  // 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 Generic Switch 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.");
+  }
+
+  // A builtin button is used to trigger and send a command to the Matter Controller
+  // 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.
+  }
+
+  // Onboard User Button is used as a smart button or to decommission it
+  uint32_t time_diff = millis() - button_time_stamp;
+  if (button_state && time_diff > debouceTime && digitalRead(buttonPin) == HIGH) {
+    button_state = false;  // released
+    // builtin button is released - toggle Fan on/off
+
+    Fan.toggle();
+    Serial.printf("User button released. Setting the Fan %s.\r\n", Fan > 0 ? "ON" : "OFF");
+
+    // Factory reset is triggered if the button is pressed longer than 10 seconds
+    if (time_diff > decommissioningTimeout) {
+      Serial.println("Decommissioning the Generic Switch Matter Accessory. It shall be commissioned again.");
+      Matter.decommission();
+    }
+  }
+
+  // checks Analog pin and adjust the speed only if it has changed
+  static int lastRead = 0;
+  // analog values (0..1023) / 110 => mapped into 10 steps (0..9)
+  int anaVal = analogRead(analogPin) / 110;
+  if (lastRead != anaVal) { 
+    // speed percent moves in steps of 10. Range is 10..100
+    if (Fan.setSpeedPercent((anaVal + 1) * 10)) {
+      lastRead = anaVal;
+    }
+  }
+}

libraries/Matter/examples/MatterFan/ci.json

@@ -0,0 +1,7 @@
+{
+  "fqbn_append": "PartitionScheme=huge_app",
+  "requires": [
+    "CONFIG_SOC_WIFI_SUPPORTED=y",
+    "CONFIG_ESP_MATTER_ENABLE_DATA_MODEL=y"
+  ]
+}

libraries/Matter/keywords.txt

@@ -15,6 +15,9 @@ MatterColorTemperatureLight	KEYWORD1
 MatterColorLight	KEYWORD1
 MatterEnhancedColorLight	KEYWORD1
 MatterEndPoint	KEYWORD1
+MatterFan	KEYWORD1
+FanMode_t	KEYWORD1
+FanModeSequence_t	KEYWORD1
 
 #######################################
 # Methods and Functions (KEYWORD2)
@@ -32,6 +35,7 @@ decommission	KEYWORD2
 attributeChangeCB	KEYWORD2
 setOnOff	KEYWORD2
 getOnOff	KEYWORD2
+toggle	KEYWORD2
 setBrightness	KEYWORD2
 getBrightness	KEYWORD2
 setColorTemperature	KEYWORD2
@@ -40,13 +44,23 @@ setColorRGB	KEYWORD2
 getColorRGB	KEYWORD2
 setColorHSV	KEYWORD2
 getColorHSV	KEYWORD2
-toggle	KEYWORD2
 updateAccessory	KEYWORD2
 onChange	KEYWORD2
 onChangeOnOff	KEYWORD2
 onChangeBrightness	KEYWORD2
 onChangeColorTemperature	KEYWORD2
 onChangeColorHSV	KEYWORD2
+getAttribute	KEYWORD2
+getAttributeVal	KEYWORD2
+setAttributeVal	KEYWORD2
+updateAttributeVal	KEYWORD2
+getFanModeString	KEYWORD2
+setSpeedPercent	KEYWORD2
+getSpeedPercent	KEYWORD2
+setMode	KEYWORD2
+getMode	KEYWORD2
+onChangeMode	KEYWORD2
+onChangeSpeedPercent	KEYWORD2
 click	KEYWORD2
 
 #######################################
@@ -56,3 +70,21 @@ click	KEYWORD2
 MAX_BRIGHTNESS	LITERAL1
 MAX_COLOR_TEMPERATURE	LITERAL1
 MIN_COLOR_TEMPERATURE	LITERAL1
+ATTR_SET	LITERAL1
+ATTR_UPDATE	LITERAL1
+MAX_SPEED	LITERAL1
+MIN_SPEED	LITERAL1
+OFF_SPEED	LITERAL1
+FAN_MODE_OFF	LITERAL1
+FAN_MODE_LOW	LITERAL1
+FAN_MODE_MEDIUM	LITERAL1
+FAN_MODE_HIGH	LITERAL1
+FAN_MODE_ON	LITERAL1
+FAN_MODE_AUTO	LITERAL1
+FAN_MODE_SMART	LITERAL1
+FAN_MODE_SEQ_OFF_LOW_MED_HIGH	LITERAL1
+FAN_MODE_SEQ_OFF_LOW_HIGH	LITERAL1
+FAN_MODE_SEQ_OFF_LOW_MED_HIGH_AUTO	LITERAL1
+FAN_MODE_SEQ_OFF_LOW_HIGH_AUTO	LITERAL1
+FAN_MODE_SEQ_OFF_HIGH_AUTO	LITERAL1
+FAN_MODE_SEQ_OFF_HIGH	LITERAL1

libraries/Matter/src/Matter.h

@@ -25,6 +25,7 @@
 #include <MatterEndpoints/MatterColorTemperatureLight.h>
 #include <MatterEndpoints/MatterColorLight.h>
 #include <MatterEndpoints/MatterEnhancedColorLight.h>
+#include <MatterEndpoints/MatterFan.h>
 
 using namespace esp_matter;
 
@@ -56,6 +57,7 @@ class ArduinoMatter {
   friend class MatterColorTemperatureLight;
   friend class MatterColorLight;
   friend class MatterEnhancedColorLight;
+  friend class MatterFan;
 
 protected:
   static void _init();

libraries/Matter/src/MatterEndPoint.h

@@ -19,15 +19,87 @@
 #include <Matter.h>
 #include <functional>
 
+using namespace esp_matter;
+
 // Matter Endpoint Base Class. Controls the endpoint ID and allows the child class to overwrite attribute change call
 class MatterEndPoint {
 public:
+
+  enum attrOperation_t {
+    ATTR_SET    = false,
+    ATTR_UPDATE = true
+  };
+
   uint16_t getEndPointId() {
     return endpoint_id;
   }
+
   void setEndPointId(uint16_t ep) {
     endpoint_id = ep;
   }
+
+  // helper functions for attribute manipulation
+  attribute_t * getAttribute(uint32_t cluster_id, uint32_t attribute_id){
+    if (endpoint_id == 0) {
+      log_e("Endpoint ID is not set");
+      return NULL;
+    }
+    endpoint_t *endpoint = endpoint::get(node::get(), endpoint_id);
+    if (endpoint == NULL) {
+      log_e("Endpoint [%d] not found", endpoint_id);
+      return NULL;
+    }
+    cluster_t *cluster = cluster::get(endpoint, cluster_id);
+    if (cluster == NULL) {
+      log_e("Cluster [%d] not found", cluster_id);
+      return NULL;
+    }
+    attribute_t *attribute = attribute::get(cluster, attribute_id);
+    if (attribute == NULL) {
+      log_e("Attribute [%d] not found", attribute_id);
+      return NULL;
+    }
+    return attribute;
+  }
+
+  // get the value of an attribute from its cluster id and attribute it
+  bool getAttributeVal(uint32_t cluster_id, uint32_t attribute_id, esp_matter_attr_val_t *attrVal){
+    attribute_t *attribute = getAttribute(cluster_id, attribute_id);
+    if (attribute == NULL) {
+      return false;
+    }
+    if (attribute::get_val(attribute, attrVal) == ESP_OK) {
+      log_v("GET_VAL Suceess for cluster %d, attribute %d with value %d", cluster_id, attribute_id, attrVal->val.u32);
+      return true;
+    }
+    log_e("GET_VAL FAILED! for cluster %d, attribute %d with value %d", cluster_id, attribute_id, attrVal->val.u32);
+    return false;
+  }
+
+  // set the value of an attribute from its cluster id and attribute it
+  bool setAttributeVal(uint32_t cluster_id, uint32_t attribute_id, esp_matter_attr_val_t *attrVal){
+    attribute_t *attribute = getAttribute(cluster_id, attribute_id);
+    if (attribute == NULL) {
+      return false;
+    }
+    if (attribute::set_val(attribute, attrVal) == ESP_OK) {
+      log_v("SET_VAL Suceess for cluster %d, attribute %d with value %d", cluster_id, attribute_id, attrVal->val.u32);
+      return true;
+    }
+    log_e("SET_VAL FAILED! for cluster %d, attribute %d with value %d", cluster_id, attribute_id, attrVal->val.u32);
+    return false;
+  }
+
+  // update the value of an attribute from its cluster id and attribute it
+  bool updateAttributeVal(uint32_t cluster_id, uint32_t attribute_id, esp_matter_attr_val_t *attrVal){
+    if (attribute::update(endpoint_id, cluster_id, attribute_id, attrVal) == ESP_OK) {
+      log_v("Update Suceess for cluster %d, attribute %d with value %d", cluster_id, attribute_id, attrVal->val.u32);
+      return true;
+    }
+    log_e("Update FAILED! for cluster %d, attribute %d with value %d", cluster_id, attribute_id, attrVal->val.u32);
+    return false;
+  }
+
   // this function is called by Matter internal event processor. It could be overwritten by the application, if necessary.
   virtual bool attributeChangeCB(uint16_t endpoint_id, uint32_t cluster_id, uint32_t attribute_id, esp_matter_attr_val_t *val) = 0;