基于STM32WB与ToF传感器的卡车月台自动化引导系统原型设计-开发者社区

1. 项目概述与核心价值

在物流仓储的日常运作中，卡车装卸货平台（Dock）是货物流转的咽喉要道。这里效率和安全上的任何一点微小提升，都能直接转化为可观的运营效益。传统的靠车、装卸流程，高度依赖司机与仓管员之间的手势、喊话或对讲机沟通，不仅存在信息误判的风险，在夜间、雨雪天气或嘈杂环境下，效率更是大打折扣。我最近完成了一个卡车月台自动化系统的概念验证项目，核心目标就是用一套低成本、易部署的硬件方案，替代这种原始的“人肉通信”，实现从卡车靠泊到驶离的全流程半自动化引导与状态同步。

这个系统的核心硬件是一块STM32WB5MM-DK开发板，它集成了蓝牙、一个用于测距的飞行时间（ToF）传感器、一个RGB LED灯和一个显示屏。软件端则用STM32duino框架编写固件，并搭配一个用MIT App Inventor快速开发的手机App原型。整套方案听起来不复杂，但真正把它跑通，让硬件、传感器、蓝牙通信和手机端界面协同工作，里面有不少值得分享的细节和踩过的坑。它不是一个商业级产品，但作为一个快速原型（Proof-of-Concept），其设计思路、组件选型和实现路径，对于想涉足工业物联网、仓储自动化或简单人机交互项目的朋友来说，会是一个非常有价值的参考案例。

2. 系统整体设计与核心思路拆解

2.1 为什么选择这个技术栈？

在项目启动时，技术选型主要基于几个核心考量：快速验证、成本可控、功能集成度高。

首先，主控板选择了STM32WB5MM-DK。这颗芯片的独特优势在于其双核架构：一个Cortex-M4内核用于运行主要应用程序，另一个Cortex-M0+内核专用于处理蓝牙协议栈。这意味着蓝牙通信不会占用主应用CPU的资源，保证了测距、逻辑判断和显示刷新的实时性。开发板自带OLED显示屏、RGB LED、用户按键和丰富的扩展接口，几乎囊括了我们所需的所有外设，省去了额外焊接和连接的工作，非常适合原型开发。

其次，采用STM32duino框架而非官方的STM32CubeIDE或HAL库，主要是出于开发效率的考虑。Arduino生态有大量现成的、经过社区验证的传感器库和通信库，学习曲线平缓。对于这个功能明确、逻辑相对线性的项目，用Arduino风格的代码可以更快地搭建出可工作的原型。我们主要用到了STM32duino核心包以及专门为STM32WB系列蓝牙功能优化的STM32duinoBLE库。

最后，手机端用MIT App Inventor。这是一个基于图形化块编程的Web工具，完全不需要编写传统Android代码。对于需要快速验证蓝牙交互逻辑、生成一个可安装的APK文件给司机测试的场景，它几乎是完美的选择。虽然界面和功能相对原生开发简陋，但“能用”和“快速”在概念验证阶段是第一位的。

2.2 核心业务流程与角色分工

系统的设计围绕两个核心角色展开：卡车司机和仓库管理员（仓管员）。整个流程被设计成一个清晰的状态机：

待机与广播：系统启动后，开发板通过蓝牙低功耗（BLE）持续广播一个包含“月台编号”（如Dock-01）的服务。这相当于一个数字化的指示灯，告诉附近的司机这个月台可用且在线。
连接与引导：司机在驾驶室打开手机App，扫描并选择对应的月台进行连接。连接成功后，App界面会显示来自ToF传感器的实时距离数据。司机根据“前进/停止”的提示（例如：“距离5.2米，请缓慢倒车”），将卡车尾部调整到精确的靠泊位置。
确认停靠：当距离值进入预设的安全停靠范围（例如0.5米 ± 0.1米）并稳定一段时间后，司机点击App上的“Park”按钮。这个动作会将一个“已停靠”的状态标志位通过蓝牙写入开发板的一个特征值（Characteristic）中。
仓管员操作：仓管员在月台内，通过开发板上的显示屏可以直观看到“卡车已就位”的状态。此时，他按下开发板上的按钮1，这个操作会通过蓝牙通知司机的App：“车轮已锁定”。同时，板载的RGB LED可能变为红色，提供额外的视觉警示。车轮锁定是一个关键的安全步骤，防止装卸货过程中卡车意外移动。
装卸货进行：此阶段系统处于监控状态，可能持续显示“作业中”并记录时间。
准备驶离：装卸完成后，仓管员按下开发板上的按钮2。系统会通过蓝牙向司机App发送“准备驶离，车轮已解锁”的通知，同时RGB LED变为绿色。司机收到通知后，安全驶离。

