matter_interface.cpp

/**
 * @file matter_interface.cpp
 * @brief Matter protocol abstraction: stack setup, clusters init and data transfer.
 * @author Ihar Hlukhau
 * @date 04/06/2026
 */

#include "matter_interface.h"

#include <inttypes.h>
#include <string.h>

#include "esp_log.h"
#include "esp_wifi.h"

#include <app/server/Server.h>
#include <esp_matter.h>
#include <app-common/zap-generated/cluster-objects.h>
#include <platform/CHIPDeviceLayer.h>

static const char *TAG = "MATTER_INTF";
/** @brief Matter runtime status (persistent across the session). */
static matter_status_s s_status;

/** @brief Temperature sensor endpoint ID. */
static uint16_t s_temperature_endpoint_id;
/** @brief Humidity sensor endpoint ID. */
static uint16_t s_humidity_endpoint_id;
/** @brief Air quality sensor endpoint ID. */
static uint16_t s_air_quality_endpoint_id;


/** @brief Map SEN66 PM2.5 (μg/m³ x 10) to Matter AirQualityEnum (1-6). */
static uint8_t air_quality_from_pm25(const float pm25) {
    if (pm25 > 225.4f) return 6; // kExtremelyPoor
    if (pm25 > 125.4f) return 5; // kVeryPoor
    if (pm25 > 55.4f)  return 4; // kPoor
    if (pm25 > 35.4f)  return 3; // kModerate
    if (pm25 > 9.0f)   return 2; // kFair
    return 1;                    // kGood
}

/** @brief Map SEN66 PM10 (μg/m³ x 10) to Matter AirQualityEnum (1-6). */
static uint8_t air_quality_from_pm10(const float pm10) {
    if (pm10 > 424.0f) return 6; // kExtremelyPoor
    if (pm10 > 354.0f) return 5; // kVeryPoor
    if (pm10 > 254.0f) return 4; // kPoor
    if (pm10 > 154.0f) return 3; // kModerate
    if (pm10 > 54.0f)  return 2; // kFair
    return 1;                    // kGood
}

/** @brief Map SEN66 CO2 (ppm) to Matter AirQualityEnum (1-6). */
static uint8_t air_quality_from_co2(const uint16_t co2) {
    if (co2 > 5000) return 6; // kExtremelyPoor
    if (co2 > 2000) return 5; // kVeryPoor
    if (co2 > 1400) return 4; // kPoor
    if (co2 > 1000) return 3; // kModerate
    if (co2 > 800)  return 2; // kFair
    return 1;                 // kGood
}

/** @brief Map SEN66 VOC Index to Matter AirQualityEnum (1-6). */
static uint8_t air_quality_from_voc(const float voc) {
    if (voc > 400) return 5; // kVeryPoor
    if (voc > 300) return 4; // kPoor
    if (voc > 200) return 3; // kModerate
    if (voc > 100) return 2; // kFair
    return 1;                // kGood
}

/** @brief Map SEN66 NOx Index to Matter AirQualityEnum (1-6). */
static uint8_t air_quality_from_nox(const float nox) {
    if (nox > 349) return 5; // kVeryPoor
    if (nox > 299) return 4; // kPoor
    if (nox > 99)  return 3; // kModerate
    if (nox > 49)  return 2; // kFair
    return 1;                // kGood
}

/** @brief Derive overall air quality as the worst level across all pollutants. */
static uint8_t derive_air_quality(const sen66_sample_s *sample) {
    // Scale raw value from SEN66
    const float pm25 = sample->pm25 / 10.0f;
    const float pm10 = sample->pm10 / 10.0f;
    const float voc = sample->voc / 10.0f;
    const float nox = sample->nox / 10.0f;

    uint8_t worst = air_quality_from_pm25(pm25);
    uint8_t level;

    level = air_quality_from_pm10(pm10);
    if (level > worst) worst = level;

    level = air_quality_from_co2(sample->co2);
    if (level > worst) worst = level;

    level = air_quality_from_voc(voc);
    if (level > worst) worst = level;

    level = air_quality_from_nox(nox);
    if (level > worst) worst = level;

    return worst;
}

