orisys/ros_contorl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

配置：消灭代码里的硬编码臂 SN，并给"换臂漏改"加一把尺子

Browse Source 
## 为什么

"设备 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>
This commit is contained in:
arm_dev
2026-09-24 09:18:44 +08:00
parent fac2d5384d
commit f5ed44a987
40 changed files with 1187 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/arm_interfaces/test/test_check_arm_prefixes.py
+135
View File
@@ -0,0 +1,135 @@
"""``scripts/check_arm_prefixes.py`` 的自证测试（R5.2）。
为什么这个检查器必须有测试
--------------------------
它是"换臂时防止漏改一级配置"的唯一守卫。**守卫自己失效过一次**：
第一个版本的正则写成 ``\\bRizon\\d+-\\d{6}\\b``，而 Flexiv 的关节名是
``Rizon4-063989_joint1`` —— ``_joint1`` 的下划线属于 ``\\w``，所以结尾的
``\\b`` 不成立，SRDF 里 24 处硬编码**一处都没报出来**，脚本还打印
"OK：8 个配置文件都指向 Rizon4-063989"。
守卫的漏洞和它要防的漏洞长得一模一样，所以这里逐条钉住：
* 挑得出 ``SN_joint1`` 这种**后缀带下划线**的形态（就是上面那个 bug）；
* 不会把 ``Rizon4-06398912`` 这种更长数字误判成长度正确的前缀；
* 混着两个 SN 的文件，只报**不属于当前臂**的那些，并带上行号；
* 读不出当前臂时**直接失败**，不输出"检查通过"。
"""
from __future__ import annotations
import importlib.util
from pathlib import Path
import pytest
_REPO = Path(__file__).resolve().parents[3]
_SCRIPT = _REPO / "scripts" / "check_arm_prefixes.py"
def _load():
"""按路径加载 ``check_arm_prefixes``（它在 scripts/ 下，不是可导入的包）。"""
if not _SCRIPT.is_file(): # pragma: no cover - 仓库被裁剪时的兜底
pytest.skip(f"找不到 {_SCRIPT}")
spec = importlib.util.spec_from_file_location("_check_arm_prefixes", _SCRIPT)
module = importlib.util.module_from_spec(spec)
assert spec and spec.loader
spec.loader.exec_module(module)
return module
@pytest.fixture(scope="module")
def mod():
return _load()
LEFT = "Rizon4-063989"
RIGHT = "Rizon4-063991"
class TestSnToken:
"""正则必须挑得出真实的关节名形态。"""
@pytest.mark.parametrize(
"text",
[
LEFT, # 裸 SN
f"{LEFT}_joint1", # ★ 就是踩过坑的形态
f"{LEFT}_base_link",
f"{LEFT}_flange",
f'joint_prefix: "{LEFT}_"',
f"- {LEFT}_joint7",
"Rizon10s-123456_joint3", # 别的型号
],
)
def test_matches_real_joint_names(self, mod, text: str):
found = mod._SN_TOKEN.findall(text)
assert found, f"应挑出 SN，但一个都没匹配到：{text!r}"
@pytest.mark.parametrize(
"text",
[
"Rizon4-0639891", # 多一位数字，不是合法的 6 位 SN 前缀
"Rizon4-06398", # 只有 5 位
"Rizon4_063989", # 下划线而不是连字符
"not a robot at all",
],
)
def test_rejects_non_sn_text(self, mod, text: str):
assert not mod._SN_TOKEN.findall(text), f"不该匹配：{text!r}"
class TestScan:
"""混着两台臂的 SN 时，只报不属于当前臂的那些。"""
def test_reports_only_other_arm(self, mod, tmp_path: Path):
f = tmp_path / "controllers.yaml"
f.write_text(
"\n".join(
[
f"# 站点机器人 {LEFT}",
"joints:",
f" - {LEFT}_joint1",
f" - {RIGHT}_joint2",
]
),
encoding="utf-8",
)
hits = mod._scan(f, want_sn=LEFT)
assert len(hits) == 1, f"只应报出 {RIGHT} 那一行，实际：{hits}"
assert hits[0].startswith("4:"), f"应带行号 4，实际：{hits[0]!r}"
assert RIGHT in hits[0]
def test_all_matching_is_clean(self, mod, tmp_path: Path):
f = tmp_path / "srdf.srdf"
f.write_text(f'<joint name="{LEFT}_joint1" value="0"/>\n', encoding="utf-8")
assert mod._scan(f, want_sn=LEFT) == []
def test_missing_file_is_reported_not_swallowed(self, mod, tmp_path: Path):
"""文件缺失也算不一致 —— 不能当成"没问题"跳过。"""
hits = mod._scan(tmp_path / "nope.yaml", want_sn=LEFT)
assert hits and "读不到文件" in hits[0]
class TestActivePrefixFailsLoudly:
"""读不出当前臂时必须失败，不能打印"检查通过"。"""
def test_missing_site_config_exits_nonzero(self, mod, monkeypatch, tmp_path: Path):
monkeypatch.setenv("SITE_CONFIG", str(tmp_path / "不存在.yaml"))
monkeypatch.delenv("ROBOT_SN", raising=False)
monkeypatch.delenv("ROBOT_ARM", raising=False)
with pytest.raises(SystemExit) as exc:
mod._active_prefix()
assert exc.value.code == 2, "缺配置应当是明确的失败退出码，不是 0"
def test_empty_sn_exits_nonzero(self, mod, monkeypatch, tmp_path: Path):
"""site.yaml 里 robot.sn 为空 → 报错，而不是兜底成某台臂。"""
site = tmp_path / "site.yaml"
site.write_text("robot:\n sn: ''\n robots: []\n", encoding="utf-8")
monkeypatch.setenv("SITE_CONFIG", str(site))
monkeypatch.delenv("ROBOT_SN", raising=False)
monkeypatch.delenv("ROBOT_ARM", raising=False)
with pytest.raises(SystemExit) as exc:
mod._active_prefix()
assert exc.value.code == 2
src/arm_interfaces/test/test_site_env.py
+289
View File
@@ -0,0 +1,289 @@
"""证明「换一份 site.yaml，导出的 SITE_* 里就不该残留任何本机站点值」。
这是 R1.1（禁止硬编码站点值）的机器化执行。与其用 grep 去数 ``Rizon4-063989``
出现了几次（数不清、还会误报注释和文档），不如直接问一个**更强**的问题：
给定一份完全不同的 site.yaml，``flatten()`` 导出的环境里
还会不会出现本机的 SN / IP / 相机序列号 / 用户路径？
只要有一处会，就说明那处的"默认值"其实是**写死的站点数据**。后果不是报错，
而是 site.yaml 一旦缺那个键，程序就**静默地去操作另一台机器**：
- ``SITE_ROBOT_SN`` 兜底成 ``Rizon4-063989`` → 配置漏了也照样连上，连的是谁看运气；
- ``SITE_D405_LEFT_SERIAL`` 兜底成某个真实序列号 → 换站点后悄悄打开别人的相机。
这类兜底比"没有默认值"危险得多（M1：不报错但结果是错的）。所以本测试的思路是
**用一份虚构站点的配置跑一遍，断言本机值一个都不许出现**。
真实工作区不存在时跳过（包可能被单独构建）。
"""
from __future__ import annotations
import sys
import pytest
from arm_interfaces import paths
# ---------------------------------------------------------------------------
# 被测模块在 scripts/lib/ 下（launch 文件也是把它加进 sys.path 再 import 的），
# 所以这里用同样的方式接进来。
# ---------------------------------------------------------------------------
_LIB = paths.ros2_root() / "scripts" / "lib"
if str(_LIB) not in sys.path:
sys.path.insert(0, str(_LIB))
pytestmark = pytest.mark.skipif(
not (_LIB / "export_site_env.py").is_file(),
reason="scripts/lib/export_site_env.py 不存在（包被单独构建），跳过",
)
export_site_env = pytest.importorskip(
"export_site_env", reason="需要 PyYAML 才能加载 site 配置"
)
# ---------------------------------------------------------------------------
# 本机（真实站点）的值 —— 这些**绝不允许**成为任何配置缺键时的兜底
# ---------------------------------------------------------------------------
LOCAL_SN_LEFT = "Rizon4-063989"
LOCAL_SN_RIGHT = "Rizon4-063991"
LOCAL_CAM_LEFT = "352122274408"
LOCAL_CAM_RIGHT = "260522274442"
LOCAL_IPS = ("192.168.2.101", "192.168.2.100", "192.168.2.10")
# 只放**设备身份**：SN、IP、相机序列号。不包含工作区绝对路径 ——
# `_root()` 派生出来的 `/home/<用户>/ros2/...` 是仓库内部默认值，
# 换站点换的也是仓库位置，不算站点数据（工具说的假错会让人不再信它，R5.3）。
LOCAL_VALUES = (LOCAL_SN_LEFT, LOCAL_SN_RIGHT, LOCAL_CAM_LEFT, LOCAL_CAM_RIGHT,
*LOCAL_IPS)
# ---------------------------------------------------------------------------
# 一份虚构站点的 site.yaml：SN / IP / 相机序列号全都不一样，
# 侧别与 --arm 别名走 robots[].arm 与 robots[].label，而不是 SN 里的数字。
# ---------------------------------------------------------------------------
FAKE_SITE = {
"robot": {
"sn": "Rizon4-777001",
"tool_name": "FakeToolA",
"robots": [
{
"sn": "Rizon4-777001",
"arm": "left",
"label": "左臂01",
"ip": "10.9.9.31",
"pc_ip": "10.9.9.30",
"iface": "eth9",
"camera": {"name": "cam_a", "serial": "99900001"},
"gripper": {"model": "FAKE-GRIP-A", "port": "/dev/ttyFAKE0"},
"named_poses_file": "/opt/fake/named_a.yaml",
},
{
"sn": "Rizon4-777002",
"arm": "right",
"label": "右臂02",
"ip": "10.9.9.41",
"pc_ip": "10.9.9.30",
"iface": "eth9",
"camera": {"name": "cam_b", "serial": "99900002"},
"gripper": {"model": "FAKE-GRIP-B", "port": "/dev/ttyFAKE1"},
"named_poses_file": "/opt/fake/named_b.yaml",
},
],
},
"paths": {"yolo_weights": "/opt/fake/weights.engine"},
"cameras": {
"d405_left": {"serial": "99900001"},
"d405_right": {"serial": "99900002"},
"d435": {"serial": "99900003"},
},
"handeye": {"mode": "eye_in_hand"},
}
def _flat(monkeypatch, sn: str | None = None, site: dict | None = None) -> dict:
"""用虚构站点配置跑一遍 flatten()，返回导出的环境字典。"""
monkeypatch.setenv("SITE_CONFIG", "/nonexistent/site.yaml") # 防止误读真配置
if sn is None:
monkeypatch.delenv("ROBOT_SN", raising=False)
monkeypatch.delenv("ROBOT_ARM", raising=False)
else:
monkeypatch.setenv("ROBOT_SN", sn)
return export_site_env.flatten(dict(site if site is not None else FAKE_SITE))
# 一份**最小**配置：只有 robots[].sn / arm，其余键一律不写。
# 这样所有 ``or <默认值>`` 的兜底分支都会被走到 —— 泄漏就藏在那些分支里。
# 注意它仍然要能跑完 flatten()，所以不能真的删到没法解析。
MINIMAL_SITE = {
"robot": {
"robots": [
{"sn": "Rizon4-777001", "arm": "left"},
{"sn": "Rizon4-777002", "arm": "right"},
]
},
}
class TestNoLocalValuesLeak:
"""换站点后，导出结果里不许出现本机的任何设备标识。"""
def test_flat_env_has_no_local_values(self, monkeypatch):
flat = _flat(monkeypatch)
leaked = {
key: value
for key, value in flat.items()
if any(token in str(value) for token in LOCAL_VALUES)
}
assert not leaked, (
"这些 SITE_* 在 site.yaml 缺键时兜底成了本机站点值，"
"会让程序静默操作另一台设备：\n"
+ "\n".join(f" {k} = {v!r}" for k, v in sorted(leaked.items()))
)
def test_flat_env_has_no_local_values_for_right_arm(self, monkeypatch):
flat = _flat(monkeypatch, sn="Rizon4-777002")
leaked = {
key: value
for key, value in flat.items()
if any(token in str(value) for token in LOCAL_VALUES)
}
assert not leaked, (
"切换到虚构站的右臂后仍有本机值残留：\n"
+ "\n".join(f" {k} = {v!r}" for k, v in sorted(leaked.items()))
)
def test_minimal_config_exercises_every_fallback(self, monkeypatch):
"""配置里只有 SN 和侧别时，兜底值也不许是本机设备值。
这条是上一条的加强版：完整配置会把 ``or <默认值>`` 短路掉，
所以泄漏只有用**最小配置**才暴露得出来。
"""
flat = _flat(monkeypatch, sn="Rizon4-777001", site=MINIMAL_SITE)
leaked = {
key: value
for key, value in flat.items()
if any(token in str(value) for token in LOCAL_VALUES)
}
assert not leaked, (
"最小配置（只给 SN/侧别）下，这些 SITE_* 兜底成了本机站点值：\n"
+ "\n".join(f" {k} = {v!r}" for k, v in sorted(leaked.items()))
)
def test_no_local_serial_fallback_without_cameras_section(self, monkeypatch):
"""``cameras:`` 整段缺失时，序列号必须为空，不能补一个真实序列号。"""
flat = _flat(monkeypatch, sn="Rizon4-777001", site=MINIMAL_SITE)
for key in ("SITE_D405_LEFT_SERIAL", "SITE_D405_RIGHT_SERIAL",
"SITE_D435_SERIAL"):
value = str(flat.get(key) or "")
assert value == "", (
f"{key} 应当是空（配置里没写），实际兜底成了 {value!r} —— "
"这会让程序悄悄打开别人的相机"
)
@pytest.mark.parametrize("builder", ["gripper_overrides", "perception_overrides",
"servo_overrides"])
def test_ros_param_dicts_have_no_local_values(self, monkeypatch, builder):
monkeypatch.setenv("SITE_CONFIG", "/nonexistent/site.yaml")
monkeypatch.delenv("ROBOT_SN", raising=False)
monkeypatch.delenv("ROBOT_ARM", raising=False)
params = getattr(export_site_env, builder)(dict(FAKE_SITE))
leaked = {
key: value
for key, value in params.items()
if any(token in str(value) for token in LOCAL_VALUES)
}
assert not leaked, (
f"{builder}() 返回的 ROS 参数里带上了本机站点值：\n"
+ "\n".join(f" {k} = {v!r}" for k, v in sorted(leaked.items()))
)
def test_active_arm_switches_camera_with_the_arm(self, monkeypatch):
"""换臂必须换相机序列号（这是 89/91 不能混用的核心）。"""
monkeypatch.setenv("SITE_CONFIG", "/nonexistent/site.yaml")
monkeypatch.setenv("ROBOT_SN", "Rizon4-777001")
left = export_site_env.flatten(dict(FAKE_SITE))
monkeypatch.setenv("ROBOT_SN", "Rizon4-777002")
right = export_site_env.flatten(dict(FAKE_SITE))
assert left["SITE_CAM_SERIAL"] == "99900001"
assert right["SITE_CAM_SERIAL"] == "99900002"
assert left["SITE_CAM_NAME"] != right["SITE_CAM_NAME"]
class TestArmAliasResolution:
"""--arm 的别名解析必须**来自 robots[]**，不能来自写死的 SN 表。"""
def test_resolves_by_side_word(self, monkeypatch):
monkeypatch.setenv("SITE_CONFIG", "/nonexistent/site.yaml")
assert export_site_env.normalize_robot_sn(dict(FAKE_SITE), "left") == "Rizon4-777001"
assert export_site_env.normalize_robot_sn(dict(FAKE_SITE), "right") == "Rizon4-777002"
def test_resolves_by_chinese_label(self, monkeypatch):
monkeypatch.setenv("SITE_CONFIG", "/nonexistent/site.yaml")
assert export_site_env.normalize_robot_sn(dict(FAKE_SITE), "左臂01") == "Rizon4-777001"
assert export_site_env.normalize_robot_sn(dict(FAKE_SITE), "右臂02") == "Rizon4-777002"
def test_resolves_by_full_sn(self, monkeypatch):
monkeypatch.setenv("SITE_CONFIG", "/nonexistent/site.yaml")
assert export_site_env.normalize_robot_sn(dict(FAKE_SITE), "Rizon4-777002") == "Rizon4-777002"
def test_site_alias_scheme_still_works(self, monkeypatch):
"""真实站点仍然要支持 --arm 89|91（由 SN 末两位派生，不是查表）。"""
monkeypatch.setenv("SITE_CONFIG", "/nonexistent/site.yaml")
site = {
"robot": {
"robots": [
{"sn": "Rizon4-063989", "arm": "left"},
{"sn": "Rizon4-063991", "arm": "right"},
]
}
}
assert export_site_env.normalize_robot_sn(site, "89") == "Rizon4-063989"
assert export_site_env.normalize_robot_sn(site, "91") == "Rizon4-063991"
class TestUnknownArmFailsLoudly:
"""给了一个匹配不上的臂别名，必须在启动时就报错，不能静默用错臂。"""
def test_unknown_numeric_alias_is_rejected(self, monkeypatch):
monkeypatch.setenv("SITE_CONFIG", "/nonexistent/site.yaml")
with pytest.raises((ValueError, SystemExit)) as exc:
export_site_env.resolve_robot(dict(FAKE_SITE), sn="89")
assert "89" in str(exc.value)
def test_unknown_side_word_is_rejected(self, monkeypatch):
monkeypatch.setenv("SITE_CONFIG", "/nonexistent/site.yaml")
with pytest.raises((ValueError, SystemExit)):
export_site_env.resolve_robot(dict(FAKE_SITE), sn="middle")
def test_error_message_lists_available_arms(self, monkeypatch):
"""报错必须告诉人有哪些臂可选 —— 否则使用者只能去读源码。"""
monkeypatch.setenv("SITE_CONFIG", "/nonexistent/site.yaml")
with pytest.raises((ValueError, SystemExit)) as exc:
export_site_env.resolve_robot(dict(FAKE_SITE), sn="89")
message = str(exc.value)
assert "Rizon4-777001" in message
assert "Rizon4-777002" in message
class TestDerivedPathsFollowTheActiveArm:
"""派生路径（手眼文件等）要跟着当前臂走，不能钉死某一台。"""
def test_handeye_filenames_derived_from_sn(self, monkeypatch):
monkeypatch.setenv("SITE_CONFIG", "/nonexistent/site.yaml")
monkeypatch.setenv("ROBOT_SN", "Rizon4-777001")
left = export_site_env.flatten(dict(FAKE_SITE))
monkeypatch.setenv("ROBOT_SN", "Rizon4-777002")
right = export_site_env.flatten(dict(FAKE_SITE))
assert left["SITE_HANDEYE_FILE"] != right["SITE_HANDEYE_FILE"], (
"两台臂的手眼文件路径不能是同一个"
)
assert left["SITE_HANDEYE_WAYPOINTS"] != right["SITE_HANDEYE_WAYPOINTS"]
assert left["SITE_HANDEYE_WORKDIR"] != right["SITE_HANDEYE_WORKDIR"]