跳到主要内容

配置

通过 master.config 访问 MasterConfig 对象，统一管理所有通信配置。

属性​

类别属性类型读写说明
周期配置loop_cycleint读写PDO 交换周期（纳秒）
high_resolution_timerbool读写读：系统当前时钟精度是否已是 1ms（或更细）；写：本进程打开/关闭，立即生效。安装包默认不打开
网络传输frame_high_prioritybool读写帧高优先级（默认关闭）
use_udpbool读写UDP 帧模式
is_udp_availablebool只读UDP 模式是否可用
vlan_idint读写VLAN ID（0-4095，0=禁用）
vlan_priorityint读写VLAN 优先级 PCP（0-7）
PDO 配置overlapping_groupsbool读写PDO 重叠模式（默认不启用，仅适用于 TI ESC）
packed_modebool读写Packed PDO 映射模式（默认不启用，启用后 bit 紧密映射）
filter_thresholdint读写PDO 连续丢帧阈值（默认 3）
互斥锁保护mutex_protectionbool读写互斥锁保护（默认启用）
自适应超时adaptive_timeout_enabledbool读写自适应超时（默认启用）
状态转换超时timeout_init_to_preopint读写INIT→PREOP 超时（毫秒），0=默认 2000ms
timeout_preop_to_safeopint读写PREOP→SAFEOP 超时（毫秒），0=默认 3000ms
timeout_safeop_to_opint读写SAFEOP→OP 超时（毫秒），0=默认 8000ms
看门狗pdi_watchdog_msint读写PDI 看门狗超时（毫秒），0=默认
process_data_watchdog_msint读写过程数据看门狗超时（毫秒），0=默认
扫描配置scan_revision_matchScanRevisionMatchMode读写扫描从站版本匹配策略
帧重复frame_repeat_countint读写帧重复次数（1-3，1=禁用）
DC 配置drift_compensationbool读写DC 漂移补偿开关
邮箱配置mailbox_configMailboxConfig只读邮箱配置子对象（超时、重试，SDK 侧本地值，不下发 native）

周期配置​

loop_cycle​

@property
def loop_cycle(self) -> int

@loop_cycle.setter
def loop_cycle(self, value: int) -> None

PDO 交换周期时间，单位：纳秒（ns）。

推荐值

Windows 系统建议不低于 125,000ns（125us）。WDK 驱动完全支持 31.25us。

示例：

master.config.loop_cycle = 1_000_000   # 1ms
master.config.loop_cycle = 500_000     # 500us
master.config.loop_cycle = 250_000     # 250us
master.config.loop_cycle = 125_000     # 125us（Windows 推荐最小值）
DC 漂移补偿

DC 漂移补偿自动完成，无需额外配置。

DC 同步窗口监控由内部诊断线程自动管理（固定 100ms 间隔），网络中有 DC 从站时自动启用。

邮箱通信与 PDO 周期

邮箱通信自动附带在 PDO 周期中，不占用额外帧。

邮箱响应延迟： 约 2-3 个 PDO 周期。如 loop_cycle=1ms，SDO 读取约需 2-3ms。

high_resolution_timer​

@property
def high_resolution_timer(self) -> bool

@high_resolution_timer.setter
def high_resolution_timer(self, value: bool) -> None
高精度时钟

读：系统当前时钟精度是否已是 1ms（或更细），不是写死的 false。写：本进程打开/关闭，立即生效。安装包默认不打开，由你在周期配置里设。打开后等待更准，鼠标可能变顿；隔离核 PDO 不依赖此项。非 Windows 为空操作。

读返回系统当前是否已 1ms，不是写死 false；安装包不开。

示例：

master.config.high_resolution_timer = True

网络传输​

frame_high_priority​

@property
def frame_high_priority(self) -> bool

@frame_high_priority.setter
def frame_high_priority(self, value: bool) -> None

通过 OS 层提升 EtherCAT 帧的发送优先级，减少排队延迟。

默认值： False（默认关闭）

各平台实现方式
  • Windows — 进程/线程优先级提升
  • Linux — SO_PRIORITY=6 socket 选项，内核网络栈排队优先级（需要 root 权限）

