esp-matter/RELEASE_NOTES.md

# 14-April-2026

## Generated Data Model (Experimental)

### Added
- Experimental support for a **generated data model** based on Matter Specification XMLs.
- Generated sources are available under:
  - `components/esp_matter/data_model/generated/`

### Changed
- Legacy handwritten data model implementation moved to:
  - `components/esp_matter/data_model/legacy/`
- Data model can now be generated using:

```
python tools/data_model_gen/data_model_gen.py
```
- Some APIs and namespaces have been updated with the generated data model.
- The examples below are representative and not a complete list of changes.


e.g.

- Namespace updates include:
```
- namespace wifi {} → namespace wi_fi {}
```

- Color Control Cluster Attribute API's
```
attribute_t *create_primary_n_x(cluster_t * cluster, uint16_t value, uint8_t index);
attribute_t *create_primary_n_y(cluster_t * cluster, uint16_t value, uint8_t index);
attribute_t *create_primary_n_intensity(cluster_t * cluster, nullable<uint8_t> value, uint8_t index);
```
to

```
attribute_t *create_primary_1_x(cluster_t *cluster, uint16_t value);
attribute_t *create_primary_1_y(cluster_t *cluster, uint16_t value);
attribute_t *create_primary_1_intensity(cluster_t *cluster, nullable<uint8_t> value);
```

### Configuration
- Enable via `CONFIG_ESP_MATTER_ENABLE_GENERATED_DATA_MODEL` (menuconfig → ESP Matter → Generated Data Model)
- Existing implementations is used by default


# 5-Mar-2026

### Controller API changes
- In `write_command`, `on_error_callback`, `on_success_callback`, and `on_write_done_callback` have been added to report the status of write_command.
- In `subscribe_command`, `subscribe_failure_cb_t` has been renamed to `connect_failure_cb_t`, and it has been added to the other interaction commands to indicate whether the CASE session is established successfully.
- `StatusIB` is added to `attribute_report_cb_t` and `event_report_cb_t`.

### API Changes
- In `subscribe_command`, `subscribe_done_cb_t` has been renamed to `subscribe_terminated_cb_t` to align better with the terminology.
- In `subscribe_command` a new callback `subscription_established_cb_t` has been added to report successfully subscription commands. 

# 4-Feb-2026
### API Changes
- Removed APIs: `plugin_init_callback_common()`, `add_bounds_callback_common()` and `delegate_init_callback_common()`.

# 27-Nov-2025
### Feature: attribute::get_val() and attribute::set_val() APIs

- `attribute::get_val()`
  - API now supports getting the value of internally managed attributes of primitive data types.
  - Complex types are not supported yet, eg: (Array, Struct, List, etc.)

- `attribute::set_val()`
  - API now supports setting the value of internally managed attributes which are writable and of data type primitive.
  - Attributes which are not writable but managed internally are not supported yet
  - Complex types are not supported yet, eg: (Array, Struct, List, etc.)

- For unsupported attributes, the APIs will return `ESP_ERR_NOT_SUPPORTED`,
  please use the cluster-specific setter APIs.

## 21-Nov-2025
### API Changes: Attribute Creation Function Names

The following attribute creation APIs have been renamed to remove inconsistencies and align with Matter specifications:

#### Descriptor Cluster
```
create_device_list() → create_device_type_list()
```

#### Thread Network Diagnostics Cluster
```
create_active_network_faults() → create_active_network_faults_list()
```

#### Ethernet Network Diagnostics Cluster
```
create_tx_error_count() → create_tx_err_count()
```

#### Groups Cluster
```
create_group_name_support() → create_name_support()
```

#### Thermostat Cluster
```
create_schedule_type() → create_schedule_types()
```

#### Door Lock Cluster
```
create_door_close_events() → create_door_closed_events()
```

#### Temperature Measurement Cluster
Removed `temperature_` prefix from attribute names:
```
create_temperature_measured_value() → create_measured_value()
create_temperature_min_measured_value() → create_min_measured_value()
create_temperature_max_measured_value() → create_max_measured_value()
```

