1. 小智 ESP32-S3CAM 上 GPIO 复用控制 LED 与 SG90 舵机的真实场景
小智 ESP32-S3CAM 是一块把 ESP32-S3 主控、摄像头、麦克风阵列和 WiFi 塞进紧凑板型里的 AI 语音开发板，跑的是 xiaozhi-esp32 开源固件。它本身能做的事已经不少：语音唤醒、云端大模型对话、摄像头拍照识别。但很多人拿到手之后最想干的其实是——让 AI 帮我控制现实里的东西。LED 灯和 SG90 舵机就是最典型的两个入门外设：一个验证数字输出，一个验证 PWM 时序。
问题在于，ESP32-S3 的可用 GPIO 数量有限，而小智板子上摄像头、屏幕、麦克风、功放已经占掉了一大半引脚。你如果按传统思路给 LED 分配一个脚、给舵机再分配一个脚，很可能发现根本没有空闲引脚可用。这时候 GPIO 复用就成了必须面对的现实：同一路 GPIO，在不同时间片里分别承担 LED 开关和舵机 PWM 输出。
我试过在 bread-compact-wifi-s3cam 这块板子上把 LED 接 GPIO 14、SG90 信号线接 GPIO 3，两个外设各自独立工作，互不干扰。但如果你手上板子的引脚布局不同，或者你想把两个外设压到同一路 GPIO 上做分时复用，就需要理解背后的电气约束和软件切换逻辑。这篇内容会从接线、配置、PWM 参数、语音触发链路到 TaoToken 统一 Key 管理，给出一套可以照着做的完整方案。
适合谁看：手里有小智 ESP32-S3CAM 或类似 ESP32-S3 开发板、想用 AI 语音控制外设、对 GPIO 和 PWM 有基本概念但没实际调过的朋友。读完你能拿到一份可复制的配置清单，知道每个参数为什么这么设，以及语音指令是怎么从麦克风一路走到舵机转动的。
核心检索词先摆出来：ESP32-S3CAM GPIO 控制 LED 与 SG90 舵机、AI 语音操控外设、TaoToken 统一 Key 接入。这三个词贯穿全文，后面每个章节都会围绕它们展开。
2. TaoToken 统一 Key 接入：语音服务调用的前置准备
小智的语音链路是这样的：板子上的麦克风采集音频，本地做唤醒词检测，然后把音频流通过 WiFi 发到云端语音服务做识别和对话，大模型返回文本指令，固件解析后调用对应的 MCP 工具去操作 GPIO。整条链路里，云端语音服务和大模型调用是需要 API Key 的。如果你同时用了语音识别、对话模型、可能还有 TTS 合成，那就是三套 Key、三个计费入口、三份额度管理，调试的时候光切换 Key 就够烦的。
TaoToken 在这里的角色是统一 Key 和 API 通道管理。你可以把它理解成一个中间层：板子固件里只配一个 Base URL 和一个 Key，后面接的是哪个模型、哪个语音服务，由 TaoToken 侧的路由决定。这样你换模型、加服务、调额度，都不用重新烧录固件。
官网入口在这里：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。API 地址是 https://taotoken.net/api ，注意这个不加 UTM 参数，直接用于代码里的 Base URL。
具体到小智固件，你需要改的是语音服务配置部分。以 xiaozhi-esp32 的配置结构为例，通常在main/boards/bread-compact-wifi-s3cam/config.h或独立的sdkconfig里会有类似这样的字段：
// 语音服务 WebSocket 或 HTTP 端点 #define CONFIG_VOICE_SERVICE_URL "wss://your-voice-endpoint/v1/audio" #define CONFIG_VOICE_API_KEY "your-api-key-here"如果你用的是 TaoToken 统一通道，Base URL 填https://taotoken.net/api，Key 填你在控制台生成的令牌。模型 ID 根据你实际调用的服务填，比如对话模型用gpt-4o-mini或claude-3-5-sonnet这类标识，语音识别用对应的 ASR 模型标识。三件套就是 Base URL + Key + Model ID，缺一不可。
这里有个容易踩的坑：小智固件里有些版本把语音服务地址写死在代码里，不是通过 menuconfig 暴露的。你需要找到main/application.cc或main/protocols/下面的 WebSocket 初始化代码，把 URL 和 Key 改成从配置读取。改完之后idf.py menuconfig里才能看到对应选项。
另外，TaoToken 的 Coding Plan 适合长期跑 Agent 类任务的场景，如果你打算让小智持续在线、频繁调用模型做语音交互，可以关注一下额度套餐。模型对话入口在 https://taotoken.net/api ，控制台在 https://taotoken.net/console ，API Keys 管理在 https://taotoken.net/api-keys 。这些 deep link 后面 CTA 部分还会再提。
配置改完之后先别急着烧录，用 curl 在电脑上验证一下 Key 能不能通：
curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer YOUR_TAOTOKEN_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [{"role": "user", "content": "ping"}] }'返回 200 且 body 里有 choices 字段，说明 Key 和通道没问题。如果返回 401，检查 Key 有没有复制完整、有没有多余空格。如果返回 404，检查 Base URL 是不是写成了https://taotoken.net/api而不是带/v1的路径——具体路径以你调用的服务文档为准。
3. 可复制配置：GPIO 14 控 LED、GPIO 3 控 SG90 的完整参数
这一章是全文的核心操作部分。我会把 LED 和舵机的配置拆开讲，然后给出分时复用的切换逻辑。
先看 LED 侧。GPIO 14 配置为输出模式，推挽输出，无上下拉，无中断。代码在lamp_controller.h里：
// lamp_controller.h #include "driver/gpio.h" #define LAMP_GPIO GPIO_NUM_14 class LampController { public: void Init() { gpio_config_t config = { .pin_bit_mask = (1ULL << LAMP_GPIO), .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(LAMP_GPIO, 0); // 默认关灯 } void TurnOn() { gpio_set_level(LAMP_GPIO, 1); } void TurnOff() { gpio_set_level(LAMP_GPIO, 0); } bool GetState() { return gpio_get_level(LAMP_GPIO) == 1; } };接线方面，LED 长脚（阳极）串一个 220Ω 电阻接 GPIO 14，短脚（阴极）接 GND。GPIO 14 输出高电平 3.3V 时灯亮，低电平时灯灭。注意一定要串电阻，直接接 GPIO 和 GND 会烧 LED 或者烧引脚。
再看舵机侧。SG90 需要 50Hz 的 PWM，周期 20ms，脉冲宽度 0.5ms 到 2.5ms 对应 0° 到 180°。ESP32-S3 用 LEDC 外设产生这个信号，配置如下：
// servo_controller.h #include "driver/ledc.h" #define SERVO_GPIO GPIO_NUM_3 #define SERVO_LEDC_TIMER LEDC_TIMER_1 #define SERVO_LEDC_CHANNEL LEDC_CHANNEL_1 #define SERVO_LEDC_MODE LEDC_LOW_SPEED_MODE #define SERVO_DUTY_RES LEDC_TIMER_13_BIT // 8192 级 class ServoController { public: void Init() { ledc_timer_config_t timer = { .speed_mode = SERVO_LEDC_MODE, .duty_resolution = SERVO_DUTY_RES, .timer_num = SERVO_LEDC_TIMER, .freq_hz = 50, .clk_cfg = LEDC_AUTO_CLK }; ledc_timer_config(&timer); ledc_channel_config_t ch = { .gpio_num = SERVO_GPIO, .speed_mode = SERVO_LEDC_MODE, .channel = SERVO_LEDC_CHANNEL, .intr_type = LEDC_INTR_DISABLE, .timer_sel = SERVO_LEDC_TIMER, .duty = 0, .hpoint = 0 }; ledc_channel_config(&ch); SetAngle(90); // 初始化到中间位置 } void SetAngle(int angle) { if (angle < 0) angle = 0; if (angle > 180) angle = 180; // 0.5ms~2.5ms 映射到 13bit 占空比 uint32_t duty = (uint32_t)(((angle / 180.0) * 2.0 + 0.5) * 8191 / 20.0); ledc_set_duty(SERVO_LEDC_MODE, SERVO_LEDC_CHANNEL, duty); ledc_update_duty(SERVO_LEDC_MODE, SERVO_LEDC_CHANNEL); } };角度和占空比的对应关系用表格看得更清楚：
| 角度 | 脉冲宽度 | 占空比（13bit） |
|---|---|---|
| 0° | 0.5ms | 约 205 |
| 90° | 1.5ms | 约 614 |
| 180° | 2.5ms | 约 1023 |
接线：SG90 棕色线接 GND，红色线接 VIN 或 5V，橙色线接 GPIO 3。注意不要从 3.3V 给舵机供电，电压不够，舵机会抖或者不动。舵机启动瞬间电流可能到 500mA 以上，如果板子 USB 供电不足，舵机会复位或者板子重启，这时候需要外接 5V 电源。
现在说 GPIO 复用。如果你确实需要同一路 GPIO 分时驱动 LED 和舵机，核心思路是：LED 模式下把引脚配成 GPIO 输出，舵机模式下把引脚配成 LEDC 通道。切换时先ledc_stop()释放 PWM，再gpio_config()重配为输出，反之亦然。但要注意，LED 和舵机不能同时工作，因为同一时刻引脚只能有一种功能。实际场景里，语音指令是串行的，AI 不会同时让你开灯又转舵机，所以分时复用是可行的。
MCP 工具注册部分，在compact_wifi_board_s3cam.cc的InitializeTools()里创建实例并注册：
void CompactWifiBoardS3Cam::InitializeTools() { lamp_ = new LampController(); lamp_->Init(); mcp_server_.AddTool("self.lamp.turn_on", [this]() { lamp_->TurnOn(); }); mcp_server_.AddTool("self.lamp.turn_off", [this]() { lamp_->TurnOff(); }); mcp_server_.AddTool("self.lamp.get_state", [this]() { return lamp_->GetState(); }); servo_ = new ServoController(); servo_->Init(); mcp_server_.AddTool("self.servo.set_angle", [this](int angle) { servo_->SetAngle(angle); }); mcp_server_.AddTool("self.servo.get_angle", [this]() { return servo_->GetAngle(); }); }这样 AI 在对话时就能发现这些工具，根据用户语音自动调用。
4. 验证请求与成功结果：从语音指令到舵机转动的完整链路
配置写完、固件烧进去之后，怎么确认整条链路是通的？我分三层来验证：串口日志、MCP 工具调用、语音实际动作。
第一层，串口日志。烧录命令用：
idf.py -p /dev/ttyUSB0 flash monitorWindows 下把/dev/ttyUSB0换成COM3之类的实际串口。启动后你会看到板子初始化日志，重点找这几行：
I (1234) LampController: GPIO 14 configured as output I (1240) ServoController: LEDC timer 1 configured, freq=50Hz I (1250) McpServer: Registered tool self.lamp.turn_on I (1255) McpServer: Registered tool self.servo.set_angle如果看到gpio_config报错或者 LEDC 初始化失败，说明引脚被其他外设占用了，需要检查config.h里有没有冲突定义。
第二层，MCP 工具调用验证。小智固件通常有一个调试串口命令或者 HTTP 接口可以手动触发工具。你可以在串口里输入类似mcp call self.lamp.turn_on的命令，观察 LED 是否亮起。舵机的话输入mcp call self.servo.set_angle 90，舵机应该转到中间位置。这一步能排除语音识别的问题，单独验证 GPIO 和 PWM 是否正常。
第三层，语音实际触发。对着板子说“打开灯”，串口日志里应该出现：
I (5678) McpServer: Tool call: self.lamp.turn_on I (5680) LampController: GPIO 14 set to 1同时 LED 亮起。说“舵机转到 90 度”，日志里出现self.servo.set_angle调用，舵机转动。如果语音识别到了但工具没调用，检查 MCP 工具注册的名字和 AI 返回的 function call 名称是否一致。如果工具调用了但硬件没反应，回到第二层单独测 GPIO。
成功的结果是：你说“开灯”，灯亮；说“关灯”，灯灭；说“舵机转到 45 度”，舵机转过去；说“舵机现在多少度”，AI 能读出当前角度。整条链路从麦克风到云端语音服务到大模型到 MCP 工具到 GPIO/PWM，全部打通。
这里顺便提一下 TaoToken 的模型对话入口，你可以在 https://taotoken.net/api 对应的控制台里查看每次语音请求消耗的 token 和调用的模型，方便排查是语音识别错了还是模型理解错了。如果发现模型经常把“开灯”理解成“关灯”，可以在系统提示词里把工具描述写得更明确，比如self.lamp.turn_on: 打开LED灯，输出高电平。
5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth
调试过程中最容易卡住的几个报错，我按出现频率排一下。
401 Unauthorized。这个基本就是 Key 的问题。检查三件事：Key 有没有复制完整（有时候复制会漏掉最后几位）、Key 前面有没有多余空格、Base URL 是不是写对了。TaoToken 的 API 地址是https://taotoken.net/api，如果你写成了https://taotoken.net/api/v1而实际服务路径不需要/v1，也可能返回 401 或 404。用 curl 在电脑上先测通，再烧到板子上。
local proxy failed。这个报错通常出现在板子通过 WiFi 访问外部服务时。先确认板子连上了 WiFi，串口日志里能看到 IP 地址。然后确认 DNS 能解析，可以 ping 一下taotoken.net。如果板子所在网络有限制，换一个网络试试。注意不要用任何网络代理工具，板子直连即可。
reading choices 报错。这个一般是大模型返回的 JSON 结构和你代码里解析的字段不匹配。比如你期望choices[0].message.content，但实际返回的是choices[0].delta.content（流式）或者choices[0].text（completion 接口）。检查你调用的接口类型和解析代码是否对应。用 curl 拿到原始返回，对着字段名改解析逻辑。
OAuth 相关报错。如果你用的是需要 OAuth 的服务，检查 token 有没有过期、refresh token 流程有没有走通。TaoToken 的 Key 是静态令牌，不涉及 OAuth 刷新，所以如果你看到 OAuth 报错，说明代码里可能混用了其他服务的认证逻辑，需要把认证头统一改成Authorization: Bearer YOUR_KEY。
舵机抖动或不转。先量电压，SG90 的 VCC 是不是 5V 左右。3.3V 供电舵机基本不动。然后检查 PWM 频率是不是 50Hz，占空比计算有没有溢出。13bit 分辨率下最大 duty 是 8191，如果你算出来超过这个值，会被截断导致角度不对。
LED 微亮或不亮。检查电阻有没有接、阻值是不是 220Ω 左右。如果 LED 一直微亮，可能是 GPIO 配置成了开漏模式或者有上下拉，改成推挽输出、禁用上下拉。
编译报错 undefined reference to ledc_timer_config。检查CMakeLists.txt里有没有把driver组件加进去。ESP-IDF 的 LEDC 和 GPIO 都在driver组件里，需要REQUIRES driver。
CC Switch / Cline MCP / Codex auth.json 三件套。如果你在电脑端用 Cline 或类似工具通过 MCP 连接小智，配置里需要写全 Base URL、Key、Model ID。Base URL 填https://taotoken.net/api，Key 填 TaoToken 控制台生成的令牌，Model ID 填你实际调用的模型标识。三个缺一个都会连不上。Codex 的auth.json里对应字段是api_base、api_key、model，路径通常在~/.codex/auth.json。
排查顺序建议：先串口日志看初始化，再 curl 测 Key，再手动触发 MCP 工具，最后语音触发。一层一层排除，不要跳步。
6. 语义一致 CTA：按场景选入口
如果你现在卡在 Key 配置或者接入报错上，先去 API Keys 管理页生成或检查令牌：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，里面有各语言 SDK 的 Base URL 填法和常见错误码说明。
如果你想先验证模型通不通、对比不同模型对语音指令的理解能力，用模型对话入口：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。在里面输入“打开灯”看模型会不会返回正确的 function call，比直接烧板子调试快得多。
如果你打算让小智长期在线、频繁调用语音服务和模型做 Agent 类任务，看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。控制台在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，可以看调用量和额度消耗。
Claude Code 相关的接入配置在 https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，如果你用 Claude Code 做固件代码补全，这里有三件套的完整填法。
最后说一个实际调试技巧：小智固件的浅休眠超时默认是 20 秒，你改完 GPIO 配置后如果 20 秒内没说话，板子可能进休眠导致串口日志断掉。把sleep_timer.h里的超时改成 60 秒，调试会舒服很多。这个改动不影响功能，只是让板子多等一会儿再睡。