/** @brief Map CO2 (ppm) to Matter LevelValueEnum. */
static uint8_t co2_level_value(const uint16_t co2) {
    if (co2 > 3000) return chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kCritical);
    if (co2 > 1300) return chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kHigh);
    if (co2 > 800)  return chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kMedium);
    return chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kLow);
}

/** @brief Map PM2.5 (µg/m³) to Matter LevelValueEnum. */
static uint8_t pm25_level_value(const float pm25) {
    if (pm25 > 125.4f)  return chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kCritical);
    if (pm25 > 55.4f)  return chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kHigh);
    if (pm25 > 35.4f)  return chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kMedium);
    return chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kLow);
}

/** @brief Map PM10 (µg/m³) to Matter LevelValueEnum. */
static uint8_t pm10_level_value(const float pm10) {
    if (pm10 > 354.0f) return chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kCritical);
    if (pm10 > 154.0f) return chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kHigh);
    if (pm10 > 54.0f)  return chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kMedium);
    return chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kLow);
}

template <typename T>
static int update_attribute(const uint16_t endpoint_id, const uint32_t cluster_id,
                            const uint32_t attribute_id, T value) {
    esp_matter_attr_val_t val = esp_matter_invalid(nullptr);
    if constexpr (std::is_same_v<std::decay_t<T>, int16_t>) {
        val = esp_matter_int16(value);
    } else if constexpr (std::is_same_v<std::decay_t<T>, uint16_t>) {
        val = esp_matter_uint16(value);
    } else if constexpr (std::is_same_v<std::decay_t<T>, uint8_t>) {
        // Only uint8_t values used are mapped to Matter's enums
        val = esp_matter_enum8(value);
    } else if constexpr (std::is_same_v<std::decay_t<T>, float>) {
        val = esp_matter_nullable_float(value);
    } else {
        static_assert(false, "Unsupported type passed to update_attribute_logged");
    }

    const esp_err_t err = esp_matter::attribute::update(endpoint_id, cluster_id, attribute_id, &val);
    if (err != ESP_OK) {
        ESP_LOGW(TAG, "Attribute update failed: cluster=0x%08" PRIx32 " err=%s",
                 cluster_id, esp_err_to_name(err));
        s_status.last_error = err;
        return 1;
    }
    return 0;
}

/** @brief Refresh s_status (initialized, commissioned, WiFi state) from live sources. */
static void refresh_status() {
    s_status.initialized = esp_matter::is_started();
    if (s_status.initialized) {
        s_status.commissioned = chip::Server::GetInstance().GetFabricTable().FabricCount() > 0;
    }

    wifi_ap_record_t ap_info = {};
    const esp_err_t wifi_err = esp_wifi_sta_get_ap_info(&ap_info);
    s_status.wifi_connected = wifi_err == ESP_OK;
    s_status.rssi = s_status.wifi_connected ? ap_info.rssi : 0;
}

static void open_commissioning_window_if_necessary()
{
    VerifyOrReturn(chip::Server::GetInstance().GetFabricTable().FabricCount() == 0);

    chip::CommissioningWindowManager & commissionMgr = chip::Server::GetInstance().GetCommissioningWindowManager();
    VerifyOrReturn(commissionMgr.IsCommissioningWindowOpen() == false);

    const CHIP_ERROR err = commissionMgr.OpenBasicCommissioningWindow(chip::System::Clock::Seconds16(300),
                                    chip::CommissioningWindowAdvertisement::kDnssdOnly);
    if (err != CHIP_NO_ERROR) {
        ESP_LOGE(TAG, "Failed to open commissioning window, err:%" CHIP_ERROR_FORMAT, err.Format());
    }
}