这个流程的关键在于，所有关键状态（停靠、锁定、解锁）都通过蓝牙在两端同步，并有硬件（LED、屏幕）和软件（App通知）的双重提示，消除了沟通盲区。

3. 硬件搭建与核心细节解析

3.1 核心组件功能与选型考量

STM32WB5MM-DK开发板：这是系统的大脑。选择它而不是更便宜的STM32板，核心就是看中了其集成蓝牙与主控的能力。单独的主控板+外部蓝牙模块（如HC-05）的方案，会增加布线复杂度和通信调试难度。这块板子“开箱即用”。
VL53L1X ToF 激光测距传感器：这是实现精准引导的核心。为什么用ToF而不是超声波传感器？主要原因有三：精度高（毫米级）、抗干扰强（不受环境光线和声音影响，对灰尘的容忍度也相对较好）、测量范围合适（通常可达4米，完全覆盖倒车引导距离）。超声波在空旷的月台环境容易因多次反射产生误差，且精度一般在厘米级。
OLED显示屏：用于向仓管员显示状态信息。选择OLED而非LCD，是因为其高对比度，在室内光线复杂的环境下更容易看清。显示内容经过精心设计，只包含最关键的信息：当前状态（如“等待连接”、“卡车已停靠”、“已锁定”）、实时距离、蓝牙连接状态。
RGB LED：作为一个强化的、无需阅读的全局状态指示。例如：蓝色闪烁（广播中）、绿色常亮（就绪/解锁）、红色常亮（已锁定）、黄色（警告/距离过近）。颜色编码能让人瞬间理解系统状态。
物理按钮：两个用户按钮，用于触发关键动作（锁定/解锁）。这里没有使用触摸屏或复杂菜单，就是为了确保操作绝对可靠和快速。在忙碌的仓库中，仓管员可能戴着手套，一个实实在在的物理按钮是最不容易出错的选择。

3.2 硬件布局与安装要点

硬件的安装位置直接决定了系统的可用性，绝不是随便找个地方固定就行。

ToF传感器：这是布局中最关键的一环。必须安装在月台外部，通常是在月台门楣或侧方立柱上，确保其激光发射面垂直对准卡车靠泊时车尾的一个固定参考点（例如后保险杠的中心、车厢后门的某个特定位置）。这个参考点需要在司机培训中明确。安装时要确保传感器前方没有玻璃、塑料板等透明或反光物体，否则会严重干扰ToF测量。同时，要做好防水防尘处理（可以使用简单的防护罩）。
蓝牙天线：开发板上的PCB天线或外接天线，其朝向需要优化以覆盖卡车驾驶室。通常，驾驶室位于月台前方，因此天线方向应略向前上方倾斜。可以进行简单的实地测试：在驾驶室位置用手机App扫描，确保信号强度（RSSI）稳定在-70dBm以上。如果信号弱，可以考虑使用带IPEX接口的外接小天线，将其引到更佳位置。
仓管员操作单元：包含显示屏、RGB LED和两个按钮的这部分，应集成在一个小盒子里，安装在月台内部、仓管员工作台附近显眼且易于操作的位置。显示屏的视角和亮度要调整好，确保在仓库照明下清晰可读。

注意：所有室外部署的部件（主要是ToF传感器）必须考虑环境耐受性。虽然VL53L1X不是工业级，但短期原型验证可以加装防护。长期使用需选择IP67等级以上的传感器外壳。

4. 软件实现与实操要点

4.1 STM32端固件开发详解

固件代码采用Arduino框架，核心逻辑围绕BLE通信和传感器数据融合展开。

首先，是BLE服务的配置。我们创建了一个自定义的BLE服务（Service），包含多个特征值（Characteristic）：

Dock Name Characteristic (可读)：用于广播月台编号，手机App一连接就能读取。
Distance Characteristic (可读，可通知)：存放ToF测量的实时距离值。我们将其属性设置为“可读”并开启“通知”（Notify），这样一旦距离更新，手机App就能自动收到推送，无需轮询，省电且实时。
Park Status Characteristic (可读，可写)：用于存放停靠状态（0=未停靠，1=已停靠）。手机App可以写入“1”来确认停靠，仓管员端可以读取这个值。
Lock Status Characteristic (可读，可写，可通知)：用于存放车轮锁状态（0=解锁，1=锁定）。仓管员按下按钮1后，固件会向此特征值写入“1”，并同时通过“通知”告知手机App。手机App也可以读取它。

其次，是主循环逻辑。代码结构大致如下：

