English | 简体中文
独立嵌入式硬件 SDK：开发预览
当前状态
这是一份开发方向和接口边界说明。开发预览源码、独立示例及构建入口见 firmware/sdk。尚无稳定发布版本和完整实机 STM32/Himax 配对验收；请勿将预览当作稳定版。
目前可用的开发入口仍是 Python SDK。固件和客户端的已有发行 资产见 Release。
两种开发方式
| 方式 | 运行位置 | 开发者控制的内容 | 状态 |
|---|---|---|---|
| Python SDK | 电脑端 | 基于已有设备固件编写应用 | 已有公开入口，见 SDK 指南 |
| 嵌入式硬件 SDK | ESP32-S3 | 自己的 app_main、UI、交互及硬件调用 | 源码开发预览，尚未正式发布 |
嵌入式 SDK 的目标是脱离官方应用运行，不要求 Python SDK、Daemon 或服务端。 它不改变现有 Python SDK/Daemon/Application 架构。
首版目标能力
| 模块 | 目标接口 |
|---|---|
| 身体运动 | 目标角度（度）、运动时间、停止；完成、拒绝、故障事件 |
| 身体灯光 | 分区颜色、亮度和基础灯效 |
| 身体触摸 | 按下、释放、长按的有序事件流 |
| 摄像头 | PTL 后端，单次拍照、连续 JPEG 取帧、停止与状态 |
| 麦克风与扬声器 | PCM 采集、播放、音量与格式配置 |
| 屏幕与屏幕触摸 | 标准 LCD/LVGL/触摸句柄及访问保护 |
组件按模块可选，统一使用 watche_hw_* 命名；开发者编写自己的业务。 首版不包含语音助手、云连接、官方表情系统、AI 推理和模型管理。 目标工具链为 ESP-IDF 6.0.2、ESP32-S3，必要依赖固定版本。
运行层负责 MCU 握手、事件采集、状态转换和断线处理；应用通过订阅接收 事件。运动提交成功不等于运动完成，未就绪应拒绝控制，重连不重放旧运动。 回调只处理轻量事件，耗时业务放到应用任务；JPEG 缓冲生命周期和显示锁 等资源合同必须在正式 SDK 文档中明确。
独立示例目标
- 身体：触摸改变灯光，用户触发小幅运动，打印完成或故障事件。
- 头部：简单 LVGL 页面、屏幕触摸、JPEG 拍照、短时 PCM 录音与回放。
- 整机：组合上述能力，展示模块共同运行和资源所有权。
基础示例不依赖 SD 卡或模型资源。开发者只修改示例应用代码，不必启动 官方固件顶层工程，也不要求修改 STM32/Himax 固件。
烧录与安全边界
正式交付必须分别说明首次准备 STM32/Himax、日常只烧录自定义 ESP32、 恢复官方整机固件三个流程。
当前 烧录指南描述的是官方整机流程；现有工具可能写入 官方 ESP32 应用，不能用于保留自定义应用。自定义工程也可能改变分区并 覆盖存储。预览的构建与自定义烧录入口见 SDK 入门说明， 操作前请阅读其中的备份要求和配对固件限制；稳定版仍需完整实机验收。
断线后不能保证 ESP32 仍能发送停止命令，安全停止依赖 STM32 侧机制。 运动示例必须经过限位、小幅运动和停止验收，不能把构建通过当作安全证明。
公开发布门禁
- 确认公开源码交付方式、许可证和固定 Git 版本；同步仓库开源范围说明。
- 从干净 checkout 验证工具安装、三个示例构建及仅修改应用代码的流程。
- Windows/Linux 主机测试和固定 IDF CI；回归官方固件。
- 实机验收运动、灯光、三类身体触摸、JPEG 解码、PCM 录放音、屏幕触摸 和整机组合；缺失或不兼容模块不得挂死或无意驱动电机。
- 记录 SDK 版本、STM32 版本、Himax 镜像校验值、板卡版本和验收证据。
- 验证自定义烧录与官方恢复流程，并提供语义一致的 PowerShell/Shell 入口。
头部和身体全部通过前不发布首版；本文不承诺发布日期。