# pkepes/vl53l8cx-library architecture

> Architecture diagram of the GitHub repository pkepes/vl53l8cx-library, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pkepes/vl53l8cx-library
- Repository: https://github.com/pkepes/vl53l8cx-library

## Overview

This is an ESP-IDF adaptation of ST’s VL53L8CX Ultra Lite Driver, not an application or an Arduino library. The principal workflow is that an ESP32 application configures the sensor through the public API, starts ranging, and retrieves multizone measurements over I²C. Optional plugins provide cross-talk calibration, detection thresholds, and motion-indicator configuration. The README also documents examples for ranging modes, power modes, per-zone targets, and parameter access. Relationships reflect sampled calls; those additional example capabilities are represented at the API level because their implementations were not sampled.

Main entry points: [`src/vl53l8cx_api.c`](https://github.com/pkepes/vl53l8cx-library/blob/master/src/vl53l8cx_api.c) (Sensor API), [`src/vl53l8cx_plugin_xtalk.c`](https://github.com/pkepes/vl53l8cx-library/blob/master/src/vl53l8cx_plugin_xtalk.c) (Cross-talk calibration), [`src/platform.c`](https://github.com/pkepes/vl53l8cx-library/blob/master/src/platform.c) (I²C and GPIO), [`src/vl53l8cx_plugin_detection_thresholds.c`](https://github.com/pkepes/vl53l8cx-library/blob/master/src/vl53l8cx_plugin_detection_thresholds.c) (Detection thresholds)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Application API"]
  node_api["Sensor API<br/>[vl53l8cx_api.c]"]
  node_api_header["API and results<br/>[vl53l8cx_api.h]"]
end

subgraph group_extensions["Sensor Features"]
  node_xtalk["Cross-talk calibration"]
  node_xtalk_header["Cross-talk API"]
  node_thresholds["Detection thresholds"]
  node_threshold_header["Threshold API"]
  node_motion["Motion indicator"]
  node_motion_header["Motion API"]
end

subgraph group_transport["ESP32 Transport"]
  node_platform_header["Platform interface<br/>[platform.h]"]
  node_platform["I²C and GPIO<br/>[platform.c]"]
end

node_app(("ESP-IDF application"))
node_sensor{{"VL53L8CX sensor"}}

node_app -->|"configures and ranges"| node_api
node_api -->|"uses types"| node_api_header
node_app -->|"calibrates cross-talk"| node_xtalk
node_app -->|"sets thresholds"| node_thresholds
node_app -->|"configures motion"| node_motion
node_xtalk -->|"uses definitions"| node_xtalk_header
node_thresholds -->|"uses definitions"| node_threshold_header
node_motion -->|"uses definitions"| node_motion_header
node_xtalk -->|"calls configuration"| node_api
node_thresholds -->|"calls DCI"| node_api
node_motion -->|"writes DCI"| node_api
node_api -->|"reads and writes"| node_platform
node_platform -->|"implements interface"| node_platform_header
node_platform -->|"transfers I²C data"| node_sensor
node_xtalk -->|"transfers calibration data"| node_platform
node_api -->|"controls ranging"| node_sensor
node_sensor -->|"returns measurements"| node_api

click node_api "https://github.com/pkepes/vl53l8cx-library/blob/master/src/vl53l8cx_api.c"
click node_api_header "https://github.com/pkepes/vl53l8cx-library/blob/master/include/vl53l8cx_api.h"
click node_platform_header "https://github.com/pkepes/vl53l8cx-library/blob/master/include/platform.h"
click node_platform "https://github.com/pkepes/vl53l8cx-library/blob/master/src/platform.c"
click node_xtalk "https://github.com/pkepes/vl53l8cx-library/blob/master/src/vl53l8cx_plugin_xtalk.c"
click node_xtalk_header "https://github.com/pkepes/vl53l8cx-library/blob/master/include/vl53l8cx_plugin_xtalk.h"
click node_thresholds "https://github.com/pkepes/vl53l8cx-library/blob/master/src/vl53l8cx_plugin_detection_thresholds.c"
click node_threshold_header "https://github.com/pkepes/vl53l8cx-library/blob/master/include/vl53l8cx_plugin_detection_thresholds.h"
click node_motion "https://github.com/pkepes/vl53l8cx-library/blob/master/src/vl53l8cx_plugin_motion_indicator.c"
click node_motion_header "https://github.com/pkepes/vl53l8cx-library/blob/master/include/vl53l8cx_plugin_motion_indicator.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_api_header toneBlue
class node_xtalk,node_xtalk_header,node_thresholds,node_threshold_header,node_motion,node_motion_header toneAmber
class node_platform_header,node_platform toneMint
class node_app,node_sensor toneIndigo
```

## Components

### Application API

- [Sensor API](https://github.com/pkepes/vl53l8cx-library/blob/master/src/vl53l8cx_api.c): `src/vl53l8cx_api.c`
- [API and results](https://github.com/pkepes/vl53l8cx-library/blob/master/include/vl53l8cx_api.h): `include/vl53l8cx_api.h`

### Sensor Features

- [Cross-talk calibration](https://github.com/pkepes/vl53l8cx-library/blob/master/src/vl53l8cx_plugin_xtalk.c): `src/vl53l8cx_plugin_xtalk.c`
- [Cross-talk API](https://github.com/pkepes/vl53l8cx-library/blob/master/include/vl53l8cx_plugin_xtalk.h): `include/vl53l8cx_plugin_xtalk.h`
- [Detection thresholds](https://github.com/pkepes/vl53l8cx-library/blob/master/src/vl53l8cx_plugin_detection_thresholds.c): `src/vl53l8cx_plugin_detection_thresholds.c`
- [Threshold API](https://github.com/pkepes/vl53l8cx-library/blob/master/include/vl53l8cx_plugin_detection_thresholds.h): `include/vl53l8cx_plugin_detection_thresholds.h`
- [Motion indicator](https://github.com/pkepes/vl53l8cx-library/blob/master/src/vl53l8cx_plugin_motion_indicator.c): `src/vl53l8cx_plugin_motion_indicator.c`
- [Motion API](https://github.com/pkepes/vl53l8cx-library/blob/master/include/vl53l8cx_plugin_motion_indicator.h): `include/vl53l8cx_plugin_motion_indicator.h`

### ESP32 Transport

- [Platform interface](https://github.com/pkepes/vl53l8cx-library/blob/master/include/platform.h): `include/platform.h`
- [I²C and GPIO](https://github.com/pkepes/vl53l8cx-library/blob/master/src/platform.c): `src/platform.c`

### Other components

- **ESP-IDF application**
- **VL53L8CX sensor**

## Connections

- ESP-IDF application → Sensor API: configures and ranges
- Sensor API → API and results: uses types
- ESP-IDF application → Cross-talk calibration: calibrates cross-talk
- ESP-IDF application → Detection thresholds: sets thresholds
- ESP-IDF application → Motion indicator: configures motion
- Cross-talk calibration → Cross-talk API: uses definitions
- Detection thresholds → Threshold API: uses definitions
- Motion indicator → Motion API: uses definitions
- Cross-talk calibration → Sensor API: calls configuration
- Detection thresholds → Sensor API: calls DCI
- Motion indicator → Sensor API: writes DCI
- Sensor API → I²C and GPIO: reads and writes
- I²C and GPIO → Platform interface: implements interface
- I²C and GPIO → VL53L8CX sensor: transfers I²C data
- Cross-talk calibration → I²C and GPIO: transfers calibration data
- Sensor API → VL53L8CX sensor: controls ranging
- VL53L8CX sensor → Sensor API: returns measurements