Metadata-Version: 2.4
Name: mmk2-sdk
Version: 0.0.4.dev5
Summary: SDK for MMK2 dual-arm robot with mobile base
Author-email: Hanyang <shy757@126.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8.1
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: grpcio>=1.68.1
Requires-Dist: protobuf>=5.29.1
Requires-Dist: numpy>=1.21.0
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: scipy
Requires-Dist: loguru
Requires-Dist: Pillow
Requires-Dist: PyOpenGL
Requires-Dist: glfw
Requires-Dist: mujoco
Requires-Dist: pygame
Requires-Dist: screeninfo
Requires-Dist: PyYAML
Dynamic: license-file

# MMK2 SDK

## 概述

MMK2 SDK 是 mmk2 机器人控制SDK，提供统一的、用户友好的API接口，支持多种运行模式，并隐藏底层gRPC实现的复杂性。
真机和仿真器模式下，提供一致的API接口，混合模式下，同时支持真机和仿真器的控制。

三种运行模式：
- 真机模式（REAL）
- 仿真器模式（SIM）
- 混合模式（MIXED）

## 主要特性

- **统一接口**: 提供一致的API接口，支持真机、仿真器、混合模式
- **用户友好**: 隐藏gRPC复杂性，提供直观的Python接口
- **状态检查**: 实现闭环控制，确保执行到位
- **模块化设计**: 清晰的架构分层，便于维护和扩展
- **错误处理**: 完善的错误处理和报警机制

## 安装

### 方式一：从源码安装（开发环境）

```bash
# 安装依赖
pip install -r requirements.txt

# 安装SDK（开发模式）
pip install -e .

# 安装SDK及UI依赖
pip install -e .[ui]
```

### 方式二：从 Wheel 包安装（推荐，体积更小）

```bash
# 构建 wheel 包
pip install build
python -m build

# 安装 wheel 包（包含 SDK 和 UI）
pip install dist/mmk2_sdk-*.whl[ui]

# 或仅安装 SDK（不包含 UI）
pip install dist/mmk2_sdk-*.whl
```

### 方式三：使用 PyInstaller 打包为独立可执行文件（体积较大）

```bash
# 安装依赖
pip install .[ui]

# 打包UI应用为独立可执行文件
pyinstaller --clean -y ./src/mmk2_ui/app.spec
```

### 运行 UI 应用

安装后，可通过以下命令运行 UI：

```bash
# 如果安装了 wheel 包
mmk2-ui

# 或使用 Python 模块方式
python -m mmk2_ui.main
```

## 运行模式

### 真机模式 (REAL)

```python
robot = MMK2Robot(ip="172.25.14.1", mode=RobotMode.REAL)
```

### 仿真器模式 (MUJOCO) - 待实现

```python
robot = MMK2Robot(ip="localhost", mode=RobotMode.MUJOCO)
```

### 混合模式 (TWIN) - 待实现

```python
robot = MMK2Robot(ip="172.25.14.1", mode=RobotMode.TWIN)
```

##
## API文档

详细的API文档请参考：
- [MMK2 SDK API文档](docs/mmk2_sdk_api.md)
- [MMK2 SDK设计文档](docs/mmk2_sdk_design_v2.md)

## 架构设计

```
MMK2 SDK
├── 用户接口层 (User Interface Layer)
│   ├── MMK2Robot (统一入口)
│   ├── MMK2Camera (相机管理)
│   └── MMK2BaseControl (底盘控制)
├── 抽象接口层 (Abstract Interface Layer)
│   └── MMK2ControlInterface (基类)
├── 实现层 (Implementation Layer)
│   ├── MMK2RealRobot (真机实现)
│   ├── MMK2MujocoRobot (仿真器实现) - 待实现
│   └── MMK2TwinRobot (混合模式实现) - 待实现
└── 底层通信层 (Communication Layer)
    ├── AirbotMMK2 (gRPC客户端)
    └── ConnectionMonitor (连接监控)
```

## 文件结构

```
src/mmk2_sdk/
├── __init__.py
├── robot/
│   ├── __init__.py
│   ├── mmk2_robot.py          # 统一入口类
│   ├── mmk2_camera.py         # 相机管理类
│   ├── mmk2_base_control.py   # 底盘控制类
│   └── interfaces/
│       ├── __init__.py
│       ├── base_robot_interface.py  # 抽象基类
│       ├── real_robot.py      # 真机实现
│       ├── mujoco_robot.py    # 仿真器实现 - 待实现
│       └── twin_robot.py      # 混合模式实现 - 待实现
├── utils/
│   ├── __init__.py
│   ├── status_checker.py      # 状态检查器
│   └── error_handler.py       # 错误处理器
└── types/
    ├── __init__.py
    ├── robot_types.py         # 机器人类型定义
    └── enums.py               # 枚举定义
```

## 开发计划

### 已完成 ✅
- [x] 设计文档和API规范
- [x] MMK2RealRobot真机控制类
- [x] MMK2Camera相机管理类
- [x] MMK2BaseControl底盘控制类
- [x] StatusChecker状态检查器
- [x] ErrorHandler错误处理器
- [x] 测试脚本

### 待实现 🔄
- [ ] MMK2MujocoRobot仿真器控制类
- [ ] MMK2TwinRobot混合模式控制类
- [ ] 更多高级功能



## 贡献

欢迎提交Issue和Pull Request来改进这个项目。

## 许可证

本项目采用MIT许可证。
