orisys/ros_contorl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
54 Commits 2 Branches 0 Tags
f882c4309c3ed9dcfac8b0db319a9444c1cf3736
Commit Graph

37 Commits

Author SHA1 Message Date
arm_dev f882c4309c 克隆下来必须带上正在用的视觉权重和本机 site.yaml，否则感知只能指到一台机器上的路径，别人起不来。 
顶视迁臂改走厂家 MoveL，D405 框心对准后再对孔；夹爪停在 caught 时 open 不再把相同目标当成已经张开，init 会真的回零。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-10-12 17:08:43 +08:00
arm_dev b903161113 左臂换成 tool10120938 后，手眼仍按旧 tool1 和 8×11 板求解，顶视迁臂又按短跳 rest-to-rest，真机上要么整体偏一截，要么中途弹射启停。 
眼在手上改用该 TCP 做 AX=XB，再折回相机→法兰；A5 内角点改为 11×8，09-04 / 10-09 旧结果留在 backup。一阶段 D435 迁臂改成一条 FollowJointTrajectory（余弦加减速，近处降速，XY 进门槛后再单独收垂直），跟踪锁高与悬停齐平，避免倾斜相机下先降一截把孔位重投影偏掉。--no-descent 只降到离面 15 mm；跳过三阶段时触觉 USB 打不开不再空等几分钟。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-10-12 15:04:23 +08:00
arm_dev 7d22f777c8 把当前控制栈收成一份可克隆的源码：腕部看不见时用顶视一次定到基座，二阶段对孔和手外标定跟着进同一份树。 
现场 site.yaml、权重和编译产物仍不入库；模板只留占位符。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-10-09 14:51:03 +08:00
arm_dev 55e5f8f20b --sim 时按仿真台别名导出手眼真值：--arm 89 --sim 照着文档敲必然失败 
`--arm 89 --sim` 是个**合法且有意的**用法（run_gauge_assembly.sh 里
_HAD_ARM 那段写着"想用仿真核对某台真机的点位时会这么用"），但手眼真值导出
传的是 ${ROBOT_SN} —— 于是帧名成了 Rizon4-063989_flange，而仿真 URDF 里是
sim_flange。导出先干等 20s，再报"仿真栈起来了吗？"，把人引去重启一个明明在
跑的仿真。文档 §7 里写的就是这条命令，所以照着敲 100% 失败。

真值必须按**仿真台**的帧名导出，与"用哪台臂的点位"无关 → 固定用仿真台别名
（SIM_ARM_ALIAS 可覆盖，默认 sim）。

顺带把 §7 那组验收命令补成真能跑的：
  · 以前只写"先编"，没说**怎么起仿真**，也没说**起之前要清干净** ——
    这次就是在这两步上栽的，新增 §6.5 把三步（编 / 清 / 起）写全；
  · "arm_application 子集 454 passed"配的那条裸 `PYTHONPATH=... pytest`
    命令实测已经收集阶段就 error（导入不到 ament），改成走 run_unit_tests.sh
    并更新数字；总测试数 1118 → 1128。

验证：`bash scripts/run_gauge_assembly.sh --arm 89 --sim --dry-run` 现在
state=DONE ok=True 2/2 孔、退出码 0（修改前必然退出码 1）。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-28 12:25:26 +08:00
arm_dev baf7601995 预检补上 arm_control 孤儿与 mock 的 joint_state_publisher 
上一轮残留的那四条孤儿（real_trajectory_adapter / named_pose_server /
arm_status_node / joint_state_publisher）在预检里**一条都报不出来**：
老的六条模式只覆盖 ros2_control_node 和 stack.launch，而它们的特征恰恰是
"栈的主体已经没了、只剩它们"，所以两条老模式全都匹配不到。

补两条：
  · `install/arm_control/lib/arm_control/` —— 一次覆盖该包全部节点
    （用 install/ 而不是 install_sim/：仿真同名节点不该被真机体检误报，
    "install_sim/" 不含子串 "install/"，这条性质用测试钉住了）；
  · `joint_state_publisher` —— mock 专用节点，真机上出现 = 上一轮 mock 栈的
    残留。它发的**静态** /joint_states 会盖掉真实关节角，是"控制器一切正常、
    TF 显示臂没动"这个假象的元凶，所以说明里把它写清楚。

人工动作也改成先指向新的 stop_real.sh（它真能带走这些孤儿），保留手动 pkill 兜底。
新增 3 项单测（含"不许误报 install_sim/"的负向用例）。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-28 12:25:20 +08:00
arm_dev 6baf989595 真机侧补 stop_real.sh 与域隔离：残留的 mock 栈会把仿真/真机的 TF 盖成"静止" 
实测（2026-09-28）在仿真里上料失败，一路查到 IK / TF / 时钟上，全是被冤枉的。
根因是两个真机侧一直缺的东西：

1) **真机侧没有停止脚本**。仿真侧早有 stop_sim_gz.sh（R4.10/R4.11：残留会伪造出
   "代码写错了"的现场），真机侧只有 run_real.sh 里两行 pkill。而真机栈里有一族
   **独立于 ros2_control_node 存活**的进程 —— 上一轮栈的主体早没了，只剩
   real_trajectory_adapter / named_pose_server / arm_status_node /
   joint_state_publisher 四条，两条 pkill 一条都匹配不到。
   危害不是占资源而是**冒名顶替**：残留的 adapter 照样订阅 /trajectory、
   残留的 joint_state_publisher 照样发 /joint_states（mock 的静态关节角）。
   现象极具误导性：控制器 feedback 与 reference 完全一致（控制器没坏），
   TF 却显示末端一动不动。

   新增 stop_real.sh + lib/real_procs.sh：扫描 = 点名表 + `install/` 前缀兜底，
   按 ROS_DOMAIN_ID 判别真机/仿真（两边有同名的 robot_state_publisher，
   否则停真机会把正在跑的仿真杀一半），杀完复查残留并非零退出。
   run_real.sh 启动前的清理改用它，不再各写一份会漂移的模式表。
   真机侧**有意不**用仿真的"进程组"法：真机栈是前台交互跑的，没有独立进程组，
   它的 PGID 就是调用它的 shell —— 记下来再 kill 会杀掉自己的终端。

