# FFG 左手套 → L20 左手 ROS 2 工作区

Ubuntu / ROS 2 Jazzy 下，通过 Type-C Linker FFG 左手套控制 CAN L20 左手。
**本项目所测 L20 使用 SDK 的 `G20` 协议及 `g20` 映射，不能据此推广到所有 L20。**

## 当前状态

- 已验证手套读取、个人标定、左手 CAN 版本/位置查询。
- 操作者已确认 ±10 单位试运行、50% 映射、100% 映射、加速跟随档正常。
- 五指触觉矩阵完整，接触响应及移开归零已验证。
- 操作者已确认低速软物抓取/释放正常。
- **非零手套力反馈未开启、未验证。** 协议力值单位、安全上限、释放及断连卸力机制尚待厂家确认。

详情：[进度记录](docs/PROGRESS.md)、[安全边界](docs/SAFETY.md)、[源码来源](docs/UPSTREAM.md)。

## 仓库布局

- `src/linker_hand_ros2_sdk/`：本地修改的硬件 SDK；`trial_guard.py` 为试运行限幅/缓变/超时策略。
- `src/linkerhand_retarget/`：手套采集、标定、位置映射及模型资产。
- `src/Linkerbot_URDF/`：固定提交的上游 Git 子模块。
- 主仓库 STL 网格由 Git LFS 管理；克隆后必须下载实际资产，不能用 LFS 指针文件替代网格。
- `tools/ffg_trial.sh`：隔离 ROS 域的测试入口；勿用原 SDK 默认启动替代。
- `tools/check_*readonly.py`：只读诊断；`tools/test_trial_guard.py`：无硬件策略测试。
- `diagnostics/`、个人标定、原始手册及构建目录仅留本地，不纳入版本控制。

## 克隆和安装

```bash
sudo apt install git-lfs
git lfs install
git clone --recurse-submodules https://gitea.robotquan.com/chenlin/ros2_ws.git
cd ros2_ws
git lfs pull
# 已安装并配置 ROS 2 Jazzy 的 Ubuntu 环境
sudo apt install python3-colcon-common-extensions python3-venv can-utils acl
source /opt/ros/jazzy/setup.bash
/usr/bin/python3 -m venv --system-site-packages .venv
touch .venv/COLCON_IGNORE
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m colcon build --symlink-install \
  --packages-select linker_hand_ros2_sdk linkerhand_retarget
```

`requirements-tested.txt` 记录本机直接依赖版本，可用 `pip install -r requirements-tested.txt` 复现 Python 版本组合；它不是 OS/ROS 的完整锁文件。本工作区依赖系统 ROS，不能使用完全隔离、不含系统包的 venv。SDK 与 retarget 需分进程运行，上游顶层 `utils` 导入存在冲突。

## 硬件准备（本机已验证配置）

- FFG 左手：`/dev/ttyUSB0`，2,000,000 baud，固件 2.1.4。
- PCAN-USB：`can0`，1 Mbps，左手标准 CAN ID `0x28`。
- 机械手独立供电；清空夹持区，准备物理断电手段。

```bash
sudo setfacl -m u:$USER:rw /dev/ttyUSB0
# can0 已启用且 bitrate 正确时无需重复设置
sudo ip link set can0 up type can bitrate 1000000
ip -details -statistics link show can0
```

重新插拔串口后 ACL 可能失效。不要在 YAML 中保存 sudo 密码。

## 新操作者必须重新标定

仓库**不包含**本地操作者标定。保持硬件 SDK 退出：

```bash
source /opt/ros/jazzy/setup.bash
source install/setup.bash
ROS_DOMAIN_ID=73 ros2 run linkerhand_retarget handretarget --ros-args \
  -p calibration:=true -p ports:='["/dev/ttyUSB0"]' -p baudrate:=2000000
```

按程序完成张手、O 姿态、握拳流程，退出标定后再启动控制。结果保存于
`src/linkerhand_retarget/linkerhand_retarget/motion/linkerforce/tmp/jointangle_data.tmp`，该目录已忽略。

## 日常测试入口

终端 1：
```bash
bash tools/ffg_trial.sh glove
```

终端 2（只能运行一个机械手控制进程）：
```bash
bash tools/ffg_trial.sh hand    # 小幅验证，输入 ARM
# 逐档确认正常、Ctrl+C 退出上一档后，才能使用下一档：
bash tools/ffg_trial.sh half    # 输入 ARM50
bash tools/ffg_trial.sh full    # 输入 ARM100
bash tools/ffg_trial.sh follow  # 输入 FOLLOW
```

| 档位 | 位置目标 | 电机速度数值 | 目标缓变上限 |
|---|---|---:|---:|
| hand | 相对第一帧手套姿态的变化，限制为硬件启动位置 ±10 单位 | 30 | 10 单位/秒 |
| half | 硬件启动位置 + 0.5 ×（手套映射目标 − 硬件启动位置） | 30 | 10 单位/秒 |
| full | 完整标定位置映射 | 30 | 10 单位/秒 |
| follow | 完整标定位置映射 | 60 | 60 单位/秒 |

位置/速度为 SDK 编码值，不是角度、物理速度或力。50% 指映射跨度，不是机械关节可用角度的一半。所有档位跳过默认启动姿态；收到手套目标后仍可能立即开始运动。脚本使用 ROS 域 74、仅本机发现及专用命令话题。

## 只读触觉检查和离线测试

退出硬件 SDK 后：
```bash
.venv/bin/python tools/check_hand_touch_readonly.py --duration 30
.venv/bin/python tools/test_trial_guard.py
```

触觉工具只查询 type-2 的 12×6 矩阵，缺帧不会复用旧矩阵；结果落在忽略的 `diagnostics/`。

**限速不等于限力；停止发目标不等于急停。** 初次/重新标定后从小幅空载开始，软物抓放使用 `full` 慢速档，不把人体放入夹持区。发生异常立即物理断电。