IoT-For-Beginners 制造篇：使用 Wio Terminal 与 Grove VL53L0X 飞行时间传感器实现接近检测-港品优选

IoT-For-Beginners 制造篇：使用 Wio Terminal 与 Grove VL53L0X 飞行时间传感器实现接近检测

【免费下载链接】IoT-For-Beginners12 Weeks, 24 Lessons, IoT for All!项目地址: https://gitcode.com/GitHub_Trending/io/IoT-For-Beginners

本指南讲解如何在 IoT-For-Beginners 开源课程"从传感器触发水果质量检测"（第 4 制造项目第 4 课）中，为 Wio Terminal 添加 Grove Time of Flight（飞行时间）接近传感器，并通过 PlatformIO 编程读取物体距离。完成本文后，你将掌握 VL53L0X 传感器的硬件连接、I²C 通信初始化、单次测距 API 调用与串口验证方法，为后续用距离触发水果图像分类打下基础。

硬件准备：Grove Time of Flight 距离传感器

本任务使用的接近传感器是 Grove Time of Flight 距离传感器（型号 VL53L0X）。其核心是一个激光测距模块，通过发射激光束并测量光束从物体反射回来所用的时间来计算传感器与物体之间的距离。

根据 wio-terminal-proximity.md 中的说明，该传感器具有以下关键特性：

特性	参数
测量原理	激光测距（Time of Flight，飞行时间）
测量范围	10mm ~ 2000mm（即 1cm ~ 2m）
超量程表现	距离超过 1000mm 时报告为 8109mm
通信协议	I²C（I2C）
激光测距模块位置	传感器背面，与 Grove 插座的相反一侧

值得注意的是，传感器报告的值在量程内相当准确，但超出量程后会返回固定的 8109mm 值，在编写业务逻辑时应将其视为"超出有效测量范围"的哨兵值。

传感器实物图可参考 images/grove-time-of-flight-sensor.png，激光测距模块位于传感器背面，测量时应让该面朝向被测物体。

在课程整体设计中，这个接近传感器正是水果质量检测系统的"触发器"：水果在传送带上到达指定位置时，传感器测得距离变化，从而触发后续的拍照与图像分类流程。关于该端到端原型系统的架构说明，可阅读第 4 课总览 README.md。

连接 Time of Flight 传感器到 Wio Terminal

Grove Time of Flight 传感器通过 Grove 线缆与 Wio Terminal 连接，步骤非常简单，但需要注意正确的插槽与方向。

将 Grove 线缆的一端插入 Time of Flight 传感器上的插座。该插座只有一个方向能插入，无需担心插反。
在 Wio Terminal断开电源（拔掉与电脑或其他电源的连接）的状态下，将 Grove 线缆的另一端连接到 Wio Terminal 正对屏幕时左侧的 Grove 插座。这是离电源按键最近的插座，是一个数字信号与 I²C 复合插座——由于 VL53L0X 是 I²C 传感器，必须接到这个支持 I²C 的复合插座上。
连接完成后，即可将 Wio Terminal 重新连接到电脑。

连接示意图可参考 images/wio-time-of-flight-sensor.png。

使用 PlatformIO 创建工程并添加传感器库

Wio Terminal 使用 PlatformIO 进行开发。需要新建一个名为distance-sensor的 Wio Terminal 工程，并在工程的platformio.ini文件中声明 Seeed 官方提供的 VL53L0X 库依赖。

仓库中提供了完整可运行代码，位于 code-proximity/wio-terminal/distance-sensor 目录。其 platformio.ini 内容如下：

[env:seeed_wio_terminal] platform = atmelsam board = seeed_wio_terminal framework = arduino lib_deps = seeed-studio/Grove Ranging sensor - VL53L0X @ ^1.1.1

配置项说明：

platform = atmelsam：Wio Terminal 基于 Atmel SAMD51 系列微控制器，使用 atmelsam 平台；
board = seeed_wio_terminal：指定目标开发板型号；
framework = arduino：使用 Arduino 框架进行编程；
lib_deps：声明 Seeed Studio 的 Grove 测距传感器库seeed-studio/Grove Ranging sensor - VL53L0X @ ^1.1.1，版本号采用^1.1.1语义化版本范围，允许安装 1.1.1 及以上、低于 2.0.0 的兼容版本。

编写代码：初始化传感器并读取距离

引入头文件并声明传感器实例

在工程src/main.cpp中，首先在已有的 include 指令下方引入 VL53L0X 库头文件，并声明一个Seeed_vl53l0x类的全局实例，后续所有传感器操作都通过该实例完成：

#include <Arduino.h> #include "Seeed_vl53l0x.h" Seeed_vl53l0x VL53L0X;

在 setup 中配置串口并初始化传感器

setup函数负责串口初始化和传感器初始化。仓库源码 main.cpp 中的完整实现为：