2) **真机侧不强制 ROS_DOMAIN_ID**。sim_env.sh 早就强制 77 并写明"隔离不能靠
   『环境里恰好没设』"，真机侧没有对应保护：先 source 过 sim_env.sh 的 shell 里
   再起真机栈，真机栈就落到**仿真的域**上，节点名撞车、/joint_states 与 /tf
   各有两个来源互相盖。补 lib/ros_domain.sh（真机 0 / 覆盖用 REAL_ROS_DOMAIN_ID），
   env.sh、run_real.sh、run_sim.sh 三处共用一份实现 —— 成对强制，否则一侧的
   强制只是把运气挪到了另一侧。

   run_sim.sh 特别容易漏：它名为 sim，用的却是**真机的 install/**、节点名与真机
   完全一样，而且当时不管域；这次也钉到真机域 0。run_sim_gz.sh 文件头那句
   "两者互不影响"是错的，一并改掉。

验证：stop_real.sh --list 在有仿真在跑时为空（REAL_PROC_INCLUDE_SIM=1 能看到
并按"域 77"标出）；伪装一个 install/arm_control/lib/arm_control/arm_status_node
的孤儿进程能被点名。新增 6 项单测钉住域的四种输入 + 一个不许误报。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-28 12:25:16 +08:00
arm_dev bb6f792922 复位命令必须带 timeout：实测它自己会永久挂住，还留下占着 USB 的僵尸进程 
上一版把触觉 wedged 的处置改成「首选 `sudo -n orisys-usb-reset`（免密，无人值守
可直接跑）」。真跑了一次，发现这句话是错的：

    sudo -n /usr/local/bin/orisys-usb-reset 1-3.4.1

跑了 **155s 都没返回**，进程停在 `S` 状态（卡在写
`/sys/bus/usb/drivers/usb/unbind`），`timeout 90` 都收不掉它 —— 现场留下了三个
残留进程。对无人值守来说这是最坏的结果：那一轮在这里永久卡死，而且这个进程还
占着 USB，后面重试触觉只会继续失败。

复位之后 `1-3.4.1` 直接从 sysfs **消失**了（复位前它还在总线上、只是没有
/dev/video*）—— 也就是设备比复位前掉得更彻底。所以这条命令**不是**"跑一下试试"
那种安全操作，必须当有副作用的操作对待。

改动：
· 两处给现场的命令一律写成 `timeout 15 sudo -n /usr/local/bin/orisys-usb-reset
  <devpath>`，并把「不加 timeout 会永久卡住 + 留僵尸进程」写进提示原文。
  这与 `orisys_tactile.py` 的自动自愈口径一致（那里本来就是 `timeout=15.0`，
  所以自动路径不受影响，只有手工执行的建议是错的）。
· 复位后设备仍不在总线上（或消失）→ 明确归到**物理**处置：拔插该相机 /
  给这个 Hub 断电重启。

测试：test_v4l_health 新增两条 —— 断言给出的复位命令里含 `timeout 15`，
以及提示里必须写出"会挂住"这件事（只给命令不说风险，人就会裸跑它）。
全仓库 1119 passed / 1 skipped。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-28 10:46:06 +08:00
arm_dev 02c26cfb86 测试运行器：位置参数真的只跑指定路径；文档改成实际能跑通的命令与数字 
scripts/run_unit_tests.sh
  用法注释里写的是「bash run_unit_tests.sh src/<pkg>/test/test_x.py -x」，但实现是
  `pytest "${test_dirs[@]}" "$@"` —— 传进来的路径只是被**追加**到「全部测试目录」
  后面，实际仍然跑整仓库。用法示例就是承诺，它不成立会让人以为「我只改了 x，
  怎么蹦出别的包的失败」。改成：位置参数里**存在的路径**当作「只跑这些」，
  其余（-k / -x / --tb=… 及其取值）原样透传。

docs/HANDBOOK.md §4.3
  原文让人逐个包手敲 `python3 -m pytest src/xxx/test`。这条命令在本仓库**会失败**，
  而且是两种最容易被误读的失败：
  · 少挂一个 src 包 → 收集阶段 ModuleNotFoundError，现象是「0 个测试 / 1 个 error」，
    像测试环境坏了；
  · 更隐蔽：install/ 里那份**旧的**同名模块会先被找到。实测直接跑
    src/arm_sim_gazebo/test 报 `cannot import name 'RESET_GIVE_UP'`，导的是
    install/ 里的旧副本，源码里明明有这个符号 —— 测的根本不是你改的那份。
  改为统一用 run_unit_tests.sh（它把 src/* 挂到 PYTHONPATH 最前面），并把这段
  原因写进文档。顺带把过期的统计数字更新为实测值：608 → 1118 项，
  分项 arm_application 233→547、arm_sim_gazebo 236→400、arm_interfaces 46→78。

实测：src/arm_sim_gazebo/test 直跑 = 2 个收集错误；经运行器 = 400 passed。
      单文件 28 passed；-k real_preflight = 28 passed / 1 skipped；
      无参数全量 = 1118 passed / 1 skipped。

docs/QUICKSTART.md
  「第一次实机」以体检开场（它只读、不需要机械臂能动），并列出四项判据各抓什么，
  免得现场跳过它直接起栈。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-28 10:42:56 +08:00
arm_dev 352270d1cc 真机开工体检的编排：把「不报错但不对」的故障源排成现场能照着做的顺序 
前一个提交给了四个单项判据（USB / V4L / RDK / 手眼）。这一批把它们的**判据入口**
补齐并编排成一条命令，产出「结论 + 要人工做的事」：

scripts/lib/real_preflight.py
  run_all() 按**现场该处理的顺序**排出结论，不是按代码顺序：
    现场配置 → 遗留进程 → 网络 → 机械臂 RDK → 腕部相机 → USB/触觉/几何
  顺序是有理由的：遗留的 ros2_control 占着 RDK，会让后面每一项的现象都指向别处，
  所以先查它；机械臂能不能动是唯一的人工硬阻断，排在相机之前。

  新增 check_cameras —— **本臂配置的那只腕部相机在不在 USB 上**。
  这是本次实测暴露的判据缺口：2026-09-28 现场 D405 整个从 lsusb 消失
  （只剩顶置 D435），而旧体检**全绿** —— check_usb 只看协商速率，遍历的是
  「发现到的」设备，对「这只根本不在了」无话可说。缺 D405 之后踩的是完全不同
  的一类错误（点云为空 / 找不到工件），排查方向会被带偏很远。
  按 site.yaml 的配置意图核对：robots[<sn>].camera.name → cameras.<name>.model，
  比**型号**而不是序列号 —— 实测这台 D435 的 sysfs serial 是空串，按序列号判会
  永远判「不在」；序列号只在型号对上时做一次「是不是本臂那只」的提醒（WARN）。

  修掉三处会误导现场的输出：
  · _run() 改成三返回值（分离 stdout/stderr，RDK 的 C++ 日志会混进 stdout）
    之后，_ps_output/网络两处还在按两返回值解包 —— 体检**第一步就崩**，
    什么结论都给不出来。现在有 test_run_all_completes_without_crashing 钉住。
  · 人工动作里「去查网线」出现过两条（check_network 与 rdk_status 各写一句
    意思相同、字面不同的话），去重是按整串文字做的，于是人读到两条、还得判断
    「这是一个问题还是两个」。措辞抽到 manual_actions.py，两边字面一致。
  · 触觉 wedged 的处置与 v4l_health 同步（免密的 reset 是首选，重插是兜底）。

scripts/lib/manual_actions.py（新）
  人工动作措辞的**唯一**来源。判据分在两个文件、还跑在两个不同的 Python 上
  （3.11 / 3.10，见 rdk_status 的模块说明），互相 import 不了，所以抽成只依赖
  标准库的公共模块。

scripts/run_real_preflight.sh（新）
  一条命令的入口：只读、不动臂，不需要机械臂能连上。

实测（2026-09-28，arm 89）：体检跑通并给出 NO-GO + 7 条互不重复的人工动作，
新判据抓到「D405 不在 USB 上」（旧版全绿）。同时确认了本机可用的部分：
夹爪 PGEA 初始化完成 / 全开 20.00mm、右指触觉 SDK 300 帧 @29.9Hz、
手眼矩阵自洽、enp4s0 千兆全双工。

测试：test_real_preflight 28 项通过（含跨模块的措辞去重回归、
编排端到端冒烟、腕部相机四种情形）。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-28 10:42:49 +08:00
arm_dev 0fadd26ca2 体检判据硬化：sysfs 读取带超时、复位命令不再写成"要密码" 
两处都是「体检工具自己失效」——本仓库最贵的那类坑：判据看起来在跑，其实
结论是假的或者干脆没有结论。

scripts/lib/usb_health.py
  Hub 在内核里卡死时，读它的 sysfs 属性会**永久阻塞**（实测
  /sys/bus/usb/devices/1-3.4/product 读 20 秒不返回）。于是体检脚本自己挂住：
  本该报出故障的那一次，恰恰什么都不输出。新增 SysfsReader —— 所有 sysfs 读取
  带 1s 超时，卡死的路径只尝试一次并记入 blocked（Python 杀不掉阻塞在系统调用
  里的线程，不记就会在 --watch 反复采样时攒出几十个），blocked 映射回父设备
  并按 error 报出「给这个 Hub 断电重启 / 改插主板直连」。

scripts/lib/v4l_health.py
  · 提示语写「到真终端里带密码跑 orisys-usb-reset」，与实际不符：sudoers 对这个
    脚本本来就是 NOPASSWD 白名单（`sudo -n -l` 可见；orisys_tactile.py 的自动
    复位用的也是 sudo -n）。现场按这句会以为无人值守时做不了这件事。
    改成 `sudo -n /usr/local/bin/orisys-usb-reset <devpath>` 并说明免密来源。
  · wedged 的处置写反了：以前是「物理重插；reset 只在没完全卡死时有效」，
    而设备还在 sysfs 里正是 unbind/bind 能生效的前提，先说 reset。
  · main() 增加可注入的 v4l_root/usb_root，用例不再读真机 sysfs。

测试：test_main_exit_code_is_nonzero_on_error 以前直接读真 sysfs，本机这只
相机没插（unplugged）时会变红 —— 它本该只在 wedged 下断言复位提示。改为注入
临时 sysfs（设备在总线上、无 /dev/video*），用例变成确定性的。
test_usb_health + test_v4l_health 共 28 项通过。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-28 10:42:37 +08:00
arm_dev 98f4277849 真机开工体检四件套：USB 链路 / V4L 设备 / RDK 状态 / 手眼几何 
这四个都是「现场看着正常、结果不对」的故障源，共同特征是**不报错**，所以要把它们
从流程里拎出来单独判，并且给出可执行的下一步，而不是只报一个失败。

scripts/lib/usb_health.py
  RealSense 协商到 480Mbps（USB 2.0）时能出图、不报错，只是帧率掉到 1/2 且
  深度不稳定。这里解析 sysfs 拓扑，把「速率对不对」独立于「有没有图」来判，
  并在 --watch 下统计掉线/重连次数（线/口/供电 Hub 的问题会表现为反复抖）。

scripts/lib/v4l_health.py
  触觉相机有两类完全不同的坏法，处置方式相反，以前都只表现为「没有 /dev/video*」：
    · unplugged —— sysfs 里也没有，是没插/线坏
    · wedged    —— sysfs 里在、/dev/video* 没有，是 USB 端点了卡死（要复位或重插）
  2026-09-28 现场左指就是 wedged（1-3.4.1 在 uvcvideo 下，video 节点缺失）。

scripts/lib/rdk_status.py
  ros2_control 卡在 wait_for_operational 时，现象是「栈起来了但关节全是 0、
  流程一直等」。原因全在 OperationalStatus 上，而它只有 RDK 读得到。
  这里把状态翻成人话 + 处置（Auto(Remote) / 松急停 / 清故障）。
  判据取自厂商头文件原话：IN_MANUAL_MODE = "need to switch to Auto (Remote) mode"。

scripts/lib/real_geometry_check.py
  手眼矩阵与悬停几何。手眼写坏不会报错，只会让位姿整体偏几毫米到几厘米；
  判据：R 正交（|RᵀR−I| ≤ 2e-3）、det(R)=+1、平移量级在 10–500mm。
  悬停几何直接复用 gauge_fsm.hover_z_guard（流程里唯一判定处，不另写一套）；
  工件面未标定（site.yaml 写 0.0 = 未知）时**明确报 FAIL 并说明判不了**，
  而不是按 0.0 算出一个假的「已修正」结论。

测试：test_usb_health / test_v4l_health / test_real_geometry_check 共 33 例，
全部钉在「判据要能报错」上（故意弄坏的输入必须被抓到）。

顺带 .gitignore 补 log_real/：真机各终端日志是运行产物，与 log_sim/ 对称。
 2026-09-28 10:17:32 +08:00
arm_dev 0a2a28a355 真机落地实测修的三处：参数类型不一致导致节点启动即崩、权重目录判据、相机日志 
1) site.yaml 的整数把节点写死（ros_node.TolerantNode）
   现场 site.yaml 写 `ae_limit_us: 8000`（YAML 整数），脚本按 `-p ae_limit_us:=8000`
   传参，而节点 declare 的是 double —— rclpy 严格比对类型，节点**启动即崩**：

     InvalidParameterTypeException: Trying to set parameter 'ae_limit_us'
     to '8000' of type 'INTEGER', expecting type 'DOUBLE'

   现场看到的只是「顶置 D435 起不来」，报错里一个字都没提 site.yaml，而
   `8000` 与 `8000.0` 在运维眼里是同一个数。同一族的雷还有 width 848.0→int、
   emitter_enabled 1→bool、带不带引号的序列号。
   修法是新增应用层统一基类 TolerantNode：在**声明阶段**把覆盖值的类型按
   声明类型收敛（异常就发生在声明阶段，所以 `float(...)` 这种事后 cast 救不了）。
   全部应用节点改继承它；补 test_ros_node.py。

2) 权重目录判据（weights_layout）
   模型文件「在不在、名字对不对」以前散在几处各判一半，缺文件时的现象是
   推理静默退回随机权重。收成 weights_layout.py 一条判据 + scripts/weights.py 调用。

3) 相机日志：USB 降速要说清怎么办
   realsense_color_pub 协商到 USB 2.1 / 480Mbps 时只打一行速率，没人知道该做什么；
   现在直接给可执行的处置（换线/换口/SuperSpeed 不复用）。realsense_view 同步。

4) stage2_locate：接上 hover_z_guard 与 tool_tip_below_flange_m
   悬停高度必须让工具尖端留在工件面上方（09-24 的教训：悬停时尖端已钻进工件
   25mm，S05 横向对准把工件拖走 92mm）。step2 侧也按同一判据兜住，且工具长
   允许由启动参数覆盖（仿真上料后实测得到）。

5) config/site.example.yaml 与 site.yaml 重新同步
   上一批给夹爪加了 auto_init: false，模板没跟着重跑，TestExampleParity 因此失败。
   重跑 scripts/gen_site_example.py 同步（模板是生成物，不手改）。

测试：全仓库 1085 passed（此前 1 failed）。
 2026-09-28 10:17:16 +08:00
arm_dev c1cd862eea 真机落地前的仿真补齐：夹持/腕力/真值位姿，让仿真能验证 S07–S09 
这批是 09-24 那轮仿真工作的收尾，一直没提交。内容按目的分四块：

1) 仿真真能「夹住」工件
   sim_grasp_lock：给规与夹爪之间加接触锁（默认关，run_gauge_assembly --sim 才开）。
   没有它时仿真里规只靠摩擦，S08 棘轮一转就滑出指间，于是把「仿真不真」误读成
   「力判据不对」。新增 test_sim_grasp_lock.py。

2) 腕部力传感器进仿真
   sim_wrist_ft（+ config/wrist_ft.yaml）：S07 的首选判据是腕部 FT 的轴向突变，
   而仿真里以前根本没有腕部力，S07 只能退到触觉兜底，两套判据从没在同一场景下比过。
   现在两条通道都在，接触判定可对照。

3) 真值位姿可查（不再靠猜）
   sim_live_pose / sim_pose_service：把 Gazebo 里刚体的实测位姿发布出来，
   stage2 的真值路径按**实测**位姿算孔位，而不是按场景文件里的标称位姿。
   顺带把真值孔位的推导（truth_holes）独立出来并补测。

4) 工具几何成为可配置项
   config/sim_tool_geometry.yaml + stage2 的 tool_tip_below_flange_m 启动参数：
   仿真里规会在指间下滑，工具长每次装夹都不同（实测见过 243/254mm），
   悬停高度与 S07 下探预算必须按实测值算，不能再写死。

应用层同时跟进：gauge_fsm / gauge_config 把「悬停时工具尖端入没入工件」的判据
（hover_z_guard）与拖件判定（drag_verdict）收成纯函数并补测；stage3 搜孔、
site 导出、run_gauge_assembly 与若干文档同步。
新增 test_gauge_exit_lift / test_gauge_gripper_client / test_node_handler_collisions。

测试：全仓库 1085 passed。
 2026-09-28 10:17:06 +08:00
arm_dev 36a59c81bf 应用层修复：S00 自检假阴性、S07 触觉假断流、S07 下探静默卡死 
三处都是"看着像硬件问题、其实是判据问题"的假警报：

1. S00 自检假阴性（gauge_boot.py）
   探测等待时用 time.sleep 不 spin → 订阅回调根本没机会执行，
   于是**健康的硬件也会被判"没有数据"**。改成等待期间持续 spin。

2. S07 触觉假断流（stage3_search_node.py）
   判据原本是 |fnormal| > 1.0，但力本来就可能是零或很小（真机轻触、
   仿真刚接触）→ 明明在发数据却判"触觉断流"。
   改成"数据够新（TACTILE_MAX_AGE_S 内）+ connected" —— 判活看的是
   **有没有在发**，不是**数值大不大**。

3. S07 下探静默卡死（gauge_fsm.py / gauge_assembly_node.py）
   _goto 的到位容差 ≥ 步长时，每一步都被判成"已在容差内"，臂一步都不走，
   而外层只看到"没进度"→ 死循环到超时，日志里看不出原因。
   新增 descend_tol_m / descend_iter_budget / descend_progress：
   容差从步长推导（不该手工调大），并显式判"连续 N 步零位移"。
   容差 ≥ 步长的反例已进 site 回归测试，防止再犯。

4. site 分段化（export_site_env.py）：89/91 两臂的 servo/handeye/点位
   各一段，避免"改 91 影响 89"。

另：run_unit_tests.sh 作为统一测试入口（932→933 项），
    devices/sim/gazebo/README.md 同步。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-24 14:43:19 +08:00
arm_dev b29339e522 仿真感知：真值孔位 + 真值相机 + 补 /home，让流程不改代码就能跑仿真 
三块补齐，目标是"同一个流程节点，仿真/真机都不改代码"：

1. 真值孔位（truth_holes.py）：把 scene.yaml 与模型 SDF 里已知的孔几何
   直接投影到相机像素坐标，替代 HoughCircles。perception.source 选：
     yolo / truth / external —— truth 就走这条路。
   为什么不用 Hough：仿真里孔是"方孔 + 贴片亮环"的近似（SDF 没有布尔运算），
   靠图像门槛去凑 radus 区间很脆；而孔位本来就是场景里已知量，直接投影
   既准又稳，还能当真实检测算法的对照基线。

2. 真值相机（sim_truth_perception.py）：同理，直接算物体位姿，供
   visual_servo/filtered_point 用，绕开 ONNX。

3. 补 /home 与 set_named_pose 服务（sim_home_service.py）：真机上这两个
   由 Flexiv 驱动提供，仿真里没有 —— 缺了 S01 直接超时。

4. sim_tactile_adapter 容错导入 ros_gz_interfaces：那一路只是"接触点"，
   力本身走 geometry_msgs/Wrench。typesupport 加载不了时退化成
   contact 恒 False + centroid 恒 0，三力判据（S07 用的）不受影响 ——
   宁可用退化模式跑，也不要整个适配器起不来。

5. repo_root 解析（已装包要能找回源码仓库根，见 test_repo_root.py 的用例）
   与 use_sim_time 向子 launch 的传递。

另：scripts/gen_sim_handeye.py 把 URDF 真值导出手眼文件（仿真不标定）。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-24 14:43:13 +08:00
arm_dev 811e71df1f 仿真上料：夹爪真能夹住通止规（新增 sim_load_gauge.py + 夹爪出力钳位） 
仿真里没有"人把规塞进夹爪"这一步，之前整条流程拖到 S07 才暴露（下探 25mm
什么也没碰到，看着像力阈值问题）。新增 scripts/sim_load_gauge.py 顶这一步。

上料为什么难（四个原因叠加，都实测踩过）：
  1. URDF 里夹爪关节 effort=80Nm → 位置控制器把规顶飞。urdf_normalize 新增
     _clamp_grip_effort：按握力 45N 与指节杠杆反推，指节 4.79Nm / 主关节 45N。
  2. **指腹接触面不在 tcp_frame 原点上**：URDF 里 inner_finger_pad_joint
     z=0.0235、finger_tcp_joint z=0.0360（同父链节同方向）→ 指腹中心比
     tcp_frame 高 12.5mm。所以规尖→指腹中心是 0.043，不是夹持段中心的
     0.0555。用错值的现象极迷惑：gz 报得出 Contacts、也能读到接触，但规
     就是托不住、一路滑下去。ΔZ 扫描实测：0/±5mm 掉、+10~+15mm 夹住。
  3. 摆完位就自由落体：ROS 往返 100ms+ 而物理步进 1ms，等合爪指令到达，
     规已掉 125mm。改成**像人手一样托着** —— 合爪期间 50Hz 按当前指腹位姿
     把规瞬移回两指之间，托到真夹住为止。
  4. 合到多少不猜：从松到紧扫开口，扫到"松手后不掉"为止。指腹实际接触面
     未必在 tcp_frame 原点，拿"指间间距=开口"反推闭合量会差好几毫米。

结果：漂移 0.4mm、两指 |fnormal|≈46.5N（正好是 45N 设计握力）。
另修 _set_gauge_pose 的 ign service 口径说明与 _gauge_pose_now 的解析。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-24 14:42:56 +08:00
arm_dev aed5d326a0 仿真环境串味根治：清残留路径 + 补 conda lib + 修入口脚本 shebang 
症状一（最隐蔽）：同一 shell 里先 source 过真机环境（scripts/env.sh）再
source 仿真环境，install/ 与 ros_flexiv 的路径不会被 conda deactivate 撤掉，
长在 install_sim/ 前面：
  - PYTHONPATH 里真机那份 arm_msgs 压住仿真那份 → 消息类型混用
  - LD_LIBRARY_PATH 里没有 $CONDA_PREFIX/lib → sim_tactile_adapter 订阅
    ros_gz_interfaces/Contacts 时抛
      Type support not from this implementation ...
      cannot open shared object file
    而库其实就在 conda 里、ldd 全齐。整条触觉链静默死掉（话题不发）。

症状二：setuptools 写 console_scripts 用的是**构建那一刻**的 python。
若在真机环境里跑过 build_sim.sh，install_sim/ 里 7 个入口脚本的 shebang
会指向 ros_flexiv —— 而 ros2 run 是照 shebang 执行的，于是**仿真节点一直
跑在真机 conda 环境里**。两个环境都是 Humble+py3.11，所以"居然能跑"，
只有偶发 dlopen / 反序列化怪错。

修法：
  - conda_switch.sh 新增 path_drop_patterns：按 glob 从冒号列表里删条目
  - sim_env.sh 清掉真机残留 + 末尾补 $CONDA_PREFIX/lib（优先级最低）
  - 新增 lib/fix_shebangs.sh，build.sh / build_sim.sh 收尾各扫一遍（幂等）

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-24 14:42:50 +08:00
arm_dev bda2fa7129 通止规装配：配置段进 site.yaml + 中文手册 + 成败判定「不看 $?」 
配置（site.yaml → gauge_assembly:，38 键全部带中文注释）
------------------------------------------------------
- 键名/单位/类型/交叉矛盾由 gauge_config.py 校验：拼错键名报错并给最相近的候选，
  单位后缀（_deg/_mm/_m/_s/_pct/_delta）逐条对表，`contact_safe_delta ≤
  contact_tangential_delta` 这类矛盾启动就拦（R1.2：没接线的键不许静默存在）。
- 借机清掉 4 个**没接线**的键（require_preview / track_*_s / hover_m：前两个是
  stage1 那层的、后两个是 servo 那层的，放在这里等于第二份真相），
  并把 contact_speed_m_s / coarse_timeout_s / 夹爪力速 真的接上。
- site.example.yaml 由 site.yaml 生成（gen_site_example.py --check 通过）。

成败判定：`ros2 launch` 的退出码**恒为 0**
------------------------------------------
实测（Humble）：子进程 exit 3，`ros2 launch` 仍返回 0。用 `$?` 判成败的脚本会把
"装配失败"记成"成功"——没人会去查一个说成功的脚本。改成：

- 节点把结论**落盘**（--result-file，默认 /tmp/gauge_assembly_result.json，原子写、
  先落盘再发话题），任何"没跑到收尾"的退出也会补一份 ok=false；
- 脚本读结论文件判成败：0=成功、1=失败、**文件不存在也算失败**并说清；
- 新增 test_gauge_result_gate.py：把脚本里那段判成败的 Python 抽出来，
  对成功/失败/干跑/缺文件/坏 JSON 五种输入断言退出码 —— 判据本身也有测试。

顺带修掉两个"看着像玄学"的现象
------------------------------
- **流程打完了终端不回提示符**：launch 里的静态 TF 发布者是常驻的，主节点退出
  带不走它 —— 挂 OnProcessExit → Shutdown。
- **"已装 1/2 孔"**：结果里 hole_index 是 0 基当前孔号，不是"装完几个"，
  新增 holes_done 给人和脚本看。

文档（全部中文，含"怎么调参/还没做"）
------------------------------------
- 新增 docs/GAUGE_ASSEMBLY.md：状态机全图、每步判据表、E1 掉件处理（**按实现**：
  掉件后该孔作废、换下一个孔；最后一个孔掉件则序号被夹住=重试本孔）、
  话题契约、调参顺序、验收命令、踩过的坑。
- FRAMEWORK_RULES 新增 R5.8（同一份数学只许一份 + 守卫测试）、R5.9（自检的
  期望类型与调用处同源）、R5.10（缺依赖 skip，别留常年红）、R6.9（硬退出前打
  traceback）、R6.10（ros2 launch 退出码恒 0）＋ R5.7 补真机/仿真"生效方式不同"
  （真机软链即改即生效，仿真拷贝必须重编）＋ 5 条症状反例、.cursor/rules 同步。
- WORKSPACE / INTERFACES / SITE_CONFIG / HANDBOOK / 两份 README 索引与决策表补齐。

验证（本机真跑）
----------------
  pytest（仿真环境）  436 passed, 14 skipped（缺 onnx 跳过）
  干跑 --sim --dry-run  → 脚本退出码 0，结论 ok=true  已装 2/2 孔
  不干跑 --sim          → 脚本退出码 1，S00 拦住，未发任何运动指令

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-24 10:30:11 +08:00
arm_dev dfc945b7e0 P6 通止规装配：主流程节点（S00–S11 跑通）+ 入口脚本 + 真机/仿真验证 
新增
----
- arm_application/gauge_assembly_node.py：主流程。每个阶段一个 _step_*，
  返回值就是状态机的事件；纯逻辑（状态机/配置/限位/夹爪后端/自检）全部
  在 gauge_*.py 里，节点只做"发指令 + 读反馈 + 报错"。
  * S00 自检报告带"缺了会怎样"，必检拦住、选检告警；
  * S01 回 home → 切工具系 → 逆时针预绕，**事后用 TF 实测绕工具 Z 转了多少度**
    （转轴偏差 >5° 直接中止：以"度"为单位的动作全建立在这条假设上）；
  * S03 手外粗定位：没有 eye-to-hand 标定文件时明确报"缺哪个文件、怎么生成"，
    回 S04 兜底（不做假装成功的反投影）；
  * S05 稳定判据用"到均值的最远距离"，不用相邻帧之差；
  * S07 悬停处测基线 → 步进下压 → 两路切向任一突变即停，法向超安全上限抬起中止；
  * S08 棘轮四步（慢转→松爪→快回转→夹紧），停止判据「切向 >阈值 且 法向突增」，
    掉件走 E1 重放；S09 反向拧出（比拧入多一轮）；
  * E1 重放等 /gauge/reload_ok 人工确认（超时按中止），E2 任何中止都先退安全高度。
- launch/gauge_assembly.launch.py：只做一件事 —— 发布手眼静态 TF（S05 的前提），
  其余判据全交给 S00（判断标准只有一处）。
- scripts/run_gauge_assembly.sh：--arm/--sim/--dry-run/--holes/--backend。
- gauge_assembly 入口（setup.py）+ 站点参数 reload_timeout_s。
- test/test_gauge_step_events.py：**读节点源码 AST**，把每个 _step_* 可能返回的
  事件逐个问状态机"合法吗" —— 节点与转移表是两份数据，漏登记要在 pytest 里炸，
  而不是在真机上跑到那一步才炸。

顺手修掉的两个真问题
--------------------
1. 四份 launch 里的四元数换算**已经互相抄歪了**（退化分支的公式各不相同）。
   统一收口到 handeye_lib.read_transform_yaml，并加回环测试（真实标定文件 +
   180°/270° 等分支切换角度）；实测 4 个 launch 输出与库完全一致。
2. pipeline_node.AssemblyPipeline 支持 node_name 复用（本流程继承它的一阶段
   跟踪/二阶段定位链，但在图上必须是另一个节点名）。

验证（都在本机真跑过）
----------------------
  pytest（仿真环境）              → 349 passed, 14 skipped（缺 onnx 的用例跳过）
  干跑全流程                      → S00→S01→…→S11→DONE，exit 0
  仿真里不干跑（缺 /home 等）      → S00 拦住，exit 1，未发任何运动指令
另：仿真环境没有 onnx（只有真机 conda 有），相关用例改为 skip —— 让测试结果
"红就是真红"。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-24 10:12:03 +08:00
arm_dev 6922b18187 仿真夹爪适配器：服务接口对齐真机，开口按正运动学换算成真毫米 
为什么
------
应用层只认 arm_msgs/srv/GripperExecute（开口毫米），真机与仿真必须同一套接口。
但 GN01 的 URDF 里 <mimic> 是**线性近似**：直接按线性系数下发 finger_width_joint，
"命令开 20 mm"在 Gazebo 里量出来是 21.75 mm —— 抓不住工件，而且看起来像算法问题。

实测（2026-09-24，Gazebo 内量两指尖间距）：
  线性下发 20 mm → 实际 21.74 mm（偏差 1.74 mm，超 2 mm 抓取容差的前半步）
  走 FK 反解     → 实际 20.00 mm（≤0.5 mm）

怎么改
------
- 新增 sim_gripper_kin.py：解析 URDF 正运动学，算出"主关节值 ↔ 真实开口 mm"的
  单调曲线，反解用二分。曲线非单调/零行程时**主动报错**，不静默退化成线性。
- sim_gripper.py：开口换算全部走该曲线；容差统一改成毫米。
- sim_gripper_adapter.py：反馈改取**从动关节**（见下）；is_gripped 按毫米判定。
- 新增 check_sim_gripper.py：三层验收（服务/开口一致/指尖真实几何行程 + 对称性）。

踩到的坑
--------
- finger_width_joint 挂在无质量的 unused_finger_width_link 上，与手指**没有机械
  连接**：命令到 0.100，它的 /joint_states 恒为 1.4e-08，6 个从动关节才准到
  0.7854。反馈若取它，/gripper/status 会永远报"开口 0 mm"。
- 残留进程会伪造出"代码写错了"的现场：旧 sim_gripper_adapter 与新实例抢话题，
  验收读到"指尖间距 0.03 mm"（真实 127 mm）；孤儿 static_transform_publisher
  用 latched /tf_static 把旧相机外参按在新仿真上。
  → 新增 scripts/lib/sim_procs.sh；run_sim_gz.sh 用 setsid 独立进程组，
    PGID 记进 log_sim/sim.pgid，stop 时整组 kill；启动前预检拒绝带病启动。
- 验收脚本自己也错过两次（把 TF 的米当毫米比 → 127 mm 显示成 0.13 mm；
  用会转动指垫的中点漂移判对称 → 必然位移 16 mm）。判据改成"两侧各走多远"，
  单位只在 _dist_mm 里换算一次。

验证
----
  python3 -m pytest src/arm_sim_gazebo/test/ -q          → 307 passed
  python3 scripts/check_sim_gripper.py                   → 三层全过
     第 2 层：请求/反馈开口最大偏差 < 0.5 mm
     第 3 层：期望行程 vs 实际行程、左右行程差，均 < 1.5 mm
  bash scripts/stop_sim_gz.sh --list                     → 整组列出（含 static tf）

文档
----
- 仿真手册：新增 §4.4（开口 mm 怎么换算）、坑 12（宽度关节不动、
  反馈必须取从动关节）；停止一节改写成进程组语义。
- FRAMEWORK_RULES：新增 R4.11（残留进程会伪造现场）、R4.12（验收判据要挑
  与实现无关的物理量）；R4.9 表补夹爪；清单补 13/14 两条。
- HANDBOOK：新增 §3.4「在仿真里开合夹爪」，补 §4.4 的两条新教训。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-24 09:46:09 +08:00
arm_dev f5ed44a987 配置：消灭代码里的硬编码臂 SN，并给"换臂漏改"加一把尺子 
## 为什么

"设备 ID 全部可配置"这条要求在代码里只做了一半：site.yaml 能配，
但**代码和静态配置里到处躺着 Rizon4-063989 当兜底**。这类兜底的危害
不是"改起来麻烦"，而是它把"配置没生效"伪装成"配置生效了"：

  * `robot_sn` 默认 `Rizon4-063989` → 换臂后节点去订**上一台臂**的关节话题，
    节点起来了、不报错、什么都不动；
  * launch 里用 `ee_frame == "Rizon4-063989_flange"` 当"用户没指定"的哨兵 →
    换个站点这个判断永远不成立，于是 site.yaml 里的 ee_frame 再也不会被用上，
    静态 TF 挂错坐标系、点还照样查得到；
  * `if SN == "Rizon4-063989"` 决定要不要拉触觉服务 → 换臂后触觉静默消失。

## 改了什么

1. **删掉所有"兜底成某台臂"的默认值**（15 处脚本 + 6 个 launch + 6 个节点）。
   没配就为空 / 直接 `:?` 报错，宁可起不来也不要连错机器：
   - `scripts/lib/export_site_env.py`：别名解析改为从 `robots[]` 现算
     （`arm_short_id` / `resolve_robot_sn` / `describe_arms`），选不出臂时
     抛 `ValueError`；`main()` 捕获后打人话 + 退出码 2（供 shell `eval`）；
   - 手眼文件/路点/工作目录由当前臂 short id 派生，不再写死 `89_*`；
   - `ROBOT_HAS_TACTILE` 改为读 site.yaml 的 `robots[].tactile`；
   - `arm_application/site_io.py` 新增 `joint_prefix_default()` /
     `base_frame_default()` / `ee_frame_default()`：优先读 `SITE_*`，
     退而由 `SITE_ROBOT_SN` 现算，**不写死 SN**；
   - `arm.urdf.xacro` 的 `robot_sn` 默认值改成明显的占位符 `UNSET_ARM_SN`
     （关节名会带出来，报错信息自解释）；
   - `ros2_control.launch.py` / `move_group.launch.py` **原先根本不传
     robot_sn**，靠 xacro 写死默认值"蒙对"本机，现在都从环境取。

2. **新增 `scripts/check_arm_prefixes.py`**：Flexiv 把 SN 编进关节名，
   所以有一批一级配置（SRDF/controllers/joint_names/bringup/servo/...）
   必须跟着当前臂走。漏改的症状是"MoveIt 规划成功但机械臂不动"，很难查。
   这个脚本逐文件逐行列出对不上的地方，并直接给出修法。
   `--list` 还会说明 SN 来自 site.yaml 还是被 `ROBOT_SN` 覆盖。

3. **文档**：`FRAMEWORK_RULES.md` 新增 R1.1.1（两类含臂名文件怎么分、
   换臂四步）+ 检查清单第 12 条 + 反例 2 条；`HANDBOOK.md` 新增 3.6.1
   与症状表 2 行。

4. **顺带修掉的真 bug**（都是这次改动带出来、被 pyflakes + 真跑抓住的）：
   - `convert_flexiv_traj.py` / `rdk_drag_bridge.py` 用了 `os` 但没 import
     → `--help` 直接 NameError；
   - `check_arm_prefixes.py` 第一版正则用 `\b` 收尾，而关节名是
     `Rizon4-063989_joint1`（`_` 属于 \w，`\b` 不成立）→ SRDF 里 24 处
     硬编码**一处都没报**，还打印 OK。已加负向测试钉住；
   - 删掉若干死代码/死 import（`pos_line`/`flat`/`names`、`IfCondition` 等）。

## 验收（都真跑过）

- `python3 -m pyflakes <全部改过的 py>` → 干净
- 逐包 pytest：233 + 69 + 78 + 24 + 236 = **640 passed**
- `env -u ROBOT_SN python3 scripts/check_arm_prefixes.py` → OK（8 文件）
- 换成 SN=Rizon4-777001 的临时 site.yaml → 报出**8 个**文件不一致并给修法（退出码 1）
- 故意不给 SITE_* → 各 launch 的 `robot_sn` / `ee_frame` / `handeye_file`
  默认值为 `''`，不再悄悄指向上一台臂
- `ros2 launch ... --show-args` 对 stack/sim/ros2_control/mock_control/
  move_group/display/visual_servo **全部通过**
- `convert_flexiv_traj.py --help` 正常；拿 `xunhuan.traj` 真转 5 个路点，
  输出 `joint_prefix: "Rizon4-063989_"` 来自 site.yaml

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-24 09:18:44 +08:00
arm_dev a91fa93339 补齐最后三处英文提示：触觉 mock 后端、mock 驱动拒绝原因、merge 用法行 
上次中文化扫出来 8 处英文提示，其中 5 处是 weights.sh 的用法/命令示例（必须保留英文，
它们就是用户要敲的命令），剩下这 3 处是真正给人看的句子，一并改掉：

  tactile_node.py        "tactile mock backend" -> "触觉使用 mock 后端（假数据，不接真实传感器）"
  mock_arm_driver.py     "Reject: already executing" -> "拒绝：上一个目标还在执行"
  merge_handeye_poses.py "Usage: ..." -> "用法：..."

merge 用法行里的 <taught_poses.txt> <waypoints.yaml> 是真实文件名，必须留着 ——
只把 "Usage:" 换成"用法："，不把文件名换成中文描述。

验收：scripts/check_text_only.py 通过（零逻辑变化）；608 passed，与改动前一致。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-23 17:42:24 +08:00
arm_dev 806efe4df1 修掉两个"存在但跑不起来"的脚本：CRLF 行尾 + 新增 .gitattributes 统一为 LF 
症状（没有报错，只有"文件在、文档说能用、一跑就死"）
    $ bash scripts/run_hole_detect.sh --arm 89 --preview
    scripts/run_hole_detect.sh: 行 11: $'\r': 未找到命令
    scripts/run_hole_detect.sh: 第 12 行： set: pipefail: 无效的选项名
  另一处 $'\r': 未找到命令 来自 scripts/run_dual_gripper.sh（同样症状）。

根因
  这两个 .sh 是 100% CRLF 行尾。bash 会把行尾的 \r 当成标识符的一部分，
  于是 `case "$1" in\r`、`set -eo pipefail\r` 全部变成非法记号。
  而文档在五处告诉用户跑它：README.md、docs/WORKSPACE.md、docs/ARCHITECTURE.md、
  docs/SITE_CONFIG.md、docs/HOLE_DETECT.md（HOLE_DETECT.md 直接给了命令）。
  即"文档齐全、文件存在、命令一敲就死"，报错信息里的那个 \r 又完全看不出来。

为什么之前没人发现（这是本次真正的教训）
  bash -n 会漏报：对 run_dual_gripper.sh 它返回 OK，可实际执行立刻死在第 6 行。
  所以"静态检查通过"不能当成"脚本能用"。验脚本要么真跑 --help，要么用
  file/bat 看行尾。这条已写进 .gitattributes 的注释里。

改了什么
  1. scripts/run_hole_detect.sh、scripts/run_dual_gripper.sh 由 CRLF 改为 LF。
     去行尾符后与改前逐字节相同 —— 只动行尾，一个字符内容都没动。
     已验证：两个脚本 bash -n 通过，且 run_hole_detect.sh --help 能正常打印中文帮助。
  2. 新增 .gitattributes：
       * text=auto eol=lf      —— 本仓库自己的文件一律 LF
       /src/flexiv_*/** -text  —— 厂商上游代码内容与行尾都不动（R4.4）
       /thirdparty/** -text
       *.onnx/*.engine/*.trt 等二进制显式标 binary，避免被当成文本转换
  3. 顺带把本仓库其余 19 个仍是 CRLF 的文件（.py 9 个、.yaml 2 个、.launch.py 2 个、
     .msg 5 个、.srv 1 个）统一为 LF。这些文件在 Python/YAML 下本来能正常读，
     所以此前没有症状；但同一仓库混着两种行尾，下次再有一个 .sh 中招就是必然。
     已核对：去掉行尾符后与 HEAD 逐字节相同 —— 内容零变化。

验收
  21 个文件：git diff --ignore-cr-at-eol -w 只列出 .gitattributes（零内容变化）
  scripts/*.sh scripts/lib/*.sh：bash -n 失败数 0（改前是 2）
  单测：608 passed，与改动前一致

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-23 17:41:06 +08:00
arm_dev 72353f3773 注释与提示信息全面中文化：源码 66 个 .py + 脚本/配置 45 个文件 
背景：现场读代码的人只读中文。此前代码里的 docstring 是英文、行内注释是中文，
一半英文一半中文反而更难看懂 —— 新手打开一个 .py 不知道这个模块为什么存在。

范围（本仓库自己的代码，厂商上游不动）
  src/arm_application/**   37 个文件：servo_node / perception_node / handeye_* / dh_pgea /
                           yolo_detector / kalman_filter / goto_ee_plane / dual_gripper …
  src/arm_interfaces/**    11 个文件：paths / manifest / loader / config_guard / errors …
  src/arm_control/**        5 个文件
  src/arm_bringup/**        3 个 launch
  scripts/**                6 个 .py + 29 个 .sh（scripts/ 是"唯一操作入口"，用户屏幕上
                           看到的就是这些提示，所以提示信息也一并中文化）
  config/ handeye/ devices/ src/arm_*/config/   17 个 .yaml/.xml/.xacro/.cfg

