Espressif's SDK for Matter Choose target... Choose version... 1. Introduction 2. Developing with the SDK 3. Matter Controller 4. Matter Certification 5. Production Considerations 6. Security Considerations 7. RAM and Flash Optimizations 8. API Reference 9. Integration with esp-insights 10. Application User Guide 11. Copyrights and Licenses Appendix FAQs Espressif's SDK for Matter Programming Guide Edit on GitHub Programming Guide Matter is a unified IP-based connectivity protocol that is designed to connect and build open, reliable and secure IoT ecosystems. This new technology and connectivity standard enables communication among a wide range of smart devices. Matter supports IP connectivity over Wi-Fi, Thread and Ethernet. Espressif’s SDK for Matter is the official Matter development framework for Espressif’s ESP32 series SoCs. We have put together a series of blog posts that introduces various aspects of Matter. We recommend that you go through this Espressif Matter Blog. Table of Contents 1. Introduction 1.1. Espressif Matter Solutions 1.2. Try it yourself 1.3. 3. Try Data Model Validator 2. Developing with the SDK 2.1. ESP-IDF Setup 2.2. ESP Matter Setup 2.3. Commissioning and Control 2.4. Device console 2.5. Developing your Product 2.6. Factory Data Providers 2.7. Using esp_secure_cert partition 2.8. Matter OTA 2.9. Mode Select 2.10. Custom Cluster 3. Matter Controller 3.1. Controller features 3.2. Commissioner features 3.3. Production Considerations 4. Matter Certification 4.1. Firmware Development 4.2. Preparation of Files Required for Certification Testing 4.3. Testing Environment Setup and Testing Methods 4.4. Submitting Certification Application Online 4.5. Filling in Certified Product Information on DCL Website 4.6. Other notes for some certification test cases 4.7. FW/SDK configuration notes 5. Production Considerations 5.1. Prerequisites 5.2. Over-the-Air (OTA) Updates 5.3. Manufacturing 6. Security Considerations 6.1. Overview 6.2. Platform Security 6.3. Product Security 6.4. More Security Considerations 6.5. Security Policy 7. RAM and Flash Optimizations 7.1. Overview 7.2. Configurations 7.3. References for further optimizations 8. API Reference 8.1. Data Model 8.2. Generated Data Model 8.3. Endpoint/Device Type 8.4. Cluster 8.5. Attribute 8.6. Command 8.7. Core Low Level 8.8. Event 8.9. Client 9. Integration with esp-insights 10. Application User Guide 10.1. Delegate Implementation 11. Copyrights and Licenses 11.1. Software Copyrights Appendix FAQs Next © Copyright 2022 - 2026, Espressif Systems (Shanghai) Co., Ltd. Built with Sphinx using a theme based on Read the Docs Sphinx Theme. Download PDF Espressif's SDK for Matter Choose target... Choose version... 1. Introduction 2. Developing with the SDK 3. Matter Controller 4. Matter Certification 5. Production Considerations 6. Security Considerations 7. RAM and Flash Optimizations 7.1. Overview 7.2. Configurations 7.2.1. Test Environment setup 7.2.2. Default Configuration 7.2.3. Disable the chip-shell 7.2.4. Adjust the dynamic endpoint count 7.2.5. Use the newlib nano formatting 7.2.6. BLE Optimizations 7.2.7. Configuring logging event buffer 7.2.8. Relocate certain code from IRAM to flash memory 7.2.8.1. Reduce BLE IRAM usage 7.2.8.2. Place FreeRTOS functions into Flash 7.2.8.3. Place non-ISR ringbuf functions into flash 7.2.8.4. Use esp_flash implementation in ROM 7.2.8.5. Force the entire heap component to be placed in flash memory 7.2.9. Reduce Task Stack Size 7.2.10. Excluding Unused Matter Clusters 7.3. References for further optimizations 8. API Reference 9. Integration with esp-insights 10. Application User Guide 11. Copyrights and Licenses Appendix FAQs Espressif's SDK for Matter 7. Configuration options to optimize RAM and Flash Edit on GitHub 7. Configuration options to optimize RAM and Flash 7.1. Overview There are several configuration options available to optimize Flash and RAM storage. The following list highlights key options that significantly increase the free DRAM, heap, and reduce the flash footprint. For more optimizations, we’ve also listed the reference links to esp-idf’s optimization guide. 7.2. Configurations 7.2.1. Test Environment setup All numbers mentioned below are collected in the following environment: esp-idf v5.4.1 esp-matter 6a77422 Example: light SoC: ESP32-C3 Note These numbers may vary slightly in a different environment. All numbers are in bytes As we are using BLE only for commissioning, BLE memory is freed post commissioning, hence there is an increase in the free heap post commissioning. (CONFIG_USE_BLE_ONLY_FOR_COMMISSIONING=y) After building an example, some DRAM will be utilized, and the remaining DRAM will be allocated as heap. Therefore, a direct increase in the free DRAM will reflect as an increase in free heap. 7.2.2. Default Configuration We have used the default light example here, and below listed are the static and dynamic sizes. Static memory stats Size Decreased by Used D/IRAM 195080 – Used Flash 1476960 – Dynamic memory stats Free Heap Increased by On Bootup 35976 – Post Commissioning 101580 – 7.2.3. Disable the chip-shell Console shell is helpful when developing/debugging the application, but may not be necessary in production. Disabling the shell can save space. Disable the below configuration option. CONFIG_ENABLE_CHIP_SHELL=n Static memory stats Size Decreased by Used D/IRAM 192892 2188 Used Flash 1410424 66536 Dynamic memory stats Free Heap Increased by On Bootup 46476 10500 Post Commissioning 112340 10760 7.2.4. Adjust the dynamic endpoint count The default dynamic endpoint count and default device type count is 16, which may be excessive for a normal application creating only 2 endpoints. eg: light, only has two endpoints, one for root endpoint and one for actual light. Adjusting this to a lower value, corresponding to the actual number of endpoints the application will create, can save DRAM. Here, we have set the dynamic endpoint count and device type count to 2. Increase in the DRAM per endpoint/count is ~550 bytes. CONFIG_ESP_MATTER_MAX_DYNAMIC_ENDPOINT_COUNT=2 CONFIG_ESP_MATTER_MAX_DEVICE_TYPE_COUNT=2 Static memory stats Size Decreased by Used D/IRAM 188452 6628 Used Flash 1476850 110 Dynamic memory stats Free Heap Increased by On Bootup 41932 5956 Post Commissioning 107984 6404 7.2.5. Use the newlib nano formatting This optimization saves approximately 25-50K of flash, depending on the target. In our case, it results in a flash reduction of 47 KB. Additionally, it lowers the high watermark of task stack for functions that call printf() or other string formatting functions. Fore more details please take a look at esp-idf’s newlib nano formatting guide. CONFIG_NEWLIB_NANO_FORMAT=y Static memory stats Size Decreased by Used D/IRAM 195080 0 Used Flash 1429916 47044 Dynamic memory stats Free Heap Increased by On Bootup 38404 2428 Post Commissioning 103500 1920 7.2.6. BLE Optimizations Since most devices will primarily operate as BLE peripherals and typically won’t need more than one connection (especially if it’s just a Matter app), we can optimize by reducing the maximum allowed connections, thereby saving DRAM. Additionally, given the peripheral nature of these devices, we can disable the central and observer roles, for further optimization. In current implementation, BLE is disabled once commissioning succeeds, so these optimizations do not contribute to free heap post-commissioning. Below are the configuration options that can be set to achieve these optimizations. CONFIG_NIMBLE_MAX_CONNECTIONS=1 CONFIG_BTDM_CTRL_BLE_MAX_CONN=1 CONFIG_BT_NIMBLE_MAX_CONNECTIONS=1 CONFIG_BT_NIMBLE_ROLE_CENTRAL=n CONFIG_BT_NIMBLE_ROLE_OBSERVER=n CONFIG_BT_NIMBLE_MAX_BONDS=2 CONFIG_BT_NIMBLE_MAX_CCCDS=2 CONFIG_BT_NIMBLE_SECURITY_ENABLE=n CONFIG_BT_NIMBLE_50_FEATURE_SUPPORT=n CONFIG_BT_NIMBLE_WHITELIST_SIZE=1 CONFIG_BT_NIMBLE_GATT_MAX_PROCS=1 CONFIG_BT_NIMBLE_MSYS_1_BLOCK_COUNT=10 CONFIG_BT_NIMBLE_MSYS_1_BLOCK_SIZE=100 CONFIG_BT_NIMBLE_MSYS_2_BLOCK_COUNT=4 CONFIG_BT_NIMBLE_MSYS_2_BLOCK_SIZE=320 CONFIG_BT_NIMBLE_ACL_BUF_COUNT=5 CONFIG_BT_NIMBLE_HCI_EVT_HI_BUF_COUNT=5 CONFIG_BT_NIMBLE_HCI_EVT_LO_BUF_COUNT=3 CONFIG_BT_NIMBLE_ENABLE_CONN_REATTEMPT=n Static memory stats Size Decreased by Used D/IRAM 192920 2160 Used Flash 1454332 22628 Dynamic memory stats Free Heap Increased by On Bootup 55048 19072 Post Commissioning 101176 -404 7.2.7. Configuring logging event buffer Matter events serve as a historical record, stored in chronological order in the logging event buffer. By reducing the buffer size we can potentially save the DRAM. However, it’s important to note that this reduction could lead to the omission of events. For instance, reducing the critical log buffer from 4K to 256 bytes could save 3K+ DRAM, but it comes with the trade-off of potentially missing critical events. CONFIG_EVENT_LOGGING_CRIT_BUFFER_SIZE=256 CONFIG_EVENT_LOGGING_INFO_BUFFER_SIZE=256 CONFIG_EVENT_LOGGING_DEBUG_BUFFER_SIZE=256 CONFIG_MAX_EVENT_QUEUE_SIZE=20 Reduce ESP system event queue size and event task stack size can increase free heap size. CONFIG_ESP_SYSTEM_EVENT_QUEUE_SIZE=16 CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE=2048 CONFIG_MAX_EVENT_QUEUE_SIZE=20 Reduce the chip device event queue size can reduce IRAM size usage, lead to free heap increase. CONFIG_MAX_EVENT_QUEUE_SIZE=20 Static memory stats Size Decreased by Used D/IRAM 189704 5376 Used Flash 1477100 -140 Dynamic memory stats Free Heap Increased by On Bootup 42504 6528 Post Commissioning 108184 6604 7.2.8. Relocate certain code from IRAM to flash memory Relocating certain code from IRAM to flash can reduce IRAM usage, so increase available heap size. However, this may increase execution time. Note The options in this section may impact performance. Please perform thorough testing before using them in production. 7.2.8.1. Reduce BLE IRAM usage Move most IRAM into flash. This will increase the usage of flash and reduce ble performance. Because the code is moved