use_udp​

@property
def use_udp(self) -> bool

@use_udp.setter
def use_udp(self, value: bool) -> None

UDP 帧模式（ETG.1500 5.3.7）。启用后，EtherCAT 数据报不再使用原始以太网帧（EtherType 0x88A4），而是封装在 UDP/IP 数据包中传输（UDP 端口 34980）。

仅适用于网关/EAP 设备，标准从站不支持

标准 EtherCAT 从站的 ESC（EtherCAT Slave Controller）芯片在数据链路层工作，只能识别 EtherType=0x88A4 的原始以太网帧。UDP/IP 封装的帧对这些从站不可见。

仅适用于：

  • 使用支持 UDP 协议的 EtherCAT 网关或桥接设备
  • 与 EtherCAT Automation Protocol（EAP）设备通信

不适用于： 直连标准 EtherCAT 从站（EK1100、EL7041、伺服驱动等）

is_udp_available​

@property
def is_udp_available(self) -> bool

系统初始化时是否成功创建了 UDP socket。只有此属性返回 True 时，才能通过 use_udp 切换到 UDP 模式。

示例：

if master.config.is_udp_available:
    master.config.use_udp = True  # 切换到 UDP 模式

vlan_id / vlan_priority​

VLAN ID（IEEE 802.1Q）范围 0-4095，0 表示禁用。VLAN 配置需要在进入 SafeOp 之前设置（build() 成功后、set_state(OP) 之前）。

仅 WDK 驱动模式下生效

VLAN 标签功能仅在安装了 WDK 内核驱动时生效。WDK 内核驱动直接发送原始帧，VLAN 标签完整保留在线缆上。

VLAN 典型应用场景：

  • IT/OT 融合网络 — 通过 VLAN 隔离工业控制流量与办公网络流量
  • TSN（时间敏感网络） — IEEE 802.1Q 优先级标签实现 QoS 调度
  • 多网段共存 — 同一物理网络承载多个 EtherCAT 网段

PDO 配置​

overlapping_groups​

PDO 重叠模式开关。启用后，每个从站的输出和输入共享同一段逻辑地址，LRW 命令发送时写入输出，返回时 ESC 用输入数据替换同一位置。仅适用于 TI ESC 等特殊从站，标准 Beckhoff/第三方从站请勿启用。

默认值： False（默认不启用）

备注

只能在 INIT 或 PRE_OP 状态下设置，因为内存布局在进入 SAFE_OP 时已确定。

packed_mode​

Packed PDO 映射模式开关。启用后 PDO 数据按 bit 紧密排列，禁用时按字节对齐。

默认值： False（默认字节对齐）

备注

只能在 INIT 或 PRE_OP 状态下设置，因为内存布局在进入 SAFE_OP 时已确定。

示例：

master.config.packed_mode = True  # 启用 bit 紧密映射

filter_threshold​

PDO 连续丢帧阈值，默认值为 3。主站在每个 PDO 周期中检测帧是否正常返回。单次丢帧被视为偶发干扰仅做计数，只有连续丢帧次数达到此阈值时才触发 pdo_frame_loss 回调。

示例：

master.config.filter_threshold = 5  # 连续丢 5 帧才触发回调

互斥锁保护​

mutex_protection​

互斥锁保护开关。控制 PDO 读写时是否自动加锁确保线程安全。

  • 启用（默认） — 框架自动加锁保证线程安全
  • 禁用 — 关闭自动互斥锁，由用户自行管理线程安全，减少锁竞争开销

默认值： True

实时优化

底层实时优化（包括但不限于 调度优先级、亲和性、热路径）在 build() 时默认自动应用。 这些优化始终生效，与 mutex_protection 无关。SDK 不弹 UAC，权限校验只做只读检查。

注意

禁用互斥锁保护后，用户需要自行确保 PDO 数据的线程安全。适用于对延迟要求极高且能自行管理并发的场景。

自适应超时​

adaptive_timeout_enabled​

自适应超时功能开关。启用后，系统自动采样网络往返时间（RTT），动态计算最优 PDO 超时值，替代固定默认超时。

默认值： True（默认启用）

为什么默认启用

