Document calibration setup and validate hand identity by model and side

This commit is contained in:
2026-10-29 15:20:49 +08:00
parent efde3ef43a
commit 4ea023332a
7 changed files with 134 additions and 19 deletions
+17
View File
@@ -2,6 +2,23 @@
完整真机流程:准备空手 → 回零和示教观察位 → 新 RGB-D 配准 → 视觉接近 → HUG 合指与触觉收紧 → 5 mm 试抬 → 补足累计约 30 mm。可选将杯子搬到桌面圆圈,人工确认落桌后松手;也可原位放回并返回零位。
默认使用新RGB-D配准与图像特征直接视觉伺服,**不依赖掌心标签定位,也不要求粘贴掌心Tag**。目录名沿用历史命名;旧标签入口不是当前默认流程。
控制器IP固定为 **192.168.10.21**,ROSBridge端口为 **9090**。主机需能访问该地址,无需修改控制器IP。
## 标定与首次部署
相机安装变化、换工位,或没有本工位已独立验证的相机外参时,先完成手眼标定,再执行抓取:
- **标定项目**:[a7-handeye-calibration](https://gitea.robotquan.com/liyang/a7-handeye-calibration)
- **完整教程**:[拍板、左右臂只读采点、求解、独立验证与部署](https://gitea.robotquan.com/liyang/a7-handeye-calibration/src/branch/main/WORKFLOW.md)
标定通过后,先备份,再将本轮camera.json放到本项目的 `config/camera_extrinsics_current.json`;具体命令见教程第8节。外参应为共同 `base_link` 下的 `T_base_cam_opencv`。右臂求得的相机外参可用于共享基座,但右臂触点偏移不能用于左手。不要直接套用仓库中原工位的外参。
手眼标定提供相机—基座坐标关系;接近阶段仍使用新视觉反馈与实测局部运动映射,不恢复掌心Tag定位。手部角度标定、模型装配及示教路线是另外的配置,不能由手眼标定替代。
灵巧手SN由CAN身份查询返回(属性0xC0)。默认按G20/LHT20型号与所需左右手标识校验,不绑定某一台设备SN;本项目左手抓取只接受左手,并继续记录实际SN、检查同轮及返回来源的设备一致性。共用SN校验函数支持left/right,但不代表整套抓取已支持右臂右手,也不允许左右手共用角度标定表。
## 安装
运行环境为 Ubuntu 24.04 x86_64、系统 Python 3.12、ROS 2 Jazzy、Intel RealSense D405。机械臂使用官方 SDK 1.0.5 与原生 MoveJ,G20 左手使用 SocketCAN。官方 SDK 下载来源、D405 驱动、USB-CAN/SocketCAN 配置及检查步骤见 [环境配置](docs/INSTALL.md)。
+5 -1
View File
@@ -6,7 +6,7 @@
- ROS 2 Jazzy;需要 rclpy、sensor_msgs、geometry_msgs、control_msgs、trajectory_msgs、shape_msgs、std_srvs、rosidl_runtime_py 和 moveit_msgs。几何模块复用消息类型,不要求启动 MoveIt Servo。
- D405 使用 realsense2_camera,848×480、30 FPS、对齐深度;执行入口会复用或启动相机驱动。避免其他程序独占设备。
- 下位机地址 192.168.10.21,原生 ROSBridge 端口 9090,机械臂保留厂家桥服务及反馈接口。
- 左手 can0,1 Mbps,设备身份默认 LHT20-011-263-L-B-1-D,标定表随包提供;其他设备必须重新确认身份与标定,不能直接套用。
- 左手 can0,1 Mbps,通过CAN返回的SN核对G20/LHT20型号和左手标识,不默认绑定单台设备SN。标定表随包提供;更换设备仍需确认角度标定,不能仅凭左右手相同直接套用。
- ROS_DOMAIN_ID 默认 29。主机和下位机网络、USB/CAN 权限由现场配置。
先按 [ROS 2 Jazzy 官方安装说明](https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debs.html) 配置 Ubuntu 24.04 的 ROS 软件源。已配置软件源的机器可补充系统组件:
@@ -143,3 +143,7 @@ sudo apt install g++ libeigen3-dev ros-jazzy-moveit-core ros-jazzy-ruckig
~~~
源文件为 runtime/arm/cpp/totg_offline.cpp,输出 runtime/arm/build/totg_offline。构建与离线定时均不连接机器人;实际执行仍受原控制检查约束。CUP_ROS_PREFIX 可覆盖 ROS 安装目录,默认从 CUP_ROS_SETUP 推导。
## 手眼标定教程
独立项目:[a7-handeye-calibration](https://gitea.robotquan.com/liyang/a7-handeye-calibration)。按[完整教程](https://gitea.robotquan.com/liyang/a7-handeye-calibration/src/branch/main/WORKFLOW.md)完成左右臂只读采点、求解和独立验证,再备份并替换本项目config/camera_extrinsics_current.json。默认抓取使用新RGB-D直接视觉伺服,不需要掌心Tag。
+7
View File
@@ -10,3 +10,10 @@
系统包检查另外报告了宿主已有 yt-dlp/websockets 与 colcon-core/setuptools 版本约束冲突。这两条不属于杯子运行依赖测试;本次没有修改全局环境。ROS 构建工具不在本流程运行链中,若另做工作区构建,应在独立构建环境处理。
新物体 pointcloud/HUG 大模型模式未做独立安装验收。默认杯子模式、搬运、返回所需的本地资源已经打包。
## 2026-10-29 身份适配与标定文档
- 基于已发布版本整理,未同步本地尚未验证的真机调试改动。
- CAN 返回的 SN 改为校验 LHT20 型号与左右手标识,默认左手入口不再绑定某一台手的序列号;跨阶段设备一致性检查保留。7 项针对性离线测试通过。
- 从项目外运行离线包检查通过,未连接机器人。
- 默认入口明确关闭标签跟踪,使用 RGB-D 视觉伺服;本轮未更改控制链。补充固定控制器地址、独立手眼标定仓库与教程链接。
+38 -15
View File
@@ -2,13 +2,13 @@
"files": [
{
"file": ".gitignore",
"bytes": 340,
"sha256": "3baca23f5830f0e75e8ab5a3d1c5664e1de75384abb1093c54ef9a4bd4e875d6"
"bytes": 360,
"sha256": "f88062cabacaf8630374116ca0ed4dc3c398689040c2e5b1a2630ebb71b1e076"
},
{
"file": "README.md",
"bytes": 2786,
"sha256": "d8a20a1f799b3efe645855d067b723032030d996361cf4c2fdc5296dbea88874"
"bytes": 4404,
"sha256": "34285c6ece195a2e113b84c15d219f573dc9d6229f74b7064adfe064d0edd6da"
},
{
"file": "assets/cup_reference/capture/camera.json",
@@ -77,8 +77,8 @@
},
{
"file": "docs/INSTALL.md",
"bytes": 2685,
"sha256": "c630cb191ab99e7624c293b0c30d7faaeddbc74b19a71eeefc059a0b5ead44f9"
"bytes": 10309,
"sha256": "dce2ab3701e61c941cb77fc41d803dcc8ed296833f3dc0cffbcd0627f5cdd14e"
},
{
"file": "docs/THIRD_PARTY.md",
@@ -87,8 +87,8 @@
},
{
"file": "docs/VALIDATION.md",
"bytes": 1285,
"sha256": "a13612c25951b5ceb77f2d909e3b177de3317a2330957e9a94324bf7b6a79959"
"bytes": 1845,
"sha256": "f9aacab94f0ad49d07e728d18e993ec64698c05eb6531c551e46b198f8dd6a2e"
},
{
"file": "docs/WORKFLOW.md",
@@ -400,6 +400,11 @@
"bytes": 4232,
"sha256": "f87de26bd5fc6386b724828453251324885814f5d3a8e6ffca3cd95bddba4d7b"
},
{
"file": "dual_tag_cup_servo/tools/test_hand_identity.py",
"bytes": 2419,
"sha256": "f81150c846e645eda259036697e94083e80699efb94e8ecbf25fa5890d3bd09d"
},
{
"file": "dual_tag_cup_servo/tools/test_lift_fault_refresh.py",
"bytes": 1106,
@@ -435,6 +440,11 @@
"bytes": 451,
"sha256": "a6d10a729060e768c308e51a616d013fdb1485a467d96ff8473897fdbcc9c040"
},
{
"file": "requirements-replay.txt",
"bytes": 35,
"sha256": "31127da4038f3c810f6c8ed761a8b18fbd59d82688fb07d5f803a14abaa63d39"
},
{
"file": "requirements.txt",
"bytes": 115,
@@ -445,6 +455,11 @@
"bytes": 758,
"sha256": "ccbbf11304fae6cc883dc3fe92db756f874e7a2b658efd9e58d261ec9bc41d8d"
},
{
"file": "runtime/arm/build_totg.py",
"bytes": 948,
"sha256": "7a2925c22045d8bcbf4ef794e6fbaaa20dc56820ba16a4b64bebf6b955c77281"
},
{
"file": "runtime/arm/config/controller.json",
"bytes": 1089,
@@ -460,6 +475,11 @@
"bytes": 1322,
"sha256": "09c7664c108b580d87d805af0f9855fa1c980affec1c51ee4cb69e36cd57c3e1"
},
{
"file": "runtime/arm/cpp/totg_offline.cpp",
"bytes": 2624,
"sha256": "bf7370f7ed2b169c644052240f9da39018d87b87c4c93fd0a51bdef7c1960b29"
},
{
"file": "runtime/arm/data/observation/legacy_rise.json",
"bytes": 1891,
@@ -687,8 +707,8 @@
},
{
"file": "runtime/arm/src/a7_left/totg_timing.py",
"bytes": 7323,
"sha256": "95016b6aaedb7c3048da04450b43c151535d0f9897474438ff5094cb178f5dd0"
"bytes": 7480,
"sha256": "07d0137752bb3703561b0e92cc7fffd9607c4e19ef9453c3e93fce560cda0022"
},
{
"file": "runtime/arm/vendor/lbot_sdk/include/lbot_api.h",
@@ -1000,6 +1020,11 @@
"bytes": 4778,
"sha256": "8c0854a558a50415695afe5620f777ccf4c9e2b00adc31a984b8d05253d0af08"
},
{
"file": "runtime/hug/scripts/hand_identity.py",
"bytes": 975,
"sha256": "19ee20c088433871b910aad59bc2a07786f42f1aede23cc4d0667ef613d3eccf"
},
{
"file": "runtime/hug/scripts/hug_infer_point.py",
"bytes": 6166,
@@ -1057,8 +1082,8 @@
},
{
"file": "runtime/hug/tools/read_left_hand.py",
"bytes": 4152,
"sha256": "738d6f47b36cd17083468f39df1fb5e55a9e475881c7feb57ba4ccd0dacdb7b0"
"bytes": 4100,
"sha256": "a307306b31bd893cfb99b9cf43e4c87fbee6b2b4c175a53ba6ae56394407f46d"
},
{
"file": "runtime/hug/tools/replay_left_cup_approach.py",
@@ -1130,7 +1155,5 @@
"bytes": 240,
"sha256": "aa387f663053bbdb69c78a1e0030a04a1260014eac2d74dc4b47f32aeb25ecff"
}
],
"file_count": 226,
"total_bytes": 111265186
]
}
@@ -0,0 +1,47 @@
"""Offline SN checks; no CAN device is opened."""
import unittest
from hand_identity import validate_hand_identity
class HandIdentityTests(unittest.TestCase):
def test_different_units_same_side(self):
for sn in ('LHT20-011-263-L-B-1-D', 'LHT20-222-999-L-B-1-D'):
self.assertEqual(validate_hand_identity(sn, 'left'), sn)
def test_right_side(self):
sn = 'LHT20-222-999-R-B-1-D'
self.assertEqual(validate_hand_identity(sn, 'right'), sn)
def test_wrong_side_or_model_rejected(self):
for sn in ('LHT20-222-999-R-B-1-D', 'LHO30-222-999-L-B-1-D', 'LHT20-222-999-L-R-D'):
with self.assertRaises(ValueError): validate_hand_identity(sn, 'left')
def test_malformed_rejected(self):
for sn in ('', 'LHT20', 'LHT20--L-B-D', 'LHT20-222-L-B-D ', None):
with self.assertRaises(ValueError): validate_hand_identity(sn, 'left')
def test_optional_pin(self):
with self.assertRaises(ValueError):
validate_hand_identity('LHT20-222-999-L-B-1-D', 'left', 'LHT20-011-263-L-B-1-D')
class ReaderIntegrationTests(unittest.TestCase):
def create(self, serial):
from unittest.mock import MagicMock, patch
from types import SimpleNamespace
import read_left_hand
encoded = list(serial.encode('ascii'))
responses = [[i//7, *encoded[i:i+7]] for i in range(0,len(encoded),7)]
self.bus = MagicMock()
module = SimpleNamespace(Bus=MagicMock(return_value=self.bus))
with patch.object(read_left_hand.importlib.util, 'find_spec', return_value=object()), \
patch.object(read_left_hand.importlib, 'import_module', return_value=module), \
patch.object(read_left_hand, 'LeftLookup'), \
patch.object(read_left_hand.LeftHandReader, 'query', side_effect=lambda prop,multi=False: responses if prop==0xC0 else [0]*6):
return read_left_hand.LeftHandReader('can0')
def test_reader_accepts_another_left_unit(self):
reader = self.create('LHT20-222-999-L-B-1-D')
self.assertEqual(reader.serial, 'LHT20-222-999-L-B-1-D')
reader.close()
self.bus.shutdown.assert_called_once()
def test_reader_rejects_right_and_closes_bus(self):
with self.assertRaises(ValueError): self.create('LHT20-222-999-R-B-1-D')
self.bus.shutdown.assert_called_once()
if __name__ == '__main__': unittest.main()
+17
View File
@@ -0,0 +1,17 @@
"""Validate G20 CAN serials by model and handedness, without a unit-specific pin."""
def validate_hand_identity(serial, side, expected_serial=None):
if side not in ('left', 'right'):
raise ValueError('Expected hand side left or right')
if not isinstance(serial, str) or not serial.isascii() or not serial or any(c.isspace() or ord(c)<33 for c in serial):
raise ValueError('Malformed hand serial')
parts = serial.split('-')
if len(parts) < 5 or any(not part for part in parts) or parts[0] != 'LHT20':
raise ValueError('Expected G20/LHT20 hand identity: '+serial)
sides = [part for part in parts[1:] if part in ('L', 'R')]
expected = 'L' if side == 'left' else 'R'
if sides != [expected]:
raise ValueError('Unexpected '+side+' hand identity: '+serial)
if expected_serial is not None and serial != expected_serial:
raise ValueError('Hand serial differs from explicitly pinned identity')
return serial
+3 -3
View File
@@ -12,10 +12,11 @@ import numpy as np
ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(ROOT/'scripts'))
from g20_left_lookup import LeftLookup, EXPECTED
from hand_identity import validate_hand_identity
class LeftHandReader:
def __init__(self, channel, expected_serial='LHT20-011-263-L-B-1-D'):
def __init__(self, channel, expected_serial=None):
if importlib.util.find_spec('can') is None:
sites = list(((portable_paths.VENV / "lib")).glob('python*/site-packages'))
if len(sites) != 1:
@@ -28,8 +29,7 @@ class LeftHandReader:
if sorted(chunks) != list(range(max(chunks)+1)):
raise ValueError('Incomplete serial')
self.serial = bytes(sum([chunks[k] for k in sorted(chunks)], [])).rstrip(b'\0').decode('ascii')
if self.serial != expected_serial or '-L-' not in self.serial:
raise ValueError('Unexpected left hand identity: '+self.serial)
validate_hand_identity(self.serial, 'left', expected_serial)
self.lookup = LeftLookup()
self.faults()
except BaseException: