本页用于查参数和返回值。第一次接入请从首次连接开始。头文件为 include/moto_freertos/terminal.h，支持 C / C++。
先看懂示例里的名称
| 名称 | 含义 |
|---|---|
t / terminal |
moto_terminal_create 创建的 SDK 实例 |
e / saved_event |
SDK 发给应用的一条事件；需要异步处理时复制整个结构体 |
connection |
本次蓝牙连接编号，断开重连后会变化 |
session |
本次安全会话编号；回报结果时使用原事件的编号 |
port |
由你实现、供 SDK 调用的硬件驱动接口 |
下表的函数名省略共同前缀 moto_terminal_。例如 start(t) 的完整写法是 moto_terminal_start(t)。尺寸用像素，时间用毫秒，码率用 bit/s。
初始化与关闭
按 config_init → create → start 启动，按 stop → destroy 释放。
| 调用 | 用法 |
|---|---|
config_init(&c) |
填写默认值；先调用，再修改配置 |
create(&c, &t, &error) |
校验配置、授权和存储；失败时 t 为 NULL，查看 error |
start(t) |
启动 SDK 任务；成功后再接收蓝牙输入 |
stop(t, timeout_ms) |
请求停止并等待；返回 AGAIN 时尚未结束，需要继续等待 |
destroy(t) |
停止所有调用者后释放；仍运行或停止中会返回 BUSY |
get_status(t) |
取得运行、认证、连接、功能配置及最近错误的副本 |
上述生命周期操作由同一个管理任务负责，不在驱动回调里调用。所有 API 都从任务调用，不从中断调用。关闭 SDK 不会删除授权和绑定记录。
必填配置与驱动
moto_terminal_config_init 会填写结构大小和接口版本，不手动修改 struct_size、abi_version。
| 字段 | 填什么 |
|---|---|
hardware_revision |
硬件版本，1–64 字节 |
firmware_version |
主.次.修订，每段 0–65535，不带前导零 |
width / height |
屏幕宽高；无显示时都填 0 |
rotation |
0、90、180 或 270，默认 0 |
port.user |
驱动上下文指针；保留到 SDK 销毁后 |
port.load_license |
读出 512 字节授权、65 字节硬件标识缓冲区、65 字节公钥；成功返回 0 |
port.ble_send |
复制数据后返回实际接收字节数；0 为暂忙，负数为失败 |
port.ble_close |
请求断开指定连接；不阻塞等待断开完成 |
FreeRTOS 接入还需提供下列存储、随机数和时钟接口；若目标平台接入包已提供适配，按包内说明复用：
| 字段 | 要求 |
|---|---|
port.read_pairing |
原样读出记录；无记录时输出长度 0；损坏或读取失败返回非 0 |
port.write_pairing |
原样写入；持久化成功后返回 0，与 read_pairing 成对使用 |
port.random |
填满指定长度的安全随机字节，成功返回 0 |
port.now_ms |
线程安全的单调毫秒计时，不使用日期时间 |
可选功能配置
| 字段 | 默认值与限制 |
|---|---|
phone_state |
true；手机主题、电量 |
notifications |
false；接好 Android 通知显示后开启 |
calls |
false；接好通话驱动后开启 |
ancs / ancs_ready |
默认关闭；开启时提供 iOS 系统通知实际订阅状态回调 |
h264 / mjpeg |
默认关闭；各自填写 enabled、fps、bitrate；fps 为 1–30，bitrate 大于 0 |
ota |
默认关闭；填写实际升级驱动 moto_ota_port |
wifi_ota |
false；开启前须配置 ota.handle |
大屏导航同时接入视频和 HUD；仅在屏幕很小、无法投屏时只接 HUD 并关闭视频能力。视频宽高必须为非零偶数，宽不超过 1920、高不超过 1080。只开启已接通的解码格式。
蓝牙收发与取事件
| 调用 | 返回值和注意事项 |
|---|---|
advertising(t, out) |
out 至少 31 字节；得到完整广播内容 |
connected(t, &connection) |
生成非零连接编号；保存到蓝牙驱动上下文 |
disconnected(t, connection) |
通知 SDK 断开；旧编号返回 STATE |
receive(t, connection, bytes, size) |
每次 1–512 字节；OK 表示全部复制，FULL 表示完全未接收 |
next_event(t, &e, timeout_ms) |
一个任务负责取事件；0 表示不等待，无事件返回 AGAIN |
驱动回调应快速返回；较慢的车辆操作、屏幕刷新交给对应任务。完整接线见蓝牙连接。
收到什么事件
下面名称除 MOTO_TERMINAL_EVENT_ERROR 外均省略 MOTO_EVENT_ 前缀。
| 事件 | 读取字段 / 处理方式 |
|---|---|
PAIRING_PIN |
value 为四位 PIN，target 为有效秒数 |
PAIRING_CLEARED / PAIR / UNPAIR |
清理或更新配对界面 |
READY / AUTHENTICATED |
加密通道就绪 / 设备主人已认证；业务能力仍由后台配置决定 |
PHONE_STATE |
data.phone：主题、电量、充电状态 |
NAV_BEGIN / NAV_END |
data.object.id：导航编号；本地结束可能为 0 |
HUD / HUD_EXPIRED |
data.hud：转向和距离；过期后清除旧提示 |
WIFI / WIFI_STOP |
data.wifi.purpose：0 为视频、1 为升级；停止时释放网络资源 |
STREAM_PREPARE / STREAM_START |
data.stream：流编号、尺寸、格式、帧率、码率 |
STREAM_STOP |
停止视频处理及旧帧提交 |
VEHICLE_COMMAND |
message / target / value：命令、对象、操作值 |
NOTIFICATION |
data.notification：编号、有效期、允许动作、应用、标题和正文 |
NOTIFICATION_REMOVE / FAULT_ACK |
data.object.id：通知或故障编号 |
CALL / CALL_ACTION |
data.call 为通话状态；data.call_action 为待执行操作 |
ACTION_RESULT |
data.action_result.status / reason；用 request 匹配请求 |
ANCS_SHARING |
value 表示分享意图，不表示 iOS 已授权订阅 |
REPORT_DROPPED |
request 为未送达的故障报告编号 |
CLOSED |
清除 PIN、视频和临时会话资源 |
MOTO_TERMINAL_EVENT_ERROR |
data.error.stage / code；详细原因用 get_status 查看 |
observed_ms 是 SDK 处理事件的时间；deadline_ms 是最晚执行时间，0 表示没有截止时间。硬件任务执行前检查截止时间和连接，避免执行已经失效的旧命令。
回报结果与上报数据
这些接口的 OK 表示已入队，FULL 表示尚未入队。FULL 时保留参数后重试；异步失败通过错误事件或状态返回。
| 调用 | 何时使用 |
|---|---|
complete(t, &e, result, reason) |
回报控车、通话操作、视频准备的结果；result 为 SUCCEEDED 或 FAILED，只有控车允许 UNKNOWN；reason 为驱动错误码 |
wifi_ready(t, &e, &ap) |
视频热点准备成功；ap 填实际 SSID、密码、IP 和端口 |
wifi_ota_ready(t, &e, &ap, psk) |
升级热点准备成功；psk 为本次生成的 32 字节随机密钥 |
report_state(t, &state) |
上报当前完整车况，见控车与车况 |
report_fault(t, id, active, module, code, severity) |
上报故障出现或解除；id 非零，module 长 1–64 字节，severity 为 0–3 |
report_call(t, id, state, actions) |
上报实际通话状态，id 非零；状态与动作值见通知与通话 |
presented(t, session, stream_id, frame_id) |
LCD 实际显示一帧后确认，使用原流的编号 |
keyframe(t, session, stream_id) |
H.264 解码需要新的关键帧时请求 |
notification_action(t, &e, action) |
使用保存的通知事件；0 为正向动作，1 为负向动作，需通知允许 |
call_action(t, &e, action) |
使用保存的有效通话事件；0 接听、1 拒接、2 挂断 |
热点失败用 complete(..., MOTO_FAILED, reason)；成功用对应的 ready 接口。
返回值怎么处理
下列常量均带 MOTO_ 前缀。
| 返回值 | 含义 | 下一步 |
|---|---|---|
OK (0) |
本次调用成功 | 提交类接口继续等待实际处理结果 |
AGAIN (1) |
暂未完成 / 无事件 | 等待后继续 |
INVALID (-1) |
参数错误 | 对照字段与范围修改 |
BUSY (-2) |
当前操作冲突 | 等已有操作结束 |
AUTH (-3) |
认证失败 | 检查授权或配对 |
STATE (-4) |
连接或调用时机失效 | 停止旧会话操作 |
UNSUPPORTED (-5) |
功能未支持 | 核对型号配置与库版本 |
EXPIRED (-6) |
请求已过期 | 取消旧操作 |
IO (-7) |
读写或初始化失败 | 查看错误阶段 |
FULL (-8) |
队列已满，本次未接收 | 保留数据，稍后重试 |
错误阶段用 moto_terminal_stage_name(error.stage) 输出，返回值用 moto_terminal_result_name(error.code) 输出。error.detail 是库管理的静态文本，不需要释放。按现象排查见常见问题。
高级配置与内存
首次接入保留这些默认值；出现明确资源问题时再调整。
| 字段 | 默认值 / 范围 |
|---|---|
rx_slots |
16 / 1–128；每项最多 512 字节 |
command_slots |
16 / 1–64 |
event_slots |
8 / 2–64；长时间不取事件会导致会话关闭 |
task_stack |
保留目标接入包的初始化值；修改前确认单位是字节还是 StackType_t 元素个数 |
task_priority |
5；小于 configMAX_PRIORITIES |
标准提交接口会复制参数；配置中的驱动上下文指针不会深拷贝，需要你保持有效。增加队列深度会增加内存占用，视频缓冲另由 moto_video_config 配置。
高级接口 moto_terminal_post(t, session, job, payload, size) 可将最多 256 字节数据提交给 SDK 任务。回调原型为 moto_result job(moto_sdk *sdk, const void *payload, size_t size)；回调不能阻塞、保留 sdk 指针或销毁 SDK，也不会自动重试。结构体里的指针只复制地址；session 为 0 仅用于本地管理。一般业务使用上面的专用接口即可。