先核对交付包的 BUILD_INFO.json 和 SHA256SUMS，再替换工程依赖。不要只凭“SDK 1.0.0”判断两个 ZIP 可以混用。
四个版本号分别表示什么
| 字段 | 当前基线 | 用途 |
|---|---|---|
sdk_version |
1.0.0 |
SDK 产品版本 |
freertos_abi |
8 |
FreeRTOS C 接口布局与链接符号版本 |
package_revision |
27 |
整套头文件、静态库和适配组件的交付修订 |
documentation_revision |
见所收包 | 文档修订；不单独表示二进制或 ABI 变化 |
CPU、编译器 ABI、IDF/FreeRTOS 和 Mbed TLS 配置仍须匹配。ABI 相同也不代表任意 package revision 的核心结构体可混用；始终使用同包的头文件、两个静态库及组件配置。config_init/create/next_event 的 _v8 符号用于阻止部分混用，不是对所有核心接口的运行期兼容保证。
影响接入的变更
| 基线 | 需要关注的变化 |
|---|---|
| revision 13 / ABI 7 | SDK 网络入口管理发现、监听、连接代次和背压；配置 network 后不再手动调用托管 connected/receive/disconnected |
| revision 14 / ABI 8 | 能力数变为 13，车辆状态数组为 13 项；新增车辆电源和 BLE 感应解锁；核心通知增加独立快照提取接口 |
| revision 15 / ABI 8 | 独立座桶能力 bit13，单次开盖59；能力14项，状态13项，结构布局不变 |
| revision 16 / ABI 8 | PROFILE key34 与 CAPS_GET key0 显式能力协商；未知可选位不影响连接，签名及授权保持严格 |
| revision 17 / ABI 8 | 创建时校验 OTA 端口；明确 Managed/Core 能力边界并提供迁移步骤，接口布局不变 |
| revision 14 的文档修订 | 按功能拆分指南并补充接入说明；只有校验确认头库相同时，才可按纯文档更新处理 |
| revision 20 / ABI 8 | navigation.control bit14，新增终端导航动作及归属明确的回执，见导航 |
| revision 21–22 / ABI 8 | audio.a2dp.sink bit15、audio.wifi bit16 与音频能力协商；revision 22 增加 Core 音频 sink 和独立接收链路 |
| revision 23 / ABI 8 | moto_terminal_set_audio 启动前配置，以及共用的 moto_audio_server 接收器，见音频 |
| revision 24 / ABI 8 | moto_terminal_set_mirror 开放 Managed 独立镜像；公开结构布局不变，见投屏 |
| revision 25 / ABI 8 | Core 地图端口新增 commit_vector，PROFILE key38 协商 RVP1/RVZ1 道路窗口；须重编所有调用方，见离线地图 |
| revision 26 / ABI 8 | PROFILE key39 与 moto_resume_mirror() 支持镜像期间主业务恢复，公开结构布局不变；见更新日志 |
| 1.0.0 / revision 27 / ABI 8 | 配套 App SDK 1.0.0；恢复必须使用新 connectionId；交付包记录源码提交与完整校验清单 |
当前 APP 使用 r25 道路矢量链路。r24 及更早的图片地图固件需接入 commit_vector 后才能接收；不能只更新头文件或把 RVS1 手机区域文件直接发给仪表。FreeRTOS ABI 仍为 8，不表示 Core 的 moto_map_port 布局未变。
电源是能力 bit 12、状态 field 12；感应解锁是能力 bit 11，状态 field 11 仍为续航米数。地图端口早于此次 ABI 8 更新，仍走核心接口；不能因为 ABI 8 就假定托管入口已有地图端口。
当前连接基线
revision 16 要求 App 在认证后读取 PROFILE key34，并在 CAPS_GET key0 声明认识的 uint32 能力位。SDK 返回当前可用能力与客户端声明的交集。签名配置和 License 原文先验签再忽略未知可选位；客户端声明不能扩大授权。当前 App 与 SDK 均实施此唯一流程，缺少必填字段直接报协议错误，不回退旧报文。后续新增可选能力沿用协商规则，不改变既有位含义。
从 Managed 扩展或迁移到 Core
Managed（moto_freertos/terminal.h）封装 Core（moto/sdk.h），提供单条主业务会话、SDK 所有者任务、命令队列和事件副本。Core 适用于完整仪表的多通道集成，由应用统一驱动实例。moto_network 在 Core 路径也能管理发现、监听、背压和连接清理；选 Core 不要求重新实现这些网络策略。
先判断扩展范围
| 需求 | 处理方式 |
|---|---|
| 已开放的路线/位置、音乐、仪表、OTA 或广告端口 | 继续 Managed，在 create 前配置端口与真实驱动 |
| Wi-Fi 音频或独立镜像 | 继续 Managed，create 后、start 前配置 moto_terminal_set_audio / moto_terminal_set_mirror；镜像要求 config.network 和真实视频能力 |
| 在现有实例上调用已配置功能的 Core API | 使用 moto_terminal_post，由 SDK 任务执行非阻塞 job |
| 当前 APP 的 Android 通知、iOS ANCS 或感应解锁 | Core 主业务 + 独立 BLE 辅助实例；ANCS 另接 GATT 适配 |
| RVP1/RVZ1 底图或同 owner 的候选连接接管 | Core 对应端口和实例编排；post 不补齐缺失的实例配置 |
post 复制最多 256 字节参数，在回调外调用 job(moto_sdk *, payload, size)；非零 session 在入队和执行时核对，0 仅用于本地初始化/清理。不得保留或销毁传入的 SDK，不得阻塞；指针指向的数据不深拷贝，job 不自动重试。它不提供实例挂接、重新配置或共享 owner 接口，不能作为“Managed 主业务旁边直接启动一个 Core BLE/mirror 实例”的完整接入方案。
可以保留的工作
| 已完成的部分 | 切换后的处理 |
|---|---|
| 无线/AP/IP、网络原语和链路 generation | 复用 moto_network_port 与板级驱动，交给 Core 的网络 runtime |
| 显示、视频解码、车辆执行器及其业务逻辑 | 保留；调整 SDK 事件到驱动的适配，以及结果返回入口 |
| OTA、广告和仪表端口 | 复用 moto_ota_port、moto_ad_port、moto_instrument_port，确认回调线程与上下文寿命 |
| 事件队列与完成回执 | Core 回调内复制数据，保留来源实例、connection/session/request 和截止时间；结果回到原实例 |
| 绑定存储和连接生命周期 | 按新架构重新接线；不能复用旧句柄或直接复制不透明记录 |
迁移顺序
- 先保留现有 BSP、UI、车辆及媒体驱动，在独立构建目标中建立 Core 单主业务。复用真实 License、随机源、时钟和网络原语，配置
moto_tls、moto_config与moto_network。不要同时启动两个工程争用同一主监听和驱动。 - 设置一个所有者任务。由它串行驱动 Core 实例及共享 owner 快照；
moto_network_poll已驱动绑定的主业务/镜像实例，不再对它们重复 poll。BLE 输入与 poll 也交回同一任务。 - 在 Core 回调中复制所需数据到有界应用队列。
moto_event的指针只借用到回调返回，moto_terminal_event则是托管队列的自持副本；不能强制转换二者。通知用moto_event_get_notification提取快照。UI/车辆任务只执行一次，回执保留原来源和会话。 - 验证主业务后，再逐项加入 BLE 辅助、地图端口或镜像实例。共享 owner 只在持久提交成功后更新；各连接保留独立 TLS 和代次。辅助通知断开不清理主导航；镜像按独立授权及失效规则收尾。
- 切换前停止输入生产者、事件消费者和异步驱动回执；对 Managed 重试 stop 直至 OK，再 destroy。随后启动 Core 构建目标，重新建立会话，不携带旧会话任务。
绑定记录需要单独处理：Managed 当前为 72 字节不透明记录，P4 Core 示例为 67 字节；SDK 当前没有公开的双向转换器。开发样机先确认云端解绑和实物本地撤权均已完成，再按已验证的存储初始化方案在目标固件重新绑定。已绑定设备若需要保留 owner，必须先取得并验证明确的存储转换方案，不能按字节数猜格式或通过擦除 NVS 强行迁移。详见 持久化。
验收覆盖主业务重连、独立 BLE 通知/ANCS 就绪、各通道断连隔离、旧会话回执、队列满与重试、owner 撤销及存储失败；启用镜像时还需验证主连接意外丢失与显式停止。复用比例取决于原驱动与调度耦合程度，不预设返工百分比。
从 ABI 7 迁移到 ABI 8
- 保存旧包、固件、工程配置和受控存储备份，记录当前二进制与文档修订；先在开发设备验证。
- 将旧 SDK 依赖目录移出构建搜索路径。导入新包全部头文件、
libmoto_sdk.a、libmoto_freertos.a、组件及配置校验，不只覆盖.h。 - 使用
moto_terminal_config_init；事件、状态与配置缓冲按新类型的sizeof和公开常量分配，清除写死的旧数组长度。修正_v7显式引用。 - 若接车辆电源，显式分派
MOTO_POWER_SET。若接感应锁，配置独立 BLE 核心实例及校准存储，并将结果交回原实例。未接入的功能保持关闭。 - 核心通知在回调内调用
moto_event_get_notification复制快照；托管事件本身已按值复制。保留来源、会话和接收时间。 - 清理旧构建缓存后重新编译、链接。ESP-IDF 使用
idf.py fullclean后idf.py build；构建清理不等于擦除设备 Flash。 - 核验首次配对、保留 owner 的升级重连、完整车况、旧会话取消与目标功能。版本和 capability 不匹配时报告错误，不绕过包内检查。
P4 公开工程的配套包以所选提交的 docs/VALIDATION.md 和导入校验为准，不能仅因本文基线为 revision 26 就假定默认分支已同步。导入方式见参考工程；道路矢量、音频与镜像接口须同时取得对应接线和匹配包。
存储与回退
当前托管格式为 72 字节，ABI 7 对应版本已使用该格式；不是 ABI 8 新增的存储布局。兼容读取 35/67 字节不代表所有旧固件能读取当前记录，也不代表 P4 核心示例可直接换成托管存储。
回退时同时恢复匹配的头库和固件，先检查目标旧版本的记录解析、能力配置和功能支持。清除已启用的新增功能或恢复存储必须走经验证的产品流程；保留新 owner 状态，不能用旧备份把已撤销用户重新授权。详细边界见 持久化。