# VL53L8CH 多区域多目标 ToF 距离传感器模块资料

## 1. 商品信息

- **SKU**: VL53L8
- **淘宝链接**: 待补充（尚未上架，链接确定后回填）
- **产品名**: VL53L8CH 多区域多目标 ToF 距离传感器模块
- **是否建议做网页**: 是

---

## 1.1 实拍图片

### 模块图

本地文件：`VL53L8\VL53L8.jpg`（正式上架前请补充正面/背面实拍图，参照 VL53L7 的双图格式）

---

## 1.2 测试实况视频

ESP32（2.8寸黄屏测试板）+ VL53L8CH 上电测试，8×8 多目标实时演示（含 LCD 热力图 + 电脑桌面 3D 点云仪表盘双屏对照）。

> 📹 本地文件：`VL53L8\VL53L8资料做B站和 网页\QQ20260711-200935.mp4`
>
> 视频内容：ESP32-2432S028 (2.8寸黄屏) + VL53L8CH 模块，串口输出 JSON 数据，LCD 实时画 8×8 热力图（含多目标角标），电脑端 PyQt6 桌面仪表盘同步显示 3D 悬浮点云——同一个格子如果测到近处遮挡物+远处背景两层目标，点云里能看到两个点叠在一起，这是 VL53L8CH 相对上一代传感器最大的卖点。

---

## 2. 买家测试前需要准备

### 硬件

| 物品 | 说明 |
|------|------|
| 单片机开发板 | ESP32（**强烈推荐**，本资料的示例代码和实测都基于 ESP32） |
| 杜邦线 | 公对母 × 4 根 |
| USB 数据线 | 与开发板匹配的供电+下载线 |
| VL53L8 模块 | 本商品 |
| 目标物体 | 白墙、纸板、手掌等均可；想看多目标效果可以用手在模块前边缘晃动 |

### 软件

