配置

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

属性

类别	属性	类型	访问	说明
周期配置	LoopCycle	uint	读写	PDO 交换周期（纳秒）。主站软件定时器以此间隔发送和接收 PDO 帧（同时自动附带 DC 漂移补偿 FRMW）
网络传输	FrameHighPriority	bool	读写	帧高优先级（默认启用）。Windows WDK 驱动模式下插入 802.1Q VLAN 标签 (PCP=6)；Npcap 模式下仅标记（不插入 VLAN）；Linux 通过 SO_PRIORITY 实现
	UseUdp	bool	读写	UDP 帧模式（仅 EtherCAT 网关/EAP 设备可用，标准 ESC 从站不支持）。将数据报封装在 UDP/IP 中传输
	IsUdpAvailable	bool	只读	UDP 模式是否可用。反映系统初始化时 UDP socket 是否创建成功
	VlanId	ushort	读写	VLAN ID（IEEE 802.1Q，0-4095，0=禁用）。仅 WDK 驱动模式下生效，Npcap 模式下自动跳过
	VlanPriority	byte	读写	VLAN 优先级 PCP（0-7，7=最高）。需要 VlanId > 0 且 WDK 驱动模式
PDO 配置	OverlappingGroups	bool	读写	PDO 重叠优化（默认启用）。输入输出共享内存区域，减少帧数
	PDOFrameLossThreshold	uint	读写	PDO 连续丢帧阈值（默认 3）。连续丢帧达到此值才触发回调
互斥锁保护	MutexProtection	bool	读写	互斥锁保护（默认启用）。启用时自动加锁确保线程安全，禁用时由用户自行管理
自适应超时	AdaptiveTimeoutEnabled	bool	读写	自适应超时（默认启用）。自动采样网络 RTT，动态计算最优 PDO 超时值

周期配置

LoopCycle

public uint LoopCycle { get; set; }

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

主站内部的软件定时器以此间隔循环执行 PDO 帧的发送和接收。这个值决定了主站与从站之间过程数据的刷新频率 —— 值越小，数据刷新越快，但对系统实时性要求也越高。

推荐值

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

示例:

master.Config.LoopCycle = 1000000;  // 1ms     = 1,000,000ns
master.Config.LoopCycle = 500000;   // 500μs   = 500,000ns
master.Config.LoopCycle = 250000;   // 250μs   = 250,000ns
master.Config.LoopCycle = 125000;   // 125μs   = 125,000ns（Windows 推荐最小值）

DC 漂移补偿

DC 漂移补偿由 PDO 帧中附带的 FRMW 数据报自动完成，无需额外配置。每次 LoopCycle 发送 PDO 帧时，主站在第一个数据报后附加 FRMW 命令，自动校正各从站时钟。

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

邮箱通信与 PDO 周期

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

工作原理：每个 PDO 周期帧自动携带邮箱状态检查，入站邮箱和出站邮箱均在同一帧中完成，零额外帧开销。

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

网络传输

FrameHighPriority

public bool FrameHighPriority { get; set; }

提升 EtherCAT 帧的网络层发送优先级，减少排队延迟。支持 802.1Q 的交换机会识别优先级字段并优先转发。

默认值: true（默认启用）

如果同时配置了 VlanId（>0），则使用用户指定的 VLAN 参数，不会自动插入优先级标签。

各平台实现方式

平台	实现方式	说明
Windows WDK 驱动	插入 802.1Q VLAN 标签 (PCP=6, VID=0)	内核驱动直接发送原始帧，VLAN 标签完整保留
Windows Npcap	无
Linux	SO_PRIORITY=6 socket 选项	内核网络栈排队优先级，不修改帧格式（需要 root 权限）

UseUdp

public bool UseUdp { get; set; }

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 bool IsUdpAvailable { get; }

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

在某些受限环境中（如缺少网络权限、防火墙阻止等），UDP socket 可能创建失败，此时 IsUdpAvailable 返回 false，设置 UseUdp = true 将无效。

示例:

if (master.Config.IsUdpAvailable)
{
    master.Config.UseUdp = true;  // 切换到 UDP 模式
}

VlanId

public ushort VlanId { get; set; }

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

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

VLAN 配置需要在 SetNetwork() / Build() 之前设置，因为帧头在网络初始化时写入发送缓冲区。

仅 WDK 驱动模式下生效

VLAN 标签功能仅在安装了 WDK 内核驱动时生效。

• WDK 驱动模式: 内核驱动直接发送原始帧，VLAN 标签完整保留在线缆上
• Npcap 模式: VLAN 标签会被 Windows 用户态网络栈剥离，导致 EtherCAT 命令失败。因此 Npcap 模式下自动跳过 VLAN 插入并输出警告日志

如果当前使用 Npcap 模式且需要 VLAN，请安装 WDK 驱动。

VlanPriority

public byte VlanPriority { get; set; }

VLAN 优先级（PCP — Priority Code Point, IEEE 802.1Q, ETG.1500 可选功能）。范围 0-7，7 为最高优先级。编码在 VLAN 标签的 TCI 字段高 3 位中。

需要先设置 VlanId 为非零值，且使用 WDK 驱动模式，此属性才有意义。在支持 QoS 的交换机中，高 PCP 值的帧将优先转发。

VLAN 典型应用场景:

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

示例:

// 在 Build() 之前设置 VLAN（需要 WDK 驱动模式）
master.Config.VlanId = 100;
master.Config.VlanPriority = 6;  // 高优先级

var (success, message) = master.Build();

PDO 配置

OverlappingGroups

public bool OverlappingGroups { get; set; }

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

默认值: true（默认启用）

备注

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

对应用层无影响

重叠仅发生在帧的逻辑地址层面。slave.PDO.OutputsMapping<T>() 和 slave.PDO.InputsMapping<T>() 始终指向独立的内存区域，slave.Ibytes / slave.Obytes 不变，所有 API 行为一致。

TI ESC

使用 TI (Texas Instruments) EtherCAT Slave Controller 的从站必须启用重叠模式，否则 LRW 命令无法正确工作。由于默认已启用，通常无需手动处理。

PDOFrameLossThreshold

public uint PDOFrameLossThreshold { get; set; }

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

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

示例:

master.Config.PDOFrameLossThreshold = 5;  // 连续丢 5 帧才触发回调

分组

PDO 配置与从站分组配合使用。每组独立的分频器和 WKC 跟踪意味着高频组和低频组的丢帧互不影响。

FrameRepeatCount

public byte FrameRepeatCount { get; set; }

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

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

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

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

为什么是全局设置 + 按组过滤？

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

DENI 配置迁移

此参数及每个从站的 FrameRepeatSupport 标志均已包含在 DENI 配置文件中。导出 DENI 后加载到另一台主站时，无需 ESI 文件即可正确计算每组的帧重复资格。

示例:

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

互斥锁保护

MutexProtection

public bool MutexProtection { get; set; }

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

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

默认值: true

实时优化

底层实时优化（包括但不限于 高精度定时器、调度优先级、亲和性、热路径）在 Build() 时默认自动应用。 这些优化始终生效，与 MutexProtection 无关。 SDK 会自动索取管理员权限，如果权限不足，SDK将无法正常启动。

注意

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

自适应超时

AdaptiveTimeoutEnabled

public bool AdaptiveTimeoutEnabled { get; set; }

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

默认值: true（默认启用）

• 启用（默认） — 自动采样 RTT，动态计算超时，显著减少超时丢帧
• 关闭 — 使用固定默认超时值

为什么默认启用

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