#include <STM32duinoBLE.h> #include <Wire.h> #include <VL53L1X.h> VL53L1X tofSensor; BLEService dockService("12345678-..."); // 自定义服务UUID // ... 定义上述各个特征值 ... void setup() { Serial.begin(115200); // 初始化I2C，连接ToF传感器 Wire.begin(); tofSensor.init(); tofSensor.setDistanceMode(VL53L1X::Long); tofSensor.setMeasurementTimingBudget(50000); // 设置测量周期 tofSensor.startContinuous(50); // 每50ms测量一次 // 初始化BLE，设置设备名、广播数据 if (!BLE.begin()) { while (1); } BLE.setLocalName("TruckDock_01"); BLE.setAdvertisedService(dockService); // ... 将特征值添加到服务中，并添加到BLE对象 ... BLE.advertise(); } void loop() { // 1. 处理BLE事件（连接、断开、数据写入） BLE.poll(); // 2. 读取ToF传感器数据 if (tofSensor.dataReady()) { uint16_t distance = tofSensor.read(); tofSensor.clearInterrupt(); // 滤波处理：简单的移动平均滤波，避免跳动 filteredDistance = updateFilter(distance); // 更新“距离”特征值，并触发通知 updateDistanceCharacteristic(filteredDistance); // 根据距离更新UI（屏幕显示、LED颜色） updateGuidanceUI(filteredDistance); } // 3. 检查按钮状态 if (digitalRead(BUTTON1_PIN) == LOW) { // 按下锁定按钮 delay(50); // 简单消抖 if (digitalRead(BUTTON1_PIN) == LOW) { setLockStatus(1); // 写入锁定状态，并通知手机 setRGBLED(RED); updateDisplay("LOCKED"); } } // 类似处理按钮2（解锁）... }

关键点在于滤波和状态判断。原始的ToF数据会有几个毫米的跳动，直接用于显示会令司机困惑。我采用了一个长度为5的移动平均窗口进行滤波，效果很好。对于“停靠到位”的判断，不能只凭某一瞬间的距离值，而是需要距离值在目标范围内（如0.4-0.6米）持续稳定至少2-3秒，才在屏幕上提示“可停靠”，这样可以防止因车辆轻微晃动导致的误判。

4.2 MIT App Inventor 应用开发实录

用App Inventor开发蓝牙应用，核心是理解其“块编程”逻辑和BLE组件的工作方式。

首先，在界面设计器中，拖拽组件：一个ListPicker（用于扫描和选择BLE设备），几个Label（用于显示距离、状态），两个Button（“连接”和“停车”），以及一个BLE非可视组件。

核心逻辑块如下（用文字描述其结构）：

扫描与连接：当“扫描”按钮被点击，调用BLE.StartScanning。当BLE.DeviceFound事件发生时，将发现的设备名添加到ListPicker的列表中。用户从列表中选择后，调用BLE.Connect，并传入设备的MAC地址。
服务与特征值发现：连接成功后，在BLE.Connected事件中，调用BLE.ReadServices。在BLE.ServicesRead事件中，遍历服务列表，找到我们自定义服务的UUID，然后调用BLE.ReadCharacteristics。在BLE.CharacteristicsRead事件中，遍历特征值列表，找到我们定义的“距离”、“停靠状态”、“锁定状态”等特征值的UUID，并保存它们的CharacteristicIndex以供后续操作。
接收距离通知：找到“距离”特征值后，调用BLE.StartNotifications启动通知。之后，每当距离更新，BLE.CharacteristicValueChanged事件就会触发，我们从事件参数中解析出字节数据，转换成整数，并更新到界面的Label上。可以在这里添加逻辑，比如距离大于3米显示“请倒车”，1-3米显示“缓慢接近”，小于1米显示“准备停车”。
写入停靠状态：当司机点击“Park”按钮时，我们构造一个字节数据（例如单字节的 0x01），调用BLE.WriteCharacteristicValue，写入到“停靠状态”特征值中。
接收锁定/解锁通知：同样，为“锁定状态”特征值启动通知。当仓管员操作按钮后，App会收到值改变事件，根据收到的值（0或1）更新界面，例如显示“车轮已锁定，请等待”或“可以安全驶离”。

实操心得：App Inventor的BLE组件有时对特征值的属性（读/写/通知）比较敏感。务必在STM32端正确定义特征值的属性。调试时，可以先用一些通用的BLE调试App（如nRF Connect）确认STM32的BLE服务和特征值是否广播和设置正确，这能排除一大半问题。

5. 系统集成调试与问题排查

5.1 蓝牙连接稳定性优化

在开阔的月台环境，蓝牙连接看似简单，实则暗藏玄机。

问题一：连接距离短或频繁断开。

