自定义ESP32-S3开发板适配ESP-WHO框架
一、ESP-WHO 示例部署
1、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/idfv4.4分支（老ESP32芯片）
ESP-WHO 提供了人脸检测、人脸识别、行人检测、二维码识别等示例。您可以基于这些示例，衍生出丰富的实际应用。ESP-WHO 基于ESP-DL开发，配合各种外设可以实现许多有趣的应用。
ESP-WHO 支持的开发版ESP32-P4 Function EV Board、ESP32-S3-EYE、ESP32-S3-Korvo-2，有的缺货，有的成本较高。
ESP32-S3-EYE 开发板：
2、 编译运行 ESP-WHO 示例
ESP-WHO 的所有示例都存放在 examples 中，进入对应的文件夹，执行下面的步骤。
添加环境变量
export IDF_EXTRA_ACTIONS_PATH=/path_to_esp-who/tools/ echo $IDF_EXTRA_ACTIONS_PATH设定目标 SOC 和默认 sdkconfig 配置文件
idf.py -DSDKCONFIG_DEFAULTS=sdkconfig.bsp.bsp_name set-target esp32xx配置 sdkconfig 选项
idf.py menuconfig编译，烧录并监视
idf.py flash monitor [-p port]ESP32_S3_EYE 配置与编译
基于esp32_s3_eye 开发板完整配置与编译步骤：
下述开发前提环境，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 set-target esp32s3 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二、自定义硬件说明
第三方 ESP32-S3-WROOM N16R8 带 DVP 开发板 + 外接 OV3660
1. 关键硬件差异
跟ESP32_S3_EYE 区别
- 核心模组一致：ESP32-S3-WROOM-1 N16R8（16MB Flash + 8MB Octal PSRAM，NNA 硬件加速完全相同）
- DVP 摄像头引脚定义完全对齐 ESP32-S3-EYE 官方标准，DVP 总线 GPIO 一一对应
- 都支持 OV2640/OV3660 DVP 摄像头，ESP-WHO 相机底层驱动通用
硬件模块 | ESP32-S3-EYE（乐鑫原厂） | 第三方 S3-WROOM N16R8 DVP 开发板 |
摄像头 | 板载 OV2640，自带独立相机 LDO 电源，软件自动上电 | 外接 OV3660，无专用相机电源电路；需外部 3.3V 供电 |
LCD 屏幕 | 板载 ST7789 SPI 小屏，BSP 内置 LCD 引脚、背光控制 | 无自带 LCD，SPI 屏需要额外接线，引脚自定义 |
麦克风 | 内置 PDM 数字麦，ESP-ADF 语音开箱即用 | 无板载麦克风 |
SD 卡槽 | 自带 TF 卡槽，人脸库可存 SD 卡 | 无板载 SD 卡，人脸模板只能存在 Flash 分区 |
按键 / LED | 板载功能按键、状态 LED，BSP 封装按键录入人脸逻辑 | 仅有通用 IO，录入人脸需要外接按键或串口指令触发 |
BSP 原生适配 | ESP-WHO 内置 / 官方配置 | 无专属官方 BSP 配置文件，只能两种方案：1. 复用 S3-EYE 相机配置，关闭 LCD / 麦 / SD2. 自建自定义 bsp 配置 |
电源噪声 | 相机独立供电，图像横纹、噪点极少 | 共用主板 3.3V，布线差容易图像干扰 |
2. 关键移植内容
LCD (ST7789) 引脚
#define BSP_LCD_SPI_MOSI (GPIO_NUM_20) #define BSP_LCD_SPI_CLK (GPIO_NUM_19) #define BSP_LCD_SPI_CS (GPIO_NUM_45) #define BSP_LCD_DC (GPIO_NUM_47) #define BSP_LCD_RST (GPIO_NUM_NC) #define BSP_LCD_BACKLIGHT (GPIO_NUM_48)关键驱动修改
- SPI 模式改为：
spi_mode = 0 - 背光反向关闭：
.flags.output_invert = false - 背光避开 SD 卡冲突：GPIO38 → GPIO48
三、完整移植步骤
因为第三方 ESP32-S3-WROOM 开发板与ESP32-S3-EYE开发板核心与摄像头接口一致，项目移植时可借用sdkconfig.bsp.esp32_s3_eye 配置文件，增加修订 LCD ST7789 的配置，项目基础功能就可以编译运行起来。
1、硬件引脚固化
修改managed_components/espressif__esp32_s3_eye/include/esp32_s3_eye.h
① LCD ST7789 引脚
// Display #define BSP_LCD_SPI_MOSI (GPIO_NUM_20) #define BSP_LCD_SPI_CLK (GPIO_NUM_19) #define BSP_LCD_SPI_CS (GPIO_NUM_45) #define BSP_LCD_DC (GPIO_NUM_47) #define BSP_LCD_RST (GPIO_NUM_NC) #define BSP_LCD_BACKLIGHT (GPIO_NUM_48) // Camera OV3660（原厂引脚和当前硬件完全匹配，无需改动） #define BSP_CAMERA_XCLK (GPIO_NUM_15) #define BSP_CAMERA_PCLK (GPIO_NUM_13) #define BSP_CAMERA_VSYNC (GPIO_NUM_6) #define BSP_CAMERA_HSYNC (GPIO_NUM_7) #define BSP_CAMERA_D0 (GPIO_NUM_11) #define BSP_CAMERA_D1 (GPIO_NUM_9) #define BSP_CAMERA_D2 (GPIO_NUM_8) #define BSP_CAMERA_D3 (GPIO_NUM_10) #define BSP_CAMERA_D4 (GPIO_NUM_12) #define BSP_CAMERA_D5 (GPIO_NUM_18) #define BSP_CAMERA_D6 (GPIO_NUM_17) #define BSP_CAMERA_D7 (GPIO_NUM_16)② 修改esp32_s3_eye.c两处驱动参数
- SPI 模式修正
esp_lcd_panel_io_spi_config_t io_config = { .dc_gpio_num = BSP_LCD_DC, .cs_gpio_num = BSP_LCD_SPI_CS, .pclk_hz = BSP_LCD_PIXEL_CLOCK_HZ, .lcd_cmd_bits = LCD_CMD_BITS, .lcd_param_bits = LCD_PARAM_BITS, .spi_mode = 0, // 原厂2改为0，适配外置ST7789 .trans_queue_depth = 10, };- 背光 PWM 关闭反向输出
const ledc_channel_config_t LCD_backlight_channel = { .gpio_num = BSP_LCD_BACKLIGHT, .speed_mode = LEDC_LOW_SPEED_MODE, .channel = LCD_LEDC_CH, .intr_type = LEDC_INTR_DISABLE, .timer_sel = 1, .duty = 0, .hpoint = 0, .flags.output_invert = false // 原厂true改为false，高电平点亮背光 };2、idf.py menuconfig 必须修改的配置项
进入配置界面命令：
idf.py set-target esp32s3 idf.py -D SDKCONFIG_DEFAULTS="sdkconfig.bsp.esp32_s3_eye" set-target esp32s3 idf.py menuconfig① 芯片与基础硬件
Serial flasher config
- Flash size：16MB（硬件 16MB flash）
- PSRAM mode：
Octal PSRAM - PSRAM clock：80MHz
Component config → ESP PSRAM
- ✅ Support external SPI RAM
- ✅ Map rodata to PSRAM（日志里提示复制模型到 PSRAM，必须开启）
- ✅ Map instruction to PSRAM（可选，释放内部 RAM）
② BSP 板卡选择（关键）
Component config → ESP BSP → Board selection
- 选中：
ESP32-S3-EYE
不要选其他板子，否则引脚宏全部错乱
③ 摄像头 Camera 配置（OV3660 专属）
Component config → ESP Camera
- Camera sensor type：OV3660
- Pixel format：RGB565（匹配 LCD 显示格式）
- Frame size：推荐 QVGA (320×240) / 480×360；人脸识别不要开太高分辨率
- XCLK frequency：20MHz（和硬件 XCLK 15 脚输出匹配）
- DVP GPIO override：关闭（我们已经在 BSP 头文件写死引脚，这里不要覆盖）
- SCCB I2C port：I2C0（SDA=4,SCL=5 固定）
④ LCD & LVGL 配置
Component config → ESP BSP → Display
- ✅ Enable display support（必须开启，禁用则无屏幕）
- Backlight LEDC channel：1（代码里 timer=1，保持一致）
- LVGL 配置：
- ✅ Enable LVGL GUI library
- LVGL buffer placement：PSRAM（画面帧缓存放外部内存）
- Tick period ms：10（默认即可）
⑤ ESP-WHO 人脸识别框架配置
Component config → ESP-WHO
- Model storage location：PSRAM（模型大，必须放 PSRAM）
- Face recognition database：
- 存储介质：SPIFFS / FATFS Flash（二选一，默认 SPIFFS 够用）
- Max registered faces：可改成 30（支持最多 30 张人脸录入）
- Inference optimization：
- ✅ Use PSRAM for model tensor buffer
- Quantization type：int8（S3 最优速度）
⑥ 串口调试
Component config → ESP System Settings
- Console UART：UART0，TX=43 RX=44（原厂默认，不要改，否则串口无法打印）
⑦ 内存与编译优化（防内存溢出）
Component config → Compiler options
- Stack size of main task：≥8192
- Enable extra heap tracing（调试内存泄漏可选）
3、app_main.cpp 最小标准代码
#include "frame_cap_pipeline.hpp" #include "who_recognition_app_lcd.hpp" #include "who_spiflash_fatfs.hpp" using namespace who::frame_cap; using namespace who::app; extern "C" void app_main(void) { vTaskPrioritySet(xTaskGetCurrentTaskHandle(), 5); #if CONFIG_DB_FATFS_FLASH ESP_ERROR_CHECK(fatfs_flash_mount()); #elif CONFIG_DB_SPIFFS ESP_ERROR_CHECK(bsp_spiffs_mount()); #endif auto frame_cap = get_dvp_frame_cap_pipeline(); auto recognition_app = new WhoRecognitionAppLCD(frame_cap); recognition_app->run(); }4、编译烧录流程
# 清理旧编译缓存 idf.py clean # 编译 idf.py build # 烧录+串口监视 idf.py flash monitor