跳到主要内容

配置

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

PascalCase 可读写属性

配置属性使用 PascalCase 重载方法：无参调用为读取，带参调用为写入。

int cycle = config.LoopCycle();        // 读取
config.LoopCycle(1_000_000);           // 写入

属性​

类别属性类型读写说明
周期配置LoopCycle()int读写PDO 交换周期（纳秒）
网络传输FrameHighPriority()boolean读写帧高优先级（默认关闭）
UseUdp()boolean读写UDP 帧模式
isUdpAvailable()boolean只读UDP 是否可用
VlanId()int读写VLAN ID（0=禁用）
VlanPriority()int读写VLAN 优先级（0-7）
PDO 配置OverlappingGroups()boolean读写PDO 重叠模式（默认不启用，仅 TI ESC）
PackedMode()boolean读写Packed PDO 映射模式（默认禁用）
FilterThreshold()int读写PDO 连续丢帧阈值（默认 3）
帧重复FrameRepeatCount()int读写帧重复次数（1-3）
互斥锁保护MutexProtection()boolean读写互斥锁保护（默认启用）
自适应超时AdaptiveTimeoutEnabled()boolean读写自适应超时（默认启用）
状态转换超时TimeoutInitToPreOp()int读写INIT→PREOP 超时（毫秒）
TimeoutPreOpToSafeOp()int读写PREOP→SAFEOP 超时（毫秒）
TimeoutSafeOpToOp()int读写SAFEOP→OP 超时（毫秒）
看门狗ProcessDataWatchdogMs()int读写过程数据看门狗超时（毫秒）
PdiWatchdogMs()int读写PDI 看门狗超时（毫秒）
DC 配置DriftCompensation()boolean读写DC 漂移补偿开关
扫描配置ScanRevisionMatch()RevisionMatch读写扫描修订号匹配策略
邮箱配置MailboxConfig()MailboxConfig只读邮箱韧性配置对象

周期配置​

LoopCycle​

public int LoopCycle()
public void LoopCycle(int timeNs)

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

主站 RT 线程（WDK 内核定时器驱动）以此周期执行 PDO 帧的发送和接收。该值决定了主站与从站之间过程数据的刷新频率 -- 值越小，数据刷新越快，但对系统实时性要求也越高。WDK 驱动最低支持 31.25μs。

推荐值

Windows 系统建议不低于 125,000ns（125us）。WDK 驱动完全支持 31.25us，更小的值在 Windows 上没有意义，应用层无法做到更高频的写入。

示例:

config.LoopCycle(1_000_000);  // 1ms     = 1,000,000ns
config.LoopCycle(500_000);    // 500us   = 500,000ns
config.LoopCycle(250_000);    // 250us   = 250,000ns
config.LoopCycle(125_000);    // 125us   = 125,000ns（Windows 推荐最小值）
DC 漂移补偿

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

DC 同步窗口监控自动管理，网络中有 DC 从站时自动启用。

邮箱通信与 PDO 周期

邮箱报文（SDO 读写、FoE 文件传输、紧急消息等）附带在 PDO 帧中，不占用额外帧。

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

网络传输​

FrameHighPriority​

public boolean FrameHighPriority()
public void FrameHighPriority(boolean enable)

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

默认值: false（默认关闭）

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

UseUdp​

public boolean UseUdp()
public boolean UseUdp(boolean enable)

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、伺服驱动等）

isUdpAvailable​

public boolean isUdpAvailable()

系统初始化时是否成功创建了 UDP socket。只有此方法返回 true 时，才能通过 UseUdp 切换到 UDP 模式。

示例:

if (config.isUdpAvailable()) {
    config.UseUdp(true);  // 切换到 UDP 模式
}

VlanId​

public int VlanId()
public void VlanId(int vlanId)

VLAN ID（IEEE 802.1Q, ETG1000_4 表9, ETG.1500 可选功能）。范围 0-4095，0 表示禁用 VLAN 标签。

设置非零值后，所有 EtherCAT 帧将插入 4 字节的 802.1Q VLAN 标签，帧头从标准的 14 字节变为 18 字节。

仅 WDK 驱动模式下生效

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

VlanPriority​

public int VlanPriority()
public void VlanPriority(int priority)

VLAN 优先级（PCP -- Priority Code Point, IEEE 802.1Q, ETG.1500 可选功能）。范围 0-7，7 为最高优先级。

需要先设置 VlanId 为非零值，且使用 WDK 驱动模式，此属性才有意义。

示例:

config.VlanId(100);
config.VlanPriority(6);  // 高优先级

PDO 配置​

OverlappingGroups​

public boolean OverlappingGroups()
public void OverlappingGroups(boolean enable)

PDO 重叠模式开关。启用后，每个从站的输出和输入共享同一段逻辑地址（取两者中较大的尺寸），LRW 命令发送时写入输出，返回时 ESC 用输入数据替换同一位置，从而减少帧大小。

默认值: false（默认不启用）

备注

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

TI ESC

