一、项目背景

最近在做一个车载仪表的语音导航功能，核心需求是通过MQTT协议实现云端与设备的双向通信——云端下发搜索指令，设备端搜索POI后上报结果，再通过语音或旋钮选择目的地和路线，最终完成导航启动。

项目基于OpenHarmony L0轻量系统，跑在D21X开发板上。MQTT作为轻量级物联网协议，天然适合这种资源受限、需要实时通信的场景。

二、整体架构

整个模块分为三层：

MQTT通信层：负责连接云端Broker、订阅下行主题、发布上行消息。下行主题接收search（搜索POI）、select_poi（选择目的地）、select_route（选择路线）等指令；上行主题上报POI列表、路线规划结果和导航确认状态。

工作线程层：MQTT回调收到指令后，不直接在回调中处理（避免阻塞网络栈），而是把任务投递到独立的工作线程。工作线程调用地图引擎接口执行实际的POI搜索和路线规划，再把结果构造成JSON通过MQTT发布。

业务处理层：解析JSON指令，调用地图模块提供的map_search_poi、map_select_poi、map_select_route等接口，完成从搜索到导航的完整闭环。

三、几个关键问题与解决

1. 回调被覆盖导致收不到消息

地图引擎初始化时会调用mqtt_set_inpub_callback，把我的回调覆盖了。解决方式是在地图加载完成后主动重置回调，用mqtt_reset_inpub_callback()把回调重新指向自己的处理函数。

2. MQTT订阅失败后不会自动恢复

mqtt_subscribe返回ERR_OK只表示请求进入队列，不代表Broker已确认订阅成功。我将订阅状态拆分为IDLE、PENDING、OK三态，在mqtt_request_cb中根据返回结果更新状态，保活线程只对未订阅状态发起重试。

3. lwIP Raw API的线程安全问题

mqtt_client_new和mqtt_client_connect属于lwIP Raw API，必须持有TCPIP核心锁或通过tcpip_callback调度到TCPIP线程执行。我用LOCK_TCPIP_CORE()包裹了所有lwIP API调用，避免偶发的连接失败或内存破坏。

4. 命令行发布时非法释放静态内存

自动上报路径传入的是cJSON_PrintUnformatted分配的堆内存，命令行发布传入的是静态全局对象的地址。我拆分了回调：自动上报用mqtt_publish_auto_cb（释放payload），命令行用mqtt_publish_cmd_cb（不释放arg），避免堆损坏。

四、调试与验证

开发过程中用MQTTX作为客户端工具模拟云端下发指令，串口打印完整的收发日志和JSON内容。WiFi连接和MQTT重连由保活线程自动维护，系统上电后约15秒内完成初始化。POI搜索、路线规划、导航启动的完整链路已跑通，单个关键词（如“网咖”）能正常走完流程。

五、总结

嵌入式环境下的MQTT开发，除了协议本身，还要特别注意线程模型、资源管理和异步回调的时序问题。lwIP的Raw API虽然高效，但对调用上下文有严格要求；订阅状态管理看似简单，但异步确认机制容易踩坑。把这些基础问题处理好，MQTT通信的稳定性能得到保障。

项目代码已合入wkx分支，后续会配合地图模块完成更多场景的联调验证。