排查：首先检查STM32WB的蓝牙发射功率。在Arduino代码中，可以使用BLE.setTxPower(4)之类的函数（具体函数名需查库文档）将发射功率调到最大（如+8dBm）。其次，检查天线附近是否有金属物体大面积遮挡。最后，在手机App端，连接后不要立即进入深度睡眠，可以在Screen.Initialize中调用BLE.KeepAlive（如果组件支持）或维持一个轻微的心跳。
解决：调整硬件天线朝向，优化代码中的发射功率设置。实测在无遮挡环境下，稳定连接距离可达20米以上，足以覆盖卡车靠泊场景。

问题二：手机App扫描不到设备。

排查：STM32WB的BLE广播默认可能不是持续进行的，或者在连接后停止广播。确保在setup()中调用BLE.advertise()后，在loop()中即使已连接，也要处理重连逻辑。另一个常见原因是设备名（BLE.setLocalName）包含特殊字符或过长，某些手机系统过滤不掉。
解决：简化设备名为“Dock_”加编号。在代码中确保广播始终开启（对于多设备场景，需要在断开连接后重新调用BLE.advertise()）。

5.2 ToF传感器数据异常处理

问题：距离数据偶尔跳变为极大值（如8190mm）或0。

原因：VL53L1X在测量不到有效反射信号（如目标过远、表面吸收性太强、强光干扰）或内部信号处理出错时，会返回特定的错误值。

解决：在固件代码中必须加入数据有效性检查。

uint16_t distance = tofSensor.read(); if (tofSensor.ranging_data.range_status == VL53L1X::RANGE_VALID) { // 有效数据，参与滤波和显示 validDistance = distance; } else { // 无效数据，丢弃，或使用上一次的有效值，并在屏幕上显示“--”或“信号弱” validDistance = lastValidDistance; updateDisplay("Signal Lost"); }

同时，在安装时要确保传感器对准的区域，在卡车停靠前后都有良好的反射面（卡车尾部通常没问题）。

5.3 电源与抗干扰考虑

系统若长期运行，需使用稳定的电源适配器（如5V/2A），避免使用简单的USB线连接电脑供电。开发板、传感器和外围电路最好集成在一个有屏蔽效果的金属盒内，以减少仓库中电机、变频器等设备产生的电磁干扰。所有信号线（如I2C线）尽量短，并做好固定。

6. 概念验证的局限性与未来演进方向

当前的这个原型，成功验证了“传感器引导+蓝牙通信”这一核心流程的可行性，但它离真正的产品化还有距离。

主要局限性：

MIT App Inventor的限制：生成的App无法上架官方应用商店，只能通过APK安装，分发和管理不便。界面和交互相对固定，难以实现复杂的动画或本地存储。
硬件防护等级：开发板和传感器未做工业级的防水、防尘、防震处理，无法应对严苛的仓库环境。
单点故障：整个系统依赖一个主控板，一旦损坏，整个月台瘫痪。
无后台管理：数据仅在现场显示和交互，没有上传到服务器，无法进行数据分析、报表生成和远程监控。

未来演进方向：

开发原生移动应用：使用Flutter或React Native开发跨平台App，或分别开发Android和iOS应用。可以实现更专业的UI/UX，集成扫码连接（扫描月台二维码）、历史记录、电子签收等功能，并方便通过应用商店分发。
硬件产品化设计：设计定制PCB，将STM32WB核心模块、电源管理、传感器接口、工业通信接口（如RS485、以太网）集成在一起。外壳采用IP65及以上防护等级，宽温设计。
引入冗余与网络化：每个月台节点可以通过有线以太网或LoRa、Wi-Fi等无线方式接入局域网，将状态数据上报给中央服务器。这样可以在服务器端实现状态监控、故障报警和数据分析。甚至可以在一个屏幕上集中管理所有月台的状态。
集成更多传感器：例如，增加红外或毫米波雷达传感器作为ToF的冗余备份，提高系统可靠性。增加声音报警器，提供听觉提示。在月台门和卡车尾部安装接触传感器或光电传感器，作为“已紧密靠泊”的最终确认信号，与ToF数据形成双重校验。
与仓库管理系统（WMS）对接：这是价值最大的一环。系统可以自动获取即将到港的卡车任务信息，并提前分配月台。装卸完成状态可自动反馈回WMS，更新库存和任务状态，真正实现流程闭环。

这个项目给我的最大体会是，在工业物联网应用中，可靠性永远排在功能和美观的前面。一个每次都能准确响应、状态明确的简单系统，远比一个功能花哨但偶尔失灵的复杂系统更有价值。从原型到产品，最大的挑战往往不是技术本身，而是对真实应用场景中各种边界条件和异常情况的深刻理解与妥善处理。