How espressif/esp-matter works
Project Type and Purpose
• Type: An embedded‐firmware SDK and framework for Matter on ESP32 series SoCs.
• Purpose: Provide a layered, modular C/C++ library (esp_matter) built on the open‐source Matter SDK (connectedhomeip), plus HAL drivers, tooling (CI, Docker), utilities (OTA, console, controller, Rainmaker), examples, and docs to accelerate Matter product development on ESP32.
Top-Level Architecture Layers
a. Application Layer (Examples / User Firmware)
• All the example apps under examples/** – e.g. light, door_lock, badge, controller, etc.
• Each example is an ESP-IDF project that pulls in esp-matter components.
b. SDK Components Layer
• esp_matter: core Matter abstractions (attributes, clusters, commands, endpoints, events, core APIs)
• esp_matter_bridge, esp_matter_console, esp_matter_controller, esp_matter_ota_provider, esp_matter_rainmaker
c. Underlying Matter Core
• connectedhomeip submodule (the upstream CSA Matter SDK code).
d. Hardware Abstraction Layer (device_hal)
• Drivers for buttons, LEDs, device board definitions.
e. Build & Configuration
• ESP-IDF (CMake + Kconfig) with idf_component.yml, CMakeLists.txt, Kconfig files
• generate-include-files.cmake, export.sh, install.sh
f. Tooling & CI
• GitHub/GitLab workflows, Jenkinsfiles, Dockerfiles under tools/, scripts (tools/ci/*.py), launchpad config, mfg_tool
Main Components and Their Relationships
• Examples → link against → esp_matter + HAL drivers + optional components → link against → connectedhomeip → runs on → ESP32 hardware
• Optional SDK modules (bridge, console, controller, OTA, Rainmaker) → depend on → esp_matter core
• HAL drivers → provide low-level GPIO, ADC, NVS abstractions → consumed by → esp_matter (for I/O and storage)
• Tools & CI → orchestrate → build pipelines (docker containers), static analysis, docs generation → target → the entire codebase
Key Architectural Patterns
• Layered/Modular: clear separation between core (esp_matter), optional extensions, hardware drivers, and application code
• Plugin via CMake & Kconfig: each component is an IDF component enabled/disabled via Kconfig
• Abstraction of Matter concepts (clusters, attributes) into C++/C modules
• Use of code generation (ZAP scripts) under components/esp_matter/zap_common → automates cluster definitions
• Toolchain as code: Docker, CI workflows, Python scripts for build/test