Fan matter device (CON-1519)

[herculesp17]

Describe the question/query that you have
I want to create a Matter device with two fan endpoints. The fans I have are each controlled by one single PWM pin. First, I created a device with two dimmable light endpoints, which I got working after a while. With the slider in the Home Assistant app, I can control the two endpoints and change the brightness of the LEDs. Then I wanted to do the same for a fan device, but it seems to be more complicated. I first tried the all device example provided and commissioned it with Home Assistant. In there, I had an on/off toggle button and a percentage scaling similar to the dimmable light. When I created my own fan device though, I only have some kind of an on/off switch and a button where I can set the fan mode in my app, but no percentage settings and no on/off toggle button as I have it in my dimmable light app. Also, when I turn on the fan in the app, it automatically turns off again and no pins are triggered. I thought when I initialize the fan endpoint like below, all the clusters are initialized as well. I did the initializing as below:

    // Configs for the fans
    fan::config_t fan_config;
    fan_config.fan_control.percent_current = 50;
    fan_config.fan_control.percent_setting = 50;

    endpoint_t *endpoint = fan::create(node, &fan_config, ENDPOINT_FLAG_NONE, fan_handle);
    ABORT_APP_ON_FAILURE(endpoint != nullptr, ESP_LOGE(TAG, "Failed to create fan endpoint device"));
    fan_endpoint_id = endpoint::get_id(endpoint);

From the esp_matter_endpoint.h i found the following section for the fan:

namespace fan {
typedef struct config : app_with_group_config {
    cluster::fan_control::config_t fan_control;
} config_t;

In the esp_matter_clusters.h I found the following information:

namespace fan_control {
typedef struct config {
    uint8_t fan_mode;
    uint8_t fan_mode_sequence;
    nullable<uint8_t> percent_setting;
    uint8_t percent_current;
    void *delegate;
    config() : fan_mode(0), fan_mode_sequence(2), percent_setting(0), percent_current(0), delegate(nullptr) {}
} config_t;

cluster_t *create(endpoint_t *endpoint, config_t *config, uint8_t flags);
} /* fan_control */

Unfortunately, it did not work as expected. And I tried to add cluster like described here, but this didn't change anything either. I also tried to adjust main app_driver.cpp to update the attributes but that didn't work as expected either:

esp_err_t app_driver_attribute_update(app_driver_handle_t driver_handle, uint16_t endpoint_id, uint32_t cluster_id,
                                      uint32_t attribute_id, esp_matter_attr_val_t *val)
{
    esp_err_t err = ESP_OK;
    led_config_t *led_configs = (led_config_t *)driver_handle;
    ESP_LOGI(TAG, "Enpoint id %d", endpoint_id);
    ESP_LOGI(TAG, "Cluster id %lu", cluster_id);

    int led_index = endpoint_id - 1;  // Assuming endpoint IDs start from 1
    if (led_index >= 0 && led_index < MAX_LEDS) {
        if (cluster_id == FanControl::Id) {
            if (attribute_id == FanControl::Attributes::PercentSetting::Id) {
                err = app_driver_light_set_brightness(&led_configs[led_index], val);
            }
        }
    }
    return err;
}

I have also another issue like described in #1074 where I wanted to change the names in the Home Assistant app for the different endpoints, but the name stays the same (Fan (1) and Fan (2)) although I did the following:

    endpoint_t *endpoint = fan::create(node, &fan_config, ENDPOINT_FLAG_NONE, fan_handle);
    ABORT_APP_ON_FAILURE(endpoint != nullptr, ESP_LOGE(TAG, "Failed to create fan endpoint device"));
    fan_endpoint_id = endpoint::get_id(endpoint);

    auto cluster = esp_matter::cluster::get(endpoint, chip::app::Clusters::BasicInformation::Id);
    auto attribute = esp_matter::attribute::get(cluster, chip::app::Clusters::BasicInformation::Attributes::NodeLabel::Id);
    std::string data = "Fan Number one";
    auto val = esp_matter_char_str(data.data(), data.length());
    esp_matter::attribute::set_val(attribute, &val);

Additional context
idf version: ESP-IDF v5.4

dimmable light repo
fan repo

So in the end I want my device to work as my dimmable light example. If I have to have fan modes definded this is not a problem and I also want the product label and or node label to be visable in the homeassistant app after commissioning. I hope someone can help me. I really like the esp matter idf and i want to develop some products, but my programming skills are just growing as of now.

[Jerry-ESP]

Hi @herculesp17 ,

I have tested the fan device before, you can refer to my example: https://github.com/Jerry-ESP/esp-matter/tree/add_fan_example_test/examples/fan, this is a simple fan without any features, the only point you need to focus on is the fan mode should be correspond to the percent. You can add your fan driver in this function: app_driver_fan_set_percent()

[Jerry-ESP]

For the detail function of the fan, you can refer to this document: Matter 1.4 Application Cluster Specification https://csa-iot.org/developer-resource/specifications-download-request/

[herculesp17]

@Jerry-ESP Thanks for the help :) I will try it out this weekend!

[herculesp17]

@Jerry-ESP Hey i tried your example and i configured everything as i need. I dont have a percentage slider in home assistant. do you know what I'm missing to get that?

[Jerry-ESP]

@Jerry-ESP Hey i tried your example and i configured everything as i need. I dont have a percentage slider in home assistant. do you know what I'm missing to get that?

Can you share your code and the screenshot for home assistant?

[herculesp17]

sure, I just updated the repo. A picture of homeassistant is in the README. It says the the device is not available, because it wasn't on when i took the picture, but it looks exactly the same when connected.