排查 A1 时，将板端推理、固件打包、Windows 联调和底盘控制分层检查，避免将所有问题归咎于模型。
做嵌入式视觉机器人时，我一开始最容易犯的错是：看到现象不对，就想先改模型。
后来发现这条路通常不高效。视觉机器人是一条很长的链：相机输入、板端推理、OSD 显示、固件打包、串口命令、底盘控制、Windows 联调工具，每一层都可能让最后现象偏离预期。
所以在 A1 视觉机器人项目里，我后来先不急着调参，而是先确认问题到底落在哪一段。
四层系统
这个项目可以拆成四层：
板端 AI Demo -> 固件打包层 -> Windows 联调层 -> STM32 底盘层板端 AI Demo 负责图像处理、模型推理、OSD 叠加、A1_TEST 调试命令和 UART 控制。
固件打包层负责把最新应用打进最后可刷写镜像。这里踩过坑：应用单独编过，不代表刷进去的镜像已经更新，最后还是要看重新打包出来的固件。
Windows 联调层负责视频预览、拍照、COM 终端、A1_TEST 手动检查，以及直连或中继到底盘的调试工具。
STM32 底盘层负责实际运动控制和遥测反馈。
这四层如果混在一起排查，很容易把“刷入的镜像不是最新”“Windows 工具连错路径”“串口中继没通”误判成“模型不准”。
模型输出要先变成契约
现在这条视觉主线已经不只是一个分类结果，还多了导航区域判断：
combined_logits[17] = semantic[5] + navgrid[12]semantic 表示语义类别，navgrid 把画面拆成 left / center / right 三个区域，每个区域再判断 clear、near、mid、far 这类障碍状态。
这 17 个维度要在板端、调试接口、Windows 页面和底盘映射里保持同一套解释。否则模型本身没变，系统也可能因为解析错位而表现异常。
两条控制路径不能混
调底盘时还有一个很容易混淆的点：直连 STM32 和经 A1 中继是两条不同路径。
PC 串口 -> STM32PC COM -> A1_TEST -> A1 UART -> STM32前者适合验证底盘协议和基础运动控制，后者适合验证板端程序、视觉结果和底盘动作之间的联动。
如果这两条路径不分开，排查会变得很混乱。比如直连能动，不代表 A1 中继能动；A1 中继能发命令，也不代表视觉推理的动作映射一定正确。
OSD 截图容易误导
视觉项目里，OSD 是最容易被截图误导的部分。
屏幕上没有显示结果，可能有很多原因：
- 应用根本没有运行。
- 镜像不是最新版本。
- OSD 初始化失败。
- 图层资源没加载。
- 贴图或刷新接口调用失败。
- Windows 预览路径没有显示真实板端画面。
如果只看一张截图，很难区分这些情况。我会在 OSD 初始化、贴图加载、刷新调用附近打 stdout 或日志，再用板端命令和 Windows 工具对一下。
工程入口要写进文档
这种项目的目录会很深，SDK、厂商代码、训练数据、构建输出和联调工具混在一起时，光靠记忆找入口很危险。
我后来更倾向于在 README 里直接写清楚：
- 改板端行为先进哪一层。
- 改镜像构建看哪个脚本。
- 改 Windows 预览和串口工具看哪个目录。
- 哪些目录是 vendor 或外部资产，不该随手改。
- 最小验证命令是什么。
这不是形式主义。嵌入式项目最怕“改了一个看似相关的地方”，结果真实运行路径根本没经过那里。
先证明各层能跑通，再优化模型
现在我会按这个顺序处理问题：
- 确认板端应用是否是最新构建。
- 确认最后镜像是否包含最新应用。
- 确认相机输入和推理接口有真实数据。
- 确认 17 维输出在各端的解析方式一致。
- 确认 Windows 工具看到的是同一条调试路径。
- 确认底盘控制路径和动作映射正确。
- 最后再回到模型效果本身。
这个顺序不一定最快，但它能减少误判。
先把各层拆清楚
嵌入式视觉机器人项目麻烦在多层之间很容易互相背锅。
把系统拆成板端推理、固件打包、Windows 联调、底盘控制四层，再把 17 维输出的含义写清楚，很多问题就能定位到具体环节，而不是反复猜模型。
这也是我现在更愿意采用的整理方式：先把每层的职责和范围讲清楚，再决定该优化哪一层。
继续读