xiaozhi-esp32 面包板 WiFi LCD Camera 板型实战基于 ESP32-S3 CAM 的 OV2640 视觉接入与编译指南【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32本文面向想为 xiaozhi-esp32 语音助手加入视觉能力的开发者以一块常见的 ESP32-S3 CAMOV2640 摄像头开发板为核心说明如何在面包板 WiFi LCD 方案的基础上构建带摄像头的板型包括完整引脚分配、摄像头初始化原理、MCP 拍照工具调用链以及从idf.py set-target到烧录的完整编译流程。读完本文你将能够独立完成该板型的接线核对、menuconfig 选型与固件构建。板型定位与硬件选型main/boards/bread-compact-wifi-s3cam/是 xiaozhi-esp32 仓库中面包板Bread Compact系列的一个变体其 READMEmain/boards/bread-compact-wifi-s3cam/README.md明确指出硬件基于ESP32-S3 CAM 开发板ESP32-S3 OV2640 摄像头模组一体板代码基于同系列bread-compact-wifi-lcd板型修改而来因此保留了面包板 WiFi LCD 的全部能力使用的摄像头传感器为OV2640。也就是说这一板型在原有ESP32-S3 DevKit 面包板外设 LCD 屏的基础上额外挂载了一个摄像头让设备从能听会说升级为能看。从仓库源码结构看面包板系列还包含 bread-compact-wifi、bread-compact-wifi-lcd、bread-compact-ml307 等多个兄弟板型本板型是其中唯一带 Camera 的 Wi-Fi 变体对应的编译选项为CONFIG_BOARD_TYPE_BREAD_COMPACT_WIFI_CAM见 main/CMakeLists.txt。引脚分配详解以 config.h 为准README 强调连线方式参考 config.h 文件中对引脚的定义硬件接线的唯一权威依据就是 main/boards/bread-compact-wifi-s3cam/config.h。下面按功能模块逐项拆解。摄像头引脚OV26408 位并口#define CAMERA_PIN_D0 GPIO_NUM_11 #define CAMERA_PIN_D1 GPIO_NUM_9 #define CAMERA_PIN_D2 GPIO_NUM_8 #define CAMERA_PIN_D3 GPIO_NUM_10 #define CAMERA_PIN_D4 GPIO_NUM_12 #define CAMERA_PIN_D5 GPIO_NUM_18 #define CAMERA_PIN_D6 GPIO_NUM_17 #define CAMERA_PIN_D7 GPIO_NUM_16 #define CAMERA_PIN_XCLK GPIO_NUM_15 #define CAMERA_PIN_PCLK GPIO_NUM_13 #define CAMERA_PIN_VSYNC GPIO_NUM_6 #define CAMERA_PIN_HREF GPIO_NUM_7 #define CAMERA_PIN_SIOC GPIO_NUM_5 #define CAMERA_PIN_SIOD GPIO_NUM_4 #define CAMERA_PIN_PWDN GPIO_NUM_NC #define CAMERA_PIN_RESET GPIO_NUM_NC #define XCLK_FREQ_HZ 20000000要点说明D0–D7 为 8 位数据总线XCLK 为主时钟输出20 MHzPCLK 为像素时钟VSYNC/HREF 为帧同步与行同步信号SIOC/SIOD 为 SCCB兼容 I2C控制总线用于读写 OV2640 寄存器PWDN 与 RESET 均为GPIO_NUM_NC未连接说明该开发板将摄像头上下电与复位交由板载电路管理无需软件控制最重要的注意事项OV2640 占用 IO 较多因此占用了 ESP32-S3 的USB D-/DGPIO 19 / GPIO 20两个引脚。这意味着使用此板型后板载 USB 串口/下载口将无法直接用于烧录与日志输出需要外接独立的 USB-UART 工具通过 TX/RX 引脚来下载固件和查看日志。音频 I2S 引脚Simplex 双路模式#define AUDIO_INPUT_SAMPLE_RATE 16000 #define AUDIO_OUTPUT_SAMPLE_RATE 24000 #define AUDIO_I2S_METHOD_SIMPLEX #define AUDIO_I2S_MIC_GPIO_WS GPIO_NUM_1 #define AUDIO_I2S_MIC_GPIO_SCK GPIO_NUM_2 #define AUDIO_I2S_MIC_GPIO_DIN GPIO_NUM_42 #define AUDIO_I2S_SPK_GPIO_DOUT GPIO_NUM_39 #define AUDIO_I2S_SPK_GPIO_BCLK GPIO_NUM_40 #define AUDIO_I2S_SPK_GPIO_LRCK GPIO_NUM_41该板型默认采用 Simplex半双工双总线I2S 模式麦克风通道占用 WS/SCK/DINGPIO 1/2/42扬声器通道占用 DOUT/BCLK/LRCKGPIO 39/40/41麦克风采样率 16 kHz、扬声器输出 24 kHz。如需改为 Duplex单总线全双工模式只需注释掉AUDIO_I2S_METHOD_SIMPLEX宏此时将使用 GPIO 4/5/6/7 四个引脚的 Duplex 配置见 config.h 第 21–28 行。LCD 显示屏引脚SPI 串行屏#define DISPLAY_BACKLIGHT_PIN GPIO_NUM_38 #define DISPLAY_MOSI_PIN GPIO_NUM_20 // 原 USB D #define DISPLAY_CLK_PIN GPIO_NUM_19 // 原 USB D- #define DISPLAY_DC_PIN GPIO_NUM_47 #define DISPLAY_RST_PIN GPIO_NUM_21 #define DISPLAY_CS_PIN GPIO_NUM_45LCD 的 SPI 时钟与数据线恰好复用了被摄像头挤走的 USB 引脚19/20这也解释了 README 中占用 USB 19 20 两个引脚的说明这两个引脚在板级定义上被分配给了显示屏而非摄像头本身从系统角度看它们已不再属于 USB 外设。config.h 还通过CONFIG_LCD_ST7789_240X320等宏为 ST7789多种分辨率、ST7735、ST7796、ILI9341、GC9A01 等驱动芯片提供了完整的显示参数预设分辨率、镜像、偏移、SPI 模式等默认板型配置文件选用的是 ST7789 240x320。按键、指示灯与 MCP 测试灯#define BUILTIN_LED_GPIO GPIO_NUM_48 #define BOOT_BUTTON_GPIO GPIO_NUM_0 #define TOUCH_BUTTON_GPIO GPIO_NUM_NC #define VOLUME_UP_BUTTON_GPIO GPIO_NUM_NC #define VOLUME_DOWN_BUTTON_GPIO GPIO_NUM_NC #define LAMP_GPIO GPIO_NUM_14板载 BOOT 键GPIO 0作为唯一的交互按键板载 LEDGPIO 48作为状态灯LAMP_GPIOGPIO 14是源码注释中标注的 A MCP Test: Control a lamp 测试灯引脚与仓库的 MCP 灯控示例配套。与 bread-compact-wifi-lcd 的引脚差异对比 main/boards/bread-compact-wifi-lcd/config.h 可以发现为了给摄像头腾出 IO本板型做了两处明显调整功能wifi-lcd 板型s3cam 板型麦克风 I2SWS4, SCK5, DIN6WS1, SCK2, DIN42扬声器 I2SDOUT7, BCLK15, LRCK16DOUT39, BCLK40, LRCK41LCD MOSI/CLK47 / 2120USB D/ 19USB D-LCD DC/RST/CS40 / 45 / 4147 / 21 / 45背光4238MCP 测试灯1814原 wifi-lcd 使用的 GPIO 4/5/6/7 与 15/16 被腾出重新分配给 OV2640 的 SIOD/SIOC 与 XCLK/D7 等信号音频通道则整体迁移到 1/2/39/40/41/42 这组引脚上。板级初始化源码解析板型入口实现位于 main/boards/bread-compact-wifi-s3cam/compact_wifi_board_s3cam.cc类CompactWifiBoardS3Cam继承自WifiBoard构造函数依次完成四件事InitializeSpi()初始化 SPI3 主机总线MOSI/SCLK 取自DISPLAY_MOSI_PIN/DISPLAY_CLK_PIN即 GPIO 20/19最大传输长度按DISPLAY_WIDTH * DISPLAY_HEIGHT * 2计算见 L70–L79InitializeLcdDisplay()创建 SPI panel IO40 MHz 时钟、8 位命令/参数位宽并按LCD_TYPE_*宏选择 ST7789 / ILI9341 / GC9A01 驱动随后依次执行 reset、init、颜色反转、坐标交换与镜像设置见 L81–L125InitializeButtons()BOOT 键单击回调中若设备处于kDeviceStateStarting状态则进入 WiFi 配网模式EnterWifiConfigMode()否则切换聊天状态app.ToggleChatState()见 L156–L165InitializeCamera()组装camera_config_t并创建Esp32Camera实例见 L127–L154。摄像头初始化配置值得展开说明compact_wifi_board_s3cam.ccconfig.pixel_format PIXFORMAT_RGB565; // 像素格式 RGB565 config.frame_size FRAMESIZE_VGA; // 帧尺寸 VGA640x480 config.jpeg_quality 12; // JPEG 质量 config.fb_count 1; // 单帧缓冲 config.fb_location CAMERA_FB_IN_PSRAM; // 帧缓冲放 PSRAM节省内部 SRAM config.grab_mode CAMERA_GRAB_WHEN_EMPTY;传感器输出 RGB565 原始帧Esp32Camera::Capture()在 main/boards/common/esp32_camera.cc 中获取最新一帧循环丢弃旧帧保证实时性按需做字节序交换并把预览帧交给LvglDisplay::SetPreviewImage()在 LCD 上显示帧缓冲指定放入PSRAM这是因为 VGA 尺寸的 RGB565 帧约 614 KB放不进常规内部 SRAM使用 ESP32-S3 模组的 PSRAM 是标配做法GrabMode CAMERA_GRAB_WHEN_EMPTY表示仅当无未处理帧时才抓取避免积压。底层Esp32Camera封装了乐鑫官方esp_camera驱动构造时调用esp_camera_init()并通过esp_camera_sensor_get()拿到sensor_t后根据 Kconfig 配置应用水平/垂直镜像见 esp32_camera.ccSetHMirror/SetVFlip分别映射到传感器的set_hmirror/set_vflip寄存器操作L149–L165。Camera抽象基类定义在 main/boards/common/camera.h板型通过GetCamera()对外暴露摄像头实例compact_wifi_board_s3cam.cc。视觉能力如何接入 MCPself.camera.take_photo带摄像头板型的价值在于把视觉开放给大模型。从 main/mcp_server.cc 的源码可以看到当Board::GetInstance().GetCamera()返回非空时MCP 服务器会自动注册self.camera.take_photo工具其描述文本明确要求模型当用户让你看东西时使用此工具拍照并解释工具接收一个question参数。调用链如下camera-Capture()抓取最新帧TaskPriorityReset priority_reset(1)先临时降低任务优先级避免卡顿camera-Explain(question)在 esp32_camera.cc 中实现启动编码线程将 RGB565 帧经image_to_jpeg_cb()编码为 JPEG 分块质量 80通过队列逐块读取以multipart/form-databoundary 为----ESP32_CAMERA_BOUNDARY向explain_url_发起 HTTP POST表单包含question字段与filenamecamera.jpg的文件字段同时携带Device-Id、Client-Id请求头配置了 token 时附加Authorization: Bearer服务端返回的识别/解释结果作为工具返回值回传给大模型。也就是说OV2640 拍到的画面会以 JPEG 上传给配置好的视觉解释服务explain_url模型据此回答你看到了什么之类的问题。这条链路将摄像头硬件与 MCP 协议打通是 xiaozhi-esp32 实现多模态交互的核心机制之一。编译配置与烧录步骤一配置编译目标为 ESP32-S3idf.py set-target esp32s3该板型仅支持 ESP32-S3 目标BOARD_TYPE_BREAD_COMPACT_WIFI_CAM在 main/Kconfig.projbuild 中声明了depends on IDF_TARGET_ESP32S3config.json 中target: esp32s3也与之对应。步骤二打开 menuconfigidf.py menuconfig步骤三选择板型在 menuconfig 中进入Xiaozhi Assistant - Board Type - 面包板新版接线WiFi LCD Camera对应的英文菜单项为Bread Compact Wi-Fi LCD Camera (面包板)Kconfig 符号BOARD_TYPE_BREAD_COMPACT_WIFI_CAM。选择后main/CMakeLists.txt 会把BOARD_DIR指向bread-compact-wifi-s3cam同时配置 16 号内置字体与noto-color-emoji_64表情集合。步骤四编译并烧录idf.py build flash板型参数化配置config.json 定义了 CI/参数化构建的默认值{ type: bread-compact-wifi-s3cam, target: esp32s3, builds: [ { name: bread-compact-wifi-s3cam, build_options: { camera_hmirror: false, camera_vflip: false }, sdkconfig_append: [ CONFIG_LCD_ST7789_240X320y ] } ] }camera_hmirror/camera_vflip默认均为false即不做镜像/翻转若摄像头画面左右或上下颠倒可在 menuconfig 的Camera Configuration菜单中开启XIAOZHI_CAMERA_MIRROR_CONFIGUREDOverride camera mirror settings再调整XIAOZHI_CAMERA_HMIRROR水平镜像与XIAOZHI_CAMERA_VFLIP垂直镜像两项其效果由Esp32Camera在传感器初始化后通过set_hmirror/set_vflip落地见 esp32_camera.ccsdkconfig_append默认追加CONFIG_LCD_ST7789_240X320y即默认匹配 240x320 分辨率的 ST7789 屏若实际屏幕不同可在 menuconfig 中改选CONFIG_LCD_ST7789_170X320、CONFIG_LCD_ILI9341_240X320、CONFIG_LCD_GC9A01_240X240等对应项config.h 第 65–302 行给出各选项的完整显示参数同一菜单下还提供了XIAOZHI_CAMERA_ALLOW_JPEG_INPUT允许 JPEG 输入USB 摄像头场景可能需要、硬件 JPEG 编解码器开关等高级选项见 main/Kconfig.projbuild。注意事项与排障要点USB 不可用由于 GPIO 19/20 被摄像头相关电路占用板载 USB 口不能用于烧录与串口监控。烧录时需使用外接 USB-UART 转接板连接串口 TX/RX并保持 3.3 V 电平一致内存分配摄像头帧缓冲依赖 PSRAMCAMERA_FB_IN_PSRAM请确认使用的 ESP32-S3 模组带 PSRAM否则摄像头初始化会失败或系统内存告警接线以 config.h 为准README 明确要求连线参照 config.h 的引脚定义动手前请逐脚核对 DVP 数据线、SCCB 与 I2S 信号避免与面包板上其他外设冲突画面方向若预览画面方向不对优先通过 menuconfig 的 Camera Configuration 菜单调整镜像设置而不必改动代码视觉服务配置self.camera.take_photo需要配置explain_url及可选 token才会真正工作否则Esp32Camera::Explain()会抛出 Image explain URL or token is not set 异常见 esp32_camera.cc。完成以上步骤后你的面包板 ESP32-S3 CAM 设备便同时具备了语音对话、LCD 显示与拍照并理解画面的完整能力可作为 xiaozhi-esp32 视觉场景如物体识别、环境问答的低成本开发平台。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考