# K210识别端文档

## 1. 端侧职责
- 进行人脸检测、特征提取、识别。
- 通过 UART1 将识别结果实时发送给 STM32。
- 通过 UART2 驱动 ESP8266，与服务端同步人脸映射与删除任务。
- 上传新增人脸照片到服务端。

对应入口文件：`k210/main.py`

## 2. 通信链路
- `UART1`（K210 <-> STM32）：发送识别结果。
- `UART2`（K210 <-> ESP8266）：HTTP 通信到服务端 `:8082`。

识别结果发送格式（给 STM32）：
- 已识别：`ID:<id>,NAME:<name>,CONF:<score>`
- 陌生人：`UNKNOWN`

## 3. 本地数据文件
- 人脸特征库：`/sd/recordftr.txt`
- 本地映射缓存：`/sd/face_mapping.txt`
- 本地同步版本：`/sd/sync_version.txt`
- 本地人脸照片缓存：`/sd/face_photos/<face_id>.jpg`

## 4. 服务端交互接口
K210 在脚本中使用 HTTP 访问以下接口：
- `GET /api/v1/sync/state?client=k210&last_version=<本地版本>`：按版本拉取统一同步状态。
- `POST /api/v1/sync/ack`：确认已完成删除任务。
- `GET /api/v1/sync/request`：轮询是否触发同步。
- `POST /api/v1/sync/request/ack`：确认收到同步请求。
- `GET /api/v1/faces/photos`：获取服务端已有照片列表，用于判断本地照片是否需要补传。
- `POST /api/v1/faces/photos/<face_id>`：上传 JPEG 人脸照片。

v1 兼容辅助接口：
- `GET /api/v1/faces/mappings`
- `GET /api/v1/faces/pending-delete`
- `POST /api/v1/faces/delete-ack`

## 5. 启动与运行流程
1. 初始化摄像头、KPU 模型、LCD、按键中断、串口。
2. 启动 ESP8266，尝试连接 WiFi。
3. 启动同步：
- 读取 `/sd/sync_version.txt`。
- 请求统一同步状态。
- 先删除 `pending_delete` 中的人脸特征。
- 再应用 `face_mappings`。
- 成功后保存新的同步版本。
4. 进入主循环：识别 + 绘制 + 向 STM32 上报。
5. 分时网络任务（避免阻塞识别帧率）：
- 新增人脸时先把 JPEG 保存到 `/sd/face_photos/`，再加入上传队列。
- 启动时先获取服务端照片列表，再扫描 `/sd/face_photos/`，只补传服务端缺失的照片；如果服务端不可达，则退回全量加入补传队列。
- 优先处理照片上传队列，上传失败会保留本地照片并等待下次重试。
- 然后处理同步任务。

## 6. 按键功能
在 `k210/main.py` 中定义：
- 短按：添加人脸。
- 长按（约2秒）：进入删除单个人脸模式。
- 超长按（约5秒）：删除全部人脸。

## 7. 当前默认配置（代码内）
- WiFi：`YOUR_WIFI_SSID / YOUR_WIFI_PASSWORD`
- 服务端：`127.0.0.1:8082`（部署时改为实际服务端地址）
- API Token：`change-me-token`（部署时必须修改）

文件位置：`k210/main.py`

## 8. 部署注意事项
- SD 卡需包含模型文件：
  - `/sd/FaceDetection.smodel`
  - `/sd/FaceLandmarkDetection.smodel`
  - `/sd/FeatureExtraction.smodel`
- 与 STM32 使用统一学号语义（映射同步后应发送真实学号语义）。
- 网络任务失败不会阻塞识别主流程，但会影响照片与映射同步时效；本地照片缓存会用于后续补传。