小鸿 SE AI 星闪智能门锁平台

小鸿 SE AI 星闪智能门锁平台是一套面向 HarmonyOS PC、小鸿 SE 双芯片开发板和本地 AI 视觉能力的端到端智能门锁 Demo。系统由 HarmonyOS Flutter 管理端、WS63 星闪通信固件、ESP32-P4 视觉固件 三部分组成：ESP32-P4 采集摄像头画面并执行 ESP-DL 人脸检测，WS63 通过板内 UART 获取状态与 JPEG，再通过 NearLink SLE/SSAP 将数据发送到 HarmonyOS PC。

当前仓库已经裁剪掉与智能门锁运行无关的通用示例、其他平台壳、Wi-Fi/HTTP/WebSocket、云端 Agent 和无关模型，只保留门锁应用、双芯片固件、必要 BSP、ESP-DL 推理子集、人脸模型与通信文档。App 的门锁协议核心由 Rust 实现，经 flutter_rust_bridge（FRB）同步暴露给 Dart；星闪本身只有 ArkTS NearLinkKit 接口，因此 ArkTS 保留为纯运输层。

小鸿 SE 开发板

当前实机链路已经验证：HarmonyOS PC 能通过星闪连接 WS63，订阅 SSAP 通知，持续查询人脸检测状态并接收由 ESP32-P4 生成的 JPEG 实时画面。TTL Type-C 只用于烧录和串口日志，不承载 App 与门锁之间的运行数据。

项目目标
系统思维导图
总体架构
组件职责
端到端数据流
星闪连接时序
通信协议速查
仓库结构
环境要求
快速开始
构建 ESP32-P4 固件
构建 WS63 固件
构建与安装 HarmonyOS App
硬件烧录
运行与验收
故障排查
测试与开发约束
安全与许可证
已知边界

项目目标

本项目聚焦一条可以在真实小鸿 SE 硬件上运行的门锁链路：

ESP32-P4 初始化摄像头、LCD、触摸、PSRAM 和 ESP-DL 人脸检测。
ESP32-P4 将检测状态、人脸框和最新 JPEG 通过板内 UART 发送给 WS63。
WS63 对 UART 数据做校验、状态缓存和完整 JPEG 双缓冲。
WS63 广播星闪设备 xiaohong_se_lock，提供 SSAP 服务 0x2222/0x2323。
HarmonyOS PC App 申请星闪权限，完成扫描、配对、连接、订阅和数据收发。
Flutter 页面展示实时画面、人脸数量、推理耗时、检测框和当前会话访客记录。

系统刻意不引入服务器、数据库和 IP 网络。门锁数据默认只在开发板与当前 HarmonyOS PC 会话之间流转。

系统思维导图

mermaid

mindmap
  root((小鸿 SE AI 智能门锁))
    HarmonyOS PC
      Flutter 管理界面
        实时监控
        访客记录
        设备与星闪
      Dart 网关
        FRB 会话驱动
        tick 轮询
        事件分发
      Rust 协议核心
        XH v1 编解码
        JPEG 分片重组
        数据完整性校验
      ArkTS 运输层
        NearLink 权限
        扫描与配对
        SSAP 写入与通知
    WS63
      SLE 广播
        xiaohong_se_lock
      SSAP Server
        Service 0x2222
        Property 0x2323
        CCCD 0x2902
      UART AI Bridge
        状态快照
        JPEG 双缓冲
        请求序号关联
    ESP32-P4
      摄像头采集
      ESP-DL 人脸检测
      JPEG 编码
      LCD 与触摸
      UART 0x0Cxx 协议
    工程交付
      P4 固件
      WS63 fwpkg
      HarmonyOS signed HAP
      协议与烧录文档

总体架构

mermaid

flowchart LR
  subgraph PC[HarmonyOS PC]
    UI[Flutter Dashboard\n实时画面 / 检测 / 访客记录]
    GW[Dart Gateway\ntick 轮询 / 字节搬运 / 事件分发]
    CORE[Rust Core via FRB\nXH v1 协议 / 状态机 / JPEG 重组]
    HOST[ArkTS EntryAbility\nNearLinkKit 运输层 / MethodChannel]
    UI --> GW
    GW <-->|FRB 同步调用| CORE
    GW <-->|MethodChannel\nBase64 二进制包| HOST
  end

  subgraph RADIO[无线星闪链路]
    SLE[SLE / SSAP\nService 0x2222\nProperty 0x2323]
  end

  subgraph BOARD[小鸿 SE 开发板]
    subgraph W[WS63]
      SERVER[SSAP Server\n通知订阅 / 请求解析]
      BRIDGE[UART AI Bridge\n状态快照 / JPEG 双缓冲]
      SERVER <--> BRIDGE
    end
    subgraph P[ESP32-P4]
      UART[P4 UART Service]
      AI[ESP-DL 人脸检测]
      CAM[Camera / JPEG]
      LCD[LCD / Touch]
      CAM --> AI
      CAM --> LCD
      AI --> UART
      CAM --> UART
    end
    BRIDGE <-->|板内 UART\n0x0C01 - 0x0C05| UART
  end

  HOST <-->|NearLink SLE / SSAP| SLE
  SLE <-->|无线| SERVER

