# linkerhand_telop_python

**Repository Path**: ericbrunt/linkerhand_telop_python

## Basic Information

- **Project Name**: linkerhand_telop_python
- **Description**: 灵心巧手摇操SD·K
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LinkerHand ROS 遥操作 SDK

ROS/ROS2 遥操作与运动重定向 SDK。

## 支持设备

| 设备 | ROS1 | ROS2 | 模块 |
|------|------|------|------|
| LinkerHand L6/L7/L10/L20/L21/L25 | ✅ | ✅ | `motion/linkerforce` |
| VTR-DYN | ✅ | ✅ | `motion/vtrdyn` |
| UdexReal | ✅ | ✅ | `motion/udexreal` |
| LinkerMCG | ✅ | ✅ | `motion/linkermcg` |
| LinkerEG | - | ✅ | `motion/linkereg` |
| Simulator | - | ✅ | `motion/simulator` |

## ROS 版本兼容

| ROS版本 | Python | 平台 |
|---------|--------|------|
| Noetic (ROS1) | 3.8 | x86_64 |
| Humble (ROS2) | 3.10 | x86_64 |
| Jazzy (ROS2) | 3.12 | x86_64 |

## 目录结构

```
new/
├── ros1/src/              # ROS1 Noetic 包
│   ├── linkerhand/        # 核心库
│   ├── motion/            # 设备驱动
│   ├── config/            # 配置文件
│   └── scripts/           # 入口脚本
│
├── ros2/src/              # ROS2 包
│   └── linkerhand_retarget/
│       ├── linkerhand/    # 核心库
│       ├── motion/        # 设备驱动
│       ├── config/        # 配置
│       └── launch/        # launch文件
│
├── LICENSE                # MIT许可证
└── NOTICE                 # 第三方依赖声明
```

## 快速开始

### ROS2 安装（git clone）

```bash
cd ros2_ws/src
git clone ssh://git@git.linkerhub.work:12222/linker-bot/linkerhand_telop_python.git
cd ..
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
source install/setup.bash
```

### ROS2 安装（下载压缩包）

```bash
cd ros2_ws/src
wget -O linkerhand_telop_python.zip https://gitee.com/ericbrunt/linkerhand_telop_python/repository/archive/master.zip
unzip linkerhand_telop_python.zip
mv linkerhand_telop_python-master/ros2/src/linkerhand_retarget ./
rm -rf linkerhand_telop_python.zip linkerhand_telop_python-master/
cd ..
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
source install/setup.bash
```

### ROS1 安装（git clone）

```bash
cd catkin_ws/src
git clone ssh://git@git.linkerhub.work:12222/linker-bot/linkerhand_telop_python.git
cd ..
catkin_make
source devel/setup.bash
```

### ROS1 安装（下载压缩包）

```bash
cd catkin_ws/src
wget -O linkerhand_telop_python.zip https://gitee.com/ericbrunt/linkerhand_telop_python/repository/archive/master.zip
unzip linkerhand_telop_python.zip
mv linkerhand_telop_python-master/ros1/src ./
rm -rf linkerhand_telop_python.zip linkerhand_telop_python-master/
cd ..
catkin_make
source devel/setup.bash
```

## 串口连接

LinkerForce 设备支持三种串口连接方式。

### 方式一：命令行候选列表（推荐）

指定候选端口列表，系统自动检测左右手类型：

```bash
ros2 run linkerhand_retarget handretarget --ros-args \
  -p ports:='["/dev/ttyUSB0", "/dev/ttyUSB1"]'
```

### 方式二：配置文件预设

在 `config/base_config.yml` 中配置：

```yaml
serial:
  auto_scan: false
  baudrates: [460800, 2000000, 1000000, 921600]
  left:
    port: /dev/ttyUSB0
    baudrate: 460800
  right:
    port: /dev/ttyUSB1
    baudrate: 460800
```

### 方式三：自动扫描

预设失败后自动扫描系统所有 USB 串口：

```bash
ros2 run linkerhand_retarget handretarget --ros-args -p auto_scan:=true
```

或在配置文件中启用：`serial.auto_scan: true`

### 连接逻辑

```
启动
  ↓
有候选列表(ports)?
  ├─ 是 → 遍历候选端口，自动检测左右手
  └─ 否 → 尝试预设端口
            ↓
          预设失败 → auto_scan=true?
                      ├─ 是 → 扫描系统串口
                      └─ 否 → 报错退出
```

### 参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `ports` | 候选串口列表 | 空 |
| `baudrate` | 指定波特率 | 使用配置文件 |
| `auto_scan` | 预设失败后是否扫描 | false |

### 使用建议

- **有明确端口** → 使用 `ports` 参数
- **端口固定** → 配置文件预设
- **端口不确定** → 启用 `auto_scan`

## 自动标定

### 启动标定

```bash
ros2 run linkerhand_retarget handretarget --ros-args -p calibration:=auto_calibrate
```

### 标定流程

1. **五指张开** - 对应电机值 255
2. **握紧拳头** - 对应电机值 0
3. **O型手势** - 对应电机中间值

### 稳定性检测

- 标定时自动检测手势稳定性（方差 < 0.03）
- 需**连续稳定 5 秒**才完成采集
- 不稳定时清空重来，无超时限制
- 进度条动态显示稳定时长

### 标定数据存储

