外部设备状态检查与显示的最佳实践 - 不要只用『连接中』敷衍了事的设计

工业相机、条码读取器、PLC、测量仪器、打印机、串口设备、USB 设备。 在与外部设备联动的 Windows 应用中，比起 实际的故障本身，更常出事的往往是 画面上的状态显示和实际情况不一致。

举几个例子：

• OS 能看到设备，但被其他进程占用而无法使用
• open 成功了，但归零、预热、认证还没完成
• 设备还挂在那里，但响应已经停止了
• 采集线程已经死掉，画面上却还留着最后一次的值
• 遇到意料之外的个体或 firmware，却只是简单地显示「连接中」

这里真正想知道的，不只是 是否连上。 而是 现在能安全地做什么。

1. 先下结论

在外部设备的状态检查与显示中，最有效的做法就是 不要把状态压缩成一个 boolean。

至少应该把下面这些分开管理：

• 存在：OS 是否能看到
• 会话建立：自身应用是否已完成 open / login / initialize
• 响应性：是否响应 heartbeat 或 status query
• 功能就绪：现在能否接受实际操作
• 数据新鲜度：画面上的值是否新鲜
• 配置一致性：是否为预期的个体、型号、firmware
• 监控健全性：监控处理本身是否还活着

粗略地说就是：

存在确认交给 OS 侧，可用性交给应用侧，新鲜度判定交给画面侧。

只要不把这 3 者混在一起，状态显示就会相当稳定。

2. 为什么「连接中」很危险

「连接中」这个词，会让一个词汇擅自背负起多重含义。

实际上，至少混杂了以下这些问题：

1. OS 是否能看到目标设备的 interface
2. 自身应用是否已经完成 open / login / initialize
3. 轻量查询能否在期限内返回
4. 现在要求的操作能否安全执行
5. 画面上的值是否新鲜
6. 是否为预期的个体、型号、firmware

满足这 6 项中的哪几项，「可用」的含义就会不同。

举例来说，下面这 4 种状态全都不一样：

• 未连接 OS 一开始就没有发现目标 interface
• 已连接 / 确认中 物理上能看到，但初始化或认证还没完成
• 已连接 / 不可用 有响应，但因为 warming up、busy、interlock、没有 media 等原因无法工作
• 值已过期 以前能获取到，但画面上的值已经超过了 freshness budget

如果把这些全部压缩成「连接中」，operator 就无法判断该做什么。

3. 首先应该分开的状态

推荐的做法是，内部状态用多轴来管理，UI 上按需要进行摘要展示。

3.1 内部想要分开的状态轴

这里重要的是，把 设备本身状态不好 和 应用没能观测到 这两件事分开。

3.2 UI 不需要把所有内容平铺展示

内部按多轴管理，画面看起来可能会变得很杂乱。 但 UI 并不需要把所有信息用同样的权重展示出来。

推荐分成 3 层：

• 上层放 摘要状态
• 下面放 理由
• 需要时再展开 详情面板

例如：

• 摘要：已连接 / 不可用
• 理由：预热中、还剩约 18 秒
• 详情：model、serial、firmware、last heartbeat、last frame time

像这样分层展示，即使信息量增加，也会相当好读。

4. 状态检查的最佳实践

4.1 启动时列举与到达 / 移除通知

在 Windows 上处理外部设备时的基础是，启动时先列举已有设备，之后接收 arrival / removal 通知。

特别要注意的是这 3 点：

• 仅靠通知无法捕捉到已存在的设备
• 在 runtime communication 中，interface class 比 setup class 更自然
• remove 通知和 I/O error 出现的先后顺序有时会颠倒

作为实务规则，其实很简单：

1. 启动时列举
2. 订阅通知
3. 收到通知后重新列举，并将内部状态 reconcile

4.2 区分「存在」「能打开」「有响应」「能使用」

外部设备的事故，往往是把这些混在一起处理时增多的。

• 存在 OS 能看到 interface
• 能打开 没有其他进程冲突或权限问题，能拿到 handle / session
• 有响应 轻量查询能在 timeout 内返回
• 能使用 能接受实际操作

这 4 者并不是同一件事。

4.3 混合使用 event 与 poll

比起全部倒向 event 或全部倒向 poll，检测用 event、健全性确认用 poll 在实务中更容易处理。

• arrival / removal 用 event
• heartbeat / status query 用 poll
• freshness 判定用 timestamp / sequence

采用这种分工，就能更容易把连接检测和实际可用性区分开来。

4.4 把监控处理和 UI 分离

