# teschrenan/esp32-vl53l1x architecture

> Architecture diagram of the GitHub repository teschrenan/esp32-vl53l1x, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/teschrenan/esp32-vl53l1x
- Repository: https://github.com/teschrenan/esp32-vl53l1x

## Overview

##### Project type + purpose (what you’re diagramming)
This is an **ESP-IDF (ESP32) firmware project** organized as an ESP-IDF app with two reusable **components**:
- `components/i2c_bus`: an ESP32 I2C bus abstraction/driver layer
- `components/vl53l1`: a port/wrapper around ST’s **VL53L1X Time-of-Flight ranging sensor “Full API”** (the official ST C library) plus ESP32 “platform” glue
- `main`: the application entrypoint that configures I2C and performs distance reads via the VL53L1X driver

##### File-structure signals (how the repo is shaped architecturally)
Top-level:
- `CMakeLists.txt`, `sdkconfig`, and per-folder `CMakeLists.txt` / `component.mk` indicate **ESP-IDF build system**.
- `main/main.c` is the firmware app entrypoint.
- `components/...` are ESP-IDF components (separately buildable modules).

Component deep dive:
- `components/i2c_bus/`
- `i2c_drv.c`, `i2cdev_esp32.c` + headers in `include/`
- This is your **platform I2C implementation** layer and reusable I2C device helpers.
- `components/vl53l1/`
- `core/inc` + `core/src` is the **upstream ST “Full API”** (large, self-contained sensor logic).
- `include/vl53l1_platform*.h` is the **platform abstraction** ST expects (logging, user config, types, platform IO).
- `vl53l1x.c` is likely the **adapter/wrapper** exposing simpler calls and mapping ST’s platform hooks to your I2C component.
- `include/vl53l1x.h`, `include/zranger2.h` are public headers for app use.

- **3 code layers** (app → sensor component → i2c component)
- plus **2 “external dependencies”** (ESP-IDF + physical VL53L1X module)
- plus **“vendor library”** as a submodule inside `vl53l1`

##### README signals to reflect
README highlights:
- This is about **distance reading** from VL53L1X on ESP32.
- Configuration is I2C channel, frequency, SCL/SDA pins, pullups (`I2cDef I2CConfig`).
- Build path is `idf.py flash monitor` (so runtime is on-device, no backend).

- **I2C configuration** (port, pins, clock)
- **Data flow**: “Range measurement” request → I2C transactions → sensor → measurement result → app/logging.

##### I2C bus lines (SCL/SDA + pullups)

**Firmware / Software layers**
##### Application (`main/main.c`)
- config: `I2cDef I2CConfig` (I2C port, pins, 400kHz)
- tasks/loop calling ranging APIs (even if not shown in README, that’s typical)
##### VL53L1 component (`components/vl53l1/`)
- **Wrapper**: `vl53l1x.c` + public headers (`vl53l1x.h`, `zranger2.h`)
- **ST Full API core**: `core/src/*` + `core/inc/*`
- **Platform glue**: `include/vl53l1_platform*.h` (implements ST platform calls: read/write, delays, logging)
##### I2C bus component (`components/i2c_bus/`)
- bus/device abstraction: `i2c_drv.c`, `i2cdev_esp32.c`, headers `i2c_drv.h`, `i2cdev.h`
##### ESP-IDF I2C driver/HAL

**Build/Config (optional but good for principal-level completeness)**
##### ESP-IDF build system
- root `CMakeLists.txt`, component `CMakeLists.txt`, `sdkconfig`

##### (c) Architectural patterns to explicitly label
- **Layered architecture**: App → Driver wrapper → Vendor core → Platform abstraction → Bus driver → HAL → Hardware
- **Adapter/Port pattern**: `vl53l1_platform*` adapts ST’s generic API to ESP32 I2C and timing/logging.
- **Component-based modularity (ESP-IDF components)**: `i2c_bus` is reusable for other I2C sensors; `vl53l1` is reusable across apps.

- **ESP-IDF** (build + RTOS environment + I2C driver)
- **I2C** @ 400 kHz (from README example)
- **ST VL53L1X Full API (STSW-IMG007)** as a vendor library embedded in `components/vl53l1/core`

##### Vendor core (`core/src`, `core/inc`)
3. **Platform adaptation** (`vl53l1_platform*.h` + whatever implementation is used to satisfy those hooks)