分层关系

text

┌──────────────────────────────────────────────────────────────┐
│ Flutter UI：实时监控、访客记录、设备连接、错误提示          │
├──────────────────────────────────────────────────────────────┤
│ Rust Core（FRB）：XH v1 包、序号、状态机、JPEG 连续性校验    │
├──────────────────────────────────────────────────────────────┤
│ Dart Gateway：FRB 会话驱动、tick 循环、事件分发              │
├──────────────────────────────────────────────────────────────┤
│ ArkTS Host：NearLink 权限、扫描、配对、SSAP Client、通知     │
├──────────────────────────────────────────────────────────────┤
│ NearLink SLE/SSAP：0x2222 / 0x2323 / CCCD 0x2902             │
├──────────────────────────────────────────────────────────────┤
│ WS63 Bridge：命令转换、状态缓存、JPEG 双缓冲                 │
├──────────────────────────────────────────────────────────────┤
│ UART AI Protocol：0x0C01 - 0x0C05                            │
├──────────────────────────────────────────────────────────────┤
│ ESP32-P4：Camera、JPEG、ESP-DL、人脸框、LCD                  │
└──────────────────────────────────────────────────────────────┘

组件职责

组件	主要职责	不负责的内容
HarmonyOS Flutter UI	连接入口、实时画面、检测状态、访客记录、错误展示	不直接调用 NearLinkKit，不执行 AI 推理
Rust Core（FRB）	XH v1 包编码/解析、连接状态机、350 ms 状态轮询、120 ms 画面请求、JPEG 分片重组与校验	不调用星闪 API，不接触 UI
Dart Gateway	驱动 FRB 会话的 tick 循环、串行化 SSAP 写入、事件分发和异常转换	不解析门锁协议字节，不保存永久访客数据库
ArkTS EntryAbility	星闪权限、设备扫描、配对、连接、MTU、服务发现、SSAP 写入和通知	不解释门锁业务协议，不处理 JPEG，不做请求节拍
WS63 SSAP Server	广播、连接、CCCD 订阅、App 命令解析、响应分包	不采集摄像头，不执行人脸检测
WS63 UART Bridge	转发 P4 命令、缓存最新状态、组装完整 JPEG、双缓冲切换	不生成图像，不依赖 Wi-Fi
ESP32-P4	摄像头、JPEG、ESP-DL 推理、LCD/触摸、本机状态源	不直接连接 HarmonyOS App

端到端数据流

控制与状态流

mermaid

flowchart LR
  A[Rust 核心每 350 ms 生成 GET_STATUS] --> B[ArkTS writeProperty]
  B --> C[WS63 SSAP 收到 XH v1 包]
  C --> D[WS63 发送 UART 0x0C01]
  D --> E[ESP32-P4 返回 0x0C03 / 0x0C04]
  E --> F[WS63 更新 AI 状态快照]
  F --> G[SSAP STATUS 0x81 通知]
  G --> H[Rust 核心解析人脸框与延迟]
  H --> I[Flutter 刷新检测 UI 和访客记录]

实时画面流

mermaid

flowchart LR
  A[Rust 核心 GET_FRAME\nafter_sequence] --> B[WS63 检查最新完整 JPEG]
  C[ESP32-P4 Camera] --> D[JPEG 编码]
  D -->|UART 0x0C05\n最大 1024 B 分片| E[WS63 JPEG 双缓冲]
  E --> B
  B --> F[FRAME_BEGIN 0x83]
  F --> G[FRAME_CHUNK 0x84\n每块 JPEG 最多 220 B]
  G --> H[FRAME_END 0x85]
  H --> I[Rust 核心校验序号 / offset / FFD8 / FFD9]
  I --> J[Flutter Image.memory 显示]

WS63 只有在 UART 分片连续、长度合法且整帧完成时才替换“最新画面”。Rust 核心再次校验 SSAP 分片连续性、请求序号和 JPEG 首尾标记，任何半帧都不会提交给 UI。