#### Relative Humidity Measurement Cluster
Removed `relative_humidity_` prefix from attribute names:
```
create_relative_humidity_measured_value() → create_measured_value()
create_relative_humidity_min_measured_value() → create_min_measured_value()
create_relative_humidity_max_measured_value() → create_max_measured_value()
create_relative_humidity_tolerance() → create_tolerance()
```

#### Illuminance Measurement Cluster
Removed `illuminance_` prefix from attribute names:
```
create_illuminance_measured_value() → create_measured_value()
create_illuminance_min_measured_value() → create_min_measured_value()
create_illuminance_max_measured_value() → create_max_measured_value()
create_illuminance_tolerance() → create_tolerance()
create_illuminance_light_sensor_type() → create_light_sensor_type()
```

#### Pressure Measurement Cluster
Removed `pressure_` prefix from attribute names:
```
create_pressure_measured_value() → create_measured_value()
create_pressure_min_measured_value() → create_min_measured_value()
create_pressure_max_measured_value() → create_max_measured_value()
create_pressure_tolerance() → create_tolerance()
create_pressure_scaled_value() → create_scaled_value()
create_pressure_min_scaled_value() → create_min_scaled_value()
create_pressure_max_scaled_value() → create_max_scaled_value()
create_pressure_scaled_tolerance() → create_scaled_tolerance()
create_pressure_scale() → create_scale()
```

#### Flow Measurement Cluster
Removed `flow_` prefix from attribute names:
```
create_flow_measured_value() → create_measured_value()
create_flow_min_measured_value() → create_min_measured_value()
create_flow_max_measured_value() → create_max_measured_value()
create_flow_tolerance() → create_tolerance()
```

#### Pump Configuration and Control Cluster
```
create_pump_power() → create_power()
```

#### Mode Select Cluster
```
create_mode_select_description() → create_description()
```

### Namespace Changes

#### Thread Network Diagnostics Cluster
```
feature::packets_counts → feature::packet_counts
```

## 31-Oct-2025
### API Changes: `feature::add()` Function
The following APIs have been updated — the config parameter has been removed, as the corresponding attributes are optional.
```
window_covering::feature::lift::add(cluster_t *cluster);
window_covering::feature::tilt::add(cluster_t *cluster);
```

## 21-Oct-2025
### API Changes: `feature::add()` Function
The following APIs have been updated — the config parameter has been removed, as the corresponding attributes are internally managed and not user-configurable:

```
general_commissioning::feature::terms_and_conditions::add(cluster_t *cluster);
ethernet_network_diagnostics::feature::packet_counts::add(cluster_t *cluster);
ethernet_network_diagnostics::feature::error_counts::add(cluster_t *cluster);
unit_localization::feature::temperature_unit::add(cluster_t *cluster);
water_heater_management::feature::energy_management::add(cluster_t *cluster);
water_heater_management::feature::tank_percentage::add(cluster_t *cluster);

```

## 30-Sep-2025

### Namespace Changes to Align with Matter Specifications

#### Cluster namespace changes
- `ota_requestor` → `ota_software_update_requestor`
- `ota_provider` → `ota_software_update_provider`

#### Device type namespace changes
- `on_off_switch` → `on_off_light_switch`
- `power_source_device` → `power_source`
- `window_covering_device` → `window_covering`
- `mode_select_device` → `mode_select`

### Namespace Changes for Consistency

- `on_off_plugin_unit` → `on_off_plug_in_unit`
- `dimmable_plugin_unit` -> `dimmable_plug_in_unit`
- `descriptor::feature::taglist` → `descriptor::feature::tag_list`
- `color_temperature_light::color_temperature::startup_color_temperature_mireds` → `color_temperature_light::color_temperature::start_up_color_temperature_mireds`

### Note

The following namespaces exist in both the `cluster` and `device_type` namespaces:

- `window_covering`
- `power_source`
- `mode_select`

