跳到主要内容

EoE (Ethernet over EtherCAT)

EoE 协议通过 EtherCAT 总线实现以太网通信，支持配置 IP/MAC/DNS 地址和以太网帧收发，符合 ETG.1000.6 和 ETG.1020 标准。

通过 slave.EoE 访问。从站不支持 EoE 时为 null。​

属性​

读写属性实时操作：getter 从设备读取当前值，setter 校验格式后立即写入设备；对偶字段重读失败或 DLL 写入失败时抛 EoEException。

类别属性类型读写说明
能力CanSendFramebool只读是否支持发送以太网帧
CanReceiveFramebool只读是否支持接收以太网帧
CanSetIPbool只读是否支持设置 IP 参数
CanGetIPbool只读是否支持获取 IP 参数
地址IPIPAddress?读写IP 地址（仅 IPv4）
SubnetIPAddress?读写子网掩码
GatewayIPAddress?读写默认网关
MACstring?读写MAC 地址（格式 "AA:BB:CC:DD:EE:FF"）
DNSDNSIPAddress?读写DNS 服务器地址
DNSNamestring?读写DNS 名称
帧选项TimeAppendedbool读写发送帧是否附加时间戳（ETG.1000.6 §5.7），默认 false
TimeRequestedbool读写接收帧时是否请求从站附加时间戳（ETG.1000.6 §5.7），默认 false
过滤InhibitBroadcastbool读写SetAddressFilters 下发时的 InhibitBroadcast 标志（ETG.1020），默认 false
超时DefaultTimeoutMsint（常量）只读帧收发与过滤方法的默认超时常量，500 毫秒

示例：

using System.Net;

if (slave.EoE != null)
{
    // 读取
    Console.WriteLine($"IP: {slave.EoE.IP}");
    Console.WriteLine($"MAC: {slave.EoE.MAC}");

    // 写入
    slave.EoE.IP = IPAddress.Parse("192.168.1.100");
    slave.EoE.Subnet = IPAddress.Parse("255.255.255.0");
    slave.EoE.Gateway = IPAddress.Parse("192.168.1.1");
    slave.EoE.MAC = "AA:BB:CC:DD:EE:FF";
    slave.EoE.DNS = IPAddress.Parse("8.8.8.8");
    slave.EoE.DNSName = "dns.google";
}

地址过滤器 (ETG.1020)​

GetAddressFilters(byte[]? macFilterMask = null, int timeoutMs = DefaultTimeoutMs)​

using System.Net.NetworkInformation;

public List<PhysicalAddress> GetAddressFilters(byte[]? macFilterMask = null, int timeoutMs = DefaultTimeoutMs)

获取 MAC 地址过滤器列表。macFilterMask 为可选的 MAC 过滤掩码参数（当前版本未传给从站，仅占位）。读取失败返回空列表并记日志，空列表不等于未配置过滤器。

SetAddressFilters(IList<PhysicalAddress> filters, byte[]? macFilterMasks = null, int timeoutMs = DefaultTimeoutMs)​

using System.Net.NetworkInformation;

public bool SetAddressFilters(IList<PhysicalAddress> filters, byte[]? macFilterMasks = null, int timeoutMs = DefaultTimeoutMs)

设置地址过滤器列表（最多 15 条）。macFilterMasks 为可选的 MAC 过滤掩码集合（最多 3 条 6 字节掩码；不传时按精确匹配设置）。InhibitBroadcast 标志取自 InhibitBroadcast 属性。

AddAddressFilter / RemoveAddressFilter / ClearAddressFilters​

using System.Net.NetworkInformation;

public bool AddAddressFilter(PhysicalAddress mac, int timeoutMs = DefaultTimeoutMs)
public bool RemoveAddressFilter(PhysicalAddress mac, int timeoutMs = DefaultTimeoutMs)
public bool ClearAddressFilters(int timeoutMs = DefaultTimeoutMs)

示例：

using System.Net.NetworkInformation;

var mac = PhysicalAddress.Parse("AA-BB-CC-DD-EE-FF");
slave.EoE.AddAddressFilter(mac);

var filters = slave.EoE.GetAddressFilters();
foreach (var f in filters)
    Console.WriteLine($"过滤器: {f}");

slave.EoE.ClearAddressFilters();

以太网帧收发​

SendFrame(byte[] frame, int timeoutMs = DefaultTimeoutMs)​

public bool SendFrame(byte[] frame, int timeoutMs = DefaultTimeoutMs)
public bool SendFrame(byte[] frame, byte port, int timeoutMs = DefaultTimeoutMs)

发送以太网帧。

ReceiveFrame(int timeoutMs = DefaultTimeoutMs)​

public byte[]? ReceiveFrame(int timeoutMs = DefaultTimeoutMs)
public byte[]? ReceiveFrame(byte port, int timeoutMs = DefaultTimeoutMs)

接收以太网帧。

返回值：

  • byte[]? — 接收到的帧数据，失败返回 null

SendFrameWithTimestamp(byte[] frame, ulong timestamp, int timeoutMs = DefaultTimeoutMs)​

public bool SendFrameWithTimestamp(byte[] frame, ulong timestamp, int timeoutMs = DefaultTimeoutMs)

