小智 ESP32-S3CAM 新功能：GPIO 同时控制 LED 灯与 SG90 舵机，AI 语音即可操控
基于 xiaozhi-esp32 开源项目，在 bread-compact-wifi-s3cam 开发板上新增了 LED 灯控制和 SG90 舵机控制功能，通过 MCP（Model Context Protocol）协议实现 AI 语音操控外设。
一、项目简介
小智 ESP32 是一款基于 ESP32-S3 芯片的开源 AI 语音助手项目。本次更新为bread-compact-wifi-s3cam开发板带来了两项实用的 GPIO 外设控制功能：
- LED 灯控制— 通过 GPIO 14 控制外部 LED 灯的开关
- SG90 舵机控制— 通过 GPIO 3 控制 SG90 舵机的旋转角度
这两个功能都通过 MCP 协议注册为 AI 可调用的工具，你可以直接用自然语言（语音）来控制它们。
二、功能一：使用 GPIO 控制 LED 灯的开关
2.1 原理说明
在代码中，LampController类负责 LED 灯的控制。它通过配置指定 GPIO 引脚为输出模式，然后通过设置高低电平来控制灯的开关。
// config.h 中定义#defineLAMP_GPIOGPIO_NUM_14// lamp_controller.h 核心代码gpio_config_t config={.pin_bit_mask=(1ULL<<gpio_num_),.mode=GPIO_MODE_OUTPUT,.pull_up_en=GPIO_PULLUP_DISABLE,.pull_down_en=GPIO_PULLDOWN_DISABLE,.intr_type=GPIO_INTR_DISABLE,};gpio_config(&config);gpio_set_level(gpio_num_,0);// 输出低电平 = 关灯gpio_set_level(gpio_num_,1);// 输出高电平 = 开灯2.2 MCP 工具注册
LampController在初始化时自动注册了三个 MCP 工具：
| 工具名称 | 说明 | 参数 |
|---|---|---|
self.lamp.get_state | 获取灯的当前开关状态 | 无 |
self.lamp.turn_on | 开灯 | 无 |
self.lamp.turn_off | 关灯 | 无 |
2.3 接线步骤
所需材料：
- ESP32-S3 开发板（bread-compact-wifi-s3cam）
- LED 灯模块（带限流电阻的模块，或自行串联 220Ω 电阻）
- 杜邦线若干
接线方式：
| LED 引脚 | 连接到 ESP32-S3 |
|---|---|
| 正极（长引脚，串联 220Ω 电阻） | GPIO 14 |
| 负极（短引脚） | GND |
┌─────────────┐ ┌─────────────┐ │ ESP32-S3 │ │ LED │ │ │ │ │ │ GPIO 14 ├──220Ω───►│ + (正极) │ │ GND ├─────────►│ - (负极) │ └─────────────┘ └─────────────┘注意事项：
- LED 长引脚为正极（阳极），短引脚为负极（阴极）
- 请务必串联一个 220Ω 限流电阻，防止电流过大损坏 LED 或 GPIO
- GPIO 14 输出高电平（3.3V）时灯亮，输出低电平时灯灭
2.4 使用方式
连接到小智 AI 助手后，你可以直接说：
- “打开灯” → AI 调用
self.lamp.turn_on - “关闭灯” → AI 调用
self.lamp.turn_off - “灯现在是开着的吗？” → AI 调用
self.lamp.get_state
三、功能二：控制 SG90 舵机
3.1 原理说明
ServoController类使用 ESP32 的 LEDC（LED Control）PWM 外设来产生 SG90 舵机所需的控制信号。SG90 舵机需要一个周期约 20ms（50Hz）的 PWM 信号，通过脉冲宽度（0.5ms2.5ms）来控制角度（0°180°）。
// config.h 中定义#defineSERVO_GPIOGPIO_NUM_3// servo_controller.h 核心 PWM 配置ledc_timer_config_t ledc_timer={.speed_mode=LEDC_LOW_SPEED_MODE,.duty_resolution=LEDC_TIMER_13_BIT,// 8192 级精度.timer_num=LEDC_TIMER_1,.freq_hz=50,// 50Hz = 20ms 周期.clk_cfg=LEDC_AUTO_CLK};// 角度转占空比计算uint32_tduty=(uint32_t)(((angle/180.0)*2.0+0.5)*8191/20.0);PWM 信号与角度的对应关系：
| 角度 | 脉冲宽度 | 占空比 |
|---|---|---|
| 0° | 0.5ms | 2.5% |
| 90° | 1.5ms | 7.5% |
| 180° | 2.5ms | 12.5% |
3.2 MCP 工具注册
ServoController在初始化时自动注册了四个 MCP 工具：
| 工具名称 | 说明 | 参数 |
|---|---|---|
self.servo.move_forward | 顺时针旋转 N 度 | degrees（整数，1~180，默认 15） |
self.servo.move_backward | 逆时针旋转 N 度 | degrees（整数，1~180，默认 15） |
self.servo.set_angle | 设置绝对角度 | angle（整数，0~180，默认 90） |
self.servo.get_angle | 获取当前角度 | 无 |
舵机角度被限制在 0°~180° 范围内，超出范围会自动截断。
3.3 接线步骤
所需材料：
- ESP32-S3 开发板（bread-compact-wifi-s3cam）
- SG90 舵机
- 杜邦线若干（母对母或母对公）
SG90 舵机线序：
| 导线颜色 | 功能 |
|---|---|
| 棕色（或黑色） | GND |
| 红色 | VCC（4.8V~6V） |
| 橙色（或黄色） | 信号线 |
接线方式：
| SG90 引脚 | 连接到 ESP32-S3 |
|---|---|
| 棕色线（GND） | GND |
| 红色线（VCC） | VIN 或 5V（如果板子有 5V 输出） |
| 橙色线（信号） | GPIO 3 |
┌─────────────┐ ┌─────────────┐ │ ESP32-S3 │ │ SG90 舵机 │ │ │ │ │ │ VIN/5V ├─────────►│ 红色 (VCC) │ │ GND ├─────────►│ 棕色 (GND) │ │ GPIO 3 ├─────────►│ 橙色 (信号) │ └─────────────┘ └─────────────┘注意事项：
- SG90 舵机工作电压为 4.8V~6V，建议从 VIN 引脚供电（USB 供电时 VIN 约 5V）
- 不要从 3.3V 引脚给舵机供电，电压不足会导致舵机无法正常工作
- 舵机启动瞬间电流较大，确保电源能够提供至少 500mA 电流
- 如果你同时使用多个舵机，需要外部独立电源供电
- 初始化时舵机会自动转到 90° 中间位置
3.4 使用方式
连接到小智 AI 助手后，你可以直接说：
- “把舵机顺时针转 30 度” → AI 调用
self.servo.move_forward(degrees=30) - “逆时针转 15 度” → AI 调用
self.servo.move_backward(degrees=15) - “舵机转到 90 度” → AI 调用
self.servo.set_angle(angle=90) - “舵机现在多少度？” → AI 调用
self.servo.get_angle
四、代码结构概览
新增和修改的关键文件：
main/ ├── boards/ │ ├── bread-compact-wifi-s3cam/ │ │ ├── config.h # GPIO 引脚定义：LAMP_GPIO=14, SERVO_GPIO=3 │ │ └── compact_wifi_board_s3cam.cc # 新增 InitializeTools() 和舵机翻转设置 │ └── common/ │ ├── lamp_controller.h # LED 灯控制类（新增） │ ├── servo_controller.h # 舵机控制类（新增） │ └── sleep_timer.h # 休眠定时器（浅休眠超时从 20s 改为 60s）关键改动点
config.h— 定义了
LAMP_GPIO（GPIO 14）和SERVO_GPIO（GPIO 3）compact_wifi_board_s3cam.cc— 新增
InitializeTools()方法，在板子初始化时创建LampController和ServoController实例；摄像头新增了垂直翻转设置lamp_controller.h— 全新的 LED 灯控制模块
servo_controller.h— 全新的 SG90 舵机控制模块，基于 LEDC PWM
sleep_timer.h— 将浅休眠超时时间从 20 秒调整为 60 秒
五、烧录及上传固件
5.1 配置项目
- 在 VS Code 中打开项目
- 设置目标芯片为 ESP32-S3：
idf.py set-target esp32s3 - 运行菜单配置：
idf.py menuconfig - 在配置中选择：
- Board type→
bread-compact-wifi-s3cam - LCD 类型→ 根据你实际连接的屏幕选择（如 ST7789 240x320）
- 配置 WiFi 和其他选项
- Board type→
5.2 编译固件
idf.py build编译成功后会在build/目录下生成固件文件。
5.3 烧录固件
方法一：使用 VS Code Espressif 扩展
- 将 ESP32-S3 通过 USB 连接到电脑
- 在 VS Code 底部状态栏选择正确的串口（如 COM3 或 /dev/ttyUSB0）
- 点击 “Flash” 按钮或按快捷键烧录
方法二：使用命令行（推荐）
# 烧录并监控串口输出idf.py-pCOM3 flash monitor将COM3替换为你的实际串口号。
方法三：仅烧录不监控
idf.py-pCOM3 flash5.5 常见问题
| 问题 | 解决方案 |
|---|---|
| 无法进入下载模式 | 按住 BOOT 按钮的同时按复位按钮，或检查 USB 连接 |
| 串口权限被拒绝 | Linux 下执行sudo usermod -aG dialout $USER |
| 编译失败 | 确认已执行idf.py set-target esp32s3 |
| 舵机不工作 | 检查是否从 VIN/5V 供电，3.3V 无法驱动 SG90 |
| LED 不亮 | 检查接线和 GPIO 引脚号是否与 config.h 一致 |
六、总结
本次更新为小智 ESP32-S3CAM 开发板带来了实用的 GPIO 外设控制能力：
- 通过简单的接线，就能用语音控制 LED 灯的开关
- 接入 SG90 舵机后，可以语音控制旋转角度
- 所有功能都通过 MCP 协议注册，AI 大模型可以自动发现并调用这些工具
- 代码设计简洁，新增的
lamp_controller.h和servo_controller.h都是 header-only 的模块，方便移植到其他开发板
未来可以继续扩展更多 GPIO 外设，如继电器、传感器、步进电机等，让小智成为一个真正的 AIoT 控制中心。
