跳到主要内容

日志

通过 master.logs 访问日志视图，或通过 LogManager.instance().default_view 全局访问。​

底层运行日志通过回调推送到日志视图（只读列表）。

快速开始​

from ethercat import EtherCATMaster, LogCategory

# 绑定到控制台输出
master.logs.on_updated = lambda: print(master.logs[-1]) if master.logs.count > 0 else None

# 只看错误和警告
master.logs.set_filter(LogCategory.ERROR, LogCategory.WARNING)

# 启用调试日志（默认关闭）
EtherCATMaster.set_debug_logging(True)

日志类别​

from enum import IntEnum

class LogCategory(IntEnum):
    ERROR   = 0   # 系统错误和异常
    WARNING = 1   # 潜在问题
    MESSAGE = 2   # 一般信息（状态切换等）
    MAILBOX = 3   # CoE/SoE/FoE/EoE 邮箱通信（默认关闭）
    PDO     = 4   # PDO 数据变化日志（默认关闭）
    DEBUG   = 5   # 详细调试信息（默认关闭）
    LOCAL   = 6   # 控制台输出捕获

属性​

master.logs​

@property
def logs(self) -> LogView

实时日志视图（只读列表）。

LogEntry 数据类:

@dataclass
class LogEntry:
    timestamp: datetime      # 日志时间戳
    category: LogCategory    # 日志类别
    message: str             # 日志消息内容

on_updated​

@master.logs.on_updated
def callback():
    ...

日志数据变化时触发（新增/清空/过滤器变化）。

容量与保留策略

日志列表设有上限，超出时自动移除最旧的条目。

自动保留模式: 进入 SafeOp/OP 状态后，日志自动切换为保留模式 -- 运行时事件（从站离线、PDO 丢帧、DC 同步丢失等）不会被后续操作清空。退出 SafeOp/OP 后恢复为普通模式。

PDO 日志

PDO 日志只在 PDO 数据发生变化时输出，不会每个周期都产生日志。适合调试 PDO 映射问题。

过滤​

set_filter()​

def set_filter(self, *categories: LogCategory) -> None

设置过滤器，只显示指定类别的日志。

示例:

# 只看错误和警告
master.logs.set_filter(LogCategory.ERROR, LogCategory.WARNING)

# 切换为只看邮箱通信
master.logs.set_filter(LogCategory.MAILBOX)

get_all()​

def get_all(self) -> List[LogEntry]

获取所有日志条目（无视过滤器）。

日志开关​

Mailbox、PDO、Debug 三类日志默认关闭，需要时手动启用。

EtherCATMaster.set_pdo_logging(True)
EtherCATMaster.set_mailbox_logging(True)
EtherCATMaster.set_debug_logging(True)

日志开关详解​

set_pdo_logging()​

EtherCATMaster.set_pdo_logging(enable: bool) -> None

启用 PDO 日志。仅在 PDO 数据变化时输出，影响实时性能，慎用。

set_mailbox_logging()​

EtherCATMaster.set_mailbox_logging(enable: bool) -> None

启用邮箱日志（CoE/SoE/FoE/EoE 邮箱通信日志）。

set_debug_logging()​

EtherCATMaster.set_debug_logging(enable: bool) -> None

启用调试日志（详细调试信息）。

完整示例​

from ethercat import EtherCATMaster, LogCategory

# 1. 绑定控制台输出
master.logs.on_updated = lambda: print(master.logs[-1]) if master.logs.count > 0 else None

# 2. 启用调试日志
EtherCATMaster.set_debug_logging(True)
EtherCATMaster.set_mailbox_logging(True)

# 3. 过滤日志
master.logs.set_filter(LogCategory.ERROR, LogCategory.DEBUG)

# 4. 导出所有日志（无视过滤器）
all_logs = master.logs.get_all()
with open("debug.log", "w", encoding="utf-8") as f:
    for entry in all_logs:
        f.write(f"{entry}\n")
tkinter / PyQt 绑定

on_updated 在非 UI 线程触发，更新 UI 时需要同步：

# tkinter
master.logs.on_updated = lambda: root.after(0, lambda: listbox.insert("end", str(master.logs[-1])))

# PyQt
from PyQt5.QtCore import QMetaObject, Qt, Q_ARG
master.logs.on_updated = lambda: QMetaObject.invokeMethod(
    widget, "append_log", Qt.QueuedConnection, Q_ARG(str, str(master.logs[-1])))