# espressif/esp-mdf architecture

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

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

## Overview

##### Project Type and Purpose
- This is an embedded framework (SDK) for ESP-WIFI-MESH development on the ESP32 chip. It provides:
- Utils (“utils layer”): common services & 3rd-party libs
- Functional Components (“components layer”): mesh configuration, upgrade, debug, LAN control
- It sits on top of Espressif’s IDF (ESP-IDF) and talks to Wi-Fi/ESP-NOW stacks in hardware.

##### File-Structure Analysis
- Top-level:
- components/ — each subfolder is a mesh-feature module or 3rd-party lib
- examples/ — sample projects grouped by use case
- tools/ — build, formatting, CI scripts
- Under components/:
a. mcommon, mconfig, mdebug, mespnow, mlink, mupgrade, mwifi — core MESH utilities & mesh-specific protocols
b. third_party/ — miniz (compression), aliyun_sdk (cloud connectivity)
- Build files: CMakeLists.txt, Kconfig, component.mk — indicating IDF-style component registration.

##### Key README Insights
- “Utils” subdivided into Third-party (drivers, miniz, Aliyun), Transmission (Mwifi, Mespnow), Mcommon (event loop, error check, memory, info store)
- “Components” include Mconfig, Mupgrade, Mdebug, Mlink
- “Examples” layer uses Components to implement full mesh solutions, plus cloud platform demos (Aliyun, AWS)

Layer 1 (bottom): ESP-IDF & Hardware
- ESP-IDF Wi-Fi & ESP-NOW stacks → ESP32 chip (radio, CPU)
Layer 2 (middle): ESP-MDF Core
- Utils
– ThirdParty: Miniz, AliyunSDK
– Transmission: Mwifi, Mespnow
– Mcommon: event loop, error handling, mem, flash store
- Components
– Mconfig ← uses Mcommon, Mwifi/Mespnow
– Mupgrade ← uses Mcommon, Mwifi
– Mdebug ← uses Mcommon, Mwifi/Mespnow
– Mlink ← uses Mcommon, Mwifi
Layer 3 (top): Applications/Examples
- Function Demos (mcommon, mconfig, mdebug, mupgrade, mwifi)
- Wireless Debug tool
- Development Kits: Light, Sense, Button
- Cloud Examples: Aliyun Linkkit, AWS
- Get-Started template
- Data ﬂows:
- Application calls Components API → Components orchestrate mesh tasks via Utils → Utils call IDF & hardware
- Mwifi/Mespnow handle packet fragmentation, compression, retransmission over the Wi-Fi/ESP-NOW stacks
- 3rd-party libs invoked by both Utils (Miniz for compression) and Components (AliyunSDK for cloud connectivity)