/** @brief Matter identification callback (log identify requests). */
static esp_err_t app_identification_cb(esp_matter::identification::callback_type_t type, uint16_t endpoint_id,
                                       uint8_t effect_id, uint8_t effect_variant, void *priv_data) {
    ESP_LOGI(TAG, "Identify endpoint=%u type=%u effect=%u variant=%u", endpoint_id, type, effect_id, effect_variant);
    return ESP_OK;
}

/** @brief Matter attribute update callback (unused, don't expect any writes). */
static esp_err_t app_attribute_update_cb(esp_matter::attribute::callback_type_t type, uint16_t endpoint_id,
                                         uint32_t cluster_id, uint32_t attribute_id,
                                         esp_matter_attr_val_t *val, void *priv_data) {
    return ESP_OK;
}

/** @brief Matter platform event callback (commissioning, fabric removal, BLE deinit). */
static void app_event_cb(const ChipDeviceEvent *event, intptr_t arg) {
    switch (event->Type) {
        case chip::DeviceLayer::DeviceEventType::kCommissioningComplete:
            s_status.commissioned = true;
            ESP_LOGI(TAG, "Matter commissioning complete");
            break;

        case chip::DeviceLayer::DeviceEventType::kFailSafeTimerExpired:
            ESP_LOGI(TAG, "Matter commissioning failed, fail safe timer expired");
            break;

        case chip::DeviceLayer::DeviceEventType::kFabricRemoved:
            refresh_status();
            ESP_LOGI(TAG, "Matter fabric removed");
            open_commissioning_window_if_necessary();
            break;

        case chip::DeviceLayer::DeviceEventType::kBLEDeinitialized:
            ESP_LOGI(TAG, "Matter BLE commissioning transport deinitialized");
            break;

        default:
            break;
    }
}

/** @brief Create a concentration measurement endpoint with full feature set. */
__unused // can be used if choose to config the concentration metrics via dedicated endpoints
static uint16_t create_concentration_endpoint(esp_matter::node_t *node,
                                              const uint32_t cluster_id, const uint8_t unit,
                                              const float min_value, const float max_value) {
    esp_matter::endpoint_t *endpoint = esp_matter::endpoint::create(node,
        esp_matter::ENDPOINT_FLAG_NONE, nullptr);
    if (endpoint == nullptr) {
        return 0;
    }

    esp_matter::cluster::concentration_measurement::config_t config;
    config.measurement_medium = chip::to_underlying(chip::app::Clusters::detail::MeasurementMediumEnum::kAir);
    config.feature_flags = esp_matter::cluster::concentration_measurement::feature::numeric_measurement::get_id()
                         | esp_matter::cluster::concentration_measurement::feature::level_indication::get_id()
                         | esp_matter::cluster::concentration_measurement::feature::medium_level::get_id()
                         | esp_matter::cluster::concentration_measurement::feature::critical_level::get_id();
    config.features.numeric_measurement.measurement_unit = unit;
    config.features.numeric_measurement.min_measured_value = nullable<float>(min_value);
    config.features.numeric_measurement.max_measured_value = nullable<float>(max_value);
    config.features.level_indication.level_value = chip::to_underlying(
        chip::app::Clusters::detail::LevelValueEnum::kUnknown);

    esp_matter::cluster_t *cluster = nullptr;
    if (cluster_id == chip::app::Clusters::CarbonDioxideConcentrationMeasurement::Id) {
        cluster = esp_matter::cluster::carbon_dioxide_concentration_measurement::create(endpoint,
            &config, esp_matter::CLUSTER_FLAG_SERVER);
    } else if (cluster_id == chip::app::Clusters::Pm25ConcentrationMeasurement::Id) {
        cluster = esp_matter::cluster::pm25_concentration_measurement::create(endpoint,
            &config, esp_matter::CLUSTER_FLAG_SERVER);
    } else if (cluster_id == chip::app::Clusters::Pm10ConcentrationMeasurement::Id) {
        cluster = esp_matter::cluster::pm10_concentration_measurement::create(endpoint,
            &config, esp_matter::CLUSTER_FLAG_SERVER);
    }

    if (cluster == nullptr) {
        return 0;
    }

    return esp_matter::endpoint::get_id(endpoint);
}

