Arduino MCP

🤖 Arduino主控（Arduino MCP）

人工智能硬件自动化平台

   

*通过智能、事件驱动的自动化弥合人工智能代理和物理硬件之间的差距*

特性 • 硬件 • 快速开始 • 例子 • 扩展

______________________________________________________________________

📋 目录

• 什么是Arduino MCP？
• 主要特点
• 是什么让这个项目与众不同
• 硬件堆栈
• 系统架构
• 先决条件
• 安装和设置
• 快速开始
• 示例工作流
• API 参考
• 可扩展性和未来增强功能
• 项目结构
• 故障排除
• 贡献
• 许可证

______________________________________________________________________

🎯 什么是Arduino MCP？

Arduino MCP 是一个AI控制的自动化平台，将Python AI代理与基于Arduino的硬件外围设备连接起来。它通过结合以下内容，实现了无需人工监督的复杂、多步骤场景：

• 实时硬件控制：显示器、传感器和执行器的实时更新
• 事件驱动自动化：后台监控和条件触发器执行
• 人工智能集成：为自然语言AI代理控制设计的高级工具
• 非阻塞架构：固件无缝运行多个并发任务

它解决的问题

传统的Arduino项目需要：

• 手动、连续控制或闭锁代码
• 用于多设备协调的复杂状态管理
• 持续轮询基于时间或传感器触发的事件
• 难以与AI/自动化系统集成

解决方案

Arduino MCP提供：

• ✅ 高级Python API 用于直观控制
• ✅ 自动背景监控 计时器、时钟和传感器
• ✅ 条件执行引擎 在没有轮询的情况下链接操作
• ✅ 实时显示 无需Python干预即可在设备上进行更新
• ✅ FastMCP集成 用于无缝的AI代理通信

______________________________________________________________________

✨ 主要特点

🖥️ 显示管理

🔧 硬件控制

⚡ 条件自动化（明星功能！）

后台触发的操作 无需轮询即可自动执行：

可用操作：

• buzzer_beep --声音警报
• start_timer --开始倒计时
• led_blink --视觉指示器
• display_message --在LCD上显示文本

______________________________________________________________________

🌟 是什么让这个项目与众不同

1. 真实生活行为

与需要不断Python调用的典型Arduino草图不同，我们的固件运行显示器和计时器 自主地 在非阻塞回路中：

• 时钟每秒自动滴答作响
• 倒计时在没有Python干预的情况下递减
• 与LED闪烁相同的策略——设置一次，它就永远运行

2. AI优先设计

专为通过FastMCP进行AI代理控制而构建：

• 高级、意图驱动的功能
• 与自然语言兼容的工具描述
• 内置复杂场景解析（例如，“启动计时器，然后发出蜂鸣声，然后在上午7:15启动另一个计时器”）

3. 条件执行引擎

Python后台监视器监视Arduino状态消息和 自动执行排队的操作:

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方法：设置触发器→ 本底监测器→ 动作自动执行

______________________________________________________________________

🔌 硬件堆栈

组件

接线图

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 │
                    └───────────────┘

通信协议

______________________________________________________________________

📦 先决条件

硬件

• Arduino Uno、Nano或兼容板
• 用于编程和串行通信的USB电缆
• 中列出的组件 硬件堆栈

软件

操作系统

• 视窗 （默认COM端口： COM6)
• macOS/Linux兼容COM端口调整

______________________________________________________________________

🚀 安装和设置

步骤1:Arduino固件

1. 打开Arduino IDE

   File → Open → master_control.ino

1. 安装所需库

   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环境

1. 再进行

   pip install pyserial fastmcp

1. 配置COM端口

- 编辑 arduino_mcp_server.py 和 master_control.py - 集 COM_PORT = "COM6" （根据您的端口进行调整） - 检查设备管理器（Windows）或 ls /dev/tty* （Linux/Mac）

1. 验证连接

   from arduino_mcp_server import test_connection
   print(test_connection())
   # Expected: ✓ SUCCESS: Arduino is connected and ready on COM6

______________________________________________________________________

⚡ 快速开始

选项1:FastMCP服务器（用于AI代理）

python arduino_mcp_server.py

服务器公开了AI代理可以直接调用的工具。

选项2：交互式CLI（用于手动测试）

python master_control.py

尝试以下命令：

led blink 500
buzzer beep 200
lcd 1:Hello Arduino!
display clock
ultra start

您的第一次自动化

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.带警报的厨房定时器

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.计划任务自动化

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.近距离安全系统

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.多级倒计时链

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.状态仪表板

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 参考

显示功能

执行器功能

传感器功能

条件自动化

可用操作：

• "buzzer_beep" --params：持续时间（ms）（例如。， "1000")
• "start_timer" --参数： "MM:SS" 格式（例如。， "02:30")
• "led_blink" --params：以毫秒为单位的间隔（例如。， "500")
• "display_message" --参数： "Line1|Line2" （例如。， "Alert!|Object Near")

系统功能

______________________________________________________________________

🔧 可扩展性和未来增强功能

易于扩展

Arduino MCP是为可扩展性而设计的。以下是如何增强它：

1. 添加新硬件

示例：添加伺服电机

*Arduino固件(master_control.ino):*

#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):*

@mcp.tool()
def servo_move(angle: int) -> str:
    """Move servo to specified angle (0-180 degrees)"""
    if angle  180:
        return "Error: Angle must be 0-180"
    response = send_command(f"SERVO:MOVE:{angle}")
    return f"Servo moved to {angle}°"

2. 添加新传感器

3. 扩展条件操作

在中添加更多触发器类型 arduino_mcp_server.py:

@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. 创建复杂场景

多设备晨间例行程序：

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")

未来增强思路

______________________________________________________________________

📁 项目结构

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

______________________________________________________________________

🐛 故障排除

常见问题

•检查接线（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() 验证|

调试模式

启用详细日志记录：

import logging
logging.basicConfig(level=logging.DEBUG)

检查Arduino状态：

from arduino_mcp_server import get_current_status
print(get_current_status())

______________________________________________________________________

🤝 贡献

欢迎投稿！以下是您可以提供帮助的方式：

贡献领域

• 🔧 新的硬件集成（传感器、执行器）
• 📚 文档改进
• 🐛 Bug修复和测试
• 💡 功能建议和实现
• 🌍 多语言支持
• 🎨 Web仪表板开发

开发设置

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/amazing-feature
3. 用实际硬件进行彻底测试
4. 提交更改： git commit -m 'Add amazing feature'
5. 推送到分支： git push origin feature/amazing-feature
6. 打开拉取请求

______________________________________________________________________

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

🙏 致谢

• FastMCP Marvin Halbach为优秀的MCP框架
• Arduino社区 硬件库及其启示
• AI代理开发人员 谁启发了智能硬件控制

______________________________________________________________________

🌟 如果你觉得这个仓库有用，就把它标上！

建于❤️ 面向制造商、修补匠和人工智能爱好者