如果在 UI thread 上直接执行 open / read / status query，显示的需求和监控处理的需求很容易混在一起。

推荐的做法是：

• 监控 worker 更新 state store
• UI 订阅 state store 并渲染
• UI 操作作为 command 传递给监控层

这样一来，就更容易把「监控停止」和「设备停止」区分开来处理。

4.5 让个体识别保持稳定

如果只靠 friendly name 或 COM3 这类外观上的标识符来追踪状态，很容易把个体搞混。

最好在内部持有：

• serial number
• logical device id
• stable device path
• 设备侧的个体 ID

这类 不易变化的 key，会更安全。

5. 显示的最佳实践

5.1 一张判断表

5.2 文案要是「状态 + 理由 + 下一步动作」

仅仅显示 错误 或 异常，作为画面来说是不够的。 消息最好靠向下面这 3 个要素，operator 才不容易迷茫：

• 状态：发生了什么
• 理由：为什么这样判断
• 下一步动作：应该做什么

例如：

• 已连接 / 不可用 - 预热中 - 请等待约 18 秒
• 无响应 - heartbeat timeout - 请检查电缆和电源
• 意外设备 - 需要 Firmware 2.1.0 - 请检查目标设备

大致是这样的形式。

5.3 不要隐藏过期数据

last known value 本身很有用。 但最好不要 用 live value 的样子来呈现它。

推荐的做法是：

• 在值旁边显示 timestamp
• 显示值的 age
• 变成 stale 之后更换颜色或标签
• 超过一定时间后就将其排除在「可操作」判定之外

5.4 按重要程度改变展示位置

status bar 很方便，但也容易被忽略。 应该避免把 critical 异常只放在 status bar 的角落里。

• 轻微的状态变化：status bar
• 可以继续工作的提醒：inline notice
• 需要停止操作的异常：主显示区域、对话框、banner

这样区分使用会更自然。

5.5 多台设备的展示要分开摘要和详情

在处理多台设备的画面中，如果一直显示所有明细，会很难看清楚。

• 上部放 整体摘要
• 下部放 逐设备的行
• 选中时展开 详情面板

分成这 3 层，就更容易同时兼顾整体把握和个别排查。

6. 重连与运维的最佳实践

6.1 重连要带上 backoff

响应停止时的重连，不要用最短循环持续重试，这样更安全。

因为这样会：

• 给 device / driver / SDK 带来负担
• 让日志泛滥
• 加剧暂时性的不稳定
• 让 UI 剧烈晃动

现实的做法是：

• 第一次立刻 retry
• 不行的话逐步拉长间隔
• 设置上限
• 同时准备手动 重新连接 选项

6.2 缓和 flapping

在 USB 接触不良或网络瞬断这类场景下，状态会在短时间内反复变化。 如果直接把原始事件呈现在 UI 上，会相当难看。

因此，比较好处理的做法是：

• 内部日志保留原始事件
• UI 设置一个短暂的确认期后再确定显示
• 但 critical 异常要立刻展示

6.3 至少要保留的日志

状态显示的改进，几乎和日志设计是一体的。

特别重要的是 状态迁移日志。

6.4 不要混淆监控停止与设备停止

• poll loop 因异常而死掉
• SDK callback 停止了
• acquisition worker 发生 deadlock
• 只是 state store 的更新停止了

出现这些情况时，设备本身还活着，但应用观测不到。 如果只用 未连接 或 无响应 来呈现这种状态，看起来就会像是设备侧的问题。

所以，监控通路的健全性 最好作为单独的一个轴来管理。

7. 按设备类型容易忽略的地方

7.1 USB / PnP 设备

• 仅靠通知无法捕捉到 existing device
• 在 runtime 中，interface class 比 setup class 更自然
• composite device 有时会暴露多个 interface
• remove 通知和 I/O error 出现的先后顺序有时会颠倒

7.2 串口设备

仅仅看到 COMx 并不能安心。

• 端口本身存在，但目标设备并没有挂在上面
• 被其他进程 open 了
• 响应已经停止
• read / write 卡在 timeout 上

对于串口，特别应该把 存在、响应、可用 分开管理，这样更安全。

7.3 网络设备

不应该把 ping 能通和应用可用等同起来。

存在这些阶段：

• 能否完成名称解析
• 能否建立 TCP 连接
• 能否完成应用层 handshake
• status 是否为 ready
• 值是否 fresh

7.4 依赖 SDK 的相机 / 测量设备

不要仅凭 SDK callback 到达就断定为 live，这样会更安全。

• callback thread 本身停止
• frame 有到达，但 timestamp 没有前进
• image stream 有到达，但 control channel 已经死掉
• reconnect 之后的配置重新应用还没完成