- 存储位置：`motion/linkerforce/tmp/jointangle_data.tmp`
- 格式：JSON
- 首次使用自动加载预设样本数据

## 标定配置建议

| 标定模式 | show_fist | MULTI_SEGMENT_CONFIG['states'] | 说明 |
|----------|-----------|-------------------------------|------|
| 两段标定 (open + opose) | false | `['original', 'opose']` | 启用延伸映射，从 opose 延伸到 fist |
| 三段标定 (open + opose + fist) | true | `['original', 'opose', 'fist']` | 三段线性插值 |
| 两段标定 (open + fist) | true | `['original', 'fist']` | 从张开到握拳 |

**注意：**
- 两段标定 + 延伸映射：需要配置 `extended_mapping.enabled = True`
- 三段标定：`show_fist` 必须为 `true`，否则不会采集 fist 数据

## 话题参数控制

通过 `/hand_teleop_param` 话题动态调整运行参数。

### 参数列表

| 参数 | 说明 | 示例 |
|------|------|------|
| `mapper_debug` | 映射器调试开关 | `true` / `false` / `["thumb_rotate"]` |
| `mapper_exp_factor` | 延伸指数因子 | `2.0` 或 `{"thumb_rotate": 2.0}` |
| `mapper_scale_factor` | 缩放因子 | `1.5` 或 `{"thumb_rotate": 1.5}` |
| `force_glove_pose` | 强制手套数据源 | `open` / `fist` / `opose` / `none` |

### 使用示例

```bash
# 开启映射器调试
ros2 topic pub /hand_teleop_param std_msgs/msg/String '{"data": "{\"mapper_debug\": true}"}' --once

# 只调试指定手指
ros2 topic pub /hand_teleop_param std_msgs/msg/String '{"data": "{\"mapper_debug\": [\"thumb_rotate\", \"thumb_abduction\"]}"}' --once

# 关闭调试
ros2 topic pub /hand_teleop_param std_msgs/msg/String '{"data": "{\"mapper_debug\": false}"}' --once

# 调整延伸指数（全局）
ros2 topic pub /hand_teleop_param std_msgs/msg/String '{"data": "{\"mapper_exp_factor\": 2.0}"}' --once

# 调整延伸指数（指定手指）
ros2 topic pub /hand_teleop_param std_msgs/msg/String '{"data": "{\"mapper_exp_factor\": {\"thumb_rotate\": 2.0, \"thumb_abduction\": 1.5}}"}' --once

# 调整缩放因子
ros2 topic pub /hand_teleop_param std_msgs/msg/String '{"data": "{\"mapper_scale_factor\": 1.5}"}' --once

# 使用标定数据替代手套数据
ros2 topic pub /hand_teleop_param std_msgs/msg/String '{"data": "{\"force_glove_pose\": \"opose\"}"}' --once

# 恢复实际手套数据
ros2 topic pub /hand_teleop_param std_msgs/msg/String '{"data": "{\"force_glove_pose\": \"none\"}"}' --once
```

### 可用手指名称

| 手指 | 名称 |
|------|------|
| 拇指 | `thumb_rotate`, `thumb_abduction`, `thumb_root_flexion`, `thumb_end_flexion` |
| 食指 | `index_roll`, `index_root_flexion`, `index_end_flexion` |
| 中指 | `middle_roll`, `middle_root_flexion`, `middle_end_flexion` |
| 无名指 | `ring_roll`, `ring_root_flexion`, `ring_end_flexion` |
| 小指 | `pinky_roll`, `pinky_root_flexion`, `pinky_end_flexion` |

## 映射器调试

### 配置文件

在 `base_config.yml` 中设置：

```yaml
debug:
  mapper_debug: false
```

### ROS 话题控制

```bash
# 显示全部手指
ros2 topic pub /hand_teleop_param std_msgs/msg/String '{"data": "{\"mapper_debug\": true}"}' --once

# 只显示指定手指
ros2 topic pub /hand_teleop_param std_msgs/msg/String '{"data": "{\"mapper_debug\": [\"thumb_rotate\", \"index_root_flexion\"]}"}' --once

# 关闭调试
ros2 topic pub /hand_teleop_param std_msgs/msg/String '{"data": "{\"mapper_debug\": false}"}' --once
```

## 映射参数说明

### 延伸指数因子 (exp_factor)

控制映射延伸到目标姿态的速度：
- `= 1.0`：线性延伸
- `> 1.0`：加速延伸（更快到达目标）
- `< 1.0`：减速延伸（更平滑）

### 缩放因子 (scale_factor)

控制输入到输出的映射比例：
- `= 1.0`：1:1 映射
- `> 1.0`：放大输出范围
- `< 1.0`：缩小输出范围

### 强制手套数据源 (force_glove_pose)

用标定数据替代实时手套数据，用于测试：

| 值 | 说明 |
|------|------|
| `open` | 使用五指张开标定数据 |
| `fist` | 使用握拳标定数据 |
| `opose` | 使用O型手势标定数据 |
| `none` | 使用实时手套数据（默认） |

## 仓库地址

- **SSH**: `ssh://git@git.linkerhub.work:12222/linker-bot/linkerhand_telop_python.git`
- **组织**: linker-bot
- **仓库**: linkerhand_telop_python

## 许可证

MIT License - 详见 [LICENSE](LICENSE)