esp_err_t matter_interface_init() {
    memset(&s_status, 0, sizeof(s_status));

    s_status.enabled = true;

    /* Initialize the Matter node */

    esp_matter::node::config_t node_config;
    esp_matter::node_t *node = esp_matter::node::create(&node_config,
        app_attribute_update_cb, app_identification_cb);
    if (node == nullptr) {
        s_status.last_error = ESP_FAIL;
        return ESP_FAIL;
    }

    /* Configure air quality endpoint */

    // Creates the Air Quality Sensor endpoint (Device Type 0x002C).
    // This automatically includes the Identify and Air Quality clusters.
    esp_matter::endpoint::air_quality_sensor::config_t aq_config;
    esp_matter::endpoint_t *aq_endpoint = esp_matter::endpoint::air_quality_sensor::create(node,
    &aq_config, esp_matter::ENDPOINT_FLAG_NONE, nullptr);
    if (aq_endpoint == nullptr) {
        s_status.last_error = ESP_FAIL;
        return ESP_FAIL;
    }
    s_air_quality_endpoint_id = esp_matter::endpoint::get_id(aq_endpoint);

    // Enable features for air quality cluster
    esp_matter::cluster_t *aq_cluster = esp_matter::cluster::get(aq_endpoint, chip::app::Clusters::AirQuality::Id);
    if (aq_cluster != nullptr) {
        esp_matter::cluster::air_quality::feature::fair::add(aq_cluster);
        esp_matter::cluster::air_quality::feature::moderate::add(aq_cluster);
        esp_matter::cluster::air_quality::feature::very_poor::add(aq_cluster);
        esp_matter::cluster::air_quality::feature::extremely_poor::add(aq_cluster);
    }

    /* Configure Temperature Sensor endpoint */

    // Creates the Temperature Sensor endpoint (Device Type 0x0302).
    // This automatically includes the Identify and Temperature Measurement clusters.
    esp_matter::endpoint::temperature_sensor::config_t temp_config;
    esp_matter::endpoint_t *temp_endpoint = esp_matter::endpoint::temperature_sensor::create(node,
        &temp_config, esp_matter::ENDPOINT_FLAG_NONE, nullptr);
    if (temp_endpoint == nullptr) {
        s_status.last_error = ESP_FAIL;
        return ESP_FAIL;
    }
    s_temperature_endpoint_id = esp_matter::endpoint::get_id(temp_endpoint);

    // -- NOTE: Find config via aggregated air quality endpoint below
    // esp_matter::cluster::temperature_measurement::config_t temp_config;
    // esp_matter::cluster::temperature_measurement::create(aq_endpoint, &temp_config, esp_matter::CLUSTER_FLAG_SERVER);

    /* Configure Humidity Sensor endpoint */

    // Creates the Humidity Sensor endpoint (Device Type 0x0307).
    // This automatically includes the Identify and Relative Humidity Measurement clusters.
    esp_matter::endpoint::humidity_sensor::config_t humidity_config;
    esp_matter::endpoint_t *humidity_endpoint = esp_matter::endpoint::humidity_sensor::create(node,
        &humidity_config, esp_matter::ENDPOINT_FLAG_NONE, nullptr);
    if (humidity_endpoint == nullptr) {
        s_status.last_error = ESP_FAIL;
        return ESP_FAIL;
    }
    s_humidity_endpoint_id = esp_matter::endpoint::get_id(humidity_endpoint);

    // -- NOTE: Find config via aggregated air quality endpoint below
    // esp_matter::cluster::relative_humidity_measurement::config_t hum_config;
    // esp_matter::cluster::relative_humidity_measurement::create(aq_endpoint, &hum_config, esp_matter::CLUSTER_FLAG_SERVER);

    /* Configure CO2 concentration measurement cluster */

    // Creates cluster as part of Air Quality Sensor endpoint
    esp_matter::cluster::carbon_dioxide_concentration_measurement::config_t co2_config;
    co2_config.feature_flags =
        esp_matter::cluster::carbon_dioxide_concentration_measurement::feature::numeric_measurement::get_id()
      | esp_matter::cluster::carbon_dioxide_concentration_measurement::feature::level_indication::get_id()
      | esp_matter::cluster::carbon_dioxide_concentration_measurement::feature::medium_level::get_id()
      | esp_matter::cluster::carbon_dioxide_concentration_measurement::feature::critical_level::get_id();
    co2_config.features.numeric_measurement.measured_value = nullable<float>(0);
    co2_config.features.numeric_measurement.min_measured_value = nullable<float>(0);
    co2_config.features.numeric_measurement.max_measured_value = nullable<float>(10000);
    co2_config.features.numeric_measurement.measurement_unit =
        chip::to_underlying(chip::app::Clusters::detail::MeasurementUnitEnum::kPpm);
    co2_config.features.level_indication.level_value =
        chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kUnknown);
    esp_matter::cluster::carbon_dioxide_concentration_measurement::create(aq_endpoint,
        &co2_config, esp_matter::CLUSTER_FLAG_SERVER);

    // -- NOTE: Find config via dedicated endpoint below
    // s_co2_endpoint_id = create_concentration_endpoint(node,
    //     chip::app::Clusters::CarbonDioxideConcentrationMeasurement::Id,
    //     chip::to_underlying(chip::app::Clusters::detail::MeasurementUnitEnum::kPpm),
    //     0.0f, 40000.0f);
    // if (s_co2_endpoint_id == 0) {
    //     s_status.last_error = ESP_FAIL;
    //     return ESP_FAIL;
    // }

    /* Configure PM1.0 concentration measurement cluster */

    // Creates cluster as part of Air Quality Sensor endpoint
    esp_matter::cluster::pm1_concentration_measurement::config_t pm1_config;
    pm1_config.feature_flags =
          esp_matter::cluster::pm1_concentration_measurement::feature::numeric_measurement::get_id();
    pm1_config.features.numeric_measurement.measured_value = nullable<float>(0);
    pm1_config.features.numeric_measurement.min_measured_value = nullable<float>(0);
    pm1_config.features.numeric_measurement.max_measured_value = nullable<float>(1000);
    pm1_config.features.numeric_measurement.measurement_unit =
        chip::to_underlying(chip::app::Clusters::detail::MeasurementUnitEnum::kUgm3);
    esp_matter::cluster::pm1_concentration_measurement::create(aq_endpoint,
        &pm1_config, esp_matter::CLUSTER_FLAG_SERVER);

    /* Configure PM2.5 concentration measurement cluster */

    // Creates cluster as part of Air Quality Sensor endpoint
    esp_matter::cluster::pm25_concentration_measurement::config_t pm25_config;
    pm25_config.feature_flags =
          esp_matter::cluster::pm25_concentration_measurement::feature::numeric_measurement::get_id()
        | esp_matter::cluster::pm25_concentration_measurement::feature::level_indication::get_id()
        | esp_matter::cluster::pm25_concentration_measurement::feature::medium_level::get_id()
        | esp_matter::cluster::pm25_concentration_measurement::feature::critical_level::get_id();
    pm25_config.features.numeric_measurement.measured_value = nullable<float>(0);
    pm25_config.features.numeric_measurement.min_measured_value = nullable<float>(0);
    pm25_config.features.numeric_measurement.max_measured_value = nullable<float>(1000);
    pm25_config.features.numeric_measurement.measurement_unit =
        chip::to_underlying(chip::app::Clusters::detail::MeasurementUnitEnum::kUgm3);
    pm25_config.features.level_indication.level_value =
        chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kUnknown);
    esp_matter::cluster::pm25_concentration_measurement::create(aq_endpoint,
        &pm25_config, esp_matter::CLUSTER_FLAG_SERVER);

    // -- NOTE: Find config via dedicated endpoint below
    // s_pm25_endpoint_id = create_concentration_endpoint(node,
    //     chip::app::Clusters::Pm25ConcentrationMeasurement::Id,
    //     chip::to_underlying(chip::app::Clusters::detail::MeasurementUnitEnum::kUgm3),
    //     0.0f, 1000.0f);
    // if (s_pm25_endpoint_id == 0) {
    //     s_status.last_error = ESP_FAIL;
    //     return ESP_FAIL;
    // }

    /* Configure PM10 concentration measurement cluster */

    // Creates cluster as part of Air Quality Sensor endpoint
    esp_matter::cluster::pm10_concentration_measurement::config_t pm10_config;
    pm10_config.feature_flags =
          esp_matter::cluster::pm10_concentration_measurement::feature::numeric_measurement::get_id()
        | esp_matter::cluster::pm10_concentration_measurement::feature::level_indication::get_id()
        | esp_matter::cluster::pm10_concentration_measurement::feature::medium_level::get_id()
        | esp_matter::cluster::pm10_concentration_measurement::feature::critical_level::get_id();
    pm10_config.features.numeric_measurement.measured_value = nullable<float>(0);
    pm10_config.features.numeric_measurement.min_measured_value = nullable<float>(0);
    pm10_config.features.numeric_measurement.max_measured_value = nullable<float>(1000);
    pm10_config.features.numeric_measurement.measurement_unit =
        chip::to_underlying(chip::app::Clusters::detail::MeasurementUnitEnum::kUgm3);
    pm10_config.features.level_indication.level_value =
        chip::to_underlying(chip::app::Clusters::detail::LevelValueEnum::kUnknown);
    esp_matter::cluster::pm10_concentration_measurement::create(aq_endpoint,
        &pm10_config, esp_matter::CLUSTER_FLAG_SERVER);

    // -- NOTE: Find config via dedicated endpoint below
    // s_pm10_endpoint_id = create_concentration_endpoint(node,
    //     chip::app::Clusters::Pm10ConcentrationMeasurement::Id,
    //     chip::to_underlying(chip::app::Clusters::detail::MeasurementUnitEnum::kUgm3),
    //     0.0f, 1000.0f);
    // if (s_pm10_endpoint_id == 0) {
    //     s_status.last_error = ESP_FAIL;
    //     return ESP_FAIL;
    // }

    static constexpr int MATTER_START_RETRIES = 3;
    static constexpr TickType_t MATTER_START_RETRY_DELAY_MS = 1000;

    esp_err_t err = ESP_OK;
    for (int attempt = 0; attempt < MATTER_START_RETRIES; ++attempt) {
        err = esp_matter::start(app_event_cb);
        if (err == ESP_OK) {
            break;
        }
        ESP_LOGW(TAG, "Matter start failed (attempt %d/%d): %s",
                 attempt + 1, MATTER_START_RETRIES, esp_err_to_name(err));
        if (attempt < MATTER_START_RETRIES - 1) {
            vTaskDelay(pdMS_TO_TICKS(MATTER_START_RETRY_DELAY_MS));
        }
    }
    s_status.last_error = err;
    refresh_status();
    return err;
}