星闪连接时序

mermaid

sequenceDiagram
  actor User as 用户
  participant UI as Flutter UI
  participant Dart as Dart Gateway
  participant Core as Rust Core
  participant ArkTS as ArkTS EntryAbility
  participant NL as HarmonyOS NearLink
  participant WS as WS63 SSAP Server
  participant P4 as ESP32-P4

  User->>UI: 点击“连接设备”
  UI->>Dart: connectToDevice()
  Dart->>Core: LockSession.connect()
  Dart->>ArkTS: scanAndConnect
  ArkTS->>NL: 请求 ACCESS_NEARLINK
  ArkTS->>NL: 扫描 xiaohong_se_lock
  NL-->>ArkTS: address / RSSI / connectable
  ArkTS->>NL: startPairing（未配对时）
  NL->>WS: SLE 配对
  WS-->>NL: pair_complete status=0
  ArkTS->>NL: SSAP connect + MTU 512
  ArkTS->>NL: getServices
  NL-->>ArkTS: 0x2222 / 0x2323 / CCCD
  ArkTS->>NL: setPropertyNotification(true)
  NL->>WS: 写 CCCD 01 00
  WS-->>NL: status=0
  Note over ArkTS,NL: HarmonyOS 6.1 可能在订阅已成功后仍返回 1009700099/-5
  ArkTS->>NL: 100 ms 后仅针对该错误重试一次
  ArkTS-->>Dart: address
  Core-->>Dart: GET_STATUS 0x01
  Dart->>WS: SSAP writeProperty
  WS->>P4: UART AI_GET_STATUS 0x0C01
  P4-->>WS: AI_STATUS / FACE_RESULT
  WS-->>Dart: SSAP STATUS 通知
  Dart->>Core: handlePacket()
  Core-->>UI: 更新实时状态

连接状态机：

mermaid

stateDiagram-v2
  [*] --> 未连接
  未连接 --> 扫描中: 点击连接
  扫描中 --> 配对中: 找到可连接门锁
  扫描中 --> 失败: 未发现设备 / 发现错误固件
  配对中 --> 连接中: 配对成功或已配对
  配对中 --> 失败: 取消 / 超时
  连接中 --> 已连接: 服务发现并启用通知
  连接中 --> 连接中: 1009700099/-5 且物理连接仍有效 / 重试
  连接中 --> 失败: 其他 SSAP 错误
  已连接 --> 检测中: 启用上报和画面轮询
  检测中 --> 已连接: 停止检测
  已连接 --> 未连接: 主动断开 / 链路断开
  检测中 --> 未连接: 链路断开
  失败 --> 未连接: 重试

通信协议速查

完整字段定义以星闪与 UART 通信协议为准。

App 与 WS63：XH v1 over SSAP

广播名：xiaohong_se_lock
SSAP Service UUID：0x2222
SSAP Property UUID：0x2323
CCCD UUID：0x2902
字节序：little-endian
单个 SSAP 包上限：240 字节
JPEG 数据块：220 字节

每个包使用 10 字节头：

偏移	字段	长度	固定值/含义
0	`magic`	2	`58 48`，ASCII `XH`
2	`version`	1	当前为 `0x01`
3	`type`	1	命令或响应类型
4	`request_sequence`	4	请求序号，用于关联响应
8	`payload_length`	2	后续负载长度
10	`payload`	N	命令或响应数据

方向	类型	名称	作用
App -> WS63	`0x01`	`GET_STATUS`	查询最新 AI 状态
App -> WS63	`0x02`	`SET_REPORTING`	启停 P4 人脸结果上报
App -> WS63	`0x03`	`GET_FRAME`	获取指定序号之后的最新 JPEG
WS63 -> App	`0x81`	`STATUS`	返回人脸数、框、置信度、尺寸和推理耗时
WS63 -> App	`0x83`	`FRAME_BEGIN`	声明帧序号、尺寸和 JPEG 总长度
WS63 -> App	`0x84`	`FRAME_CHUNK`	按连续 offset 返回 JPEG 分片
WS63 -> App	`0x85`	`FRAME_END`	标记完整帧或暂无新帧
WS63 -> App	`0xFF`	`ERROR`	请求格式、未知命令或画面发送错误

WS63 与 ESP32-P4：UART AI 协议