Similarly, split `components/i2c_bus` into:
- **Generic I2C device API** (`i2cdev.h`)
- **ESP32-specific implementation** (`i2cdev_esp32.c`)
- **Bus driver** (`i2c_drv.*`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %%========================
    %% Layers (vertical stack)
    %%========================

    subgraph "Build & Configuration (ESP-IDF Project)"
        direction TB
        BuildSys["ESP-IDF Build System<br/>CMake + sdkconfig"]:::build
        BuildMain["main build glue<br/>(CMakeLists.txt + component.mk)"]:::build
        BuildI2C["i2c_bus build glue<br/>(CMakeLists.txt + component.mk)"]:::build
        BuildVL["vl53l1 build glue<br/>(CMakeLists.txt + component.mk)"]:::build

        BuildSys -->|"configures"| BuildMain
        BuildSys -->|"configures"| BuildI2C
        BuildSys -->|"configures"| BuildVL
    end

    subgraph "Firmware on ESP32"
        direction TB

        subgraph "Application Layer"
            direction TB
            App["App Entrypoint<br/>main/main.c<br/><br/>I2cDef config:<br/>- I2C port<br/>- SDA/SCL pins<br/>- 400 kHz<br/>- pullups"]:::app
        end

        subgraph "Sensor Component: components/vl53l1"
            direction TB

            VLRoot["VL53L1 Component (root)"]:::module

            subgraph "Public Driver API (Adapter)"
                direction TB
                VLWrap["vl53l1x wrapper<br/>simplified driver API"]:::driver
                VLHdr1["vl53l1x.h"]:::header
                VLHdr2["zranger2.h"]:::header
            end

            subgraph "Vendor Library (ST Full API)"
                direction TB
                STCore["ST VL53L1 Full API core<br/>core/inc + core/src"]:::vendor
                STApiHdr["vl53l1_api.h<br/>(core API surface)"]:::vendor
            end

            subgraph "Platform Glue (ST platform abstraction)"
                direction TB
                Plat["vl53l1_platform*.h<br/>read/write, delay, log, types"]:::platform
                PlatLog["platform_log"]:::platform
                PlatCfg["user_config + user_data + defines"]:::platform
                PlatTypes["vl53l1_types.h"]:::platform
            end

            VLRoot -->|"contains"| VLWrap
            VLRoot -->|"contains"| STCore
            VLRoot -->|"contains"| Plat

            VLWrap -->|"calls"| STCore
            STCore -->|"includes"| STApiHdr
            STCore -->|"uses_hooks"| Plat
            Plat -->|"references"| PlatLog
            Plat -->|"references"| PlatCfg
            Plat -->|"uses_types"| PlatTypes
        end

        subgraph "I2C Bus Component: components/i2c_bus"
            direction TB
            I2CRoot["I2C Bus Component (root)"]:::module

            subgraph "Generic I2C Device API"
                direction TB
                I2CDevHdr["i2cdev.h"]:::header
            end

            subgraph "ESP32-specific Implementation"
                direction TB
                I2CDevESP["i2cdev_esp32.c"]:::driver
            end

            subgraph "Bus Driver / Abstraction"
                direction TB
                I2CDrv["i2c_drv.c"]:::driver
                I2CDrvHdr["i2c_drv.h"]:::header
            end

            I2CRoot -->|"exports"| I2CDevHdr
            I2CRoot -->|"implements"| I2CDevESP
            I2CRoot -->|"implements"| I2CDrv
            I2CDrv -->|"declares"| I2CDrvHdr
        end

        subgraph "Framework / HAL (External)"
            direction TB
            IDFI2C["ESP-IDF I2C Master Driver / HAL"]:::external
            FreeRTOS["ESP-IDF Runtime (FreeRTOS)"]:::external
            FreeRTOS -->|"schedules"| App
        end

        %% Call flow / dependencies
        App -->|"calls_driver_API"| VLWrap
        App -.->|"provides_I2cDef_config"| I2CRoot

        Plat -->|"i2c_read_write"| I2CRoot
        I2CDevESP -->|"uses"| IDFI2C
        I2CDrv -->|"uses"| IDFI2C
    end

    subgraph "Hardware (Physical Layer)"
        direction TB
        ESP32["ESP32 SoC<br/>I2C peripheral"]:::hardware
        Bus["I2C Bus<br/>SCL/SDA + pullups"]:::bus
        Sensor["VL53L1X ToF Sensor<br/>(ST)"]:::hardware

        ESP32 -->|"drives"| Bus
        Bus -->|"I2C_transactions"| Sensor
        Sensor -->|"measurement_registers"| Bus
    end

    %% Firmware-to-hardware linkage
    IDFI2C -->|"controls_I2C_peripheral"| ESP32

    %% Data/result flow (annotative)
    App -.->|"range_result (distance)"| App

    %%========================
    %% Click events (mappings)
    %%========================
    click App "https://github.com/teschrenan/esp32-vl53l1x/blob/main/main/main.c"
    click BuildMain "https://github.com/teschrenan/esp32-vl53l1x/blob/main/main/CMakeLists.txt"
    click BuildMain "https://github.com/teschrenan/esp32-vl53l1x/blob/main/main/component.mk"

    click I2CRoot "https://github.com/teschrenan/esp32-vl53l1x/tree/main/components/i2c_bus/"
    click I2CDrv "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/i2c_bus/i2c_drv.c"
    click I2CDrvHdr "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/i2c_bus/include/i2c_drv.h"
    click I2CDevHdr "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/i2c_bus/include/i2cdev.h"
    click I2CDevESP "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/i2c_bus/i2cdev_esp32.c"
    click BuildI2C "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/i2c_bus/CMakeLists.txt"
    click BuildI2C "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/i2c_bus/component.mk"

    click VLRoot "https://github.com/teschrenan/esp32-vl53l1x/tree/main/components/vl53l1/"
    click VLWrap "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/vl53l1/vl53l1x.c"
    click VLHdr1 "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/vl53l1/include/vl53l1x.h"
    click VLHdr2 "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/vl53l1/include/zranger2.h"
    click STCore "https://github.com/teschrenan/esp32-vl53l1x/tree/main/components/vl53l1/core/inc/"
    click STCore "https://github.com/teschrenan/esp32-vl53l1x/tree/main/components/vl53l1/core/src/"
    click STApiHdr "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/vl53l1/core/inc/vl53l1_api.h"
    click Plat "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/vl53l1/include/vl53l1_platform.h"
    click PlatLog "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/vl53l1/include/vl53l1_platform_log.h"
    click PlatCfg "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/vl53l1/include/vl53l1_platform_user_config.h"
    click PlatCfg "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/vl53l1/include/vl53l1_platform_user_data.h"
    click PlatCfg "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/vl53l1/include/vl53l1_platform_user_defines.h"
    click PlatTypes "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/vl53l1/include/vl53l1_types.h"
    click BuildVL "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/vl53l1/CMakeLists.txt"
    click BuildVL "https://github.com/teschrenan/esp32-vl53l1x/blob/main/components/vl53l1/component.mk"

    click BuildSys "https://github.com/teschrenan/esp32-vl53l1x/blob/main/CMakeLists.txt"
    click BuildSys "https://github.com/teschrenan/esp32-vl53l1x/tree/main/sdkconfig"

    %%========================
    %% Styles (colors)
    %%========================
    classDef app fill:#1f77b4,stroke:#0b2d4d,color:#ffffff,stroke-width:1.5px
    classDef module fill:#2b6cb0,stroke:#163a5f,color:#ffffff,stroke-width:1.2px
    classDef driver fill:#2c7fb8,stroke:#114b6a,color:#ffffff,stroke-width:1.2px
    classDef platform fill:#3b82f6,stroke:#1e3a8a,color:#ffffff,stroke-width:1.2px
    classDef header fill:#60a5fa,stroke:#1e40af,color:#0b1b3a,stroke-width:1px
    classDef vendor fill:#f59e0b,stroke:#92400e,color:#1f1300,stroke-width:1.2px
    classDef external fill:#9ca3af,stroke:#374151,color:#111827,stroke-width:1.2px
    classDef hardware fill:#22c55e,stroke:#166534,color:#052e12,stroke-width:1.5px
    classDef bus fill:#a7f3d0,stroke:#065f46,color:#064e3b,stroke-width:1.2px
    classDef build fill:#e5e7eb,stroke:#6b7280,color:#111827,stroke-width:1.2px
```