口径（写进 docs/FRAMEWORK_RULES.md 新增的 R6.5，作为长期约束）
  注释、docstring、print/日志/异常里给人看的句子 = 中文；
  标识符、API 名、话题名、参数名、字段名、命令名 = 保留英文原文（用 `` `` 包起来）；
  单位、十六进制、协议报文、CRC 值、命令示例 = 原样保留；
  src/flexiv_*/ = 厂商上游代码，不许改也不许翻译（R4.4）。
  翻译保原意与原有详细程度：那些"为什么不能用另一种做法""踩过什么坑"的说明
  全部完整保留 —— 它们才是这份代码里最贵的部分。

新增 scripts/check_text_only.py：只改文字时的自证工具
  人工 review 靠不住（115 个文件、3000 多行 diff）。这个脚本把改动前后的源码解析成
  语法树，删掉 docstring、抹平字符串常量、把 f-string 只留"插值了几次 + 插值是什么"，
  再比对：完全相同 = 改动范围内没有逻辑变化。
  留了一个口子：f-string 的插值按内容排序后再比 —— 因为中文语序常常要和英文反着来
  （f"on {port} read {idx} failed" → f"在 {port} 上读 {idx} 失败"），只换显示顺序不该判失败；
  但多插一个、少插一个、换掉被插入的表达式，立刻会报出来。
  本次 66 个 .py 全部通过该闸门。