命令	名称	方向	作用
`0x0C01`	`AI_GET_STATUS`	WS63 -> P4	请求当前 AI 状态
`0x0C02`	`AI_SET_FACE_REPORTING`	WS63 -> P4	启停检测结果主动上报
`0x0C03`	`AI_STATUS`	P4 -> WS63	返回检测器、尺寸和状态
`0x0C04`	`AI_FACE_RESULT`	P4 -> WS63	返回人脸框、置信度和推理耗时
`0x0C05`	`AI_CAMERA_FRAME_CHUNK`	P4 -> WS63	分片传输最新 JPEG

UART AI 负载以 ai_version:u16 和 request_sequence:u32 开头，当前版本为 1。P4 JPEG 单分片最大 1024 字节，WS63 完整 JPEG 缓存上限 40 KiB；App 接收层上限为 64 KiB，因此整条链路的有效上限是 40 KiB。

仓库结构

text

xiaohong-se-ai-lock-platform/
├── apps/
│   └── xiaohong_se_manager/       HarmonyOS Flutter App
│       ├── lib/features/           实时监控、访客记录和设备页面
│       ├── lib/services/           FRB 会话驱动与 NearLink 事件分发
│       ├── lib/src/rust/           FRB 生成的 Dart 绑定
│       ├── rust/                   XH v1 协议、状态机与 JPEG 重组
│       ├── rust_builder/           cargokit 构建粘合层
│       └── ohos/                   ArkTS 星闪运输层与 HAP 工程
├── firmware/
│   ├── esp32-p4/                   Camera、LCD、ESP-DL、UART 固件
│   └── ws63/                       UART Bridge、SLE/SSAP Server 固件
├── hardware/
│   ├── bsp/                        P4 与 WS63 OpenHarmony 板级配置
│   └── assets/                     开发板和烧录操作图片
├── esp-dl/                         P4 人脸检测所需 ESP-DL 推理核心
├── models/human_face_detect/       智能门锁人脸检测模型组件
├── docs/
│   ├── architecture.md             精简架构说明
│   └── zh_CN/product/              二进制协议定义
└── THIRD_PARTY_NOTICES.md          第三方来源与合规边界

关键实现入口：

路径	说明
`apps/xiaohong_se_manager/lib/features/dashboard/dashboard_page.dart`	门锁管理 UI、状态与画面轮询
`apps/xiaohong_se_manager/lib/services/device_gateway.dart`	FRB 会话驱动、tick 循环与 MethodChannel 收发
`apps/xiaohong_se_manager/rust/src/protocol.rs`	XH v1 包头、STATUS、FRAME_* 与 JPEG 校验
`apps/xiaohong_se_manager/rust/src/session.rs`	连接状态机、请求节拍与 JPEG 重组
`apps/xiaohong_se_manager/rust/src/api/device.rs`	FRB 导出面
`apps/xiaohong_se_manager/ohos/entry/src/main/ets/entryability/EntryAbility.ets`	星闪权限、扫描、配对、连接、通知和写入
`firmware/ws63/src/sle_server/sle_server_task.c`	SSAP 门锁命令处理与响应分包
`firmware/ws63/src/sle_server/sle_server.c`	SSAP 服务、Property 与 CCCD
`firmware/ws63/src/uart_bridge/uart_ai_bridge.c`	P4 状态缓存与 JPEG 双缓冲
`firmware/esp32-p4/components/openharmony_liteos/services/uart_link_service.c`	P4 UART 门锁服务
`firmware/esp32-p4/components/openharmony_liteos/hw/ohos_ai_camera_preview.cpp`	摄像头、预览与 AI worker
`firmware/esp32-p4/components/openharmony_liteos/hw/ohos_espdl_face_detect.cpp`	ESP-DL 人脸检测

环境要求

已验证组合

项目	已验证值
HarmonyOS PC	HAD-W24
HarmonyOS 版本	`6.1.0.117` / OpenHarmony 6.1
HarmonyOS SDK	`6.0.2(22)`，包含 NearLinkKit
Flutter	支持 OHOS 的 Flutter 3.44 系列
Rust	稳定工具链 + `aarch64-unknown-linux-ohos` 目标 + `flutter_rust_bridge_codegen 2.13.0-beta.6`
WS63	小鸿 SE WS63，OpenHarmony mini 产品树，SDK v106
ESP32-P4	小鸿 SE P4，ESP-IDF 5.4/5.5 工具链

开发机工具

Git；
DevEco Studio 和 HarmonyOS SDK；
OHOS Flutter SDK、Dart SDK；
Rust 工具链（rustup target add aarch64-unknown-linux-ohos）和与 rust/Cargo.toml 同版本的 flutter_rust_bridge_codegen；
hdc，用于发现设备、安装 HAP 和查看 HarmonyOS 日志；
完整 WS63 OpenHarmony 源码树与 hb；
ESP-IDF、Python 3.10 和 ESP32-P4 RISC-V 工具链；
WS63 烧录工具和正确的串口驱动。