这类情况会发生，所以最好在 SDK 之外也保留一份健全性判断。

8. 不应该做的事

• 把状态压缩成 连接中 / 未连接 / 错误 这 3 种
• 以为仅靠通知就能捕捉到 existing device
• 把 open 成功直接当作 可用
• 用 fresh 的样子呈现 last known value
• 不显示 timestamp
• 在 UI thread 上执行 open / read / status query
• 用最短循环执行 retry
• 把 critical 异常只放在 status bar 里
• 混淆 未连接 和 监控停止
• 只靠 friendly name 或 COM3 识别个体

9. 总结

在外部设备联动应用中，真正重要的是要决定 确认到什么程度，才能说到什么程度。

尤其是这样的分类方式很有效：

存在 自身应用能打开 有响应 现在能执行该操作 画面上的值是新鲜的

把这 5 者分开。

在此基础上，实务上的方针大致是这些：

• 启动时列举，之后靠通知
• 可用性由 heartbeat 和 device-specific status 决定
• 显示值要带上 timestamp 和 age
• critical 异常要放在不容易被忽视的位置
• 不要把监控系统的异常显示成设备异常

比起能够显示出「连接中」，这个显示与现实的偏差有多小，在实务中才是更重要的事。

10. 参考资料

• Microsoft Learn, CM_Register_Notification
• Microsoft Learn, Registering for Notification of Device Interface Arrival and Device Removal
• Microsoft Learn, Registering for Device Notification
• Microsoft Learn, Comparison of setup classes and interface classes
• Microsoft Learn, Device Information Sets
• Microsoft Learn, SetupDiEnumDeviceInterfaces
• Microsoft Learn, Communications functions
• Microsoft Learn, ClearCommError
• Microsoft Learn, COMMTIMEOUTS structure
• Microsoft Learn, WaitCommEvent
• Microsoft Learn, Monitoring Communications Events
• Microsoft Learn, Status Bars (Design basics)
• Microsoft Learn, UX checklist for desktop applications

相关文章

共享相同标签的最新文章。可以围绕相近的主题进一步加深理解。

常见问题

汇总了咨询这一主题时常见的问题。

为什么只把设备状态显示成「连接中」是不够的？

因为「连接中」这个词，把「OS 是否看得到」「自身应用能否 open」「是否有响应」「现在能否操作」「画面上的值是否新鲜」「是否是预期的个体」这几个不同的问题全部压缩成了一个。例如「未连接」「已连接 / 确认中」「已连接 / 不可用」「值已过期」都是不同的状态，如果把这些全部压成「连接中」，operator 就无法判断该采取什么行动。

外部设备的状态在内部应该怎样分开管理？

应该把「存在」（OS 是否看得到）、「会话建立」（是否已完成 open / login / initialize）、「响应性」（是否响应 heartbeat）、「功能就绪」（现在能否接受操作）、「数据新鲜度」（画面的值是否新鲜）、「配置一致性」（是否为预期的个体 / firmware）、「监控健全性」（监控处理本身是否存活）分开管理。粗略地说，就是存在确认交给 OS 侧、可用性交给应用侧、新鲜度判定交给画面侧这样的分工。UI 只要分成摘要、理由、详情这 3 层来展示，就会更容易阅读。

设备的检测和健全性确认应该用事件还是轮询？

与全部倒向某一方相比，检测走 event、健全性确认走 poll 这样的分工在实务中更容易处理。具体来说，arrival / removal 用事件通知接收，heartbeat 或 status query 用定期轮询进行，新鲜度判定用 timestamp 或 sequence 来做。不过，仅靠通知无法捕捉到已经存在的设备，所以实务规则是：启动时先列举一遍，之后订阅通知，收到通知后重新列举并将内部状态 reconcile。

对无响应设备的重连应该怎样实现？

不要用最短循环不断重试，而要带上 backoff。现实的做法是：第一次立刻 retry，不行的话逐步拉长间隔，设置上限，并同时提供手动的「重新连接」按钮。如果用最短循环不断重试，会给设备或 SDK 带来负担，让日志泛滥，还会加剧暂时性的不稳定。另外，对于 USB 接触不良等导致状态在短时间内反复变化的 flapping，有效的做法是在 UI 侧设置一个短暂的确认期，之后再确定显示。

作者简介

本文作者的个人简介页面。

Go Komura

小村软件有限公司 代表

以 Windows 软件开发、技术咨询与故障排查为中心，擅长难以复现的故障调查，以及既有资产仍在运行的项目。