# espressif/esp-matter architecture

> Architecture diagram of the GitHub repository espressif/esp-matter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/espressif/esp-matter
- Repository: https://github.com/espressif/esp-matter

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application Layer
    subgraph "Application Layer"
        direction TB
        Examples["Example Applications<br/>(examples/)"]:::example
    end

    %% SDK Components Layer
    subgraph "SDK Components Layer"
        direction TB
        ESP_MATTER["esp_matter_core<br/>(components/esp_matter/)"]:::code
        subgraph "Optional Extensions"
            direction TB
            Bridge["esp_matter_bridge<br/>(components/esp_matter_bridge/)"]:::code
            Console["esp_matter_console<br/>(components/esp_matter_console/)"]:::code
            Controller["esp_matter_controller<br/>(components/esp_matter_controller/)"]:::code
            OTA["esp_matter_ota_provider<br/>(components/esp_matter_ota_provider/)"]:::code
            Rainmaker["esp_matter_rainmaker<br/>(components/esp_matter_rainmaker/)"]:::code
        end
    end

    %% Underlying Matter Core
    ConnectedHomeIP["connectedhomeip<br/>(connectedhomeip/connectedhomeip/)"]:::external

    %% Hardware Abstraction Layer
    HAL["device_hal<br/>(device_hal/)"]:::hal

    %% Build & Configuration
    subgraph "Build & Configuration"
        direction TB
        CMake["CMakeLists.txt"]:::tool
        KconfigFile["Kconfig"]:::tool
        ComponentYML["idf_component.yml"]:::tool
        GenIncludes["generate-include-files.cmake"]:::tool
        ExportSh["export.sh"]:::tool
        InstallSh["install.sh"]:::tool
    end

    %% Tooling & CI
    subgraph "Tooling & CI"
        direction TB
        CI["tools/ci/"]:::tool
        Docker["tools/docker/"]:::tool
        Jenkins["tools/jenkins/"]:::tool
        Launchpad["tools/launchpad/"]:::tool
        Mfg["tools/mfg_tool/"]:::tool
        GHWF[".github/workflows/"]:::tool
        GitlabCI[".gitlab-ci.yml"]:::tool
    end

    %% Hardware
    subgraph "Hardware"
        direction TB
        ESP32["ESP32 SoC<br/>Buttons, LEDs"]:::hardware
        NVS["NVS Storage"]:::storage
    end

    %% Dependencies (compile/link)
    Examples -->|"links against"| ESP_MATTER
    Examples -->|"uses HAL APIs"| HAL
    ESP_MATTER -->|"built on"| ConnectedHomeIP
    ESP_MATTER -->|"uses HAL"| HAL
    Bridge -->|"extends"| ESP_MATTER
    Console -->|"extends"| ESP_MATTER
    Controller -->|"extends"| ESP_MATTER
    OTA -->|"extends"| ESP_MATTER
    Rainmaker -->|"extends"| ESP_MATTER

    %% Toolchain dependencies
    CMake --> ESP_MATTER
    KconfigFile --> ESP_MATTER
    ComponentYML --> ESP_MATTER
    GenIncludes --> ESP_MATTER
    ExportSh --> ESP_MATTER
    InstallSh --> ESP_MATTER
    CI --> CMake
    CI --> Test[Tests]:::tool
    Docker --> CI
    Jenkins --> CI
    Launchpad --> CI
    Mfg --> CI
    GHWF --> CI
    GitlabCI --> CI

    %% Runtime data flow (dashed)
    ESP_MATTER -.->|"GPIO/ADC" | HAL
    HAL -.->|"controls"| ESP32
    ESP_MATTER -.->|"stores data"| NVS

    %% Styling
    classDef example fill:#D4BFFF,stroke:#5F0F5F,color:#000
    classDef code fill:#B3D9FF,stroke:#0F3F5F,color:#000
    classDef external fill:#B3D9FF,stroke:#0F3F5F,color:#000,dasharray: 5 5
    classDef hal fill:#C2F0C2,stroke:#0F5F0F,color:#000
    classDef tool fill:#FFD9B3,stroke:#5F3F0F,color:#000
    classDef hardware fill:#F0E68C,stroke:#8B8000,color:#000
    classDef storage fill:#FFF2CC,stroke:#A67C00,color:#000

    %% Click Events
    click Examples "https://github.com/espressif/esp-matter/tree/main/examples/"
    click ESP_MATTER "https://github.com/espressif/esp-matter/tree/main/components/esp_matter/"
    click Bridge "https://github.com/espressif/esp-matter/tree/main/components/esp_matter_bridge/"
    click Console "https://github.com/espressif/esp-matter/tree/main/components/esp_matter_console/"
    click Controller "https://github.com/espressif/esp-matter/tree/main/components/esp_matter_controller/"
    click OTA "https://github.com/espressif/esp-matter/tree/main/components/esp_matter_ota_provider/"
    click Rainmaker "https://github.com/espressif/esp-matter/tree/main/components/esp_matter_rainmaker/"
    click ConnectedHomeIP "https://github.com/espressif/esp-matter/tree/main/connectedhomeip/connectedhomeip/"
    click HAL "https://github.com/espressif/esp-matter/tree/main/device_hal/"
    click CMake "https://github.com/espressif/esp-matter/blob/main/CMakeLists.txt"
    click KconfigFile "https://github.com/espressif/esp-matter/tree/main/Kconfig"
    click ComponentYML "https://github.com/espressif/esp-matter/blob/main/idf_component.yml"
    click GenIncludes "https://github.com/espressif/esp-matter/blob/main/generate-include-files.cmake"
    click ExportSh "https://github.com/espressif/esp-matter/blob/main/export.sh"
    click InstallSh "https://github.com/espressif/esp-matter/blob/main/install.sh"
    click CI "https://github.com/espressif/esp-matter/tree/main/tools/ci/"
    click Docker "https://github.com/espressif/esp-matter/tree/main/tools/docker/"
    click Jenkins "https://github.com/espressif/esp-matter/tree/main/tools/jenkins/"
    click Launchpad "https://github.com/espressif/esp-matter/tree/main/tools/launchpad/"
    click Mfg "https://github.com/espressif/esp-matter/tree/main/tools/mfg_tool/"
    click GHWF "https://github.com/espressif/esp-matter/tree/main/.github/workflows/"
    click GitlabCI "https://github.com/espressif/esp-matter/blob/main/.gitlab-ci.yml"
```
