结论：openpilot 的硬件后端在模块导入时就以 /AGNOS 是否为文件确定平台，并实例化一个 HardwareComma 或 HardwarePc 单例；这不是按 USB、车型或插件清单动态完成的，运行中增删 /AGNOS 也不会切换已导入的单例。更关键的是，热区缺测会被解析为 0 摄氏度、USB 线缆 connected 只表示 Type-C 朝向非零，二者都不能当作传感器健康证据。本文为固定源码快照 c8fb906 的静态阅读与离线探针，未接触车端设备或真实热管理 sysfs。
平台抽象与路径：能力不是「能实例化」就具备
common.hardware.__init__ 在模块导入时以 /AGNOS 是否为文件确定 AGNOS、COMMA_HARDWARE、PC 三个标记，并实例化 HARDWARE：comma 设备用 HardwareComma，其他环境用 HardwarePc。cast(HardwareBase, ...) 只是类型提示，不提供运行时能力校验。HardwareBase 只把 get_device_type() 声明为抽象方法，其余多数接口有默认值、空操作或打印行为。
| 接口 | 基类默认行为 | 含义 |
|---|---|---|
| 电流／功率 | 默认 0 | 没有实现时返回 0，不等于实测为 0 |
| 网络类型 | 默认 none |
HardwarePc 覆盖为 wifi |
shutdown() |
仅打印 | 「能实例化」不等于具备车载关机能力 |
get_thermal_config() |
PC 基类返回空配置 | 无热区配置时不应假定温度可用 |
Paths 按已选平台给出日志、配置、持久化、共享内存和下载缓存路径。PC 的 comma_home() 带 OPENPILOT_PREFIX，设备侧 log_root() 固定在 /data/media/0/realdata/ 但可被 LOG_ROOT 覆盖，下载缓存可用 COMMA_CACHE 覆盖。这些路径不是同一个全局「沙箱根」，OPENPILOT_PREFIX 不具备权限隔离语义。
热区读取的健康语义
ThermalZone.read() 第一次在 /sys/devices/virtual/thermal 中按 type 查找编号并缓存，之后读取 temp 并按 scale 转为摄氏度。临时 sysfs 探针确认：未找到匹配项时编号仍为 -1，对应路径触发 FileNotFoundError 后返回 0；temp 文件消失同样返回 0，后续名称出现又可重新发现。但 os.listdir() 和 type 文件读取位于 try 之外，缺失 type 会传播异常，temp 非整数也会传播 ValueError。更需注意的是 zone_number 一经缓存不再重新按名称查找，探针确认热区编号对应的 type 改变后仍读原编号。
ThermalConfig.get_msg() 遍历配置字段并把单项或列表输出为 cpuTempC、gpuTempC 等消息字段，未配置的类别被省略；HardwareComma.get_thermal_config() 给出对应平台的热区名称。结论很直接：自研主机不能用「0 °C」表示传感器失联，必须单独上报有效位或错误，否则后续热安全逻辑可能把缺测当低温。
USB 发现到消息的逐层判据
| 阶段 | 实现与确切含义 |
|---|---|
| 拓扑变化 | get_usb_topology() 返回 /sys/bus/usb/devices 中的名称集合；探针确认产品字符串改变但名称不变时集合不变。os.listdir() 抛 OSError 时返回空集合。 |
| 设备枚举 | usb_devices() 取有 idVendor 的 sysfs 节点并按名称排序；get_usb_state() 逐个读取 VID／PID、bus／dev 编号、速率、厂商和产品字符串。 |
| 控制器与方向 | controller() 从真实路径祖先中寻找 .ssusb 控制器；只有主控制器才把 Type-C 朝向 1／2 映射为 a／b。linkErrorCount 从 portli 读取并截 16 位，失败也变 0。 |
| 线缆状态 | cable_connected() 仅判断 Type-C 朝向整数是否非零；这是线缆／朝向指示，不是设备枚举成功、PCIe 就绪或 USB 传输健康的证明。 |
| 消息发布 | set_usb_state() 把传入列表写到 deviceState.usbState.devices；chestnutPresent 只根据运行态 VID／PID 判断，不核验产品字符串、数量或模型可用性。 |
hw_state_thread() 约每 10 秒或名称集合变化时采集昂贵的硬件信息，并尝试投递到容量为 1 的队列；队列满则丢弃新快照。原函数探针确认它在采集和入队之前更新 prev_usb_topology：如果队列满、采集异常，而拓扑随后保持不变，下一轮不会仅因刚才未送达而重试，只能等周期触发或下一次拓扑变化。队列满时 prev_hw_state 仍更新，后续调制解调器温度为空时甚至可能继承一份从未交给主线程的温度。
hardware_thread() 从初始空快照开始，拿不到新快照时沿用旧数据，随后调用 set_usb_state() 并驱动 Chestnut 维护和告警。因此 devices 与调用时重新读取的 connected 可能来自不同采样时刻，突然断线、重枚举或读取失败不能被简单解释为同一个原子 USB 状态。速率字段直接调用 read_int()：探针确认 1.5 这类非整数文本会回退为 0 Mbps 而非保留小数或标记「未知」；同一测试中缺失制造商字段变空串、portli=0x10002 截为 2、主控制器朝向 1 映射为 lane a。所以 speedMbps == 0 不能直接解释为物理链速率为零。
下游各自使用更严格或不同的判据：ChestnutStatus.update() 检查设备数量、精确产品字符串和速度；modeld.chestnut_present() 也要求产品字符串匹配；selfdrived 使用 chestnutPresent 与模型／Params 状态产生失败事件；UIState 还把线缆和编译产物纳入展示状态。不能把任意一个布尔值当作完整的外置计算就绪证明。
面向自研硬件和插件的约束
- 平台后端应声明供电、热区、关机、屏幕、蜂窝、USB／PCIe 等能力及「不可用」状态；禁止用基类静默默认值伪装传感器健康。
- 设备发现事件与状态快照应带单调时钟采样时间、错误原因和新鲜度。VID／PID、固件版本、传输速率、线缆朝向、模型就绪必须分层校验。
- 数据总线可发布只读设备观测插件；固件刷写、特权 sysfs 写入、设备重置和关机属于受信任平台服务，只能在驻车维护流程中授权。
- 替换
/AGNOS二选一选择前，先让原有 comma 与 PC 行为保持可回归，再对新平台测量热区缺测、USB 同名重枚举、队列积压和设备掉线后的退出时序。
常见问题
热区传感器缺失时读到 0 °C 意味着什么？
意味着失联被当成低温。源码中未匹配到 type 或 temp 文件消失都会返回 0。自研主机必须另设有效位或错误上报，否则热安全逻辑可能误判。
usbState.connected 为真代表设备已枚举成功吗？
不代表。cable_connected() 仅判断 Type-C 朝向整数是否非零；它是线缆／朝向指示，不是枚举成功、PCIe 就绪或传输健康的证明，且发布时是另读的当前朝向，不必与设备快照同龄。
为什么快照队列满之后可能不再重试？
因为 hw_state_thread() 在采集和入队之前就更新了 prev_usb_topology。若队列满或采集异常而拓扑保持不变的，下一轮不会仅因未送达而重试，只能等周期触发或下一次拓扑变化。
为什么 speedMbps == 0 不等于链路速率为零？
因为速率字段直接调用 read_int()，1.5 这类非整数文本会回退为 0。读取或解析失败都归一为 0，因此不能把 0 解释为物理链速率为零。
延伸阅读
- 车电接入：为什么 ESP32 的 TWAI 不等于 OBD 接口 —— 承接本文关于「接口存在不等于链路健康」的边界。
- 车载小仪表开发板选型：微雪 / M5Stack / Seeed 三家横向对照 —— 与本文热区、供电、USB 等平台能力的显式声明相关。
- 车载 HMI 的 30 FPS：SPI 与 MIPI-DSI 显示链路差在哪 —— 对照本文对传输速率与就绪状态的分层校验思路。
- panda 健康包 ABI：版本协商、主机解码与字段映射 —— 另一处「原始观测与发布字段并非无损镜像」的例子。
- 进程生命周期、通信与设备服务 —— 说明本文
deviceState快照在下游如何被消费。
参考资料
- 项目 02 ——
openpilot-research/HARDWARE_BACKEND_USB_SNAPSHOT_CONTRACT_DEEP_DIVE.md（取用了平台抽象与路径、热区健康语义、USB 逐层判据、自研硬件约束与离线探针结论）。 - 项目 02 ——
openpilot-research/SYSTEM_FOUNDATION_DEEP_DIVE.md（仅用于确认deviceState与 hardware 线程的衔接位置）。
说明：本文为对固定源码快照的静态结构分析，未运行完整测试套件、未连接硬件、未验证目标车型的真实参数组合。文中所有阈值、行号索引与配置均出自源文档，标注为未验证的结论保留其原有边界。
更新记录
首次发布 2026-10-11 最近核对：2026-10-11
发表回复