# 机器人仿真模型

**Repository Path**: zhuzhenyu_0702/robot-simulation-model

## Basic Information

- **Project Name**: 机器人仿真模型
- **Description**: 车加机械臂
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-18
- **Last Updated**: 2026-10-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PiPER 机械臂 MuJoCo 仿真平台

基于 [松灵 PiPER](https://github.com/agilexrobotics/piper_ros) 官方模型的 MuJoCo 仿真环境，
用于视觉-语言-动作（VLA）模型部署、数据采集与主动视觉研究。

支持关节控制、笛卡尔空间逆运动学、夹爪抓取、双相机渲染、示教操作，
并提供 ROS2 与 UDP 两套状态发布通道。

## 特性

- **官方模型修正**：修复了官方 MJCF 中底座穿地、连杆自碰撞、执行器力矩不足、
  质量缺失等问题（详见 `docs/02-piper-model-notes.md`）
- **完整控制栈**：关节位置控制、夹爪开合、末端位姿 IK（含奇异性处理与多初值求解）
- **抓取能力**：指尖碰撞几何 + 可抓取物体，可完成抓取-抬升全流程
- **双相机**：腕部相机 + 外部相机，支持离屏渲染
- **示教器 GUI**：滑条 / 数值输入 / 笛卡尔点动 / 示教点 / 轨迹录制
- **通信双通道**：ROS2 标准话题 + UDP JSON 调试通道
- **可复现环境**：Docker + ROS2 Humble，宿主环境零污染

## 快速开始

```bash
# 构建镜像（首次约 5–10 分钟）
./scripts/build.sh

# 运行测试
./scripts/run.sh python tests/test_m0_model.py
./scripts/run.sh python tests/test_m2_gripper.py
./scripts/run.sh python tests/test_m3_ik.py

# 启动示教器（可选 ROS2 / UDP 发布）
./scripts/run.sh python src/piper_sim/teach_pendant.py --ros2
```

容器内已自动 source ROS2，并设置好 `PYTHONPATH`。

## 环境

| 项 | 版本 |
|---|---|
| 操作系统 | Ubuntu 22.04 LTS (jammy) |
| ROS | Humble |
| Python | 3.10 |
| MuJoCo | 3.2.7 |
| 基础镜像 | `ros:humble-ros-base` |

交互窗口通过 X11 转发；无显示器时用 `MUJOCO_GL=egl` 离屏渲染。

## 目录结构

```
piper_vla/
├── docker/               # Dockerfile 与 compose 配置
├── src/piper_sim/
│   ├── model.py          # 模型加载、限位校验、夹爪换算
│   ├── robot.py          # 统一机器人接口
│   ├── ik.py             # 逆运动学（含多初值求解）
│   ├── teach_pendant.py  # 示教器 GUI
│   ├── ros2_publisher.py # ROS2 状态发布
│   ├── state_publisher.py# UDP 状态发布 / 监听
│   └── assets/piper/     # 机器人模型、场景、网格
├── tests/                # 测试与工作空间标定
├── docs/                 # 设计文档与测试记录
└── scripts/              # 构建、进入容器、运行
```

## 测试

| 测试 | 内容 |
|---|---|
| `test_m0_model.py` | 模型结构、关节限位、执行器、质量 |
| `test_m1_joint_tracking.py` | 关节阶跃与正弦跟踪 |
| `test_m2_gripper.py` | 夹爪镜像、接触、抓取保持 |
| `test_m2_gripper_definition.py` | 夹爪与官方 URDF / SDK 对齐 |
| `test_m3_ik.py` | 逆运动学精度与不可达检测 |
| `test_m3_ik_performance.py` | 求解性能与奇异性 |
| `test_m3_ik_restarts.py` | 多初值求解与不可行性诊断 |
| `test_m3_tcp_definition.py` | TCP 定义与 SDK 对齐 |
| `calibrate_workspace.py` | 工作空间标定（产出报告） |

测试规范与通过标准见 `docs/04-testing-spec.md`，实测记录见 `docs/tests/`。

## 关键约定

### 三个"末端"点

| 名称 | 说明 |
|---|---|
| `sdk_j6` | SDK 的 `GetArmEndPoseMsgs()` / `EndPoseCtrl()` 操作的点 |
| `tcp` | 两指尖中点，接口的 `tcp_pose` 用这个 |
| `fingertip` | 指尖前端面 |

`tcp` 与 `sdk_j6` 相距 **143.8 mm**，接真机时必须做换算。

### 夹爪

单自由度，用开合宽度控制。`joint7` 单侧行程 0→0.035 m，两指镜像，
总开口 `2 × joint7` = **70 mm**，与 SDK 的 `max_range_config` 一致。

### 工作空间

"指尖朝下"（抓取最常用姿态）的可达范围为
**x ∈ [0.15, 0.45] m，z ∈ [0.06, 0.16] m**，调整场景后需重新标定。

## 通信接口

### ROS2

```
/piper/joint_states       sensor_msgs/JointState
/piper/tcp_pose           geometry_msgs/PoseStamped
/piper/gripper_state      std_msgs/Float64MultiArray
/piper/command            sensor_msgs/JointState
```

### UDP（调试通道）

JSON over UDP，默认端口 17800。

```bash
./scripts/run.sh python src/piper_sim/state_publisher.py --listen
```

## 文档

| 文档 | 内容 |
|---|---|
| `docs/00-PLAN.md` | 总计划与里程碑 |
| `docs/01-hardware-architecture.md` | 整体硬件与控制架构 |
| `docs/02-piper-model-notes.md` | 官方模型的问题与修正 |
| `docs/03-interface-spec.md` | 机器人接口与动作约定 |
| `docs/04-testing-spec.md` | 测试规范 |
| `docs/05-mobile-base-plan.md` | 移动底盘集成方案 |
| `docs/06-progress-handoff.md` | 进度总结与交接 |
| `docs/tests/` | 各测试的实测记录 |

## 许可

[Apache License 2.0](LICENSE)

模型与网格资源来自 [agilexrobotics/piper_ros](https://github.com/agilexrobotics/piper_ros)，
遵循其原始许可。