🤖 Arduino主控(Arduino MCP)
人工智能硬件自动化平台
通过智能、事件驱动的自动化弥合人工智能代理和物理硬件之间的差距
📋 目录
- 什么是Arduino MCP?
- 主要特点
- 是什么让这个项目与众不同
- 硬件堆栈
- 系统架构
- 先决条件
- 安装和设置
- 快速开始
- 示例工作流
- API 参考
- 可扩展性和未来增强功能
- 项目结构
- 故障排除
- 贡献
- 许可证
🎯 什么是Arduino MCP?
Arduino MCP 是一个AI控制的自动化平台,将Python AI代理与基于Arduino的硬件外围设备连接起来。它通过结合以下内容,实现了无需人工监督的复杂、多步骤场景:
- 实时硬件控制:显示器、传感器和执行器的实时更新
- 事件驱动自动化:后台监控和条件触发器执行
- 人工智能集成:为自然语言AI代理控制设计的高级工具
- 非阻塞架构:固件无缝运行多个并发任务
它解决的问题
传统的Arduino项目需要:
- 手动、连续控制或闭锁代码
- 用于多设备协调的复杂状态管理
- 持续轮询基于时间或传感器触发的事件
- 难以与AI/自动化系统集成
解决方案
Arduino MCP提供:
- ✅ 高级Python API 用于直观控制
- ✅ 自动背景监控 计时器、时钟和传感器
- ✅ 条件执行引擎 在没有轮询的情况下链接操作
- ✅ 实时显示 无需Python干预即可在设备上进行更新
- ✅ FastMCP集成 用于无缝的AI代理通信
✨ 主要特点
🖥️ 显示管理
| 显示类型 | 功能 | 关键功能 |
|---|---|---|
| 液晶显示器(16×2) | 实时时钟、秒表、自定义文本、背光控制 | lcd_show_current_time(), lcd_start_stopwatch(), lcd_write_line1/2() |
| TM1637 7 7段 | 实时时钟、倒计时器、秒表、数字 | display_current_time(), display_timer(), display_number() |
🔧 硬件控制
| 组件 | 动作 | 功能 |
|---|---|---|
| 发光二极管 | 开/关、闪烁、切换 | led_on(), led_off(), led_blink(interval_ms), led_toggle() |
| 蜂鸣器 | 开/关,定时蜂鸣声 | buzzer_on(), buzzer_off(), buzzer_beep(duration_ms) |
| 超声波传感器 | 单读、连续监控、实时液晶流 | ultrasonic_read(), ultrasonic_start(), show_live_ultrasonic_on_lcd() |
⚡ 条件自动化(明星功能!)
后台触发的操作 无需轮询即可自动执行:
| 触发器类型 | 触发时 | 示例用例 |
|---|---|---|
when_timer_finishes() |
倒计时达到00:00 | 计时器结束时自动发出蜂鸣声,链式计时器 |
when_time_equals() |
时钟与特定时间匹配 | 在计划时间开始任务 |
when_distance_less_than() |
物体靠得太近 | 接近警报、防撞 |
可用操作:
buzzer_beep--声音警报start_timer--开始倒计时led_blink--视觉指示器display_message--在LCD上显示文本
🌟 是什么让这个项目与众不同
1. 真实生活行为
与需要不断Python调用的典型Arduino草图不同,我们的固件运行显示器和计时器 自主地 在非阻塞回路中:
- 时钟每秒自动滴答作响
- 倒计时在没有Python干预的情况下递减
- 与LED闪烁相同的策略——设置一次,它就永远运行
2. AI优先设计
专为通过FastMCP进行AI代理控制而构建:
- 高级、意图驱动的功能
- 与自然语言兼容的工具描述
- 内置复杂场景解析(例如,“启动计时器,然后发出蜂鸣声,然后在上午7:15启动另一个计时器”)
3. 条件执行引擎
Python后台监视器监视Arduino状态消息和 自动执行排队的操作:```python
display_timer(1, 30) # Start 90-second countdown
when_timer_finishes("buzzer_beep", "1000") # Auto-beep when done
when_timer_finishes("start_timer", "02:00") # Auto-start 2-min timer after first ends
No polling loop needed - monitor handles everything!
### 4. **多设备编排**
LCD、7段显示器、LED、蜂鸣器和超声波传感器的统一控制,具有同步状态管理功能。
### 5. **零手动轮询**
传统方法: `while True: check_status(); sleep(1)`\
Arduino MCP方法:设置触发器→ 本底监测器→ 动作自动执行
______________________________________________________________________
## 🔌 硬件堆栈
### 组件
|组件|型号/类型|连接|备注|
|-----------|-----------|------------|-------|
| **液晶显示器** |16×2 I2C(`LiquidCrystal_I2C`)| SCL→10, SDA→11 | 默认地址: `0x27` (试试看 `0x3F` 如果需要)|
| **7段显示器** |4位TM1637|CLK→8, DIO→9 | 亮度可调(0-15)|
| **超声波传感器** |HC-SR04或类似产品|跳闸→7, ECHO→6 | 范围:2-400cm|
| **蜂鸣器** |有源蜂鸣器|引脚13 |与LED共用引脚|
| **发光二极管** |内置| `LED_BUILTIN` |通常引脚13|
### 接线图```
Arduino Uno/Nano
├── LCD I2C ────────► SCL: Pin 10, SDA: Pin 11
├── TM1637 ─────────► CLK: Pin 8, DIO: Pin 9
├── Ultrasonic ─────► TRIG: Pin 7, ECHO: Pin 6
├── Buzzer ─────────► Pin 13
└── LED (built-in) ─► Pin 13 (LED_BUILTIN)
必需的库
通过Arduino库管理器安装:
LiquidCrystal_I2C作者:弗兰克·德·布拉班德TM1637Display作者Avishay Orpaz
🏗️ 系统架构```
┌─────────────────────────────────────────────────────────────┐
│ Python Layer (FastMCP) │
├─────────────────────────────────────────────────────────────┤
│ arduino_mcp_server.py │
│ ├── High-level Tools (led_on, display_timer, etc.) │
│ ├── Background Monitor Thread │
│ │ ├── Reads: TIMER:REMAINING, COUNTDOWN:FINISHED │
│ │ ├── Reads: CLOCK:LCD:HH:MM:SS, DISTANCE: │
│ │ └── Executes: Queued conditional actions │
│ └── Conditional Engine (when_timer_finishes, etc.) │
└─────────────────────────────────────────────────────────────┘
↕ Serial (9600 baud)
┌─────────────────────────────────────────────────────────────┐
│ Arduino Layer (Firmware) │
├─────────────────────────────────────────────────────────────┤
│ master_control.ino │
│ ├── Non-blocking loop() orchestrates all devices │
│ ├── Command Protocol: DEVICE:ACTION:VALUE │
│ │ Example: LED:BLINK:500, TM1637:COUNTDOWN:90 │
│ ├── Display Modes: │
│ │ ├── LCD: clock, stopwatch, static text │
│ │ └── TM1637: clock, countdown, stopwatch, numbers │
│ └── Status Broadcasting (auto-reports state) │
└─────────────────────────────────────────────────────────────┘
↕
┌───────────────┐
│ Hardware │
│ Peripherals │
└───────────────┘
### 通信协议
|命令|格式|示例|描述|
|---------|--------|---------|-------------|
|LED控制| `LED:ACTION[:VALUE]` | `LED:BLINK:500` |LED每500ms闪烁一次|
|蜂鸣器| `BUZZER:ACTION[:VALUE]` | `BUZZER:BEEP:1000` |蜂鸣1秒|
|液晶显示器| `LCD:ACTION:VALUE` | `LCD:LINE1:Hello World` |写入LCD第1行|
|TM1637| `TM1637:ACTION:VALUE` | `TM1637:COUNTDOWN:90` |开始90秒倒计时|
|超声波| `ULTRA:ACTION` | `ULTRA:START` |开始持续监控|
|状态| `STATUS` | `STATUS` |获取所有设备状态|
______________________________________________________________________
## 📦 先决条件
### 硬件
- Arduino Uno、Nano或兼容板
- 用于编程和串行通信的USB电缆
- 中列出的组件 硬件堆栈
### 软件
|要求|版本|目的|
|------------|---------|---------|
| **python** |3.10+|MCP服务器和脚本|
| **Arduino集成开发环境** |1.8+或2.x|固件上传|
| **pyserial** |最新|串行通信|
| **fastmcp** |最新|AI代理集成|
### 操作系统
- **视窗** (默认COM端口: `COM6`)
- macOS/Linux兼容COM端口调整
______________________________________________________________________
## 🚀 安装和设置
### 步骤1:Arduino固件
1. **打开Arduino IDE**```
File → Open → master_control.ino
- 安装所需库```
Sketch → Include Library → Manage Libraries
Search: "LiquidCrystal_I2C" → Install
Search: "TM1637Display" → Install
1. **验证接线**
- 仔细检查连接是否匹配 硬件堆栈
- 测试LCD I2C地址(尝试 `0x27`,回退 `0x3F`)
1. **上传到董事会**```
Tools → Board → Arduino Uno (or your model)
Tools → Port → COM6 (or your port)
Upload ✓
第二步:Python环境
- 再进行```powershell
pip install pyserial fastmcp
1. **配置COM端口**
- 编辑 `arduino_mcp_server.py` 和 `master_control.py`
- 集 `COM_PORT = "COM6"` (根据您的端口进行调整)
- 检查设备管理器(Windows)或 `ls /dev/tty*` (Linux/Mac)
1. **验证连接**```python
from arduino_mcp_server import test_connection
print(test_connection())
# Expected: ✓ SUCCESS: Arduino is connected and ready on COM6
⚡ 快速开始
选项1:FastMCP服务器(用于AI代理)```powershell
python arduino_mcp_server.py
服务器公开了AI代理可以直接调用的工具。
### 选项2:交互式CLI(用于手动测试)```powershell
python master_control.py
尝试以下命令:```
led blink 500
buzzer beep 200
lcd 1:Hello Arduino!
display clock
ultra start
### 您的第一次自动化```python
from arduino_mcp_server import (
display_timer,
when_timer_finishes,
lcd_show_current_time
)
# Start a 30-second countdown on 7-segment display
display_timer(0, 30)
# When countdown finishes, beep 3 times (1 second each)
when_timer_finishes("buzzer_beep", "1000")
# Show live clock on LCD while timer runs
lcd_show_current_time()
💡 示例工作流
1.带警报的厨房定时器```python
from arduino_mcp_server import display_timer, when_timer_finishes, lcd_display_message
5-minute cooking timer
display_timer(5, 0)
Show message on LCD
lcd_display_message("Cooking Timer", "5:00 remaining")
Beep 5 times when done
when_timer_finishes("buzzer_beep", "500")
### 2.计划任务自动化```python
from arduino_mcp_server import lcd_show_current_time, when_time_equals, led_blink
# Display live clock
lcd_show_current_time()
# At 7:15 AM, start blinking LED (morning alarm)
when_time_equals("07:15:00", "led_blink", "1000")
# At 7:16 AM, show message
when_time_equals("07:16:00", "display_message", "Wake Up!|Time to Start")
3.近距离安全系统```python
from arduino_mcp_server import (
ultrasonic_start,
when_distance_less_than,
show_live_ultrasonic_on_lcd
)
Start monitoring distance and show on LCD
show_live_ultrasonic_on_lcd()
If object closer than 15cm, trigger alarm
when_distance_less_than(15, "buzzer_beep", "2000")
when_distance_less_than(15, "led_blink", "100")
### 4.多级倒计时链```python
from arduino_mcp_server import display_timer, when_timer_finishes
# Workout timer: 45 sec work → beep → 15 sec rest → beep → repeat
display_timer(0, 45)
when_timer_finishes("buzzer_beep", "500")
when_timer_finishes("start_timer", "00:15")
# Add more stages as needed!
5.状态仪表板```python
from arduino_mcp_server import (
get_current_status,
lcd_show_current_time,
display_current_time,
ultrasonic_start
)
Show time on both displays
lcd_show_current_time()
display_current_time()
Monitor distance
ultrasonic_start()
Check system status
print(get_current_status())
______________________________________________________________________
## 📚 API 参考
### 显示功能
|功能|参数|说明|
|----------|-----------|-------------|
| `lcd_show_current_time()` |--| LCD上的实时PC时间(每秒更新一次)|
| `lcd_start_stopwatch()` |--|从LCD上的00:00:00开始计数|
| `lcd_write_line1(text)` | `text: str` |LCD第1行上的静态文本(最多16个字符)|
| `lcd_write_line2(text)` | `text: str` |LCD第2行上的静态文本|
| `lcd_display_message(line1, line2)` | `line1, line2: str` |同时写两行|
| `lcd_clear()` |--|清除整个LCD|
| `display_current_time()` |--| 7段实时PC时间(HH:MM)|
| `display_timer(minutes, seconds)` | `minutes, seconds: int` | **实时倒计时** 至00:00,自动发出蜂鸣声|
| `display_start_stopwatch()` |--|从7段00:00开始倒计时|
| `display_number(number)` | `number: int` |显示静态数字(-999到9999)|
| `display_clear()` |--| 7段清晰显示|
### 执行器功能
|功能|参数|说明|
|----------|-----------|-------------|
| `led_on()` |--|打开LED(稳定)|
| `led_off()` |--|关闭LED|
| `led_blink(interval_ms)` | `interval_ms: int` (默认值:500)|连续闪烁|
| `led_toggle()` |--|翻转LED状态一次|
| `buzzer_on()` |--|连续蜂鸣器(呼叫 `buzzer_off()` 停止)|
| `buzzer_off()` |--|静音蜂鸣器|
| `buzzer_beep(duration_ms)` | `duration_ms: int` (默认值:100)|单次蜂鸣,自动停止|
### 传感器功能
|功能|参数|说明|
|----------|-----------|-------------|
| `ultrasonic_read()` |--|单距离测量(cm)|
| `ultrasonic_start()` |--|连续监测(间隔200ms)|
| `ultrasonic_stop()` |--|停止监控|
| `show_live_ultrasonic_on_lcd()` |--| LCD显示+自动更新距离|
### 条件自动化
|功能|参数|说明|
|----------|-----------|-------------|
| `when_timer_finishes(action, params)` | `action: str`, `params: str` |倒计时时执行操作→ 0 |
| `when_time_equals(time, action, params)` | `time: "HH:MM:SS"`, `action: str`, `params: str` |在特定时钟时间执行|
| `when_distance_less_than(cm, action, params)` | `cm: float`, `action: str`, `params: str` |对象太近时执行|
**可用操作:**
- `"buzzer_beep"` --params:持续时间(ms)(例如。, `"1000"`)
- `"start_timer"` --参数: `"MM:SS"` 格式(例如。, `"02:30"`)
- `"led_blink"` --params:以毫秒为单位的间隔(例如。, `"500"`)
- `"display_message"` --参数: `"Line1 · Line2"` (例如。, `"Alert! · Object Near"`)
### 系统功能
|功能|说明|
|----------|-------------|
| `get_current_status()` |获取计时器、时钟、距离、待处理操作|
| `clear_all_pending_actions()` |取消所有排队的触发器|
| `all_off()` |关闭/清除所有设备(紧急停止)|
| `test_connection()` |验证Arduino连接|
______________________________________________________________________
## 🔧 可扩展性和未来增强功能
### 易于扩展
Arduino MCP是为可扩展性而设计的。以下是如何增强它:
#### 1. **添加新硬件**
**示例:添加伺服电机**
*Arduino固件(`master_control.ino`):*```cpp
#include
Servo myservo;
void setup() {
myservo.attach(5); // Servo on pin 5
}
void handleServo(String action, String value) {
if (action == "MOVE") {
int angle = value.toInt();
myservo.write(angle);
Serial.println("OK:SERVO:MOVE");
}
}
// Add to processCommand():
else if (device == "SERVO") {
handleServo(action, value);
}
Python服务器(arduino_mcp_server.py):```python
@mcp.tool()
def servo_move(angle: int) -> str:
"""Move servo to specified angle (0-180 degrees)"""
if angle < 0 or angle > 180:
return "Error: Angle must be 0-180"
response = send_command(f"SERVO:MOVE:{angle}")
return f"Servo moved to {angle}°"
#### 2. **添加新传感器**
|传感器类型|集成复杂性|潜在用例|
|------------|------------------------|---------------------|
| **温度/湿度(DHT22)** |轻松|气候监测,自动风扇控制|
| **光传感器(LDR)** |轻松|自动亮度,日夜检测|
| **PIR运动传感器** |简单|安全警报、自动照明|
| **气体/烟雾探测器** |中等|安全警报,空气质量|
| **GPS模块** |中等|位置跟踪、地理围栏|
#### 3. **扩展条件操作**
在中添加更多触发器类型 `arduino_mcp_server.py`:```python
@mcp.tool()
def when_temperature_above(threshold: float, then_action: str, params: str) -> str:
"""Execute action when temperature exceeds threshold"""
action = {
"trigger": "temp_above",
"target_temp": threshold,
"action_type": then_action,
"params": parse_params(params)
}
pending_actions.append(action)
return f"✅ Will execute '{then_action}' when temp > {threshold}°C"
4. 创建复杂场景
多设备晨间例行程序:```python
def morning_routine():
6:30 AM: Start gentle alarm
when_time_equals("06:30:00", "led_blink", "2000")
6:45 AM: Louder alarm
when_time_equals("06:45:00", "buzzer_beep", "500")
7:00 AM: Show schedule on LCD
when_time_equals("07:00:00", "display_message", "Good Morning!|Check Schedule")
### 未来增强思路
|增强|难度|影响|
|-------------|-----------|--------|
| **网络仪表盘** |中等|通过浏览器实时监控|
| **MQTT集成** |中等|物联网设备网络兼容性|
| **语音控制** |中高|“Alexa,启动计时器”|
| **数据记录** |低|历史传感器数据存储|
| **移动应用** |高|通过智能手机进行远程控制|
| **多板支持** |中等|控制多个Arduino|
| **机器学习** |高|基于模式的预测自动化|
| **继电器控制** |易于控制|高压电器|
| **RGB LED灯带** |Easy Medium |高级照明效果|
| **SD卡记录** |中等|离线数据持久性|
______________________________________________________________________
## 📁 项目结构```
Arduino-MCP/
│
├── arduino_mcp_server.py # FastMCP server with tools + conditional engine
│ ├── Tool definitions (@mcp.tool decorators)
│ ├── Background monitor thread
│ ├── Conditional execution engine
│ └── Serial communication layer
│
├── master_control.ino # Arduino firmware
│ ├── Non-blocking loop() architecture
│ ├── Device handlers (LED, buzzer, LCD, TM1637, ultrasonic)
│ ├── Command parser
│ └── Status broadcasting
│
├── master_control.py # Async CLI controller for manual testing
│ ├── Interactive command menu
│ ├── Human-friendly interface
│ └── Testing utilities
│
├── README.md # This file
├── LICENSE # MIT License
└── .gitignore # Git ignore rules
🐛 故障排除
常见问题
| 问题 | 解决方案 |
|---|---|
| LCD什么也不显示 | •尝试I2C地址 0x3F 而不是 0x27 在固件中 |
•检查接线(SCL→10, SDA→11)
•验证背光是否打开: lcd_backlight_on() |
未找到端口错误 · •检查设备管理器(Windows)或 ls /dev/tty* (Linux)
•更新 COM_PORT 在Python文件中
•确保没有其他程序正在使用该端口|
时钟显示错误的时间 · •时钟从PC时间开始初始化,然后滴答作响
•重新呼叫 lcd_show_current_time() 重新同步|
倒计时不响 · •确保蜂鸣器连接到引脚13
•需要主动蜂鸣器(非被动)
•检查 buzzer_beep() 功能独立工作|
超声波给出-1 · •检查接线(跳闸→7, ECHO→6)
•确保物体距离2-400cm
•传感器需要清晰的视线|
命令没有响应 · •Arduino可能已重置(连接后等待2秒)
•检查固件和Python中的波特率是否为9600
•电话 test_connection() 验证|
调试模式
启用详细日志记录:```python
import logging
logging.basicConfig(level=logging.DEBUG)
检查Arduino状态:```python
from arduino_mcp_server import get_current_status
print(get_current_status())
🤝 贡献
欢迎投稿!以下是您可以提供帮助的方式:
贡献领域
- 🔧 新的硬件集成(传感器、执行器)
- 📚 文档改进
- 🐛 Bug修复和测试
- 💡 功能建议和实现
- 🎨 Web仪表板开发
开发设置
- 分叉存储库
- 创建要素分支:
git checkout -b feature/amazing-feature - 用实际硬件进行彻底测试
- 提交更改:
git commit -m 'Add amazing feature' - 推送到分支:
git push origin feature/amazing-feature - 打开拉取请求
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🙏 致谢
- FastMCP Marvin Halbach为优秀的MCP框架
- Arduino社区 硬件库及其启示
- AI代理开发人员 谁启发了智能硬件控制
🌟 如果你觉得这个仓库有用,就把它标上!
建于❤️ 面向制造商、修补匠和人工智能爱好者
报告Bug • 请求功能 • 讨论
