仪表导航投屏与 HUD 接入｜FreeRTOS SDK

大屏同时接入导航投屏和 HUD；屏幕太小、无法导航投屏时，才只用 HUD。 两者不是二选一。接入前先完成 FreeRTOS 终端的蓝牙配对，并在后台型号中开启对应功能。

按屏幕能力接入

仪表条件	接入内容	硬件要求
可显示完整导航画面的大屏	导航投屏 + HUD	BLE、Wi-Fi 热点、视频解码器、屏幕
屏幕很小，无法导航投屏	仅 HUD：转向、路名和距离	BLE、屏幕

导航投屏通过 Wi-Fi 接收手机生成的地图画面；HUD 通过 BLE 接收转向、距离等数据，由仪表 UI 绘制，不包含地图底图。大屏接好两条链路，具体布局由仪表 UI 决定；投屏期间仍要持续处理 HUD 事件。

大屏按下文完成 HUD 和视频两部分；无法投屏的小屏完成 HUD 部分，保持视频能力关闭。

大小屏都要在应用事件循环中处理以下事件。大屏的视频解码放到独立任务，不阻塞 HUD 更新：

事件	界面操作
`MOTO_EVENT_NAV_BEGIN`	进入导航界面
`MOTO_EVENT_HUD`	用 `e.data.hud` 更新转向、距离和路名
`MOTO_EVENT_HUD_EXPIRED`	隐藏过期的转向提示
`MOTO_EVENT_NAV_END` / `MOTO_EVENT_CLOSED`	退出导航，清除旧提示

e.data.hud 常用字段：action 为转向动作，distance_m 为距下次转向的米数，remaining_m / remaining_s 为剩余米数和秒数，road / next_road 为当前及下一条路名。

**验证：**手机开始导航后仪表更新；结束导航或断开连接后，旧箭头消失。

大屏完成 HUD 接入后，在创建 SDK 前配置实际可用的解码器。例如支持 MJPEG 的 1024×600 屏幕：

c.width = 1024;
c.height = 600;
c.mjpeg.enabled = true;
c.mjpeg.fps = 13;
c.mjpeg.bitrate = 12000000; // bit/s

这是参数示例，帧率要按开发板的实际显示能力填写。支持 H.264 时配置 c.h264。启用的视频格式必须填写 1–30 FPS 和正数码率；宽高为非零偶数，不超过 1920×1080。

e 是收到的原事件；异步完成时使用之前保存的那一份。

收到的事件	开发板要做什么	完成后调用
`MOTO_EVENT_WIFI`，`purpose=0`	开热点，让手机能连上；设置 IP、DHCP、UDP 端口	`moto_terminal_wifi_ready(t, &e, &ap)`
`MOTO_EVENT_STREAM_PREPARE`	按 `e.data.stream` 的尺寸和编码格式准备解码器、收包及显示缓冲	`moto_terminal_complete(t, &e, MOTO_SUCCEEDED, 0)`
`MOTO_EVENT_STREAM_START`	开始接收本次视频，保存 `e.session` 和 `stream_id`	等屏幕真正显示一帧后再确认
`MOTO_EVENT_STREAM_STOP`	停止收包、解码和显示提交	清理本次视频资源

STREAM_STOP 只结束视频流，不代表导航结束，不要据此清除仍有效的 HUD。收到 HUD_EXPIRED 时清除过期提示，收到 NAV_END 或 CLOSED 时清理导航界面。

热点在 30 秒内准备好，视频准备在 10 秒内完成；失败用 complete(..., MOTO_FAILED, reason) 回报。purpose=1 是固件升级请求，不进入视频流程。

ap 是 moto_terminal_hotspot：填实际 SSID（1–32 字节）、密码（8–63 字节）、IP 和 UDP 端口。当前 APP 导航投屏使用 192.168.4.1:5001。热点可连接后再回报，不在日志中输出密码。

使用 moto/video.h 的视频重组器，把多个 UDP 包拼成完整压缩帧，再交给你的解码器：

UDP 收包 → moto_video_receive → 完整帧回调
→ MJPEG / H.264 解码 → LCD 显示完成 → moto_terminal_presented

先用 moto_video_create 创建重组器；STREAM_START 后用 moto_video_begin_codec 设置本次视频参数。
同一个视频任务调用 moto_video_receive，并每 10–20 ms 调用 moto_video_tick。单个 UDP 包最多 1400 字节，保持包边界。
Socket 层核对本次手机的源 IP/端口。视频 UDP 不加密，不对公网开放。
完整帧的内存只在回调内有效。异步解码时复制到自己的缓冲区。
LCD 真正显示后，调用 moto_terminal_presented(t, saved_session, stream_id, frame_id)。收包或解码完成时都还不能算显示成功。

H.264 缺关键帧时调用 moto_terminal_keyframe 请求恢复。停止、结束导航或断连后，取消旧流，忽略其迟到的解码回调。