签名证书、.p12、.p7b、.cer、密码和本机绝对 SDK 路径不得提交。DevEco Studio 的自动签名配置应保留在开发机本地。

快速开始

bash

git clone https://gitcode.com/xiaohong-ai/xiaohong-se-ai-lock-platform.git
cd xiaohong-se-ai-lock-platform

直接烧录预编译固件

不搭建 ESP-IDF 或 OpenHarmony 编译环境时，可直接使用仓库内的 releases/v0.1.0/ 固件包：

ESP32-P4 单文件合并镜像：xiaohong-se-p4-full.bin，烧录地址 0x0；
ESP32-P4 分段镜像：Bootloader、分区表和门锁应用；
WS63 完整镜像：ws63-liteos-app_all.fwpkg；
SHA-256 校验文件和 P4 一键烧录脚本。

下载后先执行完整性校验：

bash

cd releases/v0.1.0
shasum -a 256 -c SHA256SUMS

Linux 如果没有 shasum，使用 sha256sum -c SHA256SUMS。

详细烧录参数、串口切换和验收步骤见预编译固件说明。

推荐按以下顺序完成首次部署：

构建并烧录 ESP32-P4 固件。
构建并烧录 WS63 固件。
整块开发板断电重启，确认 WS63 广播 xiaohong_se_lock。
在 DevEco Studio 配置本机 HarmonyOS 签名。
构建、签名并安装 HarmonyOS HAP。
启动 App，允许星闪权限，点击“连接设备”。
点击开始检测，确认实时画面、帧序号和人脸状态持续更新。

第一次只验证 App 与 WS63 时，可以先不连接 P4 摄像头链路；此时应能完成扫描、配对和 SSAP 连接，但页面会显示等待 P4 相机帧。完整验收必须同时烧录并运行两颗芯片。

构建 ESP32-P4 固件

详细说明见 ESP32-P4 固件 README。

bash

source /path/to/esp-idf/export.sh
export OHOS_ROOT=/path/to/openharmony
export ESP_DL_ROOT="$(pwd)"

cd firmware/esp32-p4
idf.py set-target esp32p4
idf.py build

也可以在仓库根目录执行：

bash

./firmware/esp32-p4/build_esp32p4.sh -b

关键产物：

text

firmware/esp32-p4/build/bootloader/bootloader.bin
firmware/esp32-p4/build/partition_table/partition-table.bin
firmware/esp32-p4/build/ohos_liteos_p4_app.bin
firmware/esp32-p4/build/flash_args

只有正确设置 ESP_DL_ROOT 才会启用仓库中的 ESP-DL 和 human_face_detect 组件。未设置时可能生成不含人脸检测的基础固件。

构建 WS63 固件

详细说明见 WS63 固件 README。本目录不是完整 WS63 SDK，需要先集成到完整 OpenHarmony mini 产品树：

bash

export OHOS_ROOT=/path/to/openharmony
./firmware/ws63/install_into_ohos.sh "$OHOS_ROOT"

在 OpenHarmony 根目录选择 mini / atomgit / xiaohong-se 产品后构建：

bash

hb build --load-test-config false

不要使用 hb build -f 作为门锁交付构建命令，它会额外编译与产品镜像无关的测试目标。

典型产物：

text

out/xiaohong/xiaohong-se/ws63-liteos-app/ws63-liteos-app_all.fwpkg

WS63 门锁镜像禁用不需要的文件系统后端，避免默认 LittleFS 分区与 FOTA 分区别名冲突；firmware/ws63/src/fs_adapt_disabled.c 为平台仍然链接的文件 HAL 提供明确的不可用实现。

构建与安装 HarmonyOS App

详细说明见 HarmonyOS App README。

获取依赖和静态检查

bash

cd apps/xiaohong_se_manager
flutter pub get
cd rust && cargo test && cargo build --release && cd ..
dart analyze lib test integration_test
flutter test

cargo build --release 会在 rust/target/release/ 生成主机侧动态库，flutter test 依赖它。 flutter build hap / hvigorw assembleHap 会为 ohos-arm64 重新编译同一份 Rust 源码并打进 HAP。

直接运行到 HarmonyOS PC

bash

# `flutter build hap` 在 PATH 上找 hvigorw，需让 DevEco Studio 自带的版本优先；
# command-line-tools 的旧 hvigor 读不懂 DevEco SDK 布局，会报 `00303168 SDK component missing`。
export PATH="/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin:$PATH"