验收
  改动的 66 个 .py：scripts/check_text_only.py 全部通过（零逻辑变化）
  45 个非 .py 文件：去注释后与 HEAD 逐字节相同（零配置变化）
  docstring 总数：没有一个文件减少（不存在"翻译时顺手删了说明"）
  单测：arm_application 233 / arm_driver_flexiv 69 / arm_interfaces 46 /
        arm_kinematics 24 / arm_sim_gazebo 236 = 608 passed，与改动前一致
  全部 .sh：bash -n 通过；并额外实际执行了 --help 验证（见下一个提交：
        bash -n 对 CRLF 脚本会漏报，只有真跑才暴露）

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-23 17:40:55 +08:00
arm_dev d32e6ae53f P5c-6 场景物料落地 + Gazebo 中文手册：工件/通止规模型、场景校验、两处静默失效修复 
一、场景物料（新增）
  devices/sim/gazebo/models/workpiece/   带三个孔的铝板。碰撞体是"带方孔的平板"，
    视觉额外加两个 φ14/φ7 亮环 —— 因为真机的 HoughCircles 就是靠这两个亮环找孔，
    只按碰撞体建视觉会让"孔检测"在仿真里永远失败，而那看起来像算法问题。
  devices/sim/gazebo/models/gauge/       通止规：通端/套环/握柄/止端四段，各段异色
    便于肉眼判断方向。接触刚度刻意比台面软 —— 位置控制器会"刚性压进去"，
    用默认刚度会被弹飞（注释里写了原因，不是随手抄的参数）。
  devices/sim/gazebo/models/gauge_stand/ 规座（static）。规直接站在台面上会立刻倒，
    加个方孔底座把它立住。
  三个模型都是 model.sdf + model.config，原点在**底面中心**，单位米。

