一、ESP-WHO 整体定位

ESP-WHO 是乐鑫官方开源、面向ESP系列芯片的边缘机器视觉AI开发框架，主打低门槛快速实现人脸、物体、手势等视觉AI任务，完全基于ESP-IDF构建，底层依赖乐鑫自研深度学习库 ESP-DL 做模型推理加速。
核心定位：给资源有限的ESP32/ESP32-S3/ESP32-P4等MCU提供开箱即用的视觉流水线，不用从零搭建图像采集、预处理、AI推理、结果渲染整套代码。

版本适配关系

• ESP-IDF v5.x → 新版ESP-WHO主分支（主推S3、P4）
• ESP-IDF v4.4 → 对应esp-who/idf v4.4分支（老ESP32芯片）

二、分层软件架构

整体四层堆栈，自上而下：

1. 应用层examples：可直接编译运行的业务示例
2. ESP-WHO核心组件层：流水线节点、检测/识别内核、BSP硬件抽象
3. ESP-DL深度学习层：INT8/FP16量化推理、NNA硬件加速算子
4. 底层基础层：ESP-IDF、FreeRTOS、外设驱动（Camera/LCD/PSRAM/WiFi）

异步流水线核心设计

采用节点化异步任务流水线，每个环节封装独立WhoXXXNode类，FreeRTOS队列/事件位通信，互不阻塞：

1. WhoFrameCapNode：摄像头图像采集、裁剪、格式转换（RGB565/YUV422）
2. WhoDetect：调用ESP-DL运行检测模型（人脸/人体/猫脸）
3. WhoRecognitionCore（可选）：特征提取、比对、人脸库增删管理（录入/识别/删除状态机）
4. 输出节点：LCD渲染、串口打印、WiFi图传、继电器控制等

三、内置核心AI能力

1. 人脸体系

• 人脸检测：轻量化MTCNN三级级联，输出人脸框+5个人脸关键点
• 人脸识别：轻量化ArcFace，128维特征向量比对，支持本地人脸模板Flash存储；支持多人录入、权限区分（管理员/普通用户）
• 性能：ESP32-S3内置NNA加速，人脸检测+识别单帧几十毫秒级

2. 其他预置视觉模型

• 人体/行人检测
• 猫脸检测（宠物监控）
• 手势识别（单/多手势控制）
• 二维码/条形码识别
• 物体分类（可替换自定义训练模型）

模型优化手段

全部针对MCU深度优化：

• 权重INT8量化，大幅减少Flash/内存占用
• 深度可分离卷积、网络剪枝、通道压缩
• 充分调用S3/P4内置NNA神经网络加速器，纯CPU也可降级运行（速度慢）

四、支持硬件平台

主控芯片

1. ESP32-S3（主流首选）：自带NNA、大PSRAM，ESP32-S3-EYE官方开发板完美适配
2. ESP32-P4：更强NNA算力，高分辨率图像、多任务并行视觉
3. 老款ESP32（无硬件NNA）：仅基础人脸检测可用，识别速度偏低；ESP32-S2算力弱不推荐重度视觉

配套外设

• 摄像头：OV2640（标配200W）、OV3660等；框架统一封装驱动，BSP屏蔽引脚差异
• 显示：ST7789 LCD、OLED，流水线可直接叠加人脸框、文字渲染
• 存储：Flash存人脸模板；PSRAM必须（缓存图像帧、模型权重）
• 通信：Wi-Fi传输图片/识别日志；搭配ESP-ADF音频框架可做音视觉融合（语音唤醒+人脸识别）

官方开发板

• ESP32-S3-EYE（最适配，出厂即跑ESP-WHO人脸例程）
• ESP-EYE（初代ESP32）
• ESP32-WROVER-KIT、Korvo-2（音视一体）

兼容开发板

五、框架关键特性

1. BSP硬件抽象层
   同一套业务代码切换不同开发板，只需改sdkconfig.bsp.xxx编译配置，不用改底层摄像头/LCD引脚代码，移植极快。
2. 完整状态机管理
   人脸识别内置标准流程：空闲→录入人脸→保存模板→比对识别→删除人脸，自带校验阈值、相似度分数可调。
3. 低门槛二次开发

• 示例代码完整可跑，只需加回调函数就能对接外设（开锁、灯光、上报云平台）
• 支持替换自己训练的YOLO/MobileNet模型，通过ESP-DL模型转换工具一键部署

1. IoT无缝打通
   识别结果、抓拍图片可通过ESP-IDF MQTT/HTTP上传阿里云、华为云、ESP RainMaker；本地可配WiFi热点远程查看画面
2. 开源协议
   Apache 2.0，商用无版权限制，GitHub乐鑫官方仓库维护，持续更新模型与芯片适配

六、典型应用场景

1. 智能门禁/考勤：本地人脸开锁、打卡，脱机可用，断网不失效
2. 智能家居交互：人脸识别自动切换灯光/空调模式、手势开关设备
3. 宠物监控：猫脸检测自动抓拍推送手机
4. 工业安防：人员在岗检测、危险区域闯入提醒
5. 低功耗电池摄像头：S3深度休眠，有人脸唤醒抓拍，超长待机

七、快速上手步骤

1、ESP32_S3_EYE 配置与编译

基于esp32_s3_eye 开发板（或兼容开发板），运行examples/human_face_recognition 人脸识别的示例，完整配置与编译步骤：

开发环境（Ubuntu22.04 + IDF5.5）

cd /home/tony/esp
git clone git@gitee.com:EspressifSystems/esp-who.git
export IDF_EXTRA_ACTIONS_PATH=/home/tony/esp/esp-who/tools/
cd esp-who/examples/human_face_recognition/
idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.bsp.esp32_s3_eye" set-target esp32s3
idf.py menuconfig (可选)
idf.py update-dependencies(可选)
idf.py build
idf.py flash
idf.py monitor 

2、ESP32_S3_EYE 兼容板问题

• LCD 屏幕不亮

源文件路径：
 esp-who/examples/human_face_recognition/managed_components/espressif__esp32_s3_eye/esp32_s3_eye.c

修订 367 行，spi_mode = 0。（原厂 spi_mode = 2）

• 调整摄像头方向

源文件路径：
esp-who/examples/human_face_recognition/main/frame_cap_pipeline.cpp

八、同类方案对比

维度	ESP-WHO	裸写ESP-DL	第三方开源视觉库
上手难度	极低，现成流水线	高，需自己搭采集/预处理	中，适配ESP生态差
硬件适配	BSP统一封装，多板兼容	需手动写摄像头驱动	引脚、存储适配麻烦
人脸流程	录入/比对/存储全套封装	全部自己实现状态机	大多只有检测无识别管理
乐鑫生态	深度绑定IDF/ADL/RainMaker	仅绑定ESP-DL	生态割裂

简单总结：做ESP芯片人脸视觉首选ESP-WHO，把80%重复底层视觉工程全部封装，开发者只专注业务逻辑。