程序包 com.darra.ethercat.master

类 MasterDiagnosticsInfo

java.lang.Object
com.darra.ethercat.master.MasterDiagnosticsInfo
public class MasterDiagnosticsInfo extends Object
主站诊断信息类 - 帧/错误/抖动统计使用5秒滑动窗口, 0.2秒刷新 通过 master.getDiagnosticsInfo() 访问

使用示例:

 MasterDiagnosticsInfo diag = master.getDiagnosticsInfo();
 diag.setEnabled(true);
 System.out.println("丢包率: " + diag.getPacketLossRate());
 System.out.println("频率: " + diag.getRTcnt() + " Hz");
 System.out.println("抖动: " + diag.getAvgJitterUs() + " us");

  • 方法详细资料

    • isEnabled

      public boolean isEnabled()
      获取诊断采集是否启用

    • setEnabled

      public void setEnabled(boolean enable)
      设置诊断采集开关 启用后开始记录帧计数、抖动、错误率等统计数据。 默认关闭。PDO 丢帧统计、冗余检测、DC 同步等功能不受此开关影响。

    • getPacketLossRate

      public float getPacketLossRate()
      丢包率 (0.0 ~ 1.0) — 最近 5 秒滑窗. 用户原话 (2026-04-27): "丢包率 = 发出 vs 接收, 过慢 (pipeline) 不算". 算法: max(0, ΣTX - ΣRX - 2 帧 pipeline) / ΣTX, 内核统一计算 (单一数据源). 对齐 C# PacketLossRate.

    • getLateFrameRate

      public float getLateFrameRate()
      过慢帧率 (0.0 ~ 1.0) — 最近 5 秒滑窗. idx 出 8 帧窗的 stale 帧 kernel drop, 不计入丢包. 全双工正常 pipeline 下不该出现. 对齐 C# LateFrameRate.

    • getRTcnt

      public int getRTcnt()
      获取每秒帧数 (Hz), 5秒平均

    • getErrorCnt

      public long getErrorCnt()
      获取每秒错误数, 5秒平均

    • getCycleTimeSpan

      public int getCycleTimeSpan()
      获取实际周期时间 (微秒) - 实时值

    • getAvgJitterUs

      public double getAvgJitterUs()
      获取最近5秒平均抖动 (微秒)

    • getMailboxLatencyUs

      public double getMailboxLatencyUs()
      邮箱收发延迟 - 最大 (微秒)。

      [2026-05-21 PDO 纯内核化改造] 旧 getMaxJitterUs()("应用抖动") 测的是 异步通知线程被 PDO 每周期唤醒的间隔抖动。PDO 过程数据已是纯内核 RT 收发 + GlobalIO 共享内存指针零拷贝, 应用层直接读写过程映像, 不存在"用户态每周期通知" 环节, 该指标失去意义。

      现语义: 邮箱 (CoE/SoE/FoE/EoE/AoE/VoE 等非周期、请求-响应) 事务的收发往返 时延 —— 从请求发出到响应返回的最大耗时 (最近 1 秒结算)。平均值见 getMailboxLatencyAvgUs()。

    • getMailboxLatencyAvgUs

      public double getMailboxLatencyAvgUs()
      邮箱收发延迟 - 平均 (微秒)。见 getMailboxLatencyUs()。

    • getBusCycleHz

      public long getBusCycleHz()
      获取总线频率 (Hz) - RT 帧发送频率

    • getBusMaxJitterUs

      public double getBusMaxJitterUs()
      获取总线最大抖动 (微秒)

    • getBusAvgJitterUs

      public double getBusAvgJitterUs()
      获取总线平均抖动 (微秒)

    • getBusRoundtripUs

      public double getBusRoundtripUs()
      获取报文往返延迟 (微秒, 发送→接收) 对齐 C# BusRoundtripUs

    • getBusLoadPercent

      public double getBusLoadPercent()
      获取通讯负载 (%) — 一个 PDO 周期内, 报文发送到接收占用的时间百分比. 计算: BusRoundtripUs / CycleTimeSpan × 100. 含义: 无效输入：'<'30% 健康, 链路宽裕 30-70% 中等, 升频率/加从站需谨慎 >70% 接近极限, 必须降频或减少从站 对齐 C# BusLoadPercent.

    • getBusCleanMaxJitterUs

      public double getBusCleanMaxJitterUs()
      获取总线干净最大抖动 (微秒, 排除SMI) 对齐 C# BusCleanMaxJitterUs

    • getSmiCount

      public long getSmiCount()
      获取SMI累计次数 对齐 C# SmiCount

    • getSmiPeakUs

      public double getSmiPeakUs()
      获取SMI峰值抖动 (微秒) 对齐 C# SmiPeakUs

    • isPrimaryPortOk

      public boolean isPrimaryPortOk()
      主端口是否正常 (有流量且5秒内无错误)

    • isSecondaryPortOk

      public boolean isSecondaryPortOk()
      副端口是否正常 (有流量且5秒内无错误, 无冗余时始终 false)

    • getPrimaryPortErrors

      public long getPrimaryPortErrors()
      主端口最近5秒错误数

    • getSecondaryPortErrors

      public long getSecondaryPortErrors()
      副端口最近5秒错误数

    • isRedundancyActive

      public boolean isRedundancyActive()
      冗余是否激活 (双端口均有流量)

    • getWorstSlaveIndex

      public int getWorstSlaveIndex()
      获取最差链路质量的从站索引

    • getWorstLinkQuality

      public short getWorstLinkQuality()
      获取最差链路质量百分比 (0-100%)

    • getSyncWindowThreshold

      public int getSyncWindowThreshold()
      获取 DC 同步窗口阈值 (纳秒)

    • setSyncWindowThreshold

      public void setSyncWindowThreshold(int thresholdNs)
      设置 DC 同步窗口阈值 (纳秒), 超过阈值触发 DCSyncLost 事件

    • reset

      public void reset()
      重置所有诊断统计

    • GetSnapshot

      public MasterDiagnosticsInfo.DiagnosticsSnapshot GetSnapshot()
      获取诊断数据的一致快照 一次调用返回所有诊断指标的快照, 避免多次单独读取导致数据不一致
      返回:
      诊断快照

    • readSlaveErrorCounters

      public EtherCATTypes.SlaveErrorCounters readSlaveErrorCounters(int slaveIndex)
      读取指定从站的错误计数器 (寄存器 0x0300-0x030B)
      参数:
      slaveIndex - 从站编号 (1-based)
      返回:
      错误计数器数据

    • getPDO

      public MasterDiagnosticsInfo.MasterPDODiagnostics getPDO()
      获取 PDO 丢帧诊断 通过 master.getDiagnosticsInfo().getPDO() 访问

    • getBreakPoint

      public MasterDiagnosticsInfo.BreakPointInfo getBreakPoint()
      获取当前故障点, 有故障时返回第一个故障点, 无故障返回 null

    • getAllBreakPoints

      public MasterDiagnosticsInfo.BreakPointInfo[] getAllBreakPoints()
      获取所有故障点 (断线 + CRC 故障)

    • getTopologyMode

      public int getTopologyMode()
      获取原生拓扑模式字节 直接读取摘要结构的 topology_mode 字段 (由内核拓扑检测写入). 取值: 0=线性, 1=环形, 2=环+分支. 失败返回 0xFF.
      返回:
      原生 topology_mode 字节 (无符号, 0-255)

    • getTopologyDescription

      public String getTopologyDescription()
      获取拓扑描述字符串 读取原生 topology_mode 字节, 翻译由 DLL 支撑 (对齐 C#/C++/C/Rust SDK, 它们都下沉到 DLL EcDiagStrings_TopologyDescription).
      返回:
      拓扑描述: "线性" / "环形" / "环+分支", 未知或 DLL 不可用时 "未知"

    • getTimingMode

      public String getTimingMode()
      获取时序模式描述
      返回:
      时序模式字符串: "FreeRun" / "DC Sync0" / "DC Sync01"

    • getRingMode

      public String getRingMode()
      获取环网模式描述
      返回:
      环网模式: "无冗余" / "双向冗余" / "降级(仅primary)"

    • toString

      public String toString()
      覆盖:
      toString 在类中 Object