固定超时在大多数网络中远大于实际 RTT，导致偶发丢帧时等待过长，挤占后续周期时间。自适应超时通过采样实际网络延迟并留有安全余量，计算最优超时值，显著减少超时丢帧和由此引发的连锁丢帧。

状态转换超时​

运行时生效值 vs 语言常量

下面 timeout_init_to_preop / timeout_preop_to_safeop / timeout_safeop_to_op 标注的系统默认 2000 / 3000 / 8000 ms 是运行时生效值（build() 后由内核写入，是实际生效的转换墙钟超时；属性值为 0 时即采用这组生效值）。

但 Python 的 EsmTimeouts 常量（INIT_TO_PREOP / PREOP_TO_SAFEOP / SAFEOP_TO_OP）以及 build() 之前的回退值为 2000 / 3000 / 8000 ms，与上面这组运行时生效值一致。

timeout_init_to_preop​

INIT→PREOP 状态转换超时时间，单位：毫秒（ms）。

默认值： 0（使用系统默认 2000ms）

设置非零值可覆盖默认超时。适用于需要较长初始化时间的从站（如固件加载、EEPROM 读取较慢的设备）。

示例：

master.config.timeout_init_to_preop = 5000  # 5 秒超时

timeout_preop_to_safeop​

PREOP→SAFEOP 状态转换超时时间，单位：毫秒（ms）。

默认值： 0（使用系统默认 3000ms）

此阶段包含 SM/FMMU 配置和 PDO 映射，通常耗时最长。从站数量多或 PDO 配置复杂时可能需要增大超时值。

示例：

master.config.timeout_preop_to_safeop = 15000  # 15 秒超时

timeout_safeop_to_op​

SAFEOP→OP 状态转换超时时间，单位：毫秒（ms）。

默认值： 0（使用系统默认 8000ms）

示例：

master.config.timeout_safeop_to_op = 12000  # 12 秒超时
何时需要修改超时
  • 从站数量多 — 大型网络（>50 从站）可能需要增大 preop→safeop 超时
  • 特殊从站 — 某些伺服驱动器或安全设备初始化较慢
  • 调试阶段 — 增大超时以便观察转换过程中的问题
  • 值为 0 — 使用系统默认值，适合大多数场景

看门狗​

pdi_watchdog_ms​

PDI（Process Data Interface）看门狗超时，单位：毫秒（ms）。

PDI 看门狗监控从站本地应用程序（微控制器固件）对 ESC 的访问。如果从站固件在指定时间内没有访问 PDI 接口，ESC 会触发看门狗错误，表示从站应用可能已崩溃。

默认值： 0（使用从站 EEPROM/ESI 中的默认值）

示例：

master.config.pdi_watchdog_ms = 100  # PDI 看门狗 100ms
备注

PDI 看门狗与过程数据看门狗是独立的两个监控机制。PDI 看门狗监控从站内部固件，过程数据看门狗监控主站通信。

process_data_watchdog_ms​

过程数据看门狗超时，单位：毫秒（ms）。

过程数据看门狗监控主站到从站的 PDO 通信。如果从站在指定时间内没有收到有效的过程数据帧（SyncManager 2/3 未被主站访问），ESC 会触发看门狗超时，从站可能自动从 OP 降级到 SafeOp。

默认值： 0（使用从站 EEPROM/ESI 中的默认值，通常为 100ms）

示例：

master.config.process_data_watchdog_ms = 200  # 过程数据看门狗 200ms
设置建议

过程数据看门狗超时应大于 PDO 周期（loop_cycle）的数倍，以避免正常运行时误触发。推荐值为 PDO 周期的 10-100 倍。例如 loop_cycle=1ms 时，看门狗设为 100-200ms。

扫描配置​

scan_revision_match​

扫描从站版本匹配策略（SDK 侧本地值，读写不下发 native）。扫描结果与 DENI/ESI 设备的匹配按 ESI 设备声明的 Type@CheckRevisionNo 策略执行。

默认值： ScanRevisionMatchMode.IGNORE_REVISION

ScanRevisionMatchMode 枚举：

