硬件外设技能（Hardware MCP Tools）
本文介绍 DuckyClaw 内置的硬件外设 MCP 工具，面向希望通过 AI 语音指令直接控制 GPIO、ADC、I2C、串口、PWM 和舵机等硬件外设的开发者。
概述
硬件外设技能是一组内置 MCP（Model Context Protocol）工具，允许 AI Agent 通过自然语言指令直接操作设备硬件。开启后，你可以对 DuckyClaw 说出类似"把 GPIO 5 拉高"或"读取串口数据"这样的指令，AI 将自动调用对应的硬件工具完成操作。
- 源文件位置：
tools/tool_hw.c - 适用场景：硬件调试、外设验证、快速原型开发
启用硬件外设技能
硬件外设技能通过 ENABLE_HARDWARE_MCP 宏定义控制开关。
T5AI-BOARD 默认已开启 ENABLE_HARDWARE_MCP，无需手动配置。其他平台请按以下步骤启用。
在项目目录下运行配置菜单：
tos.py config menu
在配置界面中找到并启用 ENABLE_HARDWARE_MCP 选项，保存后重新编译固件。
如果找不到该选项，可以直接在项目的 Kconfig 或 config 文件中手动添加：
CONFIG_ENABLE_HARDWARE_MCP=y
工具列表
1. GPIO 输出
控制 GPIO 引脚的输出电平（高/低）。
| 参数 | 类型 | 说明 |
|---|---|---|
pin | 整数 | GPIO 引脚编号 |
level | 整数 | 电平值：1 为高电平，0 为低电平 |
调用示例（文字 / 语音）：
"把 GPIO 5 设置为高电平" "将引脚 12 拉低" "GPIO 8 输出 1"
参考示例：TuyaOpen/examples/peripherals/gpio/src/example_gpio.c
2. GPIO 输入
读取 GPIO 引脚的当前输入电平。
| 参数 | 类型 | 说明 |
|---|---|---|
pin | 整数 | GPIO 引脚编号 |
返回值：引脚当前电平（0 或 1）。
调用示例（文字 / 语音）：
"读取 GPIO 3 的电平" "查询引脚 7 的状态" "GPIO 10 现在是高电平还是低电平？"
3. I2C 扫描
扫描 I2C 总线，返回总线上所有响应设备的地址列表。用于检测传感器、屏幕等 I2C 设备是否正确连接。
| 参数 | 类型 | 说明 |
|---|---|---|
scl_pin | 整数 | I2C 时钟线（SCL）引脚编号 |
sda_pin | 整数 | I2C 数据线（SDA）引脚编号 |
返回值：总线上检测到的设备地址列表（十六进制）。
调用示例（文字 / 语音）：
"扫描 I2C 总线，SCL 是引脚 22，SDA 是引脚 21" "用 SCL=9、SDA=10 扫描 I2C 设备" "I2C 扫描，时钟引脚 22，数据引脚 21"
参考示例：TuyaOpen/examples/peripherals/i2c/i2c_scan/src/example_i2c_scan.c
4. ADC 采样
读取 ADC 引脚上的模拟采样值，用于测量电压、传感器输出等模拟信号。
| 参数 | 类型 | 说明 |
|---|---|---|
pin | 整数 | ADC 引脚编号 |
返回值：ADC 原始采样值（整数）。
调用示例（文字 / 语音）：
"读取引脚 34 的 ADC 值" "采样 ADC 通道 6" "GPIO 36 的电压是多少？"
ADC 采样值为原始数值，需根据实际参考电压和分辨率换算为电压值。
参考示例：TuyaOpen/examples/peripherals/adc/src/example_adc.c
5. 串口发送
通过串口 2（UART2）发送字符串数据。
| 参数 | 类型 | 说明 |
|---|---|---|
data | 字符串 | 要发送的文本内容 |
调用示例（文字 / 语音）：
"通过串口发送 'Hello World'" "串口发送字符串 AT+RESET" "用 UART 发送 '开始测试'"
当前工具使用串口 2 发送数据，波特率等参数使用默认配置。参考示例：TuyaOpen/examples/peripherals/uart/src/example_uart.c
6. 串口读取
读取串口 2（UART2）接收缓冲区中的数据。
| 参数 | 说明 |
|---|---|
| 无 | 无需参数，直接调用即可 |
返回值：串口缓冲区中当前接收到的字符串数据。
调用示例（文字 / 语音）：
"读取串口数据" "查看 UART 接收缓冲区" "串口有没有收到数据？"
7. PWM 输出
初始化指定引脚的 PWM 输出，并设置占空比。频率等其他参数按默认配置。
| 参数 | 类型 | 说明 |
|---|---|---|
pin | 整数 | PWM 输出引脚编号 |
duty | 整数 | 占空比，范围 0（0%）到 100（100%） |
调用示例（文字 / 语音）：
"引脚 18 输出 50% 占空比的 PWM" "设置 GPIO 19 的 PWM 占空比为 75" "把引脚 5 的 PWM 调到 30%"
参考示例：TuyaOpen/examples/peripherals/pwm/src/example_pwm.c
8. 舵机控制
通过 PWM 信号控制舵机旋转到指定角度。
- 频率固定为 50 Hz（20 ms 周期）
- 脉宽范围 0.5 ms（0°）到 2.5 ms（180°）自动换算
| 参数 | 类型 | 说明 |
|---|---|---|
angle | 整数 | 目标角度，范围 0 到 180（单位：度） |
调用示例（文字 / 语音）：
"把舵机转到 90 度" "舵机旋转到 45 度位置" "将舵机设置为 180 度"
舵机工具会自动将角度换算为对应的 PWM 脉宽，无需手动计算。
使用建议
- 在向 AI 描述硬件操作时，明确提供引脚编号和目标值，AI 将更准确地调用对应工具。
- 如果设备无响应，可先使用 I2C 扫描或 GPIO 输入验证硬件连接是否正常。
- 串口工具适合与外部 MCU 或传感器模块通信，发送 AT 指令等场景。
参考
- 自定义设备 MCP（硬件技能开发指南）
- DuckyClaw 快速入门（T5-AI）
- TuyaOpen 外设示例：
TuyaOpen/examples/peripherals/