二、场景配置与校验（新增）
  config/scene.yaml     物体不再写死在 world 里，改为 scene.yaml + 启动时动态 spawn。
    理由：world 是"环境"（地面/台面/相机/系统插件），场景是"这一批活做什么"。
    动 world 的风险面太大 —— 它只要丢一个系统声明，所有模型都 spawn 不进去（见旧坑 2）。
    含 operating（相机到工件的距离等作业条件）与 gates_px（像素门槛）。
  sim_scene.py          摆放校验：从 SDF **逐碰撞体**解析 AABB（不抄尺寸，避免漂移），
    检查原点在底面 / 不穿台面 / 不出界 / 物体之间不嵌入。
    重叠判定必须逐碰撞体三维判，不能拿总包围盒相交 ——
    正常装配里本来就有嵌套（规立在规座方孔里），粗判会误报，
    而误报的后果是人把检查整个关掉，之后真重叠也抓不到。
    另有成像几何：把亮环/孔间距按相机距离换算成像素，与门槛比对。
  scripts/check_sim_scene.py  验收工具（退出码可用）：摆放 + 门槛漂移 + 成像几何 +
    悬停高度 vs 工作空间 + 手外相机是否**完整**看得见工件 + Gazebo 实际位姿。

三、修掉两处静默失效（都是"看起来一切正常"）
  1) parse_spawned_poses 一直是**死代码**：它按 "x: N / y: N / z: N" 解析，
     而 Fortress 实际输出是方括号两行（XYZ / RPY）。对不上 → 永远返回空 →
     调用方按设计"降级成跳过位姿核对" → 位姿检查**从来没跑过**，
     而日志只说"跳过"，看起来像正常降级。
     现在两种格式都支持，并用真实抓下来的输出样本做回归测试。
     教训：宽容降级会把"没检查"伪装成"检查通过"。
  2) stop_sim_gz.sh 的模式表里漏了 robot_state_publisher（而注释里写着它有覆盖）：
     脚本报"已停止"，它却还在发上一份 /robot_description 与 TF，
     下一次启动就会"改了描述却不生效"。
     顺带修掉同源的两个问题：awk 用 -v 传模式导致它匹配到自己、每次复查都多报
     一个空命令行的幽灵 PID；以及"杀的时候"和"复查的时候"两份扫描实现会各自漂移。
     现在共用同一个 scan_pids()，模式改用环境变量传递，并在杀完之后**再扫一遍**：
     有残留就报出来并非零退出 —— 下次再有漏项，不再静默。
     实测：--list 列出全套 9 个进程；停止后 rc=0 且 pgrep 干净。