To avoid ambiguity, please reference them explicitly depending on context. For example:

- Use `endpoint::window_covering::create()` to create the **endpoint**
- Use `cluster::window_covering::create()` to create the **cluster**

# 2-Sep-2025

API change.

Move the macros `REMAP_TO_RANGE()` and `REMAP_TO_RANGE_INVERSE()` to from the `esp_matter_attribute_utils.h` to `common_macros.h`
in `examples/common/utils` directory.


# 10-June-2025

API Change.
Removed the `features` parameter from the `cluster::create()` API to make it consistent across all clusters.
The new API signature is:
```
cluster_t *create(endpoint_t *endpoint, config_t *config, uint8_t flags);
```
For clusters with `O.a/O.a+` features conformance, the `feature_flags` is available at cluster level.
For device types with `M` feature conformance of a cluster, the feature config is available at device type level.
For clusters with `O` feature conformance, feature should be added using `feature_name::add()` API in the application.

# 3-Feb-2024

Cluster structure change.
  - `feature_flags` are now part of `cluster::config` to configure the features in the application.
  - moved `features::config` from `cluster::config` to `cluster::config::features` structure.

# 27-December-2024

Added ``matter esp factoryreset`` command to factory reset a Matter device.
This command erases the esp-matter and connectedhomeip SDK's non-volatile storage.

# 15-Oct-2024

API Change
```
esp_err_t get_bounds(attribute_t *attribute, esp_matter_attr_bounds_t *bounds);
```
- Above API returns the `esp_err_t` and has parameter `bounds`.

# 28-Aug-2024

- Removed the configurability of the NameSupport attribute of the Groups cluster and enabled
  it by default. The NameSupport and feature-map attributes of the Groups cluster must be kept
  in sync, the connectedhomeip SDK enables the GroupName feature by default and set the
  NameSupport attribute to appropriate value.

# 08-July-2024
- Changed diagnostic cluster namespaces as per the matter specifications
  - diagnostics_network_wifi -> wifi_network_diagnostics  
  - diagnostics_network_thread -> thread_network_diagnostics  
  - diagnostics_network_ethernet -> ethernet_network_diagnostics

# 07-May-2024

- `tools/mfg_tool.py` is moved to https://github.com/espressif/esp-matter-tools/tree/main/mfg_tool
  and can be installed by running `python3 -m pip install esp-matter-mfg-tool`.

# 14-February-2024

- An optional argument, `max_val_size`, has been introduced to the `esp_matter::attribute::create()` API.
  This argument is utilized specifically when creating attributes of the char string and long char string data types
  to specify the maximum supported value size of an attribute.

# 29-January-2024

- Add a new parameter for esp_matter::client::connect() to set the CASESessionManager for finding or establishing the CASE sessions.

# 16-January-2024

- We have moved the creation of bridge devices to the application callback.
  Previously, bridge devices were created in the examples/common, but now creation
  is delegated to the application.

    Initialize the bridge with a callback.

    ```
    esp_err_t err = app_bridge_initialize(node, bridge_device_type_callback);
    ```

    Below is the example definition of callback creating on-off light.
    ```
	esp_err_t create_bridge_devices(esp_matter::endpoint_t *ep, uint32_t device_type_id, void *priv_data)
	{
		esp_err_t err = ESP_OK;

		switch (device_type_id) {
		case ESP_MATTER_ON_OFF_LIGHT_DEVICE_TYPE_ID: {
			on_off_light::config_t on_off_light_conf;
			err = on_off_light::add(ep, &on_off_light_conf);
			break;
        }
		.
		.
		.
		default: {
			ESP_LOGE(TAG, "Unsupported bridged matter device type");
			return ESP_ERR_INVALID_ARG;

		}
		return err;
	}

    ```

- Similar changes are made in bridge apps.

# 9-November-2023

- esp_matter_controller: Change the format of the command data field payload for cluster-invoke commands and the attribute value payload for attribute-write commands. Used unified JSON object format for these payloads. Please refer the document of ``Matter controller`` to learn how to construct them.

