Dumb Arm Control API

机器人手臂控制系统

基于Raspberry Pi的机器人手臂控制系统，设计时考虑了人工智能驱动的自主性。该系统为直接电机控制提供了一个简单的REST API，同时通过MCP（模型上下文协议）服务器支持智能代理控制。

🚀 特性

• 简单REST API 用于直接伺服控制
• 全面的安全功能 包括紧急停车和边界检查
• 可配置的硬件设置 通过YAML配置
• AI就绪架构 用于未来的MCP服务器集成
• 模拟硬件模式 用于开发和测试
• 广泛的日志记录和监控

📋 需求

硬件

• Raspberry Pi 4B（建议使用2GB+RAM）
• 伺服电机（SG90、MG996R或类似产品）
• 5V电源，具有足够的电流容量
• 面包板和跳线
• 紧急停止按钮（可选，但推荐）
• 状态指示灯（可选）

软件

• Raspberry Pi操作系统（基于Debian）
• Python 3.9+
• 所需的Python包（请参阅 requirements.txt)

🛠️ 安装

1.克隆存储库

git clone 
cd robo-arm-control

2.安装依赖项

# Install system dependencies
sudo apt-get update
sudo apt-get install python3-pip python3-venv

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install Python dependencies
pip install -r requirements.txt

3.配置硬件

1. 按照中的定义将伺服系统连接到GPIO引脚 config/config.yaml
2. 将紧急停止按钮连接到GPIO引脚21（可配置）
3. 将状态指示灯连接到GPIO引脚22（可配置）
4. 确保所有伺服系统都有适当的电源

4.配置系统

编辑 config/config.yaml 要匹配您的硬件设置：

hardware:
  servos:
    servo_1:
      name: "Base Rotation"
      pin: 18
      min_angle: 0
      max_angle: 180
      # ... other settings

⚙️ 配置

系统使用全面的YAML配置文件(config/config.yaml)其中包括：

硬件配置

• 伺服设置：引脚分配、角度范围、脉冲宽度
• GPIO配置：紧急停止，状态指示灯
• 安全限值：每个伺服系统的软限制

安全配置

• 紧急停止：启用/禁用和超时设置
• 边界检查：职位验证
• 速度限制：全局和每个伺服限制
• 超时保护：命令和移动超时

API配置

• 服务器设置：主机、端口、调试模式
• CORS 设置：跨来源资源共享
• 速率限制：请求限制和突发保护

开发配置

• 模拟硬件：无需物理硬件即可进行测试
• 测试模式：减少测试的伺服次数
• 日志记录：详细的日志记录和诊断

🧪 测试配置

运行配置测试以验证您的设置：

python src/utils/test_config.py

这将：

• 加载并验证配置文件
• 显示所有配置的伺服系统及其设置
• 测试位置验证和速度限制
• 验证安全和API设置

🚀 用法

启动API服务器

# From the project root
python -m src.main

API将于 http://localhost:8000

API终点

设置伺服位置

curl -X POST "http://localhost:8000/api/servos/servo_1/position" \
     -H "Content-Type: application/json" \
     -d '{"position": 90, "speed": 50}'

获取伺服位置

curl "http://localhost:8000/api/servos/servo_1/position"

紧急停止

curl -X POST "http://localhost:8000/api/emergency-stop"

系统状态

curl "http://localhost:8000/api/status"

交互式API文档

访问 http://localhost:8000/docs 用于Swagger UI提供的交互式API文档。

🔧 发展

项目结构

robo-arm-control/
├── .cursorrules                 # Cursor AI rules
├── PROJECT_DOCUMENT.md          # Project specification
├── README.md                    # This file
├── requirements.txt             # Python dependencies
├── config/
│   └── config.yaml             # Main configuration file
├── src/
│   ├── main.py                 # FastAPI application entry point
│   ├── hardware/               # Hardware control modules
│   ├── api/                    # REST API modules
│   ├── utils/                  # Utility modules
│   └── tests/                  # Test modules
├── scripts/                    # Setup and utility scripts
└── docs/                       # Documentation

运行测试

# Run configuration tests
python src/utils/test_config.py

# Run unit tests (when implemented)
pytest src/tests/

发展模式

启用无物理伺服的模拟硬件进行开发：

development:
  mock_hardware: true
  test_mode: true
  test_servo_count: 2

🔒 安全功能

内置安全机制

• 位置边界检查：防止伺服系统超出安全限制
• 速度限制：防止损坏的最大速度限制
• 紧急停止：立即停止所有电机运动
• 超时保护：如果命令超过时间限制，则自动停止
• 软限制：软件强制限制比硬件限制更严格

安全配置

所有安全功能都可以在中配置 config/config.yaml:

safety:
  enabled: true
  emergency_stop_enabled: true
  bounds_checking_enabled: true
  speed_limiting_enabled: true
  global_max_speed: 80
  command_timeout: 5000

🔮 未来功能

第2阶段：增强的API功能

• 动作顺序和协调
• 高级安全功能
• 状态监测和记录
• 性能优化

第3阶段：MCP服务器集成

• MCP服务器实现
• AI代理工具和功能
• 自主运动算法
• 多智能体协调

第四阶段：高级AI功能

• 计算机视觉集成
• 路径规划算法
• 从示范中学习
• 预测性维护

🐛 故障排除

常见问题

未找到配置文件

FileNotFoundError: Configuration file not found: config/config.yaml

解决方案：确保配置文件存在并且路径正确。

GPIO权限错误

PermissionError: [Errno 13] Permission denied

解决方案：使用sudo运行或将您的用户添加到 gpio 组：

sudo usermod -a -G gpio $USER

伺服系统无响应

• 检查电源电压和电流
• 验证GPIO引脚连接
• 检查配置中的伺服脉冲宽度设置
• 首先使用模拟硬件模式进行测试

调试模式

在配置中启用调试模式以进行详细日志记录：

system:
  debug_mode: true
  log_level: "DEBUG"

📝 贡献

1. 遵循中定义的编码标准 .cursorrules
2. 为新功能添加测试
3. 根据需要更新文档
4. 确保所有安全功能都得到正确实施

📄 许可证

\[在此处添加您的许可证信息\]

🤝 支持

对于问题和疑问：

1. 检查故障排除部分
2. 查看配置文档
3. 使用模拟硬件模式进行测试
4. 创建包含详细错误信息的问题

______________________________________________________________________

⚠️ 安全警告：在全面操作之前，始终在安全的环境中进行测试。确保紧急停止功能正常工作且易于使用。