How teschrenan/esp32-vl53l1x works
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.*)