四、相机：D405 分辨率对齐真机
  仿真的 D405 此前渲染 640x480，而真机跑 848x480（fx 337 而非 447）。后果是
  58mm 的两孔间距成像只剩 85px，低于 hole_distance_min=90 ——
  孔检测在仿真里根本不可能通过，而现象看起来像"算法不行"。
  已把 xacro 与 cameras.yaml 一起改成 848x480，并把启动时的比对从"只比视场"
  扩成"视场 + 图幅"（sim_cameras.check_camera_consistency），
  不一致时说明它对像素门槛的影响。

五、文档
  devices/sim/gazebo/README.md 重写为中文手册：使用方法 / 建模要求 / 导入格式 /
    配置方式（含"改哪里才真的生效"的接线表）/ 11 条实测坑（每条都有"怎么发现"）。
  manifest.yaml 的进度、assets、description、坑清单与本轮状态对齐。
  scripts/README.md 补两个验收工具与停止脚本；根 README 补仿真入口与手册链接。
  cameras.yaml 里一处过期的函数名（check_fov_consistency）修正。

六、测试
  新增 test_sim_scene.py（79 条，此前 sim_scene.py 完全没有单测 —— 这正是
    位姿解析死掉却无人发现的原因）与 test_check_sim_scene.py（21 条），
  含三条回归：world_boxes 的偏移碰撞体不能被对称化放大（假重叠）、
  center_bore 不能被 _bore 后缀吃掉、Fortress 位姿输出格式。
  全量：src/arm_sim_gazebo + arm_interfaces + arm_application 共 515 通过。

同时附上 config/site.example.yaml 的重新生成（此前 site.yaml 的注释改动没同步，
它的 parity 测试是红的）。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-23 17:13:00 +08:00
arm_dev 47ad9d9a8b P5c-4 相机出图联调：桥接 d405/d435 到 ROS，并修掉两处静默的几何错误 
相机链路（devices/sim/gazebo/config/cameras.yaml 是唯一真相）
  - sim_cameras.py        纯逻辑：话题映射 / 深度换算 / 内参 / 视场一致性比对
  - sim_camera_adapter.py 改光学系 frame_id、32FC1 米 → 16UC1 毫米、覆盖内参
  - gazebo_sim.launch.py  桥接 + 适配器 + 世界相机的静态 TF（位姿从 world 解析）

本轮修掉两个**静默**的几何错误（都能出图、都能查到 TF，但点位是错的）

  1. gz 发的 camera_info 是错的：恒为 fx=fy=277, cx=160, cy=120
     （等于它的默认 60° 视场 + 半分辨率主点），而渲染用的是配置的 87° 视场。
     照抄它做三维反投影，点会偏半米量级；单目预览完全正常。
     用已知地面平面做最小二乘反解，得 fy=337.2 / cy=239.5，与
     640/(2·tan(87°/2))=337.2、480/2=240 吻合（残差中位 0.2mm）。
     改为由 sim_cameras.intrinsics() 按 cameras.yaml 的视场重算并覆盖。
     代价：cameras.yaml 的 horizontal_fov 必须与 SDF 一致，启动时自动比对告警。

  2. assembly.world 里 D435 的 rpy 写成 (0, 50°, 180°)，
     而 URDF 相机的视线是**本体 X 轴**、rpy 复合顺序又是 Rz·Ry·Rx，
     于是"先俯 50° 再偏航 180°"把视线翻到了背面：相机背对台面、只看地面。
     它不报错，而且几何自洽（点确实落在真实地面上），只查数值发现不了。
     改为 (0, 50°, 0)，并加回归测试锁住。

新增验收工具 + 测试
  - scripts/check_sim_cameras.py  反投影深度、要求命中地面/台面才算通过。
    "有图像"不是验收标准；实测 d435 台面 11.9%/地面 75.3%、d405 台面 37.8%。
  - 97 项单测（新增 sim_cameras 22 项、sim_site 16 项）

顺带修掉一处"改了配置静默无效"
  - sim.world 此前硬编码在 robot_description._WORLD_REL，而 site.yaml 与
    manifest.yaml 都宣称改它就生效。现在真的读了：
    优先级 --world > site.yaml:sim.world > 内置默认（相对路径按仓库根解析）。
  - physics_enable / joint_prefix 仍未接线，但若其值与实际状态冲突，
    启动时会告警（sim_site.unwired_warnings），不再静默忽略。

文档
  - devices/sim/gazebo/README.md 重写：原文还写着"仿真不是 Gazebo"、
    相机插件用 libgazebo_ros_camera.so，与实现早已不符。现分三部分：
    哪个"仿真"是真的 / 现状与缺什么 / 五条静默失效的坑及怎么验。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-23 15:19:16 +08:00
arm_dev 01940f54e7 P5c-3 仿真启动器跑通：Gazebo + spawn + 两个控制器 active 
端到端验收（headless，本机无显示器）：
    ign 加载 Physics/UserCommands/SceneBroadcaster/Sensors + gz_ros2_control
    机械臂 spawn 进 assembly 世界，7 个 sim_joint 全在 /joint_states
    joint_state_broadcaster 与 rizon_arm_controller 双双 active
    world → sim_tcp 可查，且末端位姿 3 秒内不变（重力下站住）
    网格解析报错 0 条

新增：
  scripts/run_sim_gz.sh                  此前**不存在**，却被 install_sim_env.sh
                                         与 build_sim.sh 的提示语引用
  arm_sim_gazebo/robot_description.py    展开 + 归一化，launch 与 CLI 共用一份
  arm_sim_gazebo/gazebo_sim_launcher.py  薄壳：准备描述后转发给 launch 文件
  launch/gazebo_sim.launch.py            起 gz → 发归一化 URDF → spawn → 拉控制器
  test/test_robot_description.py         含"仓库里这份 world 必须过守卫"的测试

接线过程中实测踩到并修掉的三个坑，共同特征是**每一步看起来都成功**：

1) urdf_normalize 在 Python 路径下静默失效（我自己引入的，最严重）
   xacro 的输出格式在不同环境里不一样：真机环境的 CLI 缩进成多行，而仿真环境
   走 xacro.process_file().toxml() 时全挤在一行。归一化的正则要求标签之间必须有
   \n，于是**仿真路径下它什么都没做**（报告"包裹 0 处"），而 CLI 路径下正常 ——
   之前那次"已修好"的验证走的就是 CLI，所以看起来过了。
   后果是 Gazebo 会丢掉整条机械臂，正是这个归一化本来要防的事。
   已改成对空白格式零假设，并加回归测试锁住。

2) world 里声明了 <plugin> 会把默认系统挤掉
   只要 world 声明任何一个 <plugin>，Gazebo 就不再加载 server.config 的
   Physics/UserCommands/SceneBroadcaster。缺 UserCommands →
   /world/<名>/create 服务不存在 → ros_gz_sim create 调服务超时后回退发 topic、
   没人收 → **模型从未进入 Gazebo**，而 create 节点仍打印
   "OK creation of entity"，控制器则永远卡在 "waiting for service"。
   已在这三个系统在 assembly.world 里显式声明，并加纯文本守卫
   check_base_plugins()，让"加了插件忘了补基础系统"在启动前就被指出。

3) gz 的插件与资源搜索路径缺 $CONDA_PREFIX/lib
   gz_ros2_control 报 "Failed to load system plugin
   [libgz_ros2_control-system.so] : couldn't find shared library"，而 ldd 全齐、
   库就在 $CONDA_PREFIX/lib 下。原因是 gz 的 SystemLoader 先在搜索路径里找文件，
   找不到就直接放弃，不去 dlopen 裸文件名（所以 conda 二进制的 RPATH 兜不住）；
   而 ros_gz_sim 只把 LD_LIBRARY_PATH 拼进搜索路径，conda 激活并不往那里加。
   同一原因导致 mesh 的 model:// 也解析不了（视觉报错很吵，但更要紧的是
   **碰撞网格也加载不出来**，会让后续装配的接触判据失效）。
   由于 gz_sim.launch.py 用 `from os import environ` 在生成 launch 描述时就读
   进程环境，这些变量**必须在 ros2 launch 之前**设好，因此放在 sim_env.sh ——
   在 launch 文件里用 SetEnvironmentVariable 补是无效的，会被它自己算的那份
   字典覆盖。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-23 14:48:16 +08:00
