先找到问题发生在哪一步，再查该段链路。下面按首次接入时最常见的现象排列。
APP 搜不到开发板
- 确认板子已开机，无线芯片已启动，手机已允许蓝牙权限。
- 检查广播是否使用
moto_terminal_advertising返回的完整 31 字节。 - 检查服务 UUID 是否与蓝牙连接一致。
扫描只验证广播；找到设备后继续检查连接和配对。
能连接，但一直配对不成功
先看仪表有没有显示 PIN：
- **没显示：**检查手机是否订阅 TX 通知、
ble_send是否真的发出了数据、应用是否持续调用next_event。 - **已显示但失败：**检查 PIN 是否含前导
0、是否过期，再检查绑定信息是否成功保存。 - **每次重启都要配对：**检查绑定记录的存储读写，不要在启动时擦除绑定记录。
若已经认证但没有某项功能，核对后台型号设置和 get_status().enabled_capabilities。
创建 SDK 失败
打印创建时返回的错误，只保留阶段、错误名和说明：
printf("%s: %s (%s)\n",
moto_terminal_stage_name(error.stage),
error.detail,
moto_terminal_result_name(error.code));
| 阶段 | 优先检查 |
|---|---|
config |
是否调用 config_init；固件版本、宽高、回调是否填写正确 |
license_read |
是否完整读出 512 字节授权文件 |
license_verify |
授权、公钥和硬件标识是否匹配 |
storage_read / storage_write |
绑定记录能否完整读取并保存 |
memory / task |
FreeRTOS 可用堆内存、应用任务栈和 SDK 工作任务栈 |
tls / core |
是否使用匹配的静态库和接入包配置 |
任务栈先使用目标接入包的默认配置，再按运行时的栈余量调整。确认工具链使用的是字节还是 StackType_t 元素个数，不照搬其他开发板的数值。
导航能开始，但仪表黑屏
以下针对同时接入投屏和 HUD 的大屏。先分别确认 HUD 更新与视频显示，HUD 正常不代表视频链路已接通。
按顺序记录各阶段是否到达：
热点可连接 → STREAM_PREPARE 已成功回报 → 收到 STREAM_START
→ 收到 UDP 包 → 解码出像素 → LCD 显示完成
停在哪一步，就检查那一步的驱动。特别核对解码格式、尺寸、RGB565 字节序和显示缓冲。presented 必须由 LCD 完成显示后调用。
若第二次导航才黑屏，检查旧视频任务是否已停止，以及新旧 session / stream_id 是否混用。
队列满或反复断连
MOTO_FULL 表示 SDK 本次没有接收数据；保留并稍后重试，不重复提交已经返回 MOTO_OK 的数据。
频繁出现时检查事件读取是否被解码、屏幕刷新或耗时硬件操作阻塞。把慢操作移到对应驱动任务。event_queue 错误通常说明应用没有及时读取事件。
发布前实际测一遍
| 测试 | 通过标准 |
|---|---|
| 配对与重启 | PIN 有效；重启保留绑定 |
| 控车与通信超时 | 真实动作和 APP 结果一致；失败能被识别 |
| 导航反复开始、停止 | 新画面正常，旧提示和旧帧不再出现 |
| 手机锁屏、撤销通知权限 | 通知和通话界面及时更新 |
| 断连再连接、正式解绑 | 不执行旧指令；解绑后旧用户不能控制 |
使用目标手机、屏幕和控制器测试，记录 APP、SDK、固件及板型版本。
若接固件升级，还要实现 Flash 写入、镜像校验、启动切换和掉电恢复。传输完成不代表新固件已经安装。
仍无法定位时，向技术团队提供版本、错误阶段和复现步骤；不要发送授权文件、PIN、密钥或热点密码。