---
name: isaaclab-soarm101
description: 通过 HTTP API 控制 IsaacLab 仿真中的 SO-ARM101 机械臂
emoji: 🦾
requires:
  bins:
   - curl
---

# IsaacLab 机械臂控制

通过 HTTP API 控制运行在 IsaacLab 仿真中的 SO-ARM101 6自由度机械臂

## 配置

机械臂服务器地址:`http://127.0.0.1:8000`

## 可用命令

### 1.获取机械臂状态(每次操作前必须先执行)

在发送任何运动指令前，先查看当前关节位置:

```bash
curl -s http://127.0.0.1:8000/state
```

返回 JSON，包含 `joint_positions` (6个关节角度，单位弧度)， `joint_velocities` (关节速度)
`gripper_position` (夹爪位置) 和 `timestamp` (时间戳)。

## 2.移动手臂 - 关节位置控制

发送6个关节角（单位弧度）:

```bash
curl -s -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command_type":"joint_position","target":[J1,J2,J3,J4,J5,J6]}'
```

添加 'duration' 参数实现平滑运动 (单位秒):

```bash
curl -s -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command_type":"joint_position","target":[J1,J2,J3,J4,J5,J6],"duration":2.0}'
```

### 3.夹爪控制

打开夹爪：
```bash
curl -s -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command_type":"gripper","target":[1.0]}'
```

关闭夹爪：
```bash
curl -s -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command_type":"gripper","target":[0.0]}'
```

### 4. 回到初始位置

返回默认安全姿态：
```bash
curl -s -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command_type":"home"}'
```

### 5.等待指令

在多步骤任务中，插入等待时间 (单位秒):

```bash
curl -s -X POST http://127.0.0.1:8000/command \
  -H "Content-Type: application/json" \
  -d '{"command_type":"wait","duration":1.5}'
```


### 6.重置仿真
重置整个仿真环境：
```bash
curl -s -X POST http://127.0.0.1:8000/reset
```

### 7.健康检查
```bash
curl -s http://127.0.0.1:8000/health
```

### 8.获取机械臂配置信息
```bash
curl -s http://127.0.0.1:8000/config
```

## SO-ARM101 关节参考

|关节|名称 |功能 | 大致范围(弧度)|
|J1|shoulder_pan|底座旋转(左右转动)|-3.14 到 3.14|
|J2|shoulder_lift|肩部俯仰(前后倾斜)|-1.57 到 1.57|
|J3|elbow_flex|肘部弯曲|-1.57 到 1.57|
|J4|wrist_flex|腕部俯仰|-1.57 到 1.57|
|J5|wrist_roll|腕部旋转|-3.14 到 3.14|
|J6|gripper|夹爪 (0.0=打开, 0.5=关闭)|0.0 到 0.5|

默认初始位置(home): `[0.0, 0.0, 0.0, 1.57, 0.0, 0.0]`

## 重要规则

1.**操作前必须先获取状态** - 发送运动指令前，必须先调用 state 接口了解当前位置。
2.**小幅增量运动** - 每次每个关节的变化量不要超过 0.3-0.5 弧度，避免剧烈运动。
3.**使用 duration实现平滑运动** 例如`"duration":20`表示2秒内平滑过渡到目标位置。
4.**不要超出关节限位** - 超出范围的值会导致不可预测的行为。
5.**不确定时先回到初始位置** - 发送 `home` 指令回到已知的安全姿态。
6. 当用户说"抬起手臂"、"向左移动"、"向前伸"等自然语言时，根据上面的关节功能描述将其转换为关节角度变化。
7. 对于多步骤运动(如抓取物体)，规划并依次执行一系列小幅运动，每步之间检查状态确认到位。

## 交互示例

用户："把机械臂抬起来"

操作步骤：
1. 获取当前状态 - 读取关节位置
2. J2（肩部俯仰）控制上下运动，当前值可能是 0.0。要抬起手臂，增加J2（如 0.5）。
3. 发送 `{"command_type":"joint_position","target":[0.0, 0.5, 0.0, 1.57, 0.0, 0.0],"duration":2.0}`
4. 再次获取状态，确认手臂已经移动到位。

用户："打开夹爪"

发送: `{"command_type":"gripper","target":[1.0]}`

用户:“回到初始位置”

发送: `{"command_type":"home"}`