使用 TI (Texas Instruments) EtherCAT Slave Controller 的从站必须启用重叠模式，否则 LRW 命令无法正确工作。标准 Beckhoff/第三方从站请勿启用。

PackedMode​

public boolean PackedMode()
public void PackedMode(boolean enable)

Packed PDO 映射模式开关。启用后，PDO 变量按 bit 紧密排列，不强制字节对齐。

默认值: false（默认禁用，字节对齐模式）

适用场景

适用于 bit-level IO 模块（如 Beckhoff EL1008/EL2008 等数字 IO 终端），这些模块的 PDO 数据为单个 bit，启用 PackedMode 可以将多个 bit IO 紧密排列在连续内存中，节省 IOmap 空间。

示例:

config.PackedMode(true);  // 启用 bit 紧密排列

FilterThreshold​

public int FilterThreshold()
public void FilterThreshold(int threshold)

PDO 连续丢帧阈值，默认值为 3。

主站在每个 PDO 周期中检测帧是否正常返回。单次丢帧被视为偶发干扰仅做计数，只有连续丢帧次数达到此阈值时才触发 PDOFrameLoss 回调，避免因偶发丢帧产生过多告警。

示例:

config.FilterThreshold(5);  // 连续丢 5 帧才触发回调

扫描配置​

ScanRevisionMatch​

public RevisionMatch ScanRevisionMatch()
public void ScanRevisionMatch(RevisionMatch match)

扫描从站时的版本匹配策略。控制 Build() 过程中扫描到的从站与配置中从站的版本号匹配严格程度。

默认值: RevisionMatch.IGNORE_REVISION

相关结构:

public enum RevisionMatch {
    EXACT(0),              // 精确匹配 VendorID + ProductID + RevisionID
    COMPATIBLE_HIGHER(1),  // 兼容匹配: 扫描到的 RevisionID >= 配置的 RevisionID
    IGNORE_REVISION(2);    // 忽略 RevisionID, 仅匹配 VendorID + ProductID（默认）
}

示例:

config.ScanRevisionMatch(RevisionMatch.COMPATIBLE_HIGHER);

DC 配置​

DriftCompensation​

public boolean DriftCompensation()
public void DriftCompensation(boolean enable)

DC 漂移补偿开关。启用后主站周期性检测 DC 系统时间偏差并写入补偿值 (0x0920)。

默认值: false

备注

也可通过 master.enableDriftCompensation() 方法启用，该方法额外支持配置阈值和增益参数。

帧重复​

FrameRepeatCount​

public int FrameRepeatCount()
public void FrameRepeatCount(int count)

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

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

此属性为主站级全局设置，运行时自动按组过滤 -- 仅对组内所有从站均在 ESI 中声明 FrameRepeatSupport=1 的组执行帧重复：

  • 组内所有从站都支持 -> 该组启用帧重复
  • 组内有任何一个不支持 -> 该组跳过帧重复

示例:

config.FrameRepeatCount(2);  // 对所有符合条件的组，每周期发送 2 次

互斥锁保护​

MutexProtection​

public boolean MutexProtection()
public void MutexProtection(boolean enable)

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

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

默认值: true

注意

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

自适应超时​

AdaptiveTimeoutEnabled​

public boolean AdaptiveTimeoutEnabled()
public void AdaptiveTimeoutEnabled(boolean enable)

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

默认值: true（默认启用）

为什么默认启用

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

状态转换超时​

TimeoutInitToPreOp​

public int TimeoutInitToPreOp()
public void TimeoutInitToPreOp(int ms)

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

默认值: 3000（3000ms）

示例:

config.TimeoutInitToPreOp(5000);  // 5 秒超时

TimeoutPreOpToSafeOp​

public int TimeoutPreOpToSafeOp()
public void TimeoutPreOpToSafeOp(int ms)

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

默认值: 10000（10000ms）

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

示例:

config.TimeoutPreOpToSafeOp(15000);  // 15 秒超时

TimeoutSafeOpToOp​

public int TimeoutSafeOpToOp()
public void TimeoutSafeOpToOp(int ms)

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

默认值: 10000（10000ms）

示例:

config.TimeoutSafeOpToOp(8000);  // 8 秒超时
何时需要修改超时
  • 从站数量多 -- 大型网络（>50 从站）可能需要增大 PreOp->SafeOp 超时
  • 特殊从站 -- 某些伺服驱动器或安全设备初始化较慢
  • 调试阶段 -- 增大超时以便观察转换过程中的问题

看门狗​

PdiWatchdogMs​

public int PdiWatchdogMs()
public void PdiWatchdogMs(int ms)

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

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

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

示例:

config.PdiWatchdogMs(100);  // PDI 看门狗 100ms
备注

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

ProcessDataWatchdogMs​

public int ProcessDataWatchdogMs()
public void ProcessDataWatchdogMs(int ms)

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

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

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

示例:

config.ProcessDataWatchdogMs(200);  // 过程数据看门狗 200ms
设置建议

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

邮箱配置​

通过 master.Config().MailboxConfig() 访问：

