# 小智AI GPIO控制无效（按教程不行）排查顺序
小智GPIO本质是**MCP工具调用 + ESP32底层GPIO初始化**，绝大多数不是语音识别问题，是**引脚冲突、MCP没注册、电平逻辑、固件版本**四类坑。
## 一、先做隔离测试（最重要，快速定位）
1. **先脱离小智MCP，单独写一段简单blink代码（Arduino/ESP-IDF）直接控制这个GPIO**
- 如果单独闪烁代码都不亮：**硬件/引脚本身问题**，和小智无关
- 单独代码能正常翻转电平：硬件没问题，问题出在**小智MCP注册、回调、固件配置**
> ESP32-S3重点：S3有很多引脚是**strapping、flash/PSRAM、I2S音频占用脚**，原版小智音频、屏幕、功放已经占用一堆GPIO，教程里的引脚不一定适配你的底板版本
## 二、硬件层面高频踩坑
1. **选错引脚（头号原因）**
- ESP32：GPIO34~39 **只能输入，不能输出**，拿来点灯/继电器完全没反应
- ESP32-S3：GPIO46、47、48很多底板是PSRAM/boot strapping脚；I2S音频引脚（7、15、16等）原版小智已经占用，重复定义会冲突，直接抢GPIO控制权
- 板载LED很多是**低电平点亮**！教程写`HIGH亮`，实际是`LOW亮`，逻辑反了，你以为没控制
2. **共地、供电、限流**
- 继电器、MOS管、LED必须和ESP32 **GND连在一起**，不共地电平飘移，看着接线对，不动作
- ESP32所有GPIO是**3.3V耐压，不能直接接5V外设**
- LED不加限流电阻，轻则不亮，重则烧引脚
3. 虚焊、面包板内部断线、杜邦线坏、底板丝印标号和芯片GPIO号不一致（很多商家底板丝印坑人）
## 三、小智MCP代码/固件层面（单独blink正常，接入小智就不行）
1. **MCP工具没有正确注册**
- 只写了gpio_set_level，忘记把控制函数注册到MCP工具列表；小智后台不知道有这个GPIO能力，语音指令不会下发回调
- 函数名字、参数名称必须和LLM提示词匹配，参数拼写错（state / on/off），调用直接失败，串口看不到执行
2. **`config.h` 引脚被原版占用覆盖**
小智官方固件在 `config.h` 预先定义了：I2S、PA使能、按键、屏幕CS、复位脚，**你在MCP里重复定义同一个GPIO，会被音频驱动抢占**，输出被覆盖掉
✅ 解决：换一个**完全空闲、不在config.h里定义**的GPIO
3. **回调函数里没做GPIO初始化**
很多新手只在回调里写`digitalWrite`，忘记在`setup()`里执行 `pinMode(GPIO, OUTPUT)`；MCP调用时引脚默认浮空，无输出
4. **固件版本差异（v1.8.2 / v2.2.6 / v2.5.2不互通）**
教程是2.2.6，你烧的是1.8.2，MCP接口、工具注册写法不一样，旧版本不支持动态GPIO工具；不同版本WebSocket地址、token校验逻辑有区别
5. **WiFi/MCP连接断连**
看串口日志：
- 没有打印 `MCP connected` → 根本连不上小智服务器，指令下不来
- 识别到语音，但没有打印`call tool xxx` → LLM没有触发你的GPIO工具（prompt描述写的不对，AI不知道可以控制这个设备）
## 四、后台&语音Prompt坑
- 只改了设备端代码，**没在MCP工具描述写清楚功能**：LLM听不懂“开灯”对应调用哪个gpio工具，会直接回答文字，不下发控制指令
- 唤醒、ASR识别成功，但工具调用被安全拦截、token失效、设备未绑定
## 五、最简排查流程（照着跑）
1. 串口打开，波特率115200，看日志：WiFi连上？MCP连上？语音识别后有没有调用工具日志
2. 用万用表测GPIO脚电平：MCP触发指令时，电平有没有变化
3. 换一个**安全空闲引脚**：ESP32-S3优先选 GPIO10,11,12,13,14,21,33（避开音频、PSRAM脚）
4. 确认电平逻辑：板载LED大多低电平亮，把on/off逻辑反过来测试
5. 版本对齐：教程是什么固件版本，你就刷同版本源码，不要跨版本抄代码
## 快速区分一句话
- 裸程序点灯OK → 【MCP注册、prompt、config引脚冲突】
- 裸程序点灯也不行 → 【引脚是输入脚/strapping脚、硬件接线、电平反了、引脚烧毁】
你可以发一下：**芯片型号（ESP32/ESP32S3）、固件版本、你用的GPIO编号、串口日志里MCP连接和工具调用片段**，我直接帮你定位。 |
|