# 2-November-2023

All of the non-volatile attribute values now are stored in the namespace `esp_matter_kvs` with the attribute key base64-encoded of bytes (`endpoint-id`+`cluster-id`+`attribute-id`). For the devices that store the non-volatile attribute values in the previous namespace with previous attribute-key, the values will be moved and the previous keys will be erased.

# 29-August-2023

- `ot_storage` partition is no longer required for thread devices as the mechanism for storing data related to the Thread network has been changed in the `openthread` component in ESP-IDF.

# 14-April-2023

#### *Changed how attribute data is stored in NVS*
By default primitive data types are stored as blob and that consumes more space in NVS.
Added a configuration option (`CONFIG_ESP_MATTER_NVS_USE_COMPACT_ATTR_STORAGE`) which uses
the primitive data type specific NVS APIs to store the attribute. This saves space in NVS partition.

Newer developments shall enable option `ESP_MATTER_NVS_USE_COMPACT_ATTR_STORAGE` to save on NVS space.
All the examples have this option enabled.

# 7-April-2023

- `tools/mfg_tool/mfg_tool.py` now uses `connectedhomeip/connectedhomeip/src/setup_payload/python/generate_setup_payload.py` instead of previously used compiled `chip-tool` binary executable which additionally depends on `python-stdnum` module.
- Reinstall dependencies to use `mfg_tool` by running the following commands -
```
source $IDF_PATH/export.sh
python3 -m pip install -r tools/mfg_tool/requirements.txt
```

# 15-March-2023

API Change

```
esp_err_t esp_matter::identification::init(uint16_t endpoint_id, uint8_t identify_type,
                                            uint8_t effect_identifier = EMBER_ZCL_IDENTIFY_EFFECT_IDENTIFIER_BLINK,
                                            uint8_t effect_variant = EMBER_ZCL_IDENTIFY_EFFECT_VARIANT_DEFAULT);
```

- Above API now accepts the parameters for initial identification `effect_identifier` and `effect_variant`.
- If not used, then default value will be used for initialization

```
typedef esp_err_t (*callback_t)(callback_type_t type, uint16_t endpoint_id, uint8_t effect_id, uint8_t effect_variant,
                                    void *priv_data);
```

- Added additional parameter `effect_variant` in identification callback.

```
esp_matter::start(event_callback_t callback, intptr_t callback_arg = static_cast<intptr_t>(NULL))
```

- This API now accepts a parameter to pass additional data to the event callback. By default, the data is set to NULL in the API.

# 14-June-2022

First Github release of ESP Matter

Features
--------
    - Aligns to Matter Test Event 9 and ESP-IDF v4.4.1.
    - ESP Matter Data Model - Intuitive, simple and dynamic.
    - Utility device types supported:
        Root Node
        OTA Requestor
        OTA Provider
        Bridged Node
    - Application device types supported:
        Lighting
          On/Off Light
          Dimmable Light
          Color Temperature Light
          Extended Color Light
        Smart Plugs/Outlets
          On/Off Plug-in Unit
          Dimmable Plug-in Unit
        Switches
          On/Off Light Switch
          Dimmer Switch
          Color Dimmer Switch
        Sensors
          Contact Sensor
          Occupancy Sensor
          Temperature Sensor
        Closure
          Door Lock
        HVAC
          Thermostat
          Fan
    - Mass manufacturing tool that generates manufacturing NVS partition image and onboarding codes.
    - RainMaker integration.
    - Zigbee to Matter and BLE Mesh to Matter Bridge.

# 25-Sep-2023

API Change

```
esp_err_t add(endpoint_t *endpoint, config_t *config)
```
- Above API returns the esp_err instead of endpoint.

Known Issues
------------
    - BLE memory is not freed if the device has already been commissioned on bootup.
    - Host-based chip-tool shows the following error during commissioning/cluster control, but the functionality works fine:
        CHIP Error 0x00000070: Unsolicited msg with originator bit clear.