属性类型说明
MailboxTimeout() / MailboxTimeout(int)int邮箱超时（毫秒，默认 3000）
MailboxRetries() / MailboxRetries(int)int邮箱重试次数（默认 3）

示例:

config.MailboxConfig().MailboxTimeout(5000);
config.MailboxConfig().MailboxRetries(5);

IOmap 锁定​

lockIOmap / unlockIOmap​

public void lockIOmap()
public void unlockIOmap()

手动锁定/解锁 IOmap，用于多轴批量原子写入。当 MutexProtection = false 时，需要手动调用此方法保证 PDO 数据的原子性。

三种线程安全模式对比:

  • 自动互斥锁 — MutexProtection(true)（默认），通用场景，无需关心线程安全
  • 手动 IOmap 锁 — MutexProtection(false) + lockIOmap / unlockIOmap，多轴插补，需要批量原子写入
  • 无锁 — MutexProtection(false)，不调用 lock，单线程写入，保证无竞争
多轴插补场景

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

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

// 关闭自动互斥锁，改用手动 IOmap 锁
master.setMutexProtection(false);

// PDO 回调中批量写入多轴位置
master.Events().addProcessDataCyclicSyncListener((mi) -> {
    master.lockIOmap();
    try {
        ByteBuffer out1 = slave1.PDO().GetOutputByteBuffer();
        ByteBuffer out2 = slave2.PDO().GetOutputByteBuffer();
        ByteBuffer out3 = slave3.PDO().GetOutputByteBuffer();
        out1.putInt(0, targetPos1);
        out2.putInt(0, targetPos2);
        out3.putInt(0, targetPos3);
    } finally {
        master.unlockIOmap();
    }
});

完整示例​

try (EtherCATMaster master = EtherCATMaster.create()) {
    master.SetNetwork("\\Device\\NPF_{...}");

    MasterConfig config = master.Config();

    // 周期配置
    config.LoopCycle(1_000_000);           // 1ms 周期

    // 网络传输
    config.FrameHighPriority(true);

    // PDO 配置
    config.FilterThreshold(5);

    // 状态转换超时
    config.TimeoutPreOpToSafeOp(15000);

    // 看门狗
    config.ProcessDataWatchdogMs(200);

    // 邮箱配置
    config.MailboxConfig().MailboxTimeout(5000);

    // 扫描配置
    config.ScanRevisionMatch(RevisionMatch.COMPATIBLE_HIGHER);

    // 启动
    master.Start();
}

超时配置最佳实践​

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

关键字段速查​

  • LoopCycle (ns) — 默认 1,000,000 (1ms)，推荐 125,000 ~ 4,000,000 (125us ~ 4ms)，PDO 周期, 决定刷新率与 CPU 负载
  • TimeoutInitToPreOp (ms) — 默认 3000，推荐 3000 ~ 10000，INIT→PREOP 等待时间 (慢从站 / EEPROM 加载)
  • TimeoutPreOpToSafeOp (ms) — 默认 10000，推荐 10000 ~ 30000，PREOP→SAFEOP 等待时间 (含 SM/FMMU/PDO 映射, 大网络可加大)
  • TimeoutSafeOpToOp (ms) — 默认 10000，推荐 5000 ~ 15000，SAFEOP→OP 等待时间
  • ProcessDataWatchdogMs (ms) — 默认 0 (从站默认 ≈100)，推荐 LoopCycle × 10 ~ 100，从站丢失主站连接后回退 SafeOp 的时间
  • PdiWatchdogMs (ms) — 默认 0 (从站默认)，推荐 0 ~ 200，从站本地固件停止访问 ESC 的检测窗口
  • MailboxConfig.MailboxTimeout (ms) — 默认 3000，推荐 1000 ~ 10000，SDO / FoE / 紧急消息单次邮箱等待

何时调大 / 调小​

调大 适用场景:

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

调小 适用场景:

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

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

MasterConfig config = master.Config();

// (1) SDK 默认 — 适合标准短电缆 + 桌面 ~ 普通车间
config.LoopCycle(1_000_000);                  // 1ms
config.TimeoutPreOpToSafeOp(10000);
config.ProcessDataWatchdogMs(0);              // 从站默认 (~100ms)
config.MailboxConfig().MailboxTimeout(3000);

// (2) 实验室高速 — 短线 + 严苛 RT
config.LoopCycle(250_000);                    // 250us
config.TimeoutPreOpToSafeOp(5000);
config.ProcessDataWatchdogMs(20);             // 极快检测
config.MailboxConfig().MailboxTimeout(1000);

// (3) 工业典型 — 长电缆 + 大网络
config.LoopCycle(1_000_000);
config.TimeoutPreOpToSafeOp(20000);           // 大网络放宽
config.ProcessDataWatchdogMs(200);
config.MailboxConfig().MailboxTimeout(5000);

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

启用 AdaptiveTimeoutEnabled(true) (默认开) 后, SDK 自动按真实 RTT 计算 PDO 单帧超时, 无需手动收紧 LoopCycle. 上面的 watchdog / state transition 字段仍需按场景配置.