小智 ESP32-S3CAM 新功能：GPIO 同时控制 LED 灯与 SG90 舵机，AI 语音即可操控

qq_29364971

309人浏览 · 2026-06-12 09:51:24

qq_29364971 · 2026-06-12 09:51:24 发布

小智 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 中定义
#define LAMP_GPIO GPIO_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.5ms_{2.5ms）来控制角度（0°}180°）。

// config.h 中定义
#define SERVO_GPIO GPIO_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_t duty = (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 和其他选项

5.2 编译固件

idf.py build

编译成功后会在 build/ 目录下生成固件文件。

5.3 烧录固件

方法一：使用 VS Code Espressif 扩展

将 ESP32-S3 通过 USB 连接到电脑
在 VS Code 底部状态栏选择正确的串口（如 COM3 或 /dev/ttyUSB0）
点击 “Flash” 按钮或按快捷键烧录

方法二：使用命令行（推荐）

# 烧录并监控串口输出
idf.py -p COM3 flash monitor

将 COM3 替换为你的实际串口号。

方法三：仅烧录不监控

idf.py -p COM3 flash

5.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 控制中心。