跳到主要内容

错误处理

EtherCAT 通信中的错误处理策略和常见故障排查。

错误类型​

类型来源处理方式
AL Status Code从站状态转换失败通过 slave.error_code 读取，使用 classify_al_error() 分类
SDO ErrorCoE 读写失败SDO 方法返回 None 或 False，错误码见 SDOError
PDO 丢帧通信异常通过 pdo_frame_loss 事件 监控
Emergency从站硬件/固件错误通过 emergency_event 事件 接收
状态降级从站异常回退通过 state_changed 事件 监控

状态转换错误​

检测方式​

if not master.set_state(EcState.OP):
    print(f"状态切换失败, 错误码: {master.error_code}")

    for slave in master.slaves:
        ec = slave.error_code
        if ec != 0:
            print(f"  从站 {slave.index}: 0x{ec:04X}")

错误分类​

使用 classify_al_error() 快速判断处理策略：

from darra_ethercat import classify_al_error, ALErrorCategory

category = classify_al_error(slave.error_code)
if category == ALErrorCategory.TRANSIENT:
    # 重试状态转换
    slave.set_state(EcState.OP)
elif category == ALErrorCategory.CONFIGURATION:
    # 检查 PDO 映射、SM 配置
    print("配置错误，请检查 PDO/SM 配置")
elif category == ALErrorCategory.HARDWARE:
    # 检查从站设备、线缆、电源
    print("硬件错误，请检查从站设备")

常见 AL Status Code​

  • 0x001E 无效输入映射 — 检查 PDO 映射配置是否与从站支持的映射一致
  • 0x001D 无效输出映射 — 检查 PDO 输出映射配置
  • 0x0017 无效 SM 配置 — 检查 SyncManager 配置（大小、方向）
  • 0x001B SM 看门狗超时 — PDO 周期过慢或通信中断
  • 0x002D 同步错误 — DC 同步配置问题，检查 SYNC0 周期
  • 0x0032 DC 同步超时 — DC 启动时间配置问题
  • 0x0003 无效设备设置 — 耦合器无物理模块，或模块配置不匹配

事件驱动的异常处理​

推荐通过事件监控异常，而非轮询：

# 状态降级检测
# 状态变化
master.on_state_change(lambda mi, si, old, new:
    print(f"从站 {si}: 0x{old:02X} -> 0x{new:02X}"))

# 从站发现/丢失
master.on_slave_discovery(lambda mi, si, found:
    print(f"从站 {si} {'上线' if found else '离线'}"))

# PDO 丢帧
master.on_pdo_frame_loss(lambda mi, group, consecutive, total:
    print(f"组 {group} 严重丢帧: 连续 {consecutive} 帧") if consecutive > 10 else None)

# 紧急消息
master.on_emergency(lambda mi, si, err_code, err_reg, b1, w1, w2:
    print(f"从站 {si} 紧急消息: 0x{err_code:04X}"))
自动日志

所有事件（PDO 周期回调除外）触发时系统均自动记录日志，无论是否订阅。详见 事件。

常见故障排查​

初始化失败​

  • 管理员权限不足 — 以管理员身份运行
  • 网卡名称不匹配 — 检查 get_network_info() 返回的网口列表
  • set_network() 返回 0 — 检查网线连接和从站供电
  • RuntimeError — 主站实例数已达上限

从站无法进入 OP​

  • PDO 映射不匹配 — 检查 slave.error_code，常见 0x001E / 0x001D
  • ESI 版本不匹配 — 使用与固件版本对应的 ESI 文件
  • DC 同步失败 — 检查 DC 配置，确认 SYNC0 周期合理
  • SM 配置错误 — 检查 SyncManager 大小和方向
  • 缺少启动参数 — 使用 DENI 文件或 enable_auto_startup()

通信不稳定​

  • 丢帧率高 — 检查网线质量、交换机端口、EMI 干扰
  • 抖动大 — 安装 DarraRT 驱动，隔离 CPU 核心
  • 偶尔超时 — 检查系统负载，关闭不必要的后台进程
  • DC 同步偏差大 — 使用 DarraRT 驱动降低抖动

日志系统​

from darra_ethercat import EtherCATMaster

# 启用日志监控
# 设置日志回调
master.set_log_callback(lambda cat, msg: print(f"[{cat}] {msg}"))

# 启用详细日志（调试用）
EtherCATMaster.set_debug_logging(True)
EtherCATMaster.set_mailbox_logging(True)
EtherCATMaster.set_pdo_logging(True)
日志详情

日志系统详见 日志。