flutter devices
flutter run -d <HARMONY_DEVICE_ID>

构建签名 HAP

推荐用 DevEco Studio 打开 apps/xiaohong_se_manager/ohos，在 Project Structure 中配置本机自动签名，然后执行 Build Hap。不要把生成的签名材料或带口令的 signingConfigs 提交到 Git。

ohos/build-profile.json5 刻意不写 compileSdkVersion：DevEco Studio 会用自身内置 SDK 编译，显式写成其他 API 版本会直接报 compileSdkVersion is incompatible。

在工具链已经配置好的环境中也可以使用 Hvigor。以下是 macOS DevEco Studio 的路径形式示例，其他系统按实际安装目录调整：

bash

cd apps/xiaohong_se_manager/ohos
export DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk
export NODE_HOME=/Applications/DevEco-Studio.app/Contents/tools/node

/Applications/DevEco-Studio.app/Contents/tools/hvigor/bin/hvigorw \
  assembleHap \
  -p product=default \
  -p buildMode=debug \
  --no-daemon \
  -p FLUTTER_TARGET=lib/main.dart \
  -p TARGET_PLATFORM=ohos-arm64 \
  -p PACKAGE_CONFIG="$(cd .. && pwd)/.dart_tool/package_config.json"

签名产物通常位于：

text

apps/xiaohong_se_manager/ohos/entry/build/default/outputs/default/
  entry-default-signed.hap

安装和启动

bash

hdc list targets
hdc -t <HARMONY_DEVICE_ID> install -r \
  apps/xiaohong_se_manager/ohos/entry/build/default/outputs/default/entry-default-signed.hap

hdc -t <HARMONY_DEVICE_ID> shell aa force-stop \
  com.xiaohongse.xiaohong_se_manager

hdc -t <HARMONY_DEVICE_ID> shell aa start \
  -a EntryAbility \
  -b com.xiaohongse.xiaohong_se_manager

硬件烧录

完整图片说明见硬件、BSP 与烧录接口。

小鸿 SE 右侧 TTL Type-C 口由 ESP32-P4 和 WS63 共用，P4/WS63 按键决定串口连接到哪颗芯片：

按键/指示灯	TTL 当前目标	用途
按键弹起、P4 蓝灯亮	ESP32-P4	P4 烧录与日志
按键压下、WS63 蓝灯亮	WS63	WS63 烧录与日志

烧录 P4

bash

cd firmware/esp32-p4
idf.py -p /dev/ttyUSB0 flash monitor

macOS 串口通常是 /dev/cu.usbserial-* 或 /dev/cu.usbmodem*，Linux 通常是 /dev/ttyUSB*。以 flash_args 中的真实分区地址为准，不要手工猜地址。

烧录 WS63

将共享 TTL 切换到 WS63，确认 WS63 蓝灯亮。
在烧录工具中选择 WS63 和正确串口。
选择 ws63-liteos-app_all.fwpkg。
点击连接；工具显示 Connecting... 时按一次 WS63 Reset。
等待 loaderboot 和 App 分区均达到 100%，确认 Execution Successful。
烧录完成后整板断电重启。

App 运行时使用无线星闪，不要求 TTL 一直连接。TTL 接错只会影响烧录和串口日志，不会直接造成 SSAP 配对错误。

运行与验收

正常操作

给小鸿 SE 开发板稳定供电并确认两颗芯片都启动。
打开 HarmonyOS PC 的“小鸿智能门锁”。
首次使用时允许 ohos.permission.ACCESS_NEARLINK。
点击“连接设备”，等待约 10 秒扫描完成。
若系统弹出配对确认框，确认配对。
按钮变为“断开设备”且页面显示“设备已连接”。
点击开始检测，观察实时画面、帧序号、人脸数和推理耗时。

App 验收

扫描目标为 xiaohong_se_lock，不会把 XH-KB 键盘示例当成门锁；
服务发现结果包含 0x2222/0x2323；
连接后状态轮询持续工作，页面不反复掉线；
JPEG 帧序号持续增加，画面不是固定占位图；
人脸出现时，人数、框和最高置信度更新；
当前会话访客记录按检测结果生成，最多保留 50 条；
断开后轮询停止，旧的半帧不会继续显示为新画面。

WS63 串口验收

应能看到类似关键日志：

text

sle_start_announce OK
pair_complete status[0x00]
CCCD DESC write
CCC[01 00]
ssaps_write_request_cbk ... len[10]
sle_server_send_notify_to_conn ... len[32]

