BVLGARISSK/xiaomi-wpftb-lidar
GitHub: BVLGARISSK/xiaomi-wpftb-lidar
面向小米及追觅扫地机器人所用 X-WPFTB-V2.6.2 激光雷达的 Arduino 驱动库、通信协议文档与 Windows 实时可视化工具。
Stars: 1 | Forks: 0
# 小米 X-WPFTB LiDAR
Arduino 库、协议说明，以及用于三线制
`X-WPFTB-V2.6.2` 2D LiDAR 的实时 Windows 可视化工具（该雷达应用于多款小米和追觅扫地机器人）。
[繁體中文說明](README.zh-TW.md)
## 在真实硬件上确认的信息
| 项目 | 数值 |
|---|---|
| PCB | `X-WPFTB-V2.6.2` |
| 接口 | 单向 UART 输出 |
| UART | `115200 baud, 8N1`，正常极性 |
| 帧头 | `55 AA 03 08` |
| 数据包大小 | 36 字节 |
| 每包采样点数 | 8 |
| 距离单位 | 毫米 |
| 测试主机 | Arduino Uno，LiDAR 的 DOUT 连接至 D9 |
这与公开文档中记载的 `T-WPFTB-V3.2.2` 的有线协议**不同**，后者使用 `230400 baud`、帧头为 `55 AA 23 10`，并且采用 60 字节的数据包。
## 接线说明
照片丝印和实时抓取的数据支持以下三线分配方式：
| LiDAR 导线 | 功能 | Arduino Uno |
|---|---|---|
| 黑色/棕色 | GND | GND |
| 橙色 | DOUT | 在 Uno 示例中连接至 D9 |
| 红色 | VCC | 保留已知可用的传感器供电 |
注意事项：
- DOUT 是 LiDAR 的输出端。切勿从 Arduino 端将其拉高（HIGH）。
- Arduino 和 LiDAR 必须共地。
- 红线电源电压无法通过 UART 分析确定。在更改原始供电方式之前，请先测量电压。
- 在 Uno 示例中，D8 仅作为未使用的 `SoftwareSerial` TX 占位符，应保持断开。
## Arduino 库快速入门
将此代码库下载为 ZIP 文件，然后在 Arduino IDE 中使用：
`项目 > 包含库 > 添加 .ZIP 库...`
打开 `文件 > 示例 > Xiaomi WPFTB LiDAR > UnoSerialMonitor`。
```
#include
#include
SoftwareSerial lidarUart(9, 8); // RX=D9, unused TX=D8
XiaomiWPFTBLidar lidar(lidarUart);
void setup() {
Serial.begin(250000);
lidarUart.begin(XiaomiWPFTBLidar::kBaudRate);
}
void loop() {
lidar.update();
XiaomiWPFTBFrame frame;
if (!lidar.readFrame(frame)) return;
for (uint8_t i = 0; i < XiaomiWPFTBLidar::kSampleCount; ++i) {
const XiaomiWPFTBSample &point = frame.samples[i];
if (!point.valid()) continue;
Serial.print(point.angleDeg, 2);
Serial.print(',');
Serial.println(point.distanceMm);
}
}
```
该库不执行动态内存分配。它提供对角度、距离、质量、标志位、数据包计数器、原始尾部校验和字段以及初步 RPM 估算值的访问。
### Uno 性能说明
在 Uno 上以 115200 波特率运行 `SoftwareSerial` 已接近其实际性能极限。
包含的 Uno 示例对文本输出进行了节流处理。如需连续采集数据，建议使用 Mega、ESP32、RP2040 或其他带有可用硬件 UART 的开发板。
## 实时 Windows 可视化工具
1. 上传 `examples/WindowsVisualizerBridge/WindowsVisualizerBridge.ino`。
2. 关闭 Arduino 串口监视器，以便释放 COM 端口。
3. 双击 `tools/windows-visualizer/Start_LiDAR_Visualizer.bat`。
4. 从下拉列表中选择 Arduino 的 COM 端口，然后点击 **连接**。
桥接程序以 115200 波特率读取 LiDAR 数据，并通过 USB 串口以 500000 波特率转发验证后的 36 字节数据包。可视化工具仅使用 Windows PowerShell、WinForms 和 `System.IO.Ports`；它不会安装任何内容，也不会进行任何网络调用。
## 文档
- [有线协议](docs/protocol.md)
- [逆向工程笔记](docs/reverse-engineering.md)
- [Windows 可视化工具](tools/windows-visualizer/README.md)
- [贡献指南](CONTRIBUTING.md)
## 已知限制
- 尚未识别出第 34-35 字节的校验和/CRC 算法。
- `rpmEstimate = rateRaw / 60` 与观察到的数值量级相符，但仍需要通过外部转速计进行验证。
- 供电电压、电流消耗、逻辑阈值和光学内部结构未在本研究中进行表征。
## 许可证
MIT。请参阅 [许可证](LICENSE)。
标签：AI合规, Arduino库, Libemu, 机器人配件, 激光雷达(LiDAR), 硬件与物联网, 通信协议