发送以太网帧并按 ETG.1000.6 附加 DC 时间戳。分片由 SDK 完成，整帧可大于从站邮箱。

参数：

  • frame (byte[]) — 以太网帧数据
  • timestamp (ulong) — 附加的时间戳（DC 时间，纳秒）
  • timeoutMs (int) — 超时时间（毫秒）

返回值：

  • bool — 成功返回 true

Ping 测试​

Ping(IPAddress targetIp, int timeoutMs = 5000, byte ttl = 64)​

using System.Net;

public EoEPingResult Ping(IPAddress targetIp, int timeoutMs = 5000, byte ttl = 64)

通过 EoE 发送 ICMP Ping 并等待响应。

参数：

  • targetIp (IPAddress) — 目标 IP 地址
  • timeoutMs (int) — 超时时间（毫秒）
  • ttl (byte) — 生存时间

相关结构：

public class EoEPingResult
{
    public bool Success { get; set; }           // 是否成功
    public double RoundTripTimeMs { get; set; } // 往返时间（毫秒）
    public string TargetAddress { get; set; }   // 目标地址
    public byte TTL { get; set; }               // 生存时间
    public string ErrorMessage { get; set; }    // 错误信息
}

示例：

using System.Net;

var result = slave.EoE.Ping(IPAddress.Parse("192.168.1.1"));
Console.WriteLine(result.ToString());

帧接收事件​

FrameReceived​

public event EventHandler<EoEFrameEventArgs>? FrameReceived;

从站主动推送的以太网帧到达事件。订阅时自动向 DLL 注册接收回调；回调运行在 DLL 主循环线程，订阅者应尽快把数据拷贝到队列，避免阻塞。

相关结构：

public class EoEFrameEventArgs : EventArgs
{
    public ushort MasterIndex { get; }   // 主站索引
    public ushort SlaveIndex { get; }    // 源从站编号
    public byte[] Frame { get; }         // 完整以太网帧数据
    public DateTime ReceivedAt { get; }  // 接收时间戳（UTC）
}

配套方法：UnregisterFrameReceiveHook() 停止本实例的订阅（不影响其他从站）；ClearMasterFrameReceiveHook() 清除整个主站的接收钩子，通常在主站 Dispose 前调用。

完整示例​

网络配置与 Ping​

using System.Net;

if (slave.EoE != null)
{
    Console.WriteLine($"当前 IP: {slave.EoE.IP}");
    Console.WriteLine($"当前 MAC: {slave.EoE.MAC}");

    slave.EoE.IP = IPAddress.Parse("10.0.0.100");
    slave.EoE.Subnet = IPAddress.Parse("255.255.255.0");
    slave.EoE.Gateway = IPAddress.Parse("10.0.0.1");
    slave.EoE.DNS = IPAddress.Parse("10.0.0.1");

    var ping = slave.EoE.Ping(IPAddress.Parse("10.0.0.1"));
    if (ping.Success)
        Console.WriteLine($"Ping 成功: {ping.RoundTripTimeMs:F1}ms");
}

ARP 缓存管理​

SetArpEntry(IPAddress ip, byte[] mac)​

using System.Net;

public void SetArpEntry(IPAddress ip, byte[] mac)

在 SDK 本地 ARP 缓存中绑定 IP 与 MAC（手动指定下一跳 MAC，用于 Ping 帧寻址）。

参数：

  • ip (IPAddress) — IP 地址
  • mac (byte[]) — MAC 地址（6 字节）

ClearArpCache()​

public void ClearArpCache()

清除 SDK 本地 ARP 缓存（不清除从站侧缓存）。

ArpCacheTtl / ExpireArpCache()​

public static TimeSpan ArpCacheTtl { get; set; }  // 本地 ARP 缓存有效期，默认 5 分钟
public void ExpireArpCache()                       // 清除超过 ArpCacheTtl 的过期条目

首次 Ping 走广播，收到 Echo Reply 后记录源 MAC，之后同 IP 走单播；条目超过 ArpCacheTtl 自动过期。

示例：

using System.Net;

if (slave.EoE != null)
{
    // 设置静态 ARP 条目
    var ip = IPAddress.Parse("192.168.1.1");
    byte[] mac = new byte[] { 0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF };
    slave.EoE.SetArpEntry(ip, mac);

    // 清除 ARP 缓存
    slave.EoE.ClearArpCache();
}

异步方法​

每个同步方法都有对应 Async 版本，后缀 Async，多接 CancellationToken cancellationToken = default：SendFrameAsync / ReceiveFrameAsync / SendFrameWithTimestampAsync / PingAsync / GetAddressFiltersAsync / SetAddressFiltersAsync 等。

相关结构​

EoEException​

属性 setter 写入失败或对偶字段重读失败时抛出。

public class EoEException : Exception
{
    public EoEException(string message);
    public EoEException(string message, Exception innerException);
}

EoEAddressFilterConfig​

地址过滤器配置聚合结构：

using System.Net.NetworkInformation;

public class EoEAddressFilterConfig
{
    public List<PhysicalAddress> Filters { get; set; }  // MAC 过滤器列表
    public byte[]? MacFilterMask { get; set; }          // MAC 过滤掩码
    public bool InhibitBroadcast { get; set; }          // 是否抑制广播
}