class ScanRevisionMatchMode(IntEnum):
    EXACT              = 0   # 精确匹配 VendorID + ProductID + RevisionID
    COMPATIBLE_HIGHER  = 1   # 兼容匹配: 扫描到的 RevisionID >= 配置的 RevisionID
    IGNORE_REVISION    = 2   # 忽略 RevisionID, 仅匹配 VendorID + ProductID（默认）

示例：

master.config.scan_revision_match = ScanRevisionMatchMode.COMPATIBLE_HIGHER

帧重复​

frame_repeat_count​

帧重复机制（ETG.1500 5.4.3），全局设置每周期发送相同 PDO 帧的次数，自动对符合条件的组生效。

默认值： 1（禁用），范围 1-3

此属性为主站级全局设置，运行时自动按组过滤——仅对组内所有从站均在 ESI 中声明 FrameRepeatSupport=1 的组执行帧重复。组资格在 IO 映射阶段自动计算：

  • 组内所有从站都支持 → 该组启用帧重复
  • 组内有任何一个不支持 → 该组跳过帧重复
为什么是全局设置 + 按组过滤？

ETG.1500 将帧重复定义为主站级能力，重复次数全局统一。由于 EtherCAT PDO 帧以 LRW 广播方式发送，同一帧内无法对个别从站区分处理，因此按组"全有或全无"是唯一合规做法。不需要为每组单独设置不同的重复次数。

示例：

# 全局设置: 对所有符合条件的组，每周期发送 2 次相同 PDO 帧
master.config.frame_repeat_count = 2

DC 配置​

drift_compensation​

DC 漂移补偿开关（SDK 侧本地标志，读写不下发 native）。

默认值： False

备注

真正下发 native 的入口是 master.enable_drift_compensation()：启用后主站周期性检测 DC 系统时间偏差并写入补偿值 (0x0920)，并支持阈值和增益参数。

IOmap 锁定​

lock_iomap / unlock_iomap​

def lock_iomap(self) -> None
def unlock_iomap(self) -> None

手动锁定/解锁过程映像互斥锁，用于多轴批量原子写入。当 mutex_protection = False 时，需要手动调用此方法保证 PDO 数据的原子性。写入走金路径 outputs_mapping（字段同址写内核过程映像），write_outputs 整帧替换是快照路径。

三种线程安全模式对比：

  • 自动互斥锁 — mutex_protection = True（默认），延迟 ~200ns，通用场景，无需关心线程安全
  • 手动锁 — mutex_protection = False + lock_iomap/unlock_iomap，延迟 ~50ns，多轴插补，需要批量原子写入
  • 无锁 — mutex_protection = False，不调用 lock，延迟 0，单线程写入，保证无竞争
多轴插补场景

多轴联动插补时，多个从站的目标位置必须在同一 PDO 周期内同时生效。使用手动锁可以保证一批写入操作在一次 PDO 帧中原子提交。

示例（多轴插补批量写入）:

# 关闭自动互斥锁，改用手动锁
master.mutex_protection = False

import struct

def on_pdo_cycle(mi):
    master.lock_iomap()
    try:
        for s, pos in ((slave1, target_pos1), (slave2, target_pos2), (slave3, target_pos3)):
            frame = bytearray(s.pdo.outputs or b'')
            if len(frame) >= 4:
                struct.pack_into('<i', frame, 0, pos)
                s.pdo.write_outputs(bytes(frame))
    finally:
        master.unlock_iomap()

master.on_pdo_cycle(on_pdo_cycle)

完整示例​

# 基本配置
master.config.loop_cycle = 1_000_000        # 1ms 周期
master.config.frame_high_priority = False    # 帧高优先级（默认关闭）
master.config.overlapping_groups = False     # PDO 重叠模式 (仅 TI ESC)
master.config.filter_threshold = 5   # 连续丢 5 帧才触发

# 超时配置
master.config.timeout_preop_to_safeop = 15000  # 15秒

# 看门狗
master.config.process_data_watchdog_ms = 200   # 200ms

# VLAN（需要 WDK 驱动模式）
master.config.vlan_id = 100
master.config.vlan_priority = 6

超时配置最佳实践​