esp_err_t matter_interface_send_sample(const sen66_sample_s *sample) {
    if (sample == NULL) {
        return ESP_ERR_INVALID_ARG;
    }

    if (!esp_matter::is_started()) {
        s_status.last_error = ESP_ERR_INVALID_STATE;
        return ESP_ERR_INVALID_STATE;
    }

    const sen66_sample_s sample_copy = *sample;
    chip::DeviceLayer::SystemLayer().ScheduleLambda([sample_copy]() {
        int rc = 0;

        // NOTE: can replace with s_air_quality_endpoint_id if NO dedicated temp endpoint
        rc += update_attribute(s_temperature_endpoint_id,
            chip::app::Clusters::TemperatureMeasurement::Id,
            chip::app::Clusters::TemperatureMeasurement::Attributes::MeasuredValue::Id,
            static_cast<int16_t>(sample_copy.temp / 2));

        // NOTE: can replace with s_air_quality_endpoint_id if NO dedicated hum endpoint
        rc += update_attribute(s_humidity_endpoint_id,
            chip::app::Clusters::RelativeHumidityMeasurement::Id,
            chip::app::Clusters::RelativeHumidityMeasurement::Attributes::MeasuredValue::Id,
            static_cast<uint16_t>(sample_copy.hum));

        rc += update_attribute(s_air_quality_endpoint_id,
            chip::app::Clusters::AirQuality::Id,
            chip::app::Clusters::AirQuality::Attributes::AirQuality::Id,
            derive_air_quality(&sample_copy));

        // NOTE: can replace with s_co2_endpoint_id if dedicated co2 endpoint exists
        rc += update_attribute(s_air_quality_endpoint_id,
            chip::app::Clusters::CarbonDioxideConcentrationMeasurement::Id,
            chip::app::Clusters::CarbonDioxideConcentrationMeasurement::Attributes::MeasuredValue::Id,
            static_cast<float>(sample_copy.co2));

        // NOTE: can replace with s_co2_endpoint_id if dedicated co2 endpoint exists
        rc += update_attribute(s_air_quality_endpoint_id,
            chip::app::Clusters::CarbonDioxideConcentrationMeasurement::Id,
            chip::app::Clusters::CarbonDioxideConcentrationMeasurement::Attributes::LevelValue::Id,
            co2_level_value(sample_copy.co2));

        rc += update_attribute(s_air_quality_endpoint_id,
            chip::app::Clusters::Pm1ConcentrationMeasurement::Id,
            chip::app::Clusters::Pm1ConcentrationMeasurement::Attributes::MeasuredValue::Id,
            sample_copy.pm1 / 10.0f);

        // NOTE: can replace with s_pm25_endpoint_id if dedicated pm25 endpoint exists
        rc += update_attribute(s_air_quality_endpoint_id,
            chip::app::Clusters::Pm25ConcentrationMeasurement::Id,
            chip::app::Clusters::Pm25ConcentrationMeasurement::Attributes::MeasuredValue::Id,
            sample_copy.pm25 / 10.0f);

        // NOTE: can replace with s_pm25_endpoint_id if dedicated pm25 endpoint exists
        rc += update_attribute(s_air_quality_endpoint_id,
            chip::app::Clusters::Pm25ConcentrationMeasurement::Id,
            chip::app::Clusters::Pm25ConcentrationMeasurement::Attributes::LevelValue::Id,
            pm25_level_value(sample_copy.pm25 / 10.0f));

        // NOTE: can replace with s_pm10_endpoint_id if dedicated pm10 endpoint exists
        rc += update_attribute(s_air_quality_endpoint_id,
            chip::app::Clusters::Pm10ConcentrationMeasurement::Id,
            chip::app::Clusters::Pm10ConcentrationMeasurement::Attributes::MeasuredValue::Id,
            sample_copy.pm10 / 10.0f);

        // NOTE: can replace with s_pm10_endpoint_id if dedicated pm10 endpoint exists
        rc += update_attribute(s_air_quality_endpoint_id,
            chip::app::Clusters::Pm10ConcentrationMeasurement::Id,
            chip::app::Clusters::Pm10ConcentrationMeasurement::Attributes::LevelValue::Id,
            pm10_level_value(sample_copy.pm10 / 10.0f));

        if (rc == 0) {
            s_status.consecutive_update_failures = 0;
            s_status.last_publish_timestamp = sample_copy.timestamp;
        } else {
            s_status.consecutive_update_failures++;
        }
        refresh_status();
    });

    return ESP_OK;
}

esp_err_t matter_interface_factory_reset() {
    if (!esp_matter::is_started()) {
        return ESP_OK;
    }
    return esp_matter::factory_reset();
}

void matter_interface_get_status(matter_status_s *status) {
    if (status == nullptr) {
        return;
    }
    refresh_status();
    *status = s_status;
}

bool matter_interface_is_live_ready() {
    refresh_status();
    return s_status.initialized && s_status.commissioned && s_status.wifi_connected;
}