void setup() { Serial.begin(9600); while (!Serial) ; // Wait for Serial to be ready delay(1000); VL53L0X.VL53L0X_common_init(); VL53L0X.VL53L0X_high_accuracy_ranging_init(); }

关键点说明：

Serial.begin(9600)将串口波特率配置为 9600，用于后续向串口监视器输出测距结果；
while (!Serial);等待串口就绪，避免初始化后立即输出时数据丢失；
delay(1000)等待 1 秒，给传感器上电稳定时间；
VL53L0X_common_init()执行传感器的通用初始化，完成 I²C 总线上的基础配置；
VL53L0X_high_accuracy_ranging_init()切换到"高精度测距"模式。与普通模式相比，高精度模式会调整激光测距的测量参数以获得更精确的距离读数，代价通常是更长的单次测量时间。在水果检测场景中，精度优先于吞吐量，因此选择该模式。

在 loop 中执行单次测距并输出结果

loop函数循环执行单次测距、输出结果并延时 1 秒：

void loop() { VL53L0X_RangingMeasurementData_t RangingMeasurementData; memset(&RangingMeasurementData, 0, sizeof(VL53L0X_RangingMeasurementData_t)); VL53L0X.PerformSingleRangingMeasurement(&RangingMeasurementData); Serial.print("Distance = "); Serial.print(RangingMeasurementData.RangeMilliMeter); Serial.println(" mm"); delay(1000); }

代码逻辑逐行解读：

首先定义一个VL53L0X_RangingMeasurementData_t类型的结构体变量，用于承接测距数据；
memset(&RangingMeasurementData, 0, sizeof(...))将结构体内存清零，确保未填充字段不会携带脏数据；
调用PerformSingleRangingMeasurement(&RangingMeasurementData)，该方法执行一次完整的单次测距，并把结果写入传入的结构体；
通过RangingMeasurementData.RangeMilliMeter读取以毫米为单位的距离值，并用Serial.print/Serial.println输出Distance = xxx mm格式的文本；
delay(1000)让测距循环以约 1 秒的间隔运行。

需要留意的是，测距结构体中的RangeMilliMeter字段单位为毫米，输出时直接拼接mm后缀。若需在后续代码中判断"是否有物体接近"，可结合量程上限（2000mm）与超量程哨兵值（8109mm）编写阈值逻辑。

编译、烧录与串口验证

在 PlatformIO 中构建并上传代码到 Wio Terminal，然后打开串口监视器即可实时查看距离读数。将物体（例如课程示例中的香蕉）靠近传感器，会看到读数随之变化：

Distance = 29 mm Distance = 28 mm Distance = 30 mm Distance = 151 mm

验证时需要注意两点：

激光测距模块位于传感器背面（与 Grove 插座相反的一侧），测量距离时务必让背面朝向被测物体；
距离传感器正对水果测量时的实物效果可参考 images/time-of-flight-banana.png。

从上面的输出可以看到，当物体稳定在传感器前方时读数保持稳定（29mm / 28mm / 30mm），当物体移开或距离变化时读数立即更新（151mm），这正是后续用距离阈值触发水果图像分类所依赖的信号。

在水果质量检测系统中的角色

本任务属于第 4 课"从传感器触发水果质量检测"中的硬件实操部分，课程同时提供了 Raspberry Pi 与虚拟设备两种替代实现（分别见 pi-proximity.md 与 virtual-device-proximity.md）。在课程设计的水果质检参考架构中：

装有接近传感器的 IoT 设备检测到水果到达传送带，向云端发送"已检测到水果"的消息；
云端 Serverless 应用向另一台设备发送拍照与图像分类命令；
分类结果回传云端存储，若判定为未成熟水果，则向带 LED 的设备发送告警命令。

因此，本文实现的测距程序正是整个原型系统触发链的第一环。在工程实践中还需考虑：距离阈值判定放在设备端还是云端、消息字段与单位的统一定义、以及量产时通过云端（如设备孪生）动态配置触发距离而非硬编码等问题，详见课程总览 README.md 中的"触发水果质量检测"与"数据定义"章节。

常见问题排查

串口无输出：确认Serial.begin(9600)的波特率与串口监视器设置一致；确认 USB 连接正常且while (!Serial);已通过。
读数始终为 8109mm：表示距离超出量程或未检测到反射物，请将物体移到 2m 有效量程内，并确认激光测距模块（传感器背面）正对物体。
读数始终为 0：检查 Grove 线缆是否插紧，以及传感器是否连接到了 Wio Terminal 左侧的复合数字/I²C 插座。
构建失败：确认platformio.ini中lib_deps的库名称与版本号写法与仓库示例一致（seeed-studio/Grove Ranging sensor - VL53L0X @ ^1.1.1），并确认网络可正常拉取 PlatformIO 依赖库。

参考代码位置

完整可运行的工程代码位于 code-proximity/wio-terminal/distance-sensor 目录，其中：

主要逻辑：src/main.cpp
工程配置：platformio.ini

课程总览、Raspberry Pi 实现与虚拟设备实现分别位于 README.md、pi-proximity.md 和 virtual-device-proximity.md，可作为扩展学习入口。

【免费下载链接】IoT-For-Beginners12 Weeks, 24 Lessons, IoT for All!项目地址: https://gitcode.com/GitHub_Trending/io/IoT-For-Beginners

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析