arm_dev d93dab31c9 P4d：文档同步 —— 修掉 P3 手眼路径迁移后遗留的过期引用，并指向新的 weights 工具 
P3 把 handeye 相关文件从 src/arm_application/config/ 迁到了仓库根的 handeye/，
但文档还写着老路径。这类"代码改了、文档没跟"的偏差最麻烦：新人照着文档敲
命令会直接报文件不存在，然后开始怀疑人生。

同步内容
- docs/HANDEYE.md / WORKSPACE.md / SITE_CONFIG.md / ARCHITECTURE.md：
  手眼结果与示教点位改指 handeye/results|poses/<臂号>_<模式>.yaml，
  临时目录改指 handeye/tmp/<臂号>/，并补上 --mode / --points / --auto-solve。
- docs/INTERFACES.md / TRACKING.md / docs/HOLE_DETECT.md / README.md：
  权重那一行从 export_yolo_trt.sh 改为 weights.sh，并注明前者已是兼容转发壳。
- docs/HOLE_DETECT.md：hole_weights / workpiece_weights 的实际取值改为
  models/hole_insert/detect_best_1.onnx（原文档写的是不存在的 best.pt）。
- scripts/merge_handeye_poses.py：只更新文件头注释里的示例路径。

多处改为指向 models/README.md 与 handeye/README.md，避免同一套规则在
七八个文件里各写一遍、然后各自漂移。

验证：rg 扫 docs/ README.md，已无 handeye_poses_/handeye_result_/
/tmp/handeye 之类过期路径残留。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-23 13:52:28 +08:00
arm_dev a89250d05d P5c-1：把 Gazebo 仿真环境真正装起来（独立 conda 环境），并固化安装/构建流程 
在此之前，仓库里所有 Gazebo 相关的东西都是"声明"而非"事实"：
arm.gazebo.xacro 零引用、stack.launch.py 的 isaac 分支只打印日志、
没有 world 文件、devices/sim/gazebo 下的目录全是空占位。
更关键的是：**这台机器上根本没装 Gazebo**，而 ROS 在 conda 里，没有 /opt/ros，
apt 的 ros-humble-gazebo-* 装了也不会被 conda 的 ROS 认到。

环境（与真机环境物理隔离）
- 新建 conda 环境 ros_gz_sim，**不碰能跑真机的 ros_flexiv**。
  仿真要往环境里塞 Gazebo 及 protobuf/ignition/渲染一整条链，
  和真机环境混装随时可能把它弄坏，代价远大于仿真带来的便利。
- 频道组合照抄 ros_flexiv 的安装记录（robostack-staging + conda-forge），
  那是本机已经证明可用的搭配。

两个实测踩到的坑（都写进了脚本注释，避免下次重踩）
1. empy 版本：conda 默认给 empy 4.x，而 Humble 的 rosidl_adapter 用的是 3.x 的
   API。症状是构建自定义消息包时报 `_interpreter.shutdown()` 的 AttributeError，
   报错点在 rosidl_adapter 内部，完全看不出跟 empy 有关。必须钉 empy=3.3.4。
2. conda 激活是**堆叠**的：同一 shell 里从 ros_gz_sim 切到 ros_flexiv 后，
   `which python` 指向 ros_flexiv，但 `python -m pip` 却解析到 ros_gz_sim 的 pip，
   导致 colcon --symlink-install 报 "option --editable not recognized"。
   这个报错和真实原因毫无关系，极易误判成"环境被搞坏了"。
   现在 scripts/lib/conda_switch.sh 会在切换前退到 base，两个 env 脚本共用。

仿真用独立构建产物
- build_sim/ + install_sim/（scripts/build_sim.sh）。工作区只有一份源码，
  若仿真也写 install/，就会覆盖真机的构建产物。
- 排除 11 个真机专属包（flexiv_hardware 需要 Flexiv RDK C++ SDK，根本装不上；
  另有真机驱动/GPIO/MoveIt 配置/真机 bringup），每个都在脚本里写了理由。

已验证（不是只看退出码）
- Gazebo Fortress 6.16 无头启动正常，物理初始化完成
- /clock 桥接到 ROS 成功收到仿真时间；ros_gz_sim create 成功往世界里建物
- 真机构建 18 包通过、233 项测试通过，build/ install/ 时间戳未变（没被覆盖）
- 仿真侧 7 包构建通过；两环境互切后各自都能正常构建

注：Humble 配的是 Gazebo Fortress（ignition-gazebo6，命令行 `ign gazebo`），
不是现代的 gz-sim —— 后者要 libprotobuf>=6.31，与 RoboStack Humble 钉住的
5.29.3 解不开依赖。Fortress 属于新 Gazebo 家族（非已 EOL 的 Classic），
且是 Humble 的官方配对版本。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-23 13:52:04 +08:00
arm_dev d289168dd0 P4s：模型审计 —— 移出零引用模型，修掉代码里三处悬空 best.pt 
先回答"这些模型到底有没有人用"，用全仓库引用扫描判定，不靠猜：

  在用   yolo/detect_best_0.onnx + .engine   ← paths.yolo_weights
  在用   hole_insert/detect_best_1.onnx      ← hole_detect.weights / workpiece_weights
  零引用 detect_hc90（pt/onnx/engine）       ← 只剩注释里的历史说明
  零引用 detect_yolo26_gongjian.pt
  零引用 detect_best（onnx/engine）          ← 仅代码兜底候选，而那个候选是 .pt，不存在

所以 detect_hc90 不需要修复，是不用的东西：连同另两个一起移出仓库。
注意**二进制权重被 gitignore**，删掉就找不回来了，因此是移出到
~/ros2-models-unused-20260923/ 而非 rm。搬回 models/ 即可被 list 重新发现。

顺手挖出并修掉三处悬空引用（和之前 site.yaml 里那个 best.pt 同一类问题）：
- hole_detector.weights_from_site：兜底路径写死 models/hole_insert/best.pt（不存在）
- hole_detector._default_model_path：三个候选路径**全都不存在**，函数却
  `return candidates[0]`，于是永远返回不存在的 best.pt；报错路径看着很合理，
  极易被误判成"文件被误删"。现改为以 site.yaml 为准，再退到规范模型。
- config/hole_insert.yaml 顶部注释同样写的是 best.pt

新增 test_hole_detector.py（8 项）锁住这个回归。测试刻意**不断言文件存在**
——二进制不进 git，新克隆的仓库里 models/ 是空的——只断言解析结果指向规范模型名。

体检从 4 处问题降到 0：bash scripts/weights.sh doctor --check-engines → "没有发现问题"

测试 233 项通过；18 个包构建通过。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-23 13:08:11 +08:00
arm_dev 2b77ec127d P4：权重/标签模块 —— 旁挂标签文件 + PT→ONNX→TRT 转换工具 + 归档归位 
痛点：TensorRT 10.13 的 Python API 没有元数据读写，engine 一转就把类名丢了；
推理侧只能退化成 str(cid)（"0"、"1"），界面上看不出是什么类，属于静默失效。
同时旧的 export_yolo_trt.sh 只能手工搬文件、手工改 site.yaml、标签无处安放。

标签子系统（model_labels.py）
- 旁挂标签文件 <模型名>.labels.yaml，放在权重旁边，文本、可手改、进 git
  （二进制权重不进 git，标签是配置所以进）
- 读取优先级：旁挂文件 > ONNX 元数据 > 模型元数据 > 占位符 class_N
  占位符是故意的：缺标签时要一眼看出来，而不是悄悄退回 cid
- 解析器容忍多种写法：dict / list / 逗号串 / 逐行文本 / Python repr 串

布局与转换（weights_layout.py + weights.py + weights.sh）
- models/<分组>/<模型名>.{pt,onnx,engine} + 同名 .labels.yaml
- convert：PT→ONNX→TensorRT，支持自定义名字、自动归位、固化标签
- staging/：非标准格式先进这里，转换后源文件归档到 staging/done/
- list / labels / doctor / show 四个子命令
- doctor --check-engines 能查出 engine 与 TensorRT 版本不匹配（反序列化返回空）

推理侧接入
- yolo_detector / onnx_workpiece / hole_detect_hough 统一走 read_labels()
- 画框标签不再硬编码 "gongjian"，改用实际类名

顺手修掉的真实问题
- setup.py 撞上断掉的符号链接会让整包构建失败，报错还指向 build/ 里的幽灵文件
  （源文件被挪走后 build/ 里留下的断链被 os.walk 列出来）。加 _existing() 过滤。
- P3 遗漏：site.yaml / export_site_env.py / run_handeye.sh / handeye_teach.py /
  handeye_calibrate.py 里的 handeye 工作目录仍是 /tmp/handeye_calib*，
  与已迁到 handeye/ 的其余路径不一致。统一到 handeye/tmp/<臂号>。
- site.yaml 的 hole_weights / hole_detect.weights 原指向不存在的 best.pt，
  改为实际存在的 detect_best_1.onnx；active.pt 符号链接已废弃并清理。
- weights.sh labels 原先不接受 "分组/模型名" 写法，而 list 输出正是这个形式，
  照着敲会报"找不到模型"。补上，并让报错直接给出可复制的全名。

测试：225 项通过（新增 test_model_labels.py / test_weights_layout.py）。
真实 ONNX→engine 端到端转换已验过。

Co-authored-by: Cursor <cursoragent@cursor.com>
 2026-09-23 12:39:18 +08:00
arm_dev adc72955c7 P3c：teach --auto-solve —— 采完自动 merge 并接着标定，收尾手眼手动闭环 
新增 teach --auto-solve：采完点按 q 后自动 merge、重启相机、接着 calibrate，
不再需要手敲第二、三条命令。

但只有 --ros（示教器）模式能真正全程跑通，这一点如实处理而非强行自动：
标定必须通过 run_real.sh 的控制器驱动机械臂走点位，而 --rdk 软拖拽要求
RDK 独占，两者无法同时存在。这是硬件约束，脚本绕不过去。
所以 --rdk --auto-solve 会照常自动 merge，然后打印明确的两步指令，
并提示想要一条命令就改用示教器 Free Drive 模式。
硬跑一个必然失败的 calibrate 只会让人以为标定坏了。

顺带修正一处不可达代码：_need_camera / _need_files / _need_robot 内部用的是
exit（终止整个脚本）而非 return，所以 `if ! _need_camera; then echo ERROR; fi`
里的分支永远不会执行。改为直接调用，由它们自己打印原因并退出。

usage 里补上 --auto-solve 及其限制说明；handeye/README.md 第 5 节补
"一条命令跑完"小节，写明为什么 RDK 模式做不到。
usage() 的 sed 行号改为按首个非注释行自动计算，避免以后加注释又要同步。

测试：224 passed
 2026-09-23 11:55:08 +08:00
