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

体检判据硬化：sysfs 读取带超时、复位命令不再写成"要密码"

Browse Source 
两处都是「体检工具自己失效」——本仓库最贵的那类坑：判据看起来在跑，其实
结论是假的或者干脆没有结论。

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>
This commit is contained in:
arm_dev
2026-09-28 10:42:37 +08:00
parent 98f4277849
commit 0fadd26ca2
4 changed files with 239 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/lib/usb_health.py
+133 -15
View File
@@ -19,11 +19,26 @@ USB3 接口里 SuperSpeed 是一对独立的差分针脚，它们一旦接触不
一开始就报"协商速率不对"，能把这一类问题从"查算法"挪回"插紧线"。
还有一种更彻底的坏法：**Hub 在内核里卡死**
--------------------------------------------
2026-09-28 又实测到一次：不只是掉速，而是挂在同一个 Hub 下的**四台设备一起消失**
（腕部 D405 + 顶置 D435 + 左右两个视触觉）。此时 ``/sys/bus/usb/devices`` 里那个
Hub 节点还在，但读它的属性会**永久阻塞**：
/sys/bus/usb/devices/1-3.4/product ← 读 2 秒、20 秒、永不返回
原因是内核正在跟这个卡死的设备对话，拿不到应答就不返回。于是本脚本自己也挂住 ——
用户看到的是"体检卡死"，比报一行错更难判断。所以这里的 sysfs 读取**一律带超时**，
超时就当作一条 error 结论报出来（见 ``SysfsReader``）：宁可少读到一个字段，
也不能让体检本身失去意义。
判定口径（这里就是**唯一一处**）
--------------------------------
· 5000 Mbps → USB3，OK（D435 可用 1280x720@30）
· 480 Mbps → USB2，RealSense 会掉到 640x480@15 —— WARN 并给出拔插建议
· 12 / 1.5 → USB 全速/低速，串口转换器正常，不告警
· 读属性超时 → Hub/设备内核级卡死，ERROR（软件复位要 root，现场断电重启该 Hub）
· 一台都没有 → ERROR
用法::
@@ -36,6 +51,7 @@ from __future__ import annotations
import argparse
import json
import threading
import time
from dataclasses import dataclass, asdict
from pathlib import Path
@@ -65,6 +81,70 @@ USB_RESEAT_HINT = (
"核对速率：lsusb -t（设备后面写 480M 还是 5000M）。"
)
#: 读 sysfs 属性的超时 [s]。正常读取是微秒级，1 秒足够宽松。
DEFAULT_READ_TIMEOUT_S = 1.0
class SysfsReader:
"""带超时的 sysfs 读取 —— 卡死的 USB 设备会让读取**永久阻塞**。
为什么不能直接用 ``Path.read_text``：内核在跟卡死的设备对话时，
``/sys/bus/usb/devices/1-3.4/product`` 这类属性读下去不返回，Python 就
卡在系统调用里。对体检工具来说这是最坏的结果 —— 本该报出故障的那一次
恰恰什么都不输出。
超时后读属性用的线程会一直留在后台（Python 没法强杀阻塞在系统调用里的
线程），所以同一个路径**只尝试一次**并记入 ``blocked``，后续直接跳过。
这样 ``--watch`` 反复采样也不会攒出几十个卡住的线程。
"""
def __init__(self, timeout_s: float = DEFAULT_READ_TIMEOUT_S) -> None:
self.timeout_s = timeout_s
#: 读取超时的 sysfs 路径（按出现顺序，去重）
self.blocked: List[str] = []
self._tried_blocked: set[str] = set()
def read(self, path: Path) -> str:
key = str(path)
if key in self._tried_blocked:
return ""
done = threading.Event()
box: Dict[str, str] = {}
def _worker() -> None:
try:
box["v"] = path.read_text(encoding="utf-8", errors="replace").strip()
except OSError:
box["v"] = ""
finally:
done.set()
threading.Thread(target=_worker, daemon=True).start()
if not done.wait(self.timeout_s):
self._tried_blocked.add(key)
if key not in self.blocked:
self.blocked.append(key)
return ""
return box.get("v", "")
def blocked_devices(blocked: Sequence[str]) -> List[str]:
"""把阻塞的 sysfs 路径归到 USB 设备路径上（``/sys/.../1-3.4/product`` → ``1-3.4``）。
归类是为了给出**该动哪一个**：报"1-3.4/product 读不了"没用，
要能说出"1-3.4 这个 Hub 卡死了，挂在它下面的设备一起没了"。
"""
devs: List[str] = []
for raw in blocked:
parts = Path(raw).parts
if "devices" in parts:
name = parts[parts.index("devices") + 1]
else:
name = Path(raw).parent.name
if name and name not in devs:
devs.append(name)
return devs
@dataclass(frozen=True)
class UsbDevice:
@@ -131,37 +211,63 @@ def _parse_speed(raw: str) -> Optional[int]:
return None
def read_devices(root: Path = SYS_USB) -> List[UsbDevice]:
"""列出当前 USB 设备（不需要 root）。"""
def read_devices(
root: Path = SYS_USB, reader: Optional[SysfsReader] = None
) -> List[UsbDevice]:
"""列出当前 USB 设备（不需要 root）。
``reader`` 传入时，读取超时的路径会记在它上面（见 :class:`SysfsReader`）——
调用方据此把"Hub 卡死"报出来，而不是默默少列几台设备。
"""
rd = reader or SysfsReader()
out: List[UsbDevice] = []
if not root.is_dir():
return out
for entry in sorted(root.iterdir()):
vid = _read(entry / "idVendor")
vid = rd.read(entry / "idVendor")
if not vid:
continue # 不是设备节点（接口/端口目录没有 idVendor）
out.append(
UsbDevice(
path=entry.name,
vid=vid,
pid=_read(entry / "idProduct"),
product=_read(entry / "product"),
speed_mbps=_parse_speed(_read(entry / "speed")),
serial=_read(entry / "serial"),
pid=rd.read(entry / "idProduct"),
product=rd.read(entry / "product"),
speed_mbps=_parse_speed(rd.read(entry / "speed")),
serial=rd.read(entry / "serial"),
)
)
return out
def findings_for(devices: Sequence[UsbDevice]) -> List[Finding]:
"""对一批设备给出体检结论（纯函数，便于单测）。"""
def findings_for(
devices: Sequence[UsbDevice], blocked: Sequence[str] = ()
) -> List[Finding]:
"""对一批设备给出体检结论（纯函数，便于单测）。
``blocked`` 是读取超时的 sysfs 路径（``SysfsReader.blocked``）。
"""
out: List[Finding] = []
# 卡死的 Hub 要**排在最前面**：它是根因，后面"一台相机都没枚举到"只是症状。
for dev in blocked_devices(blocked):
out.append(
Finding(
"error",
f"USB 设备 {dev} 的 sysfs 属性读取超时 —— 内核正卡在跟它对话，"
f"这一台**及其下游设备**会一起从系统里消失"
f"（相机/触觉都挂它下面时，现象是「相机和触觉同时没了」）。"
f"软件复位需要 root；现场处置是给这个 Hub 断电重启："
f"拔插它的上游线，或把设备改插到主板后面板直连的 USB 口"
f"（两个 RealSense 都走同一个总线供电的小 Hub 很容易把它拖垮）。",
)
)
cams = [d for d in devices if d.is_realsense]
if not cams:
out.append(
Finding(
"error",
"一台 RealSense 都没枚举到。拔插一次；确认没有 "
"一台 RealSense 都没枚举到。先看上面有没有「sysfs 读取超时」那条"
"（有就是 Hub 卡死，不是相机的问题）；否则拔插一次，并确认没有 "
"realsense-viewer / 其它进程占着相机。",
)
)
@@ -214,13 +320,17 @@ def flap_events(snapshots: Sequence[Sequence[str]]) -> List[str]:
def watch_realsense(
seconds: float, interval_s: float = 1.0, root: Path = SYS_USB
seconds: float,
interval_s: float = 1.0,
root: Path = SYS_USB,
reader: Optional[SysfsReader] = None,
) -> List[List[str]]:
"""在 ``seconds`` 秒内反复采样 RealSense 的设备路径。"""
rd = reader or SysfsReader()
snaps: List[List[str]] = []
deadline = time.monotonic() + max(0.0, seconds)
while True:
snaps.append(sorted(d.path for d in read_devices(root) if d.is_realsense))
snaps.append(sorted(d.path for d in read_devices(root, rd) if d.is_realsense))
if time.monotonic() >= deadline:
break
time.sleep(interval_s)
@@ -233,9 +343,12 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
ap.add_argument("--json", action="store_true", help="输出 JSON")
args = ap.parse_args(argv)
devices = read_devices()
findings = findings_for(devices)
snaps = watch_realsense(args.watch) if args.watch > 0 else []
# 整轮共用一个 reader：某条路径一旦确认卡死就不再重读，
# 否则 --watch 每次采样都会再攒一个卡在内核里的线程。
reader = SysfsReader()
devices = read_devices(reader=reader)
findings = findings_for(devices, reader.blocked)
snaps = watch_realsense(args.watch, reader=reader) if args.watch > 0 else []
flaps = flap_events(snaps) if snaps else []
if flaps:
findings.append(
@@ -252,6 +365,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
"devices": [asdict(d) for d in devices if d.is_realsense],
"findings": [asdict(f) for f in findings],
"flaps": flaps,
"blocked_sysfs": list(reader.blocked),
}
if args.json:
print(json.dumps(payload, ensure_ascii=False, indent=2))
@@ -262,6 +376,10 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
f" {d.model or d.product:8} {d.path:8} "
f"{str(d.speed_mbps) + ' Mbps':>10} vid:pid={d.vid}:{d.pid}"
)
if reader.blocked:
# 单独打一行：它意味着"下面那些设备根本没被列出来"，
# 不写清楚的话，上面的列表看起来就像"设备没了"而没有原因。
print(f" （{len(reader.blocked)} 条 sysfs 属性读取超时，详见下面的 FAIL）")
for f in findings:
mark = {"ok": "OK ", "warn": "WARN", "error": "FAIL"}[f.level]
print(f" [{mark}] {f.text}")