收到 len[10] 的写入表示 App 正在发送无负载的 XH v1 GET_STATUS。连续出现通知发送及 220/240 字节附近的数据，表示状态或 JPEG 正在通过星闪返回。

P4 串口验收

摄像头预览连续显示，无黑屏和明显闪烁；
人脸进入画面后检测序号持续变化；
收到 AI_GET_STATUS / AI_SET_FACE_REPORTING；
返回 AI_STATUS、AI_FACE_RESULT 和 AI_CAMERA_FRAME_CHUNK；
JPEG 分片 offset 连续，完整帧不超过 WS63 40 KiB 缓存。

故障排查

`hdc list targets` 没有 HarmonyOS PC

确认 HarmonyOS PC 已开启开发者模式和 USB 调试；
确认数据线支持数据传输；
在设备上接受调试授权；
使用 DevEco Studio SDK 内的 hdc，避免系统中不同版本的 hdc 冲突。

App 提示未发现门锁

确认 WS63 已烧录门锁固件并上电；
查看 WS63 串口是否打印 sle_start_announce OK；
确认广播名是 xiaohong_se_lock；
断开其他已连接的星闪客户端后重试；
App 扫描固定需要约 10 秒，不要连续点击按钮。

App 提示发现 `XH-KB`

XH-KB 是星闪键盘示例固件，不是智能门锁。将 TTL 切换到 WS63，重新烧录本项目生成的 ws63-liteos-app_all.fwpkg，然后断电重启。

配对成功后出现 `1009700099 Operation failed`

在 HarmonyOS 6.1 的部分 NearLink 实现中，WS63 已经接受 CCCD 01 00 后，setPropertyNotification(true) 仍可能在 App 侧返回原生 -5，映射为 1009700099。当前 ArkTS 兼容逻辑会：

只在错误码为 1009700099 或 -5 且物理连接仍有效时进入兼容路径；
延迟 100 ms 后在同一连接上重试一次；
第二次仍返回同一假失败但连接有效时保留连接；
其他错误或已经断线时仍按真实错误断开。

可通过 HarmonyOS 日志确认兼容路径：

text

notification enable returned HarmonyOS false-negative; retrying
notification enable still returned false-negative; keeping active connection

同时必须查看 WS63 是否打印 CCCD DESC write 和 CCC[01 00]。如果板端没有收到 CCCD 写入，就不是这个兼容问题，不能简单忽略错误。

显示已连接但没有画面

检查 P4 是否运行摄像头预览和 AI worker；
检查 P4 与 WS63 是否使用同一版 0x0Cxx 协议；
检查 WS63 是否收到 0x0C05 JPEG 分片；
检查 JPEG 是否超过 40 KiB，过大时应降低分辨率或 JPEG 质量；
检查 UART 分片 offset 是否连续；
页面显示“等待 P4 相机帧”通常表示星闪连接正常，但 P4 数据源未就绪。

WS63 烧录工具一直没有反应

确认 TTL 接口已经切换到 WS63 且 WS63 蓝灯亮；
确认选择的是 TTL Type-C 串口，而不是其他 USB 接口；
重新插拔 TTL 后重新选择串口；
点击连接后，在出现 Connecting... 时按一次 WS63 Reset；
不要把 P4 的串口复位操作当作 WS63 复位。

Hvigor 报 `SDK component missing`

独立命令行工具与 DevEco Studio SDK 版本不一致时会出现该错误。优先使用同一套 DevEco Studio 内置的 Node、Hvigor 和 SDK，并设置：

bash

export DEVECO_SDK_HOME=/path/to/DevEco-Studio/Contents/sdk
export NODE_HOME=/path/to/DevEco-Studio/Contents/tools/node

如果报 Invalid value of DEVECO_SDK_HOME，检查路径是否直接指向包含 default/openharmony 和 default/hms 的 SDK 目录。

HAP 无法安装

确认安装的是 entry-default-signed.hap，不是 unsigned HAP；
确认签名 profile 包含当前 HarmonyOS 设备；
使用 hdc install -r 覆盖安装同包名应用；
若签名身份发生变化，需要先处理设备上旧包的签名冲突；删除旧应用会清除其本地数据，应先确认是否需要保留。

测试与开发约束

App 静态检查与测试

bash

cd apps/xiaohong_se_manager/rust && cargo test
cd .. && cargo build --release        # flutter test 需要主机侧动态库
dart analyze lib test integration_test
flutter test
flutter test integration_test/simple_test.dart

