Auto: twincat-3.2 — cycle-time / jitter / PLC-state diagnostics

Closes #314

src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDeviceDiagnostics.cs

@@ -0,0 +1,51 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+/// <summary>
+///     Per-device runtime diagnostics surfaced by the TwinCAT probe loop (PR 3.2 / issue #314).
+///     Built by reading four well-known system symbols once per probe interval and stashed on
+///     <see cref="TwinCATDriver.DeviceState.LastDiagnostics"/> alongside the existing reachability
+///     state. The driver also folds the latest snapshot into
+///     <see cref="Core.Abstractions.DriverHealth.Diagnostics"/> so the cross-driver
+///     <c>driver-diagnostics</c> RPC (introduced for Modbus task #154) can render TwinCAT
+///     cycle-time / jitter / online-change counters next to its peers without a per-driver
+///     special-case.
+/// </summary>
+/// <param name="AppName">
+///     Value of <c>TwinCAT_SystemInfoVarList._AppInfo.AppName</c>. Identifies the running PLC
+///     application (e.g. <c>"Plc1"</c>) so an operator can tell which project is loaded against
+///     the AMS target.
+/// </param>
+/// <param name="OnlineChangeCnt">
+///     Value of <c>TwinCAT_SystemInfoVarList._AppInfo.OnlineChangeCnt</c>. Increments on every
+///     accepted online-change. Diffing the value across probe ticks lets operators (and the
+///     driver itself) react to runtime symbol-table churn — see the
+///     <c>TwinCAT.OnlineChangeCntDelta</c> diagnostic key.
+/// </param>
+/// <param name="CycleTimeMs">
+///     Value of <c>TwinCAT_SystemInfoVarList._TaskInfo[1].CycleTime</c> after the
+///     100 ns → ms conversion. Configured task period; constant under normal operation.
+/// </param>
+/// <param name="LastExecTimeMs">
+///     Value of <c>TwinCAT_SystemInfoVarList._TaskInfo[1].LastExecTime</c> after the
+///     100 ns → ms conversion. Wall-clock time the last task tick spent running. Compared to
+///     <see cref="CycleTimeMs"/> to surface jitter / overrun.
+/// </param>
+/// <param name="JitterMs">
+///     <c>LastExecTimeMs - CycleTimeMs</c>. Positive values indicate the task overran its
+///     configured cycle (potential cycle exceedance); negative / zero values are healthy.
+/// </param>
+/// <param name="UpdatedAt">UTC instant the snapshot was captured.</param>
+/// <remarks>
+///     Each field is best-effort — the probe wraps individual symbol reads in try/catch so a
+///     runtime that doesn't expose <c>_TaskInfo[1]</c> (older TwinCAT 2 builds) still produces a
+///     partial snapshot with a non-null <see cref="AppName"/> + <see cref="OnlineChangeCnt"/>.
+///     Missing reads fall back to the previous snapshot's value (or the type default for the
+///     first probe tick).
+/// </remarks>
+public sealed record TwinCATDeviceDiagnostics(
+    string? AppName,
+    uint OnlineChangeCnt,
+    double CycleTimeMs,
+    double LastExecTimeMs,
+    double JitterMs,
+    DateTimeOffset UpdatedAt);