# LeARM_Virtual_Simulation

**Repository Path**: slick-zhang/LeARM_Virtual_Simulation

## Basic Information

- **Project Name**: LeARM_Virtual_Simulation
- **Description**: LeARM仿真，无ROS2
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LeArm — Hiwonder LeArm 机械臂 Gazebo 模型

> 6-DOF 桌面机械臂的独立 Gazebo Fortress 模型，**无需 ROS 2**，纯 SDF + Ignition Transport 控制。

该模型从 [andrewda/learm_ros2](https://github.com/andrewda/learm_ros2) 的 `learm_ros2_description` 包提取，兼容 Gazebo Fortress (Ignition Gazebo 6.x)。

## 项目结构

```
learm_model/
├── go.sh               # 启动 Gazebo 仿真
├── ctrl.sh             # 关节速度控制脚本
├── servo.sh            # 机械臂联动与位置控制（支持联动夹爪并行控制）
├── gui.config          # Gazebo GUI 布局配置
├── model.sdf           # 机械臂 SDF 模型（包含夹爪四连杆闭环物理约束）
├── model.config        # 模型元信息
├── learm.urdf          # URDF 模型（也补充了闭环约束逻辑）
├── learm_world.sdf     # 世界文件（地面 + 光照 + 模型）
└── meshes/             # STL 网格文件（10 个）
    ├── base.stl        (~3.6 MB)  底座
    ├── shoulder.stl    (~3.2 MB)  肩部云台
    ├── humerus.stl     (~2.4 MB)  大臂
    ├── forearm.stl     (~2.7 MB)  前臂
    ├── wrist.stl       (~5.8 MB)  腕部
    ├── hand.stl        (~4.2 MB)  手掌
    ├── carpal-left.stl (~130 KB)  左夹爪
    ├── carpal-right.stl(~521 KB)  右夹爪
    ├── tendon.stl      (~131 KB)  腱
    └── finger.stl      (~167 KB)  指尖
```

## 依赖

- **Gazebo Fortress** (Ignition Gazebo 6.x / `ign-gazebo`)
- **Ignition Transport** (`ign-transport`)

```bash
# Ubuntu 22.04 安装
sudo apt install ignition-fortress
```

## 快速开始

### 1. 启动仿真

```bash
cd ~/learm_model
./go.sh
```

这会打开 Gazebo GUI，LeArm 站在地面上，关节初始位置为零。

### 2. 控制关节

打开**另一个终端**：

```bash
cd ~/learm_model
```

#### 舵机 PWM 控制

模拟实体舵机：PWM 范围 500-2500，默认值 500。

| 舵机 ID | 关节名 | 功能 | PWM 500→角度 | PWM 2500→角度 |
|---------|--------|------|-------------|--------------|
| ID1 | `grip_left` | 夹爪开合 | -1.57 rad (闭合) | 0 (张开) |
| ID2 | `wrist_flex` | 腕部弯曲 | -1.57 rad | +1.57 rad |
| ID3 | `wrist_roll` | 腕部旋转 | -1.57 rad | +1.57 rad |
| ID4 | `elbow` | 肘部弯曲 | -1.57 rad | +1.57 rad |
| ID5 | `shoulder_lift` | 肩部俯仰 | -1.57 rad | +1.57 rad |
| ID6 | `shoulder_pan` | 底座旋转 | -1.57 rad | +1.57 rad |

```bash
# 单个舵机控制：./servo.sh <舵机ID> <PWM值>
./servo.sh 1 2500        # ID1 夹爪张开
./servo.sh 4 1500        # ID4 肘部居中
./servo.sh 6 1500        # ID6 底座旋转到中心
./servo.sh all 500       # 全部回到默认(最小值)

# 姿态控制：./pose.sh <pwm1> <pwm2> ... <pwm6>
./pose.sh home           # 预设：全部最小值
./pose.sh rest           # 预设：全部居中(夹爪张开)
./pose.sh ready          # 预设：预备姿态
./pose.sh 2500 1200 1400 1800 1500 1500   # 自定义 6 个 PWM
```

> **PWM → 角度公式**：
> - ID1：`angle = (PWM − 500) / 2000 × π/2 − π/2`（500=闭合, 2500=张开）
> - ID2~6：`angle = (PWM − 500) / 2000 × π − π/2`（500=−1.57, 1500=0, 2500=+1.57）

#### 弧度位置控制（备用）

```bash
# 底座旋转到中心
./pos_ctrl.sh shoulder_pan 0

# 肩部抬起 0.5 rad
./pos_ctrl.sh shoulder_lift 0.5

# 肘部弯曲 -0.8 rad
./pos_ctrl.sh elbow -0.8

# 腕部弯曲
./pos_ctrl.sh wrist_flex 0.3

# 腕部旋转
./pos_ctrl.sh wrist_roll 0.5

# 夹爪闭合 (-1.57 闭合, 0 张开)
./pos_ctrl.sh grip_left -1.57

# 所有关节归零
./pos_ctrl.sh all 0
```

> **位置控制**：关节会自动移动到目标角度并保持。使用 `JointController` PID 闭环控制。

#### 速度控制（兼容保留）

```bash
# 底座旋转（顺时针/逆时针）
./ctrl.sh shoulder_pan 0.5       # 逆时针 0.5 rad/s
./ctrl.sh shoulder_pan -0.5      # 顺时针 0.5 rad/s

# 肩部俯仰
./ctrl.sh shoulder_lift 0.3      # 抬升
./ctrl.sh shoulder_lift -0.3     # 下压

# 肘部
./ctrl.sh elbow 0.5              # 弯曲
./ctrl.sh elbow -0.5             # 伸展

# 腕部
./ctrl.sh wrist_flex 0.3         # 腕部弯曲
./ctrl.sh wrist_roll 0.8         # 腕部旋转

# 夹爪
./ctrl.sh grip_left 0.3          # 左夹爪闭合
./ctrl.sh grip_left -0.3         # 左夹爪张开
./ctrl.sh grip_right 0.3         # 右夹爪闭合

# 停止任意关节
./ctrl.sh shoulder_pan 0         # 停止底座
```

> **注意**：速度模式下关节会**持续转动**直至收到 `0` 命令。请及时发送停止指令。

### 3. 直接通过 Ignition Transport 发送命令

```bash
# 位置命令（推荐）
ign topic -t "/model/learm/joint/<joint_name>/cmd_pos" \
  -m ignition.msgs.Double \
  -p "data: <position_in_radians>"

# 速度命令（兼容）
ign topic -t "/model/learm/joint/<joint_name>/cmd_vel" \
  -m ignition.msgs.Double \
  -p "data: <velocity>"

# 示例
ign topic -t "/model/learm/joint/elbow/cmd_pos" -m ignition.msgs.Double -p "data: -0.5"
```

## 机械臂结构

```
base_link                ▓ 底座（深灰）
  └─ shoulder_pan  [ID6] ↻ 绕 Z 旋转  ±90°
     └─ shoulder_link    🟦 肩部（蓝色）
        └─ shoulder_lift [ID5] ↻ 绕 Y 俯仰  ±90°
           └─ humerus_link 🟧 大臂（橙色）
              └─ elbow    [ID4] ↻ 绕 Y 弯曲  ±90°
                 └─ forearm_link  🟩 前臂（绿色）
                    └─ wrist_flex [ID2] ↻ 绕 Y 弯曲  ±90°
                       └─ wrist_link 🟪 腕部（紫色）
                          └─ wrist_roll [ID3] ↻ 绕 Z 旋转 ±90°
                             └─ hand_link 🟨 手掌（黄色）
                                ├─ grip_left  [ID1] 🩵 左夹爪
                                ├─ grip_right       🩵 右夹爪
                                ├─ tendon_left      ⬜ 左腱
                                ├─ tendon_right     ⬜ 右腱
                                ├─ finger_left      🔵 左指尖
                                └─ finger_right     🔵 右指尖
```

| 关节名 | 舵机 ID | 类型 | 限制 | PWM 范围 | 说明 |
|--------|---------|------|------|----------|------|
| `grip_left` | **ID1** | revolute | −1.57 ~ 0 | 500-2500 | 夹爪（500=闭合） |
| `wrist_roll` | **ID2** | revolute | ±1.57 rad | 500-2500 | 腕部旋转 |
| `wrist_flex` | **ID3** | revolute | ±1.57 rad | 500-2500 | 腕部弯曲 |
| `elbow` | **ID4** | revolute | ±1.57 rad | 500-2500 | 肘部弯曲 |
| `shoulder_lift` | **ID5** | revolute | ±1.57 rad | 500-2500 | 肩部俯仰 |
| `shoulder_pan` | **ID6** | revolute | ±1.57 rad | 500-2500 | 底座旋转 |
| `grip_right` | — | revolute | 0 ~ 1.57 | — | 右夹爪（联动） |
| `tendon_left` | — | revolute | −1.57 ~ 0 | — | 左腱（四连杆联动） |
| `tendon_right` | — | revolute | 0 ~ 1.57 | — | 右腱（四连杆联动） |
| `finger_left` | — | revolute | 0 ~ 1.57 | — | 左指尖（与腱锁定约束） |
| `finger_right` | — | revolute | −1.57 ~ 0 | — | 右指尖（与腱锁定约束） |

## 键盘控制（可选）

无需脚本，直接用键盘快捷键向 Gazette 窗口发送命令：

1. 启动后在右侧面板 **"Entity tree"** 中选择 `learm` 模型
2. 展开 `learm` → 找到对应的 joint
3. 右键 joint → **"Move To..."** → 输入目标角度

或者安装键盘控制插件，在终端直接：

```bash
# shoulder_pan 旋转
ign topic -t "/model/learm/joint/shoulder_pan/cmd_vel" -m ignition.msgs.Double -p "data: 1.0" ; sleep 0.5 ; ign topic -t "/model/learm/joint/shoulder_pan/cmd_vel" -m ignition.msgs.Double -p "data: 0"
```

## 参数调优

模型参数在 `model.sdf` 中：

| 参数 | 位置 | 说明 |
|------|------|------|
| `<mass>` | `<inertial>` | 各连杆质量（kg），可根据实物调整 |
| `<ixx/iyy/izz>` | `<inertia>` | 惯性张量 |
| `<lower/upper>` | `<limit>` | 关节软限位 |
| PID 增益 | `<plugin>` 内 | 如需要位置控制模式 |

## 安装为系统模型（可选）

放入 Gazebo 模型搜索路径后可在 Insert 面板中直接拖入：

```bash
cp -r ~/learm_model ~/.ignition/gazebo/models/learm
```

或在任意世界文件中用：

```xml
<include>
  <uri>file:///home/<user>/learm_model/model.sdf</uri>
  <pose>0 0 0.1 0 0 0</pose>
</include>
```

## 已知问题与技巧

- **四连杆平行闭环运动**：最新改款的 SDF 与 URDF 模型中已经修补了左/右平行夹爪的四连杆物理机构闭环（`tendon_finger` 约束），并且针对旋转极限 (`Limits`) 进行了修正，现在调用 `servo.sh` 进行开合可以精确实现完全的仿生平行与同步。
- **并行控制指令**：`servo.sh` 执行联动夹爪时（例如 `./servo.sh 1 500`），采用多线程并行发送 Ignition Topic（使用 `&`），解决并消除了原串行模式带来的运动延迟卡顿及不同步现象。
- **重力塌缩**：机械臂在物理仿真下会受重力下拉。建议先暂停仿真（空格键），调整好位姿后再播放。
- **碰撞体为 Box**：为提升物理性能，碰撞体使用简化 Box 而非 STL 网格。如需精确碰撞，可修改 `model.sdf` 中的 `<collision>` 块。
- **渲染引擎**：`go.sh` 使用 `--render-engine ogre`。如遇渲染问题可尝试移除该参数（使用默认 OGRE2）。