# hexapod-evolve

**Repository Path**: jkin8010/hexapod-evolve

## Basic Information

- **Project Name**: hexapod-evolve
- **Description**: 树莓派六足机器人 + Qwen2.5测试项目
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-03-27
- **Last Updated**: 2026-03-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 六足机器人控制系统

## 项目概述
本项目是一个基于Python的六足机器人控制系统，支持多种控制方式（远程App、游戏手柄、语音交互），并集成了大模型Agent实现智能控制。系统采用模块化设计，具有良好的可扩展性和可维护性。

## 系统架构

### 目录结构
```
hexapod/
├── src/                # 源代码目录
│   ├── robot_core/    # 核心控制模块
│   ├── sensors/       # 传感器模块
│   ├── mcp/          # MCP协议实现
│   │   ├── servers/  # MCP服务器
│   │   ├── mcp_client.py
│   │   └── servers_manager.py
│   ├── interfaces/    # 控制接口
│   ├── agent/        # 智能代理
│   ├── config/       # 配置文件
│   └── utils/        # 工具库
├── docs/             # 文档
│   ├── mcp_development_guide.md  # MCP开发指南
│   └── 项目架构设计文档.md
├── tests/            # 测试文件
└── logs/             # 日志文件
```

### 模块说明

#### 1. 核心控制层 (robot_core)
- `motion_controller.py`: 运动控制核心
- `servo_controller.py`: 舵机控制
- `balance_controller.py`: 平衡控制
- `action_executor.py`: 动作执行器

#### 2. 传感器层 (sensors)
- `imu_sensor.py`: IMU传感器
- `ultrasonic_sensor.py`: 超声波传感器
- `vision_sensor.py`: 视觉传感器

#### 3. MCP协议层 (mcp)
- `mcp_client.py`: MCP客户端实现
- `servers_manager.py`: MCP服务器管理器
- `servers/`: MCP服务器包
  - `motion_server.py`: 运动控制服务器
  - `servo_server.py`: 舵机控制服务器
  - `imu_server.py`: IMU传感器服务器
  - `ultrasonic_server.py`: 超声波传感器服务器
  - `camera_server.py`: 相机服务器
  - `voice_server.py`: 语音服务器
  - `battery_server.py`: 电池状态服务器
  - `status_server.py`: 系统状态服务器
  - `config_server.py`: 配置管理服务器

#### 4. 控制接口层 (interfaces)
- `remote_server.py`: 远程控制服务
- `joystick_controller.py`: 手柄控制
- `voice_controller.py`: 语音控制

#### 5. 智能代理层 (agent)
- `agent_core.py`: 代理核心
- `intent_processor.py`: 意图理解
- `action_planner.py`: 动作规划
- `sensor_fusion.py`: 传感器融合

#### 6. 配置管理 (config)
- `robot_config.py`: 机器人配置
- `sensor_config.py`: 传感器配置
- `agent_config.py`: 代理配置

#### 7. 工具库 (utils)
- `logging.py`: 日志工具
- `pid_controller.py`: PID控制器
- `filter.py`: 信号滤波

## 安装部署

### 环境要求
- Python 3.10+
- Raspberry Pi OS (推荐)
- 相关硬件依赖（舵机、传感器等）

### 环境初始化
在开始开发前，需要执行以下环境初始化步骤：

1. 设置串口权限和配置pigpiod服务：
```bash
# 进入scripts目录
cd src/scripts

# 执行环境初始化脚本
chmod +x setup_env.sh
./setup_env.sh
```

该脚本会：
- 设置串口设备权限（/dev/ttyS0）
- 配置pigpiod服务开机自启
- 启动pigpiod服务
- 检查服务状态和串口权限

2. 检查环境是否配置成功：
```bash
# 检查串口权限
ls -l /dev/ttyS0  # 应该显示权限为 666

# 检查pigpiod服务状态
systemctl status pigpiod  # 应该显示服务正在运行
```

### 安装uv
```bash
# 使用 curl 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或者使用 pip 安装
pip install uv
```

### 项目安装
```bash
# 创建虚拟环境
uv venv

# 激活虚拟环境
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate     # Windows

# 安装项目依赖
uv pip install -e .

# 安装开发依赖
uv pip install -e ".[dev]"
```

### 配置说明
1. 修改 `config/robot_config.py` 中的机器人参数
2. 配置 `config/sensor_config.py` 中的传感器参数
3. 设置 `config/agent_config.py` 中的代理参数

## 使用说明

### 启动MCP服务
```bash
# 启动MCP服务器
python src/interfaces/mcp_server_entry.py
```

### 控制方式
1. **MCP控制**
   - 通过MCP协议控制机器人
   - 支持多种传感器和控制接口
   - 集成大模型Agent实现智能控制

2. **远程App控制**
   - 通过TCP连接控制机器人
   - 支持自定义动作和实时控制

3. **手柄控制**
   - 支持PS4/Xbox手柄
   - 实时控制机器人运动

4. **语音控制**
   - 支持语音指令识别
   - 通过大模型Agent理解意图

## 开发指南

### MCP开发
详细MCP开发指南请参考 [MCP开发指南](docs/mcp_development_guide.md)

### 代码规范
- 遵循PEP 8编码规范
- 使用类型注解
- 编写完整的文档字符串
- 保持代码简洁清晰

### 测试规范
- 单元测试覆盖核心功能
- 集成测试确保模块协作
- 性能测试保证系统稳定性

### 版本控制
- 使用Git进行版本控制
- 遵循语义化版本号
- 保持提交信息清晰

## 注意事项
1. 确保硬件连接正确
2. 注意电源管理
3. 定期检查传感器状态
4. 做好异常处理

## 贡献指南
1. Fork 项目
2. 创建特性分支
3. 提交更改
4. 推送到分支
5. 创建Pull Request

## 许可证
本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

## 联系方式
如有问题或建议，请通过以下方式联系：
- 项目Issues
- 邮件联系