Initialize FFG left-glove L20 teleoperation workspace with guarded trial modes

docs/PROGRESS.md

@@ -0,0 +1,36 @@
+# 实验进度（2026-09-15）
+
+## 环境及模型
+
+- 工作区 `/home/cen/ros2_ws`，ROS 2 Jazzy，system-site-packages venv；两个 ROS 包已编译。
+- 手套为 Type-C 左 FFG（固件 2.1.4），串口 2 Mbps；21 通道读数有限且有明显活动范围。
+- 已完成个人张手/O 姿态/握拳标定，三组数据均为 21 维有限值。
+- 用户提供的 L20 LEFT URDF 与 `g20` 关节名、限位一致；已替换 retarget 中 G20 左手 URDF，包含拇指 origin RPY 修正。
+- URDF 名称匹配之外，独立完成 CAN 线协议验证：左手 `0x28` 对 C1/C2/C4 及五指 41–45 查询均有真实回复。软件版本原始字节 `01 00 0a`。
+
+## 控制与实机验证
+
+1. 添加 `safe_trial`，跳过 SDK 默认启动速度/力矩/姿态动作，禁用设置话题。
+2. 加入初始状态检查、20 维有限值及 0–255 范围检查、目标缓变、300 ms 命令超时锁定。
+3. 手套位置包新鲜度门限为 300 ms，防止断连后持续发布缓存姿态。
+4. 小幅相对运动、50% 映射、完整映射：操作者均反馈运动正常。
+5. 跟随档将目标缓变从 10 提升至 60 单位/秒、电机速度从 30 提升至 60；操作者确认正常。
+6. 五指触觉只读验证：75 组数据均完整，补测峰值依次为 108、126、127、124、129，结束均归零。这些是原始强度，不是牛顿或克。
+7. 操作者确认慢速软物抓取、释放正常，无明显过度挤压、抖动、异常声音或发热。属于人工观察，不是力学安全认证。
+8. 当前策略离线单测 12 项、SDK `test_topic_prefix.py` 的 5 项测试通过；Python 语法、shell 语法及两个包 colcon 构建通过。SDK 测试需先 source ROS 和 install 环境（未 source 的首次采集因找不到包失败，加载环境后通过）。未声称全套上游测试通过。
+
+## 未完成事项
+
+- **非零手套力反馈未测试/未开启**：现有 `max(matrix)*4`、上限 500 缺乏安全单位依据。
+- FFG `0x04/A7` 协议单位、安全值、零力释放和固件断连卸力行为需厂家确认。
+- 当前抓取为位置控制；无接触力闭环、已验证扭矩限制或硬件急停联锁。
+- 尚未测量端到端延迟，也未做长时间耐久、故障注入及硬件断连恢复测试。
+
+## 本地证据（默认不上传）
+
+- `diagnostics/ffg-readonly.json`
+- `diagnostics/can-version-query.json`、`diagnostics/can-position-query.json`
+- `diagnostics/touch-readonly-1789455774825105359.json`
+- `diagnostics/touch-readonly-1789455849390860026.json`
+- 标定：`src/linkerhand_retarget/linkerhand_retarget/motion/linkerforce/tmp/jointangle_data.tmp`
+- 构建日志：`/tmp/ffg-*-build.log`；临时文件不是长期归档。

docs/SAFETY.md

@@ -0,0 +1,15 @@
+# 安全边界
+
+这是研究/调试工作区，不是安全认证控制系统。`safe_trial` 名称表示软件试运行策略，不承诺物理安全。
+
+- 原 SDK 默认入口仍保留上游初始化姿态行为；应使用 `tools/ffg_trial.sh`。不要同时运行多个 SDK/遥操作控制器。
+- 初始版本、五指位置完整性及数值范围检查不替代持续硬件反馈监控。
+- 手套位置数据超过 300 ms 不发布目标；SDK 检查消息时间戳、接收间隔并锁定。锁定后需退出并重启，禁止自动恢复运动。
+- 超时只停止发送新目标。机械手可能继续完成最后目标并保持力矩，**不保证松手**。操作系统/进程卡死、CAN 驱动内部重连和固件行为不由此保护覆盖。
+- 速度是固件编码值，软件缓变限制的是命令数值，并不保证实际速度、夹持力或碰撞力。
+- 试运行不会提高或重设力矩，硬件既有力矩设置仍生效。当前无经标定的抓取力限制或接触自动停止。
+- 初始状态与目标不同时，half/full/follow 会在首帧输入后渐进运动。不要误把“无启动姿态命令”当作“不动”。
+- 测试保持空载或软泡沫置于支撑面，不用玻璃/金属/易碎物，不夹人体，不提起重物。准备物理断电；Ctrl+C 不是急停。
+- 启动器把手套触觉订阅重映射至未使用话题，不接入非零反馈。底层上游代码仍含 `0x04/A7` 输出路径（部分协议可能回复零值）；这不是硬件级禁能，不应手动重映射回触觉话题或发布反馈数据。
+- 手套施力前必须取得适配固件的协议：力值单位、安全上限、单指顺序、零力释放、设备看门狗/断连卸力。现有上限 500 只是代码常数。
+- 私人标定、原始硬件日志和密码不入库。重建/换操作者必须重新标定。

docs/UPSTREAM.md

@@ -0,0 +1,26 @@
+# 上游来源与版本
+
+本仓库是 ROS 2 应用工作区整合，不宣称对上游代码/模型拥有原创版权。
+
+## SDK 与 retarget（vendored 源码）
+
+- 来源：https://gitea.robotquan.com/admin/linkerhand_retarget_ros2.git
+- 基线提交：`7953e50ca7d4a38a364ab7d06a2859f0e53b8166`
+- 导入目录：`src/linker_hand_ros2_sdk`、`src/linkerhand_retarget`、`src/requirements-retarget.txt`
+- 选择直接跟踪源码，以便同一提交复现本工作区的 G20 适配、命令调度、话题隔离、试运行控制和手套新鲜度修改。没有把其他 Git 历史伪装成本仓库历史。
+- 保留多型号资产以维持上游模型路径。主仓库的 STL 网格使用 Git LFS，避免首次普通 Git 请求包含约 142 MiB 对象而触发 HTTP 413。单个网格低于 10 MiB，克隆需安装 Git LFS 并下载资产。
+- 首次普通 Git 推送失败后，确认远端没有分支，重建未发布的根提交；旧提交 `ec13b93` 保留在本地 `backup/pre-lfs-ec13b93` 分支，不推送该备份分支。
+
+## URDF（Git 子模块）
+
+- 来源：https://gitea.robotquan.com/sunxianghui/Linkerbot_URDF.git
+- 固定提交：`afc0ac84a4e7cee4245ba421fb985bab014768a0`
+- 路径：`src/Linkerbot_URDF`
+- 提供的 `L20/LEFT/linkerhand_g20_left.urdf` 已用于工作区 retarget 的左 G20 模型。
+- 克隆需 `--recurse-submodules`；上游若需鉴权，须另行具备访问权限。
+
+## 许可与参考资料
+
+遵守各来源文件自带的版权和许可声明。原上游根目录未发现统一 LICENSE，**本整合不额外授予第三方资产的再分发许可**，也不为整个工作区添加未经确认的开源许可证；进一步公开分发前请核实授权。
+
+操作者提供的 FFG 产品 PDF 与中文操作笔记保留本地、默认不上传；README 已独立整理适用于本工作区的步骤。