跳到主要内容

从站诊断

每个从站提供独立的诊断属性和子对象，可查询端口错误、冗余、DC 同步等信息。

从站基础属性

从站状态（state、error_code、is_lost）等基础属性请参考从站 API。

配合事件使用

建议通过 事件 驱动异常处理（如 slave_state_changed、slave_offline、dc_sync_lost），而非轮询。

功能概览​

功能访问路径说明
通信诊断slave.diagnostics.read_port_errors()ESC 端口错误计数器
冗余诊断slave.diagnostics.*冗余激活、主/冗余线路断路检测
DC 同步slave.diagnostics.dc.*同步状态、时间差

通信诊断​

read_port_errors()​

def read_port_errors(self) -> Optional[EscPortErrors]

读取从站 ESC 端口错误计数器。

EscPortErrors 数据类:

@dataclass
class EscPortErrors:
    rx_error: List[int]         # 各端口 RX 错误计数 [Port0-3]
    invalid_frame: List[int]    # 各端口无效帧计数 [Port0-3]
    lost_link: List[int]        # 各端口链路丢失计数 [Port0-3]
    has_errors: bool            # 是否存在任何错误

示例:

for slave in master.slaves:
    errors = slave.diagnostics.read_port_errors()
    if errors is not None and errors.has_errors:
        print(f"从站 {slave.slave_num}: "
              f"RX错误={errors.rx_error}, "
              f"无效帧={errors.invalid_frame}, "
              f"链路丢失={errors.lost_link}")

冗余诊断​

通过 slave.diagnostics 访问从站的冗余状态。

属性类型说明
redundancy_activatedbool冗余被激活
primary_link_brokenbool主线路断路
secondary_link_brokenbool冗余线路断路

示例:

for slave in master.slaves:
    if not slave.diagnostics.redundancy_activated:
        continue

    msg = f"从站 {slave.slave_num}: 冗余激活"
    if slave.diagnostics.primary_link_broken:
        msg += ", 主线路断路"
    if slave.diagnostics.secondary_link_broken:
        msg += ", 冗余线路断路"
    print(msg)

DC 同步​

通过 slave.diagnostics.dc 访问从站的 DC 同步状态。

属性类型说明
is_in_syncbool是否在同步窗口内
sync_time_differenceint当前与参考时钟的时间差（纳秒）

SyncWindowStatus 数据类 (唯一定义来源: slave/slave_stats.py):

@dataclass
class SyncWindowStatus:
    diff_ns: int = 0              # 当前时间差 (纳秒)
    max_diff_ns: int = 0          # 最大时间差 (纳秒)
    min_diff_ns: int = 0          # 最小时间差 (纳秒)
    in_sync: bool = False         # 是否在同步窗口内
    out_of_sync_count: int = 0    # 超出同步窗口次数

通过 DcConfig.get_sync_window_status() 获取一次性快照。

示例:

for slave in master.slaves:
    if not slave.has_dc:
        continue

    dc = slave.diagnostics.dc
    print(f"从站 {slave.slave_num}: "
          f"时间差={dc.sync_time_difference}ns, "
          f"同步={dc.is_in_sync}")

完整示例​

for slave in master.slaves:
    print(f"--- 从站 {slave.slave_num}: {slave.name} ---")

    # 端口错误
    errors = slave.diagnostics.read_port_errors()
    if errors is not None and errors.has_errors:
        print(f"  端口错误: RX={errors.rx_error}, "
              f"无效帧={errors.invalid_frame}, "
              f"链路丢失={errors.lost_link}")

    # 冗余（仅冗余模式下有意义）
    if slave.diagnostics.redundancy_activated:
        print(f"  冗余激活: "
              f"主线路断={slave.diagnostics.primary_link_broken}, "
              f"冗余线路断={slave.diagnostics.secondary_link_broken}")

    # DC 同步
    if slave.has_dc:
        dc = slave.diagnostics.dc
        print(f"  DC: 时间差={dc.sync_time_difference}ns, "
              f"同步={dc.is_in_sync}")