##### Architectural Patterns & Principles
- Layered Architecture: clear separation between hardware/IDF, core services (Utils), feature modules (Components), and top-level apps.
- Component-based: each mesh service (mconfig, mupgrade, etc.) encapsulated in its own IDF component folder.
- Plug-and-play extensibility: new 3rd-party modules go under components/third_party, new mesh functions added as additional components.
- Kconfig/CMake integration: each subcomponent registers itself with ESP-IDF build and configuration system.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: ESP-IDF & Hardware
    subgraph "Layer 1: ESP-IDF & Hardware"
        direction TB
        Esp32["ESP32 Hardware\n(Radio, CPU)"]:::hardware
        EspIdf["ESP-IDF Wi-Fi & ESP-NOW\nstacks"]:::hardware
    end
    Esp32 -->|"provides HW for"| EspIdf

    %% Layer 2A: Utils
    subgraph "Layer 2: Utils (ESP-MDF Core)"
        direction TB
        subgraph "Third-Party Libraries" 
            direction TB
            Miniz["Miniz"]:::thirdparty
            AliyunSDK["Aliyun SDK"]:::thirdparty
        end
        subgraph "Transmission"
            direction TB
            Mwifi["components/mwifi"]:::utils
            Mespnow["components/mespnow"]:::utils
        end
        Mcommon["components/mcommon\n(event loop, error handling,\nmemory, info store)"]:::utils
    end
    EspIdf -->|"calls Wi-Fi APIs"| Mwifi
    EspIdf -->|"calls ESP-NOW APIs"| Mespnow
    Mwifi -->|"uses compression"| Miniz
    Mespnow -->|"depends on"| Mcommon
    Mwifi -->|"depends on"| Mcommon
    Mcommon -->|"invokes cloud"| AliyunSDK

    %% Layer 2B: Components
    subgraph "Layer 2: Components"
        direction TB
        Mconfig["components/mconfig"]:::component
        Mupgrade["components/mupgrade"]:::component
        Mdebug["components/mdebug"]:::component
        Mlink["components/mlink"]:::component
    end
    Mcommon -->|"used by"| Mconfig
    Mcommon -->|"used by"| Mupgrade
    Mcommon -->|"used by"| Mdebug
    Mcommon -->|"used by"| Mlink
    Mwifi -->|"transport for"| Mconfig
    Mespnow -->|"transport for"| Mconfig
    Mwifi -->|"transport for"| Mupgrade
    Mwifi -->|"transport for"| Mdebug
    Mespnow -->|"transport for"| Mdebug
    Mwifi -->|"transport for"| Mlink

    %% Layer 3: Applications/Examples
    subgraph "Layer 3: Examples (Applications)"
        direction TB
        FuncDemo["examples/function_demo"]:::example
        WirelessDebug["examples/wireless_debug"]:::example
        DevKit["examples/development_kit"]:::example
        AliyunLink["examples/aliyun_linkkit"]:::example
        GetStarted["examples/get-started"]:::example
    end
    FuncDemo -->|uses| Mcommon
    FuncDemo -->|uses| Mconfig
    FuncDemo -->|uses| Mdebug
    FuncDemo -->|uses| Mupgrade
    FuncDemo -->|uses| Mwifi

    WirelessDebug -->|uses| Mdebug
    DevKit -->|uses| Mlink
    DevKit -->|uses| Mwifi
    DevKit -->|uses| Mcommon

    AliyunLink -->|uses| AliyunSDK
    AliyunLink -->|uses| Mlink

    GetStarted -->|uses| Mcommon
    GetStarted -->|uses| Mconfig

    %% Click Events
    click Miniz "https://github.com/espressif/esp-mdf/tree/master/components/third_party/miniz"
    click AliyunSDK "https://github.com/espressif/esp-mdf/tree/master/components/third_party/aliyun_sdk"
    click Mcommon "https://github.com/espressif/esp-mdf/tree/master/components/mcommon"
    click Mwifi "https://github.com/espressif/esp-mdf/tree/master/components/mwifi"
    click Mespnow "https://github.com/espressif/esp-mdf/tree/master/components/mespnow"
    click Mconfig "https://github.com/espressif/esp-mdf/tree/master/components/mconfig"
    click Mupgrade "https://github.com/espressif/esp-mdf/tree/master/components/mupgrade"
    click Mdebug "https://github.com/espressif/esp-mdf/tree/master/components/mdebug"
    click Mlink "https://github.com/espressif/esp-mdf/tree/master/components/mlink"
    click AliyunLink "https://github.com/espressif/esp-mdf/tree/master/examples/aliyun_linkkit"
    click GetStarted "https://github.com/espressif/esp-mdf/tree/master/examples/get-started"
    click WirelessDebug "https://github.com/espressif/esp-mdf/tree/master/examples/wireless_debug"
    click DevKit "https://github.com/espressif/esp-mdf/tree/master/examples/development_kit"
    click FuncDemo "https://github.com/espressif/esp-mdf/tree/master/examples/function_demo"

    %% Styles
    classDef hardware fill:#cccccc,stroke:#333,stroke-width:1px
    classDef utils fill:#cce5ff,stroke:#005cbf,stroke-width:1px
    classDef thirdparty fill:#ffddcc,stroke:#ff6600,stroke-width:1px
    classDef component fill:#d4edda,stroke:#28a745,stroke-width:1px
    classDef example fill:#fff3cd,stroke:#d39e00,stroke-width:1px
```