arm_dev e4f513392d P3b：手眼标定支持 --mode 模式选择与 --points 目标点数 
--mode eye_in_hand|eye_to_hand
- 切换读写的文件为 <臂号>_<模式>.yaml，两种模式的采点与结果互不覆盖、可共存
- 臂号从 Flexiv 序列号后两位取（Rizon4-063989 → 89），不做硬编码映射
- 非法模式立即报错退出。不静默退回默认值 —— 那会造成"以为标的是
  eye-to-hand、其实算的是 eye-in-hand"，是这类工具最难排查的错误
- 求解侧本来就支持（calibrate_hand_eye(eye_to_hand=...) 对 gripper2base 求逆），
  这次把入口补上，让模式不再只存在于参数文件里

--points N（仅 teach）
- teach 新增 target_points 参数并实现计数：显示 [3/12] ... 还差 9 个点，
  采够时提示可以收工
- 刻意不强制关窗：实际采点常出现"某个角度还没覆盖"，强制退出要重开

usage 重写：路径改为 handeye/，补上全局选项与组合示例；
usage() 的 sed 行号随之同步（原 2,18p 已不覆盖新头部）。

handeye/README.md 补第 5 节：模式切换与点数的完整用法，
并说明为什么非法模式要报错而不是兜底。

测试：224 passed
 2026-09-23 11:48:11 +08:00
arm_dev a3a589b9e3 P3a：手眼标定集中到 handeye/，修复三套板尺寸矛盾与从未生效的稳定性参数 
新建 handeye/ 专用文件夹（用户要求：专用文件夹 + 使用说明）
- handeye/README.md：从小白视角讲清楚两种模式怎么选、板尺寸怎么量、
  完整流程、出问题先看哪里。以前这些知识散在 docs/ 和代码注释里。
- 结构：calibrate.yaml（参数）/ poses/（采点输入）/ results/（结果输出）/ tmp/（临时，不进 git）
- 文件用 git mv 迁移，历史保留

命名约定改为 <臂号>_<模式>.yaml
- 如 89_eye_in_hand.yaml、91_eye_to_hand.yaml
- 臂号 = Flexiv 序列号后两位；模式 = eye_in_hand | eye_to_hand
- 换模式 = 改 site.yaml 里 paths.handeye_file 一行，不动代码
- 迁移只需改 site.yaml（4 个 launch + servo_node 都经 paths 读取，一行没改）

修复：三套互相矛盾的标定板尺寸（真实 bug）
同一个"板子多大"分散在三处，且值各不相同：
  handeye_calibrate.py 默认 9x6 / 0.025
  handeye/calibrate.yaml   11x16 / 0.011
  site.yaml + 结果文件头     8x11 / 0.015   ← 实测的真实板子
谁生效取决于覆盖顺序。症状是"标定流程跑得很顺、不报错，但结果明显不对"，
极难排查。已全部统一为 8x11 / 0.015，README 里写明换板必须三处同改。

修复：site.yaml 里五项稳定性配置从未生效
run_handeye.sh 一直在传 settle_qd_max / settle_stable_sec / settle_timeout_sec /
pin_holds / pin_hold_sec，但 handeye_calibrate.py 从未声明这些参数 ——
ROS 2 会静默忽略未声明的覆盖参数，所以"等机械臂停稳再拍照"这件事其实没实现，
实际只有一次固定 settle_sec。现已声明并实现：
- _wait_settled()：用关节速度 |qd|_max 判定"真的停了"，比固定 sleep 可靠
  （负载/姿态不同刹车距离差别很大；等太短会在臂还动时拍照导致角点抖动）
- _pin_hold()：静止后再保持几拍，抑制到位后的微小回弹

新增：自动标定进度条
一条可视化进度条（[ 4/12] [████░░░░]  33.3%），无人值守的长流程能一眼看出还剩多久。

清理重复文件（内容逐字节比对确认后删除）
- config/handeye_result.yaml 与 _89 逐字节相同 → 删
- config/handeye_poses.yaml 与 _89 逐字节相同 → 删
迁移后 src/arm_application/config/ 下已无 handeye 文件。

测试：224 passed（原 198，新增 26）
新增 src/arm_application/test/test_handeye_lib.py —— 手眼模块此前零测试。
关键用例是合成数据往返：用人为设定的 X_true 反推出每个视图的
(gripper→base, target→cam)，再让求解器还原。坐标链方向/求逆/转置
只要有一处写错就必然失败。
- 真值恢复（旋转+平移，atol 1e-6）
- 单独验证平移精确（旋转对而平移错是最易漏的一类 bug）
- 结果必须是 det=+1 的正交阵（排除镜像解）
- 退化输入（全同位姿）不得悄悄给出"看起来能用"的结果
- 稳定性判据：窗口未满不判稳、丢帧后重新计数、抖动超阈不判稳
- 写盘再读回不漂移
 2026-09-23 11:46:03 +08:00
arm_dev 52c108de07 P2：修复 run_all.sh 缺失，消除等待超时陷阱，标注无消费者的配置 
修复：run_all.sh 不存在，但被三处依赖
- docs/HOLE_DETECT.md 有 4 处用法示例；
- pipeline.launch.py 文件头写着"相机 / 触觉由 scripts/run_all.sh 负责拉起一次"；
- run_pipeline.sh 唯一职责就是 exec 它。

也就是说文档在教用户跑一个不存在的脚本，而 run_pipeline.sh 执行必然失败。
按 pipeline.launch.py 的实际参数（skip_stage1/2/3、target_hole、insert_depth_mm、
screw_pitch_mm、preview、resnap）重建：先确认控制器 ACTIVE，再拉起相机与触觉
（都已就绪则跳过），最后 exec pipeline.launch.py。无硬件时会明确报错退出。

修复：判活循环反复撞超时，脚本看起来像卡死
服务/话题不存在时，`ros2 service call` / `ros2 topic echo` 每次都要耗满 timeout
才返回。原写法 30 次循环最坏等 165s（实测无 ROS 时白等 63s）。改成先
`ros2 service list` / `topic list` 探测，再决定要不要 call/echo。
- run_stage2_locate.sh、run_stage3_search.sh 同步修复（165s → ~0s）
- run_all.sh 一开始就按正确顺序写
- run_handeye.sh 原本就是对的（这次是向它对齐）

标注：site.yaml 的 sim 段没有任何消费者
它声明 platform: gazebo，但 Gazebo 尚未接线，改它不会有任何效果。
加注释说明真实现状，避免用户以为改了就生效。

澄清：camera 与 cameras 不是重复键，两者都在读
- camera（单数）= 当前激活相机的参数，被各 launch 与节点读
- cameras（复数）= 相机目录（型号/序列号），被 export_site_env.py 读
命名容易混淆，但删任一个都会坏的。

保留：fetch_isaac_flexiv.sh
一度按"0 引用"删除，随后发现 thirdparty/ 里确实存在 isaac_sim_ws 与
flexiv_sim_plugin，说明这条路线被真实使用过；且该脚本还负责 clone
flexiv_rdk（核心依赖）。已恢复，并在 scripts/README.md 标为"搁置未用"。

docs/scripts/README.md 补上 run_all.sh、rdk_drag_bridge.py、fetch_isaac_flexiv.sh，
并新增"排查脚本卡住时的常识"一节记录判活顺序。

测试：198 passed
 2026-09-23 11:25:19 +08:00
arm_dev 883ed6b0b9 P1：设备契约层收尾 + Flexiv 驱动适配器 + 触觉四路数据打通 
新增包
- arm_kinematics：从 arm_application 提取几何雅可比 + DLS 逆解（纯 numpy）。
  它被应用层和驱动层共用，留在应用层会让驱动反向依赖应用层。
  arm_application/geom_ik.py 改为 re-export shim，现有 import 一行未改。
- arm_driver_flexiv：非夕驱动适配器。只补 manifest 声明而现有节点缺失的接口
  （/home /enable /clear_fault /switch_tool /soft_drag /compliant_descent），
  已有能力不重复实现。RDK 访问经 rdk_py310 下的长驻桥，本包不 import flexivrdk。

新接口
- arm_msgs/SwitchTool.srv、arm_msgs/CompliantDescent.action
- 合并 capabilities 里语义重复的 set_tool / switch_tool

修复（都是只在真机上暴露、且难以定位的问题）
- rdk_client 会永久挂死：select 的"可读"不等于"有完整一行"，readline 遇到
  半行 JSON 会一直阻塞等换行符，超时机制完全失效。改用 os.read + 自己做行缓冲。
- CompliantDescent 行程少一步：descended + step > max 在浮点累加下会提前跳出，
  永远到不了标称行程。改用整数步数计数。
- CompliantDescentRunner 的 TF frame 退化成 _base_link：没继承节点已解析的 SN。
- resolve_orisys_config 仍指向旧路径；load_orisys_from_site 读的是旧键 config。

触觉四路数据打通
- 深度图 / 力矢量场原先被 tactile_worker 有意丢弃（注释写"图像不过队列"），
  从未发布到 ROS。新增 image_utils（数组→Image，编码自动判定）、独立的图像
  队列（maxsize=1 满则丢旧）与 /tactile/<side>/{image,vector}。
  默认关闭（tactile.image_hz=0），开启也不影响三力的 30fps 时序。
- mock 后端也会发图像，无硬件即可验证整条发布链路。

配置
- site.yaml 新增 tactile.image_hz；移除与 model 重复的旧键 tactile.config
- 型号配置从 src/arm_application/config/orisys/ 迁到
  devices/sensors/orisys/models/dd03/（随 SDK 一起放）

测试：198 个（原 139）
- arm_kinematics 24（雅可比/逆解的解析算例与不变量）
- arm_driver_flexiv 69（下压状态机 34 + RDK 协议层 35）
- arm_application 59（图像打包 36 + 矢量场探测 23）
 2026-09-23 11:17:12 +08:00
arm_dev 6edb8d39ab chore: 框架科学优化前的完整基线 
在开始'设备契约层 + 目录重构 + 通止规装配'改造之前，先钉住当前可运行状态，
使后续任何删除/重构都可回退。

本基线包含：
- 现有 ROS 2 工作区全部源码（arm_application / arm_control / arm_bringup 等）
- 官方 flexiv_ros2 栈（含 flexiv_hardware / flexiv_controllers 等符号链接）
- 设备契约层 src/arm_interfaces（新增，46 项单测通过）
- devices/ 设备选型与品牌清单（新增）
- scripts/gen_site_example.py 与由它生成的 config/site.example.yaml

按 .gitignore 排除：build/ / install/ / log/ / config/site.yaml / 模型权重二进制。
 2026-09-23 10:53:06 +08:00