EtherCAT 通信涉及的多种超时字段彼此独立， 对网络异常的检测灵敏度和恢复时延有直接影响。 下表汇总常用字段、典型默认值与推荐范围， 实际部署时按照网络长度 / 干扰水平 / 实时性优先级三维平衡选取。

字段单位默认推荐范围影响
loop_cyclens1,000,000 (1ms)125,000 ~ 4,000,000 (125us ~ 4ms)PDO 周期， 决定刷新率与 CPU 负载
timeout_init_to_preopms0 (=2000)2000 ~ 10000INIT→PREOP 等待时间 （慢从站 / EEPROM 加载）
timeout_preop_to_safeopms0 (=3000)3000 ~ 30000PREOP→SAFEOP 等待时间 （含 SM/FMMU/PDO 映射， 大网络可加大）
timeout_safeop_to_opms0 (=8000)8000 ~ 15000SAFEOP→OP 等待时间
process_data_watchdog_msms0 （从站默认 ≈100）loop_cycle × 10 ~ 100从站丢失主站连接后回退 SafeOp 的时间
pdi_watchdog_msms0 （从站默认）0 ~ 200从站本地固件停止访问 ESC 的检测窗口
mailbox_config.timeout_msms5000—SDK 侧本地值，不改变 native 行为（实际邮箱超时/重试由 native 管理）

何时调大 / 调小​

调大 适用场景：

  • 长电缆 / 跨机柜 / 跨车间 — 物理传输延迟大， 偶发 RTT 抖动需缓冲
  • 高 EMI / 焊接 / 大功率变频器附近 — 噪声造成偶发丢帧， 重试空间需放宽
  • 跨 VLAN / TSN 复合网络 — 经过交换机会引入排队抖动
  • 大网络（>50 从站） — timeout_preop_to_safeop 必须放大，否则 SafeOp 转换失败
  • 慢从站 （FoE 大文件下载 / EEPROM 写入） — 邮箱 / Init→PreOp 都要拉长

调小 适用场景：

  • 快速故障检测优先 — 工业紧急停车场景， 看门狗调到 5×loop_cycle, 50ms 内检测到丢帧
  • 桌面短电缆 / 实验室 — RTT 极低， 看门狗可下探到 20~50ms
  • RT 严苛 （≤ 250µs 周期） — 整体时序紧凑， 任何超时都要短

默认 / 实验室 / 工业 / 高 EMI 四档示例​

# (1) SDK 默认 — 适合标准短电缆 + 桌面 ~ 普通车间
master.config.loop_cycle = 1_000_000          # 1ms
master.config.timeout_preop_to_safeop = 0     # = 3000ms
master.config.process_data_watchdog_ms = 0    # 从站默认 (~100ms)

# (2) 实验室高速 — 短线 + 严苛 RT
master.config.loop_cycle = 250_000            # 250us
master.config.timeout_preop_to_safeop = 5000
master.config.process_data_watchdog_ms = 20   # 极快检测

# (3) 工业典型 — 长电缆 + 大网络
master.config.loop_cycle = 1_000_000
master.config.timeout_preop_to_safeop = 20000  # 大网络放宽
master.config.process_data_watchdog_ms = 200

# (4) 高 EMI / 焊接现场 — 容忍偶发丢帧
master.config.loop_cycle = 2_000_000          # 2ms
master.config.timeout_preop_to_safeop = 30000
master.config.process_data_watchdog_ms = 500
master.config.adaptive_timeout_enabled = True  # 自适应吸收抖动
副作用
  • 超时太大 — 真实故障也要等到超时才上报， 应用层告警 / 安全停机延迟变长
  • 超时太小 — 偶发抖动被误判成故障， 频繁触发 pdo_frame_loss / state_change 噪声告警
  • 看门狗 < loop_cycle × 数倍 — 正常运行也会触发，从站反复回退 SafeOp
  • 调整后建议跑 24h 通讯压力测试再上线
配合自适应超时

启用 adaptive_timeout_enabled （默认开） 后， SDK 自动按真实 RTT 计算 PDO 单帧超时， 无需手动收紧 loop_cycle. 上面的 watchdog / state transition 字段仍需按场景配置。