cargo test 覆盖包头编解码、状态解析、请求节拍和 JPEG 连续性校验；flutter test 通过 FRB 驱动完整会话。集成测试依赖真实 HarmonyOS NearLink 能力和已烧录的 WS63；普通桌面 Flutter 环境无法替代硬件链路验收。

修改 rust/src/api/ 后必须运行 flutter_rust_bridge_codegen generate 重新生成绑定； rust/src/frb_generated.rs 与 lib/src/rust/** 都是生成产物，不要手工编辑。

修改协议时的同步点

任何协议变更必须同步修改以下位置：

docs/zh_CN/product/xiaohong_se_ai_bridge_protocol.rst；
Rust rust/src/protocol.rs 与 rust/src/session.rs，然后重新生成 FRB 绑定；
WS63 src/sle_server/sle_server_task.c；
WS63 src/uart_bridge/uart_ai_bridge.*；
P4 services/include/ohos_uart_protocol.h 和对应实现；
三端 README、验收日志和版本号。

建议每次协议修改至少验证：魔数、版本、长度、序号、最大人脸数、JPEG 上限、分片连续性、断线清理和大小端。

不提交的文件

DevEco/HarmonyOS 签名材料和密码；
local.properties 和本机绝对 SDK 路径；
entry/build/、Flutter build/、.dart_tool/；
ESP-IDF build/、out/、本机生成的 dependencies.lock；
.DS_Store、IDE 工作区、串口日志和真实访客图像；
设备真实地址、量产密钥、Wi-Fi 密码或云端令牌。

安全与许可证

本项目是开发板 Demo，不应直接作为量产门锁安全方案。量产前至少需要补充：

设备身份、密钥注入和安全存储；
配对授权、重放防护和命令权限模型；
固件安全启动、签名升级和回滚保护；
访客数据加密、保留期限、导出和删除机制；
异常断电、链路中断、传感器失效和执行器故障的安全策略；
渗透测试、隐私评审、硬件可靠性和法规认证。

ESP-DL 上游代码遵循仓库根目录 LICENSE 中的 MIT License。P4/WS63 定制文件、硬件图片、预编译库和 Flutter/HarmonyOS 依赖可能具有各自许可证或授权边界，详见 THIRD_PARTY_NOTICES.md。根许可证不能自动覆盖没有明确授权的第三方或项目自有文件。

已知边界

当前仅支持 HarmonyOS 端，不保留 Android、iOS、Windows、macOS、Linux 或 Web 壳；
App 与门锁仅通过 NearLink SLE/SSAP 通信，不提供 Wi-Fi、HTTP、WebSocket 或云端通道；
访客记录只保存在当前 App 会话内，重启后不会恢复；
当前状态最多解析 4 张人脸；
WS63 JPEG 缓存上限 40 KiB；
App 每 350 ms 查询状态，画面轮询频率由 UI 控制，后续可根据功耗和带宽调优；
HarmonyOS 6.1 的 SSAP 通知订阅存在已记录的假失败兼容逻辑；
仓库不包含 PCB 原理图、Gerber、BOM、机械 CAD 或量产密钥；
本项目目前控制的是 AI 门锁 Demo 状态与画面链路，不应把它描述为已经完成量产级锁体执行器和安全认证。

小鸿 SE AI 星闪智能门锁平台

目录

项目目标

系统思维导图

总体架构

分层关系

组件职责

端到端数据流

控制与状态流

实时画面流

星闪连接时序

通信协议速查

App 与 WS63：XH v1 over SSAP

WS63 与 ESP32-P4：UART AI 协议

仓库结构

环境要求

已验证组合

开发机工具

快速开始

直接烧录预编译固件

构建 ESP32-P4 固件

构建 WS63 固件

构建与安装 HarmonyOS App

获取依赖和静态检查

直接运行到 HarmonyOS PC

构建签名 HAP

安装和启动

硬件烧录

烧录 P4

烧录 WS63

运行与验收

正常操作

App 验收

WS63 串口验收

P4 串口验收

故障排查

hdc list targets 没有 HarmonyOS PC

App 提示未发现门锁

App 提示发现 XH-KB

配对成功后出现 1009700099 Operation failed

显示已连接但没有画面

WS63 烧录工具一直没有反应

Hvigor 报 SDK component missing

HAP 无法安装

测试与开发约束

App 静态检查与测试

修改协议时的同步点

不提交的文件

安全与许可证

已知边界

延伸文档

`hdc list targets` 没有 HarmonyOS PC

App 提示发现 `XH-KB`

配对成功后出现 `1009700099 Operation failed`

Hvigor 报 `SDK component missing`