76 lines
3.1 KiB
Markdown
76 lines
3.1 KiB
Markdown
# 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 使用统一学号语义（映射同步后应发送真实学号语义）。
|
||
- 网络任务失败不会阻塞识别主流程，但会影响照片与映射同步时效；本地照片缓存会用于后续补传。
|
||
|