| 软件 | 说明 |
|------|------|
| Arduino IDE | [arduino.cc](https://www.arduino.cc/en/software) 下载，版本 ≥ 1.8，装好 ESP32 开发板支持（步骤同 VL53L7 资料第 5.2 节） |
| VL53LMZ ULD API 驱动源码 | **没有现成的 Arduino 库管理器可搜索安装**（这点和 VL53L7CX 不一样）。需要把驱动源码文件和 .ino 放进同一个 sketch 文件夹，Arduino IDE 会自动一起编译。驱动源码来源见第 6.1 节 |
| 串口监视器 | Arduino IDE 自带，波特率 115200 |
| （可选）Python 桌面仪表盘 | 本项目自带 `VL53L8\软件与测试工具\Python仪表盘\vl53l8_dashboard.py`，PyQt6 + pyqtgraph 做的 3D 多目标点云可视化，比串口监视器直观得多 |

### 供电要求

- VL53L8CH 芯片本身需要 3 路电源（AVDD 3.3V / CORE_1V8 1.8V / IOVDD 1.2V或1.8V），但**买到的是集成好的模块**，模块板载稳压电路，对外通常只暴露一个 VCC（3.3V）
- 测距时电流与 VL53L7CX 量级相近（约 100~150 mA 峰值），确保开发板 3.3V 输出能力足够
- I²C 总线速率最高支持 1 MHz（实测用 400kHz 更稳）

---

## 3. 模块基础说明

### 3.1 工作原理

VL53L8CH 是 ST（意法半导体）FlightSense™ 系列的 **AI 使能型多区域 ToF（Time-of-Flight）距离传感器**，官方定位是"Artificial intelligence enabler"。

- 发射 940nm 不可见红外激光（Class 1 人眼安全），新一代 VCSEL + 双超表面透镜
- SPAD 阵列接收反射光，计算光子飞行时间 → 距离
- 一次测量最多输出 **64 个区域（8×8）**的数据
- **每个区域最多能同时测到 4 个目标**（近处遮挡物 + 远处背景可以分开测出来，不是简单地"选一个"）——这是它和 VL53L5CX/VL53L7CX（每区域只有 1 个距离值）最本质的区别
- 额外提供 **CNH（Compact Normalized Histogram，紧凑归一化直方图）**原始数据输出：每个 bin 的信号计数，最多 128 bin 可配置，专门给 AI/机器学习应用用来做手势识别、材质识别等（本项目桌面仪表盘暂未用到这个高级功能，只用了标准的多目标测距输出）

### 3.2 VL53L8CH 与 VL53L7CX / VL53L5CX 差异

| 参数 | VL53L8CH | VL53L7CX | VL53L5CX |
|------|----------|----------|----------|
| **每区域目标数** | **最多 4 个**（多目标） | 1 个 | 1 个 |
| **视场角（FoV）** | 45°×45° 方形，对角 65° | 60°×60° 方形，对角 90° | 45°×45° 方形，对角 65° |
| **最远测距** | 400 cm | ~350 cm | ~400 cm |
| **采样率** | 最高 60 Hz | 最高 60 Hz（4×4 时） | 最高 60 Hz（4×4 时） |
| **AI 直方图输出(CNH)** | ✅ 有 | ❌ 无 | ❌ 无 |
| **I²C 速率** | 最高 1 MHz | 通常 400kHz 使用 | 通常 400kHz 使用 |
| **封装尺寸** | 6.4 × 3.0 × 1.75 mm | 6.4 × 3.0 mm（引脚兼容） | 6.4 × 3.0 mm |
| **接口** | I²C（默认地址 0x52）或 SPI | I²C（默认地址 0x52） | I²C（默认地址 0x52） |
| **驱动** | 和 VL53L7CH 共用同一套 VL53LMZ ULD API；**和 VL53L7CX/VL53L5CX 的驱动源码也是逐字节相同的文件**，区别只在 `platform.h` 里 `VL53LMZ_NB_TARGET_PER_ZONE` 这个宏（1=单目标，4=多目标） |

> ⚠️ **容易搞错的点**：不要以为"L8 比 L7 数字大就是全面升级"——VL53L8CH 的视场角其实和窄视角的 VL53L5CX 一样（45°），比 VL53L7CX 的 60° 更窄。VL53L8CH 的核心卖点是**多目标 + AI 直方图**，不是"看得更广"。选型时如果需要广角覆盖，VL53L7CX 可能反而更合适；如果需要透过遮挡看到背景、或做 AI 手势/材质识别，选 VL53L8CH。

### 3.3 关键概念

- **Zone（区域）**: 8×8=64 个独立测距区，每区最多返回 4 个目标（近→远排列，可配置成"最近优先"或"信号最强优先"）
- **nb_target_detected**: 每个 zone 实际测到的目标数（0~4）
- **Target status（状态码）**: 每个目标槽位的数据有效性标记，**不可忽略**
- **Reflectance（反射率）**: 每个目标的反射率估计值（0~100%），可以当作"置信度"参考——反射率很低的目标通常是弱回波/幽灵目标
- **连续模式 vs 自主模式**: 连续模式始终以最高功率测距；自主模式可设积分时间，功耗更低

### 3.4 状态码速查

| 状态码 | 含义 | 是否有效 |
|--------|------|----------|
| 5 | 测距完成（最高置信度） | ✅ 有效 |
| 6 | 测距完成（中等置信度） | ✅ 有效 |
| 9 | 测距完成（有干扰目标，合脉冲） | ✅ 有效（精度略降） |
| 其他非 255 | 测到了但置信度较低 | ⚠️ 实测发现：多目标模式下，同一 zone 里较弱的那个目标（通常反射率也很低）经常是这类状态码，官方文档说"只有5/6/9算OK"，但既然 `nb_target_detected` 已经把它算进去了，建议照样显示出来，用反射率去体现"这个目标不太可信"，而不是直接丢弃——不然多目标最想展示的"边缘还有一层"效果就没了 |
| 255 | 空槽（这个 zone 本来就没这么多目标） | ❌ 无效 |

> 实测现象：**几乎每个 zone 都会测到一个很近（几十毫米）、反射率很低（0~2%）的目标**，这不是模块坏了，是盖板玻璃的反射（cover-glass crosstalk），单目标模式下这类回波通常被内部滤掉看不见，开了多目标之后才会暴露出来。ST 官方有专门的盖板玻璃指南（AN5939）和串扰标定流程，对显示效果有更高要求时可以做标定去掉这个近场幽灵点。

---

## 4. 接线说明

### 4.1 模块引脚定义

典型 VL53L8CH 模块（breakout board）引脚：

| 模块引脚 | 功能 | 说明 |
|----------|------|------|
| **VCC / VDD** | 电源正 | 3.3V |
| **GND** | 电源地 | 接开发板 GND |
| **SDA** | I²C 数据线 | 需上拉电阻（通常模块已板载） |
| **SCL** | I²C 时钟线 | 需上拉电阻（通常模块已板载） |
| **INT** | 中断输出（可选） | 传感器数据就绪时拉低，可不用接，用轮询方式即可 |
| **LPn** | 低功耗/使能（可选） | 拉低=禁用I²C，悬空或拉高=正常工作；单模块场景可不用接 |

> **模块最简接法（3.3V 系统）: 只需接 VCC、GND、SDA、SCL 四根线即可工作。**

### 4.2 ESP32 接线（推荐）

ESP32 原生 3.3V，无需电平转换，默认 I²C 接口稳定可靠。

```
VL53L8 模块        ESP32
==========         ==========
VCC (3.3V)   →     3V3
GND          →     GND
SDA          →     GPIO21
SCL          →     GPIO22
INT          →     (可不接)
LPn          →     (可不接，或接 GPIO19)
```

> 本项目实测用的是 ESP32-2432S028（带 2.8 寸屏的测试板），该板子把传感器接口引到 CN1 排针（GND-IO22(SCL)-IO27(SDA)-3V3），实际固件里对应 `I2C_SDA=27, I2C_SCL=22`——如果你用的是不带屏幕的普通 ESP32 开发板，用上面 GPIO21/22 这组更通用的接法即可，代码里改一下 `Wire.begin()` 的引脚号就行。

### 4.3 树莓派 / Pico

I²C 均可直连（3.3V 电平），接线方式与 VL53L7CX 相同：

- 树莓派：SDA→GPIO2 (Pin3)，SCL→GPIO3 (Pin5)，3.3V→Pin1
- Pico：SDA→GPIO0/4/8 等（可自定义），SCL→GPIO1/5/9 等

> 具体引脚和驱动安装步骤以树莓派/Pico 官方文档为准，此处不作展开。

---

## 5. Arduino IDE 环境搭建

### 5.1 安装 Arduino IDE + ESP32 开发板支持

步骤与 VL53L7 完全一样，参照 `VL53L7_产品技术资料.md` 第 5.1~5.2 节：装 Arduino IDE → 附加开发板管理器网址加 ESP32 → 开发板管理器搜索安装 `esp32 by Espressif Systems`。

### 5.2 驱动源码（没有现成的库管理器安装方式）

⚠️ 和 VL53L7CX 不同，VL53L8CH **目前没有找到可以在 Arduino 库管理器直接搜索安装的官方库**。实测验证过的可行方法：

1. 从 ST 官方软件包 **STSW-IMG043**（ULD API for VL53L8CH）获取驱动源码，或者直接用本项目已经验证过的一份（见第 6.1 节路径）
2. 把驱动源码文件（`vl53lmz_api.c/h`、`platform.c/h` 等一整套）和你自己写的 `.ino` 放进**同一个 sketch 文件夹**
3. Arduino IDE 打开 `.ino` 时会自动把同目录下的 `.c/.cpp/.h` 一起编译，不需要额外配置

### 5.3 选择开发板和端口

同 VL53L7 资料第 5.4 节：**工具 → 开发板** 选 `ESP32 Dev Module`；**工具 → 端口** 选对应 COM 口。

---

## 6. 测试程序说明

### 6.1 驱动源码来源

本项目实测验证过的驱动源码（和 VL53L7CX 用的是同一套 VL53LMZ ULD API，逐字节比对完全相同的文件）：

```text
G:\01_工程项目库\01_PCB总\01535\资料\ESP32 2.8黄屏\程序\ESP32_2432S028_VL53L8CH_Tester\
```

唯一的改动在 `platform.h`：

```c
#define VL53LMZ_NB_TARGET_PER_ZONE        4U   // VL53L7CX 版本这里是 1U
```

### 6.2 最小测试程序（8×8 多目标测距）

```cpp
/**
 * VL53L8CH 8×8 多目标测距 — 最小示例
 * 每个 zone 最多读 4 个目标（近→远）
 *
 * 接线（ESP32）：
 *   VL53L8 VCC → 3.3V    GND → GND
 *   VL53L8 SDA → GPIO21  SCL → GPIO22
 *
 * 驱动源码（vl53lmz_api.c/h 等）需要和本文件放在同一个 sketch 文件夹
 */

#include <Arduino.h>
#include <Wire.h>
#include "vl53lmz_api.h"   // platform.h 里 VL53LMZ_NB_TARGET_PER_ZONE 要设成 4U

static VL53LMZ_Configuration g_dev;
static VL53LMZ_ResultsData  g_results;

void setup()
{
    Serial.begin(115200);
    delay(300);

    Wire.begin(21, 22, 400000);   // SDA=GPIO21, SCL=GPIO22, 400kHz

    g_dev.platform.address = VL53LMZ_DEFAULT_I2C_ADDRESS;  // 8-bit 地址 0x52

    uint8_t isAlive;
    uint8_t status = vl53lmz_is_alive(&g_dev, &isAlive);
    if (!isAlive || status) {
        Serial.println("ERROR: VL53L8CH not detected! Check wiring.");
        while (1) { delay(1000); }
    }

    status = vl53lmz_init(&g_dev);
    if (status != VL53LMZ_STATUS_OK) {
        Serial.printf("ERROR: init failed (code %d)\n", status);
        while (1) { delay(1000); }
    }

    // module_type 读回来应该是 2 (VL53LMZ_MODULE_TYPE_L8)，可以用来确认芯片型号
    Serial.printf("Driver: %s, module_type=%u\n", VL53LMZ_API_REVISION, g_dev.module_type);

    vl53lmz_set_resolution(&g_dev, VL53LMZ_RESOLUTION_8X8);
    vl53lmz_set_ranging_frequency_hz(&g_dev, 10);
    vl53lmz_set_ranging_mode(&g_dev, VL53LMZ_RANGING_MODE_CONTINUOUS);
    vl53lmz_set_target_order(&g_dev, VL53LMZ_TARGET_ORDER_CLOSEST);
    vl53lmz_start_ranging(&g_dev);
}

void loop()
{
    uint8_t isReady;
    vl53lmz_check_data_ready(&g_dev, &isReady);
    if (!isReady) { delay(2); return; }

    vl53lmz_get_ranging_data(&g_dev, &g_results);

    Serial.printf("=== Frame #%u ===\n", g_dev.streamcount);
    for (int zone = 0; zone < 64; zone++) {
        uint8_t nb = g_results.nb_target_detected[zone];
        if (nb == 0) continue;

        Serial.printf("Zone %2d (%u targets): ", zone, nb);
        for (uint8_t k = 0; k < nb; k++) {
            uint16_t idx = VL53LMZ_NB_TARGET_PER_ZONE * zone + k;
            Serial.printf("[%dmm @%u%%] ", g_results.distance_mm[idx], g_results.reflectance[idx]);
        }
        Serial.println();
    }
    Serial.println();
}
```

### 6.3 串口输出示例（简化演示）

```
=== Frame #206 ===
Zone  1 (2 targets): [69mm @0%] [1077mm @1%]
Zone  2 (2 targets): [85mm @0%] [1274mm @2%]
Zone  3 (2 targets): [107mm @0%] [7860mm @77%]
Zone  4 (3 targets): [87mm @0%] [683mm @1%] [7902mm @84%]
Zone  5 (3 targets): [84mm @0%] [859mm @90%] [8025mm @90%]
```

可以看到每个 zone 除了远处的墙面（几米，反射率通常较高），还多了一个很近、反射率极低的目标——这就是第 3.4 节提到的盖板玻璃反射，正常现象。

### 6.4 电脑桌面 3D 可视化（本项目自带）

比看串口文字直观得多，本项目自带 PyQt6 + pyqtgraph 做的桌面仪表盘：

```bash
cd VL53L8\软件与测试工具\Python仪表盘
python vl53l8_dashboard.py COM6 115200    # COM口以实际串口号为准
python vl53l8_dashboard.py --demo         # 没接硬件时看模拟效果
```

3D 悬浮点云里，同一个 zone 如果测到多个目标，能直接看到好几个发光点垂直叠在一起（用发光"糖葫芦"连线区分），比文字列表直观很多。

---

## 7. 常见问题排查

### 7.1 编译错误

| 错误信息 | 原因 | 解决 |
|----------|------|------|
| `No such file: vl53lmz_api.h` | 驱动源码没放进 sketch 文件夹 | 把 `vl53lmz_api.c/h` 等一整套文件复制到 `.ino` 同目录 |
| `undefined reference to vl53lmz_*` | C/C++ 链接问题 | 确保 `platform.cpp` 是 `.cpp` 后缀（不是 `.c`），`vl53lmz_api.h` 用 `extern "C"` 包裹 |
| `VL53LMZ_NB_TARGET_PER_ZONE` 相关报错 | 这个宏在 `platform.h` 里，多目标模式要设成 `4U` | 检查 `platform.h`，确认改过这一行 |

### 7.2 传感器未检测到 / 初始化失败

排查思路和 VL53L7CX 完全一样（接线、供电、I²C 地址、电平），参照 `VL53L7_产品技术资料.md` 第 7.2~7.3 节，这里不重复。VL53L8CH 的 I²C 地址（8-bit）同样是 `0x52`，Arduino Wire 7-bit 地址是 `0x29`。

### 7.3 只有 1 个目标，多目标不生效

检查 `platform.h` 里 `VL53LMZ_NB_TARGET_PER_ZONE` 是不是还是 `1U`（这是官方默认值），改成 `4U` 重新编译烧录。

### 7.4 显示的距离全是几十毫米、反射率很低

不是故障，是第 3.4 节说的盖板玻璃反射（crosstalk），真正的目标距离会是同一 zone 里的另一个（更远的）目标。如果这个近场幽灵点影响观感，可以参考 ST 官方 AN5939（盖板玻璃指南）做串扰标定。

---

## 8. 参考资料

| 资料 | 链接/路径 |
|------|------|
| VL53L8CH Datasheet (DS14310) | 本地：`VL53L8\VL53L7资料\VL53(VL53L7_8CX)\Database\vl53l8ch\vl53l8ch.pdf` |
| AN5939 盖板玻璃指南 | 本地：`VL53L8\VL53L7资料\VL53(VL53L7_8CX)\Database\vl53l8ch\an5939-*.pdf` |
| AN5945 连接 STM32 Nucleo64 指南 | 本地：`VL53L8\VL53L7资料\VL53(VL53L7_8CX)\Database\vl53l8ch\an5945-*.pdf` |
| AN5897 PCB 散热指南 | 本地：`VL53L8\VL53L7资料\VL53(VL53L7_8CX)\Database\vl53l8ch\an5897-*.pdf` |
| UM3183 AI Enabler 使用指南（VL53L7CH/VL53L8CH） | 本地：`VL53L8\VL53L7资料\VL53(VL53L7_8CX)\Database\vl53l8ch\um3183-*.pdf` |
| ST 官方 VL53L8CH 产品页 | https://www.st.com/en/imaging-and-photonics-solutions/vl53l8ch.html |
| ST 官方 ULD API 软件包 (STSW-IMG043) | https://www.st.com/en/embedded-software/stsw-img043.html |
| VL53L7 同款技术资料（很多排查步骤通用） | `VL53L7\软件与测试工具\芯片资料\VL53L7_产品技术资料.md` |

---

> 📝 本文档基于 ST 官方 VL53L8CH Datasheet (DS14310 Rev 3) 和 2026-07-11 实际烧录测试整理。VL53L8CH 驱动和 VL53L7CX 共用同一套 VL53LMZ ULD API，很多排查思路通用，但**多目标是 VL53L8CH 独有的核心卖点**，测试和展示时应该重点突出这一点。