dohertj2/lmxopcua
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Auto: focas-f1f — figure scaling + diagnostics

Browse Source 
Closes #262
This commit is contained in:
Joseph Doherty
2026-04-25 15:01:37 -04:00
parent 63a79791cd
commit 1abf743a9f
6 changed files with 555 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

161
src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasDriver.cs
View File

@@ -40,6 +40,8 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
new(StringComparer.OrdinalIgnoreCase);
private readonly Dictionary<string, string> _currentBlockNodesByName =
new(StringComparer.OrdinalIgnoreCase);
private readonly Dictionary<string, (string Host, string Field)> _diagnosticsNodesByName =
new(StringComparer.OrdinalIgnoreCase);
private DriverHealth _health = new(DriverState.Unknown, null, null);
/// <summary>
@@ -95,6 +97,23 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
/// </summary>
private static readonly string[] WorkOffsetAxisNames = ["X", "Y", "Z"];
/// <summary>
/// Names of the five fixed-tree <c>Diagnostics/</c> child nodes per device — runtime
/// counters surfaced for operator visibility (issue #262). Order matters for
/// deterministic discovery output.
/// <list type="bullet">
/// <item><c>ReadCount</c> (Int64) — successful probe ticks since init</item>
/// <item><c>ReadFailureCount</c> (Int64) — failed probe ticks since init</item>
/// <item><c>LastErrorMessage</c> (String) — text of the last probe / read failure</item>
/// <item><c>LastSuccessfulRead</c> (DateTime) — UTC timestamp of the last good probe tick</item>
/// <item><c>ReconnectCount</c> (Int64) — wire reconnects observed since init</item>
/// </list>
/// </summary>
private static readonly string[] DiagnosticsFieldNames =
[
"ReadCount", "ReadFailureCount", "LastErrorMessage", "LastSuccessfulRead", "ReconnectCount",
];
public event EventHandler<DataChangeEventArgs>? OnDataChange;
public event EventHandler<HostStatusChangedEventArgs>? OnHostStatusChanged;
@@ -197,6 +216,13 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
device.Options.HostAddress;
_currentBlockNodesByName[CurrentBlockReferenceFor(device.Options.HostAddress)] =
device.Options.HostAddress;
// Diagnostics/{ReadCount, ReadFailureCount, LastErrorMessage,
// LastSuccessfulRead, ReconnectCount} — runtime counters surfaced for
// operator visibility (issue #262). Permissive across all CNC series.
foreach (var field in DiagnosticsFieldNames)
_diagnosticsNodesByName[DiagnosticsReferenceFor(device.Options.HostAddress, field)] =
(device.Options.HostAddress, field);
}
if (_options.Probe.Enabled)
@@ -244,6 +270,7 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
_offsetNodesByName.Clear();
_messagesNodesByName.Clear();
_currentBlockNodesByName.Clear();
_diagnosticsNodesByName.Clear();
_health = new DriverHealth(DriverState.Unknown, _health.LastSuccessfulRead, null);
}
@@ -326,6 +353,14 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
continue;
}
// Fixed-tree Diagnostics/ nodes — runtime counters maintained by the probe
// loop (issue #262). No wire call here.
if (_diagnosticsNodesByName.TryGetValue(reference, out var diagKey))
{
results[i] = ReadDiagnosticsField(diagKey.Host, diagKey.Field, now);
continue;
}
if (!_tagsByName.TryGetValue(reference, out var def))
{
results[i] = new DataValueSnapshot(null, FocasStatusMapper.BadNodeIdUnknown, null, now);
@@ -599,10 +634,38 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
IsHistorized: false,
IsAlarm: false,
WriteIdempotent: false));
// Fixed-tree Diagnostics/ subfolder — 5 read-only counters surfaced for
// operator visibility (issue #262). ReadCount / ReadFailureCount /
// ReconnectCount are Int64; LastErrorMessage is String;
// LastSuccessfulRead is DateTime. Permissive across CNC series — every
// device gets the same shape.
var diagnosticsFolder = deviceFolder.Folder("Diagnostics", "Diagnostics");
foreach (var field in DiagnosticsFieldNames)
{
var fullRef = DiagnosticsReferenceFor(device.HostAddress, field);
diagnosticsFolder.Variable(field, field, new DriverAttributeInfo(
FullName: fullRef,
DriverDataType: DiagnosticsFieldType(field),
IsArray: false,
ArrayDim: null,
SecurityClass: SecurityClassification.ViewOnly,
IsHistorized: false,
IsAlarm: false,
WriteIdempotent: false));
}
}
return Task.CompletedTask;
}
private static DriverDataType DiagnosticsFieldType(string field) => field switch
{
"ReadCount" or "ReadFailureCount" or "ReconnectCount" => DriverDataType.Int64,
"LastErrorMessage" => DriverDataType.String,
"LastSuccessfulRead" => DriverDataType.DateTime,
_ => DriverDataType.String,
};
private static string StatusReferenceFor(string hostAddress, string field) =>
$"{hostAddress}::Status/{field}";
@@ -627,6 +690,9 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
private static string CurrentBlockReferenceFor(string hostAddress) =>
$"{hostAddress}::Program/CurrentBlock";
private static string DiagnosticsReferenceFor(string hostAddress, string field) =>
$"{hostAddress}::Diagnostics/{field}";
private static ushort? OverrideParamFor(FocasOverrideParameters p, string field) => field switch
{
"Feed" => p.FeedParam,
@@ -699,12 +765,23 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
while (!ct.IsCancellationRequested)
{
var success = false;
string? failureMessage = null;
try
{
var client = await EnsureConnectedAsync(state, ct).ConfigureAwait(false);
success = await client.ProbeAsync(ct).ConfigureAwait(false);
if (success)
{
// Refresh figure-scaling cache once per session (issue #262). The
// increment system rarely changes mid-session; re-reading every probe
// tick would waste a wire call. Best-effort — null result leaves the
// previous good map in place.
if (state.FigureScaling is null)
{
var fig = await client.GetFigureScalingAsync(ct).ConfigureAwait(false);
if (fig is not null) state.FigureScaling = fig;
}
// Refresh the cached ODBST status snapshot on every probe tick — this is
// what the Status/ fixed-tree nodes serve from. Best-effort: a null result
// (older IFocasClient impls without GetStatusAsync) just leaves the cache
@@ -784,7 +861,27 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
}
}
catch (OperationCanceledException) when (ct.IsCancellationRequested) { break; }
catch { /* connect-failure path already disposed + cleared the client */ }
catch (Exception ex)
{
failureMessage = ex.Message;
/* connect-failure path already disposed + cleared the client */
}
// Diagnostics counters refreshed per probe tick (issue #262). Successful
// ticks bump ReadCount + LastSuccessfulRead; failed ticks bump
// ReadFailureCount + LastErrorMessage. The reconnect counter is bumped in
// EnsureConnectedAsync's connect path so a wedged probe doesn't double-count.
if (success)
{
Interlocked.Increment(ref state.ReadCount);
state.LastSuccessfulReadUtc = DateTime.UtcNow;
}
else
{
Interlocked.Increment(ref state.ReadFailureCount);
if (!string.IsNullOrEmpty(failureMessage))
state.LastErrorMessage = failureMessage;
}
TransitionDeviceState(state, success ? HostState.Running : HostState.Stopped);
@@ -908,6 +1005,46 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
device.LastCurrentBlockUtc, now);
}
private DataValueSnapshot ReadDiagnosticsField(string hostAddress, string field, DateTime now)
{
if (!_devices.TryGetValue(hostAddress, out var device))
return new DataValueSnapshot(null, FocasStatusMapper.BadNodeIdUnknown, null, now);
// Diagnostics counters are always Good — they're driver-internal state, not wire
// reads. LastSuccessfulRead surfaces DateTime.MinValue before the first probe
// tick rather than null because OPC UA's DateTime variant has no "unset" sentinel
// a generic client can interpret (issue #262).
object? value = field switch
{
"ReadCount" => Interlocked.Read(ref device.ReadCount),
"ReadFailureCount" => Interlocked.Read(ref device.ReadFailureCount),
"ReconnectCount" => Interlocked.Read(ref device.ReconnectCount),
"LastErrorMessage" => device.LastErrorMessage ?? string.Empty,
"LastSuccessfulRead" => device.LastSuccessfulReadUtc,
_ => null,
};
if (value is null)
return new DataValueSnapshot(null, FocasStatusMapper.BadNodeIdUnknown, null, now);
return new DataValueSnapshot(value, FocasStatusMapper.Good, now, now);
}
/// <summary>
/// Apply <c>cnc_getfigure</c>-derived decimal scaling to a raw position value.
/// Returns <paramref name="raw"/> divided by <c>10^decimalPlaces</c> when the
/// device has a cached scaling entry for <paramref name="axisName"/> AND
/// <see cref="FocasFixedTreeOptions.ApplyFigureScaling"/> is on; otherwise
/// returns the raw value as a <c>double</c>. Forward-looking — surfaced for
/// future PRs that wire up <c>Axes/{name}/AbsolutePosition</c> etc. so they
/// don't need to re-derive the policy (issue #262).
/// </summary>
internal double ApplyFigureScaling(string hostAddress, string axisName, long raw)
{
if (!_options.FixedTree.ApplyFigureScaling) return raw;
if (!_devices.TryGetValue(hostAddress, out var device)) return raw;
if (device.FigureScaling is not { } map) return raw;
if (!map.TryGetValue(axisName, out var dec) || dec <= 0) return raw;
return raw / Math.Pow(10.0, dec);
}
private void TransitionDeviceState(DeviceState state, HostState newState)
{
HostState old;
@@ -934,6 +1071,10 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
private async Task<IFocasClient> EnsureConnectedAsync(DeviceState device, CancellationToken ct)
{
if (device.Client is { IsConnected: true } c) return c;
// Reconnect counter bumps before the connect call — a successful first connect
// counts as one "establishment" so the field is non-zero from session start
// (issue #262, mirrors the convention from the AbCip / TwinCAT diagnostics).
Interlocked.Increment(ref device.ReconnectCount);
device.Client ??= _clientFactory.Create();
try
{
@@ -1028,6 +1169,24 @@ public sealed class FocasDriver : IDriver, IReadable, IWritable, ITagDiscovery,
public FocasCurrentBlockInfo? LastCurrentBlock { get; set; }
public DateTime LastCurrentBlockUtc { get; set; }
/// <summary>
/// Cached per-axis decimal-place counts from <c>cnc_getfigure</c> (issue #262).
/// Populated once per session (the increment system rarely changes mid-run);
/// served by <see cref="FocasDriver.ApplyFigureScaling"/> when a future PR
/// surfaces position values that need scaling. Keys are axis names (or
/// fallback <c>"axis{n}"</c> until <c>cnc_rdaxisname</c> integration lands).
/// </summary>
public IReadOnlyDictionary<string, int>? FigureScaling { get; set; }
// Diagnostics counters per device — surfaced under Diagnostics/ subtree (issue
// #262). Public fields rather than properties so Interlocked.Increment can
// operate on them directly. Long-typed for the OPC UA Int64 surface.
public long ReadCount;
public long ReadFailureCount;
public long ReconnectCount;
public string? LastErrorMessage;
public DateTime LastSuccessfulReadUtc;
public void DisposeClient()
{
Client?.Dispose();

28
src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FocasDriverOptions.cs
View File

@@ -11,6 +11,34 @@ public sealed class FocasDriverOptions
public IReadOnlyList<FocasTagDefinition> Tags { get; init; } = [];
public FocasProbeOptions Probe { get; init; } = new();
public TimeSpan Timeout { get; init; } = TimeSpan.FromSeconds(2);
/// <summary>
/// Fixed-tree behaviour knobs (issue #262, plan PR F1-f). Carries the
/// <c>ApplyFigureScaling</c> toggle that gates the <c>cnc_getfigure</c>
/// decimal-place division applied to position values before publishing.
/// </summary>
public FocasFixedTreeOptions FixedTree { get; init; } = new();
}
/// <summary>
/// Per-driver fixed-tree options. New installs default <see cref="ApplyFigureScaling"/>
/// to <c>true</c> so position values surface in user units (mm / inch). Existing
/// deployments that already published raw scaled integers can flip this to <c>false</c>
/// for migration parity — the operator-facing concern is that switching the flag
/// mid-deployment changes the values clients see, so the migration path is
/// documentation-only (issue #262).
/// </summary>
public sealed record FocasFixedTreeOptions
{
/// <summary>
/// When <c>true</c> (default), position values from <c>cnc_absolute</c> /
/// <c>cnc_machine</c> / <c>cnc_relative</c> / <c>cnc_distance</c> /
/// <c>cnc_actf</c> are divided by <c>10^decimalPlaces</c> per axis using the
/// <c>cnc_getfigure</c> snapshot cached at probe time. When <c>false</c>, the
/// raw integer values are published unchanged — used for migrations from
/// older drivers that didn't apply the scaling.
/// </summary>
public bool ApplyFigureScaling { get; init; } = true;
}
/// <summary>

37
src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FwlibFocasClient.cs
View File

@@ -318,6 +318,43 @@ internal sealed class FwlibFocasClient : IFocasClient
new FocasCurrentBlockInfo(TrimAnsiPadding(buf.Data)));
}
public Task<IReadOnlyDictionary<string, int>?> GetFigureScalingAsync(CancellationToken cancellationToken)
{
if (!_connected) return Task.FromResult<IReadOnlyDictionary<string, int>?>(null);
// kind=0 → position figures (absolute/relative/machine/distance share the same
// increment system per axis). cnc_rdaxisname is deferred — the wire impl keys
// by fallback "axis{n}" (1-based), the driver re-keys when it gains axis-name
// discovery in a follow-up. Issue #262, plan PR F1-f.
short count = 0;
var buf = new FwlibNative.IODBAXIS { Data = new byte[FwlibNative.MAX_AXIS * 8] };
var ret = FwlibNative.GetFigure(_handle, kind: 0, ref count, ref buf);
if (ret != 0) return Task.FromResult<IReadOnlyDictionary<string, int>?>(null);
return Task.FromResult<IReadOnlyDictionary<string, int>?>(DecodeFigureScaling(buf.Data, count));
}
/// <summary>
/// Decode the per-axis decimal-place counts from a <c>cnc_getfigure</c> reply
/// buffer. Each axis entry per <c>fwlib32.h</c> is 8 bytes laid out as
/// <c>short dec</c> + <c>short unit</c> + 4 reserved bytes; we read only
/// <c>dec</c>. Keys are 1-based <c>"axis{n}"</c> placeholders — a follow-up
/// PR can rewire to <c>cnc_rdaxisname</c> once that surface lands without
/// changing the cache contract (issue #262).
/// </summary>
internal static IReadOnlyDictionary<string, int> DecodeFigureScaling(byte[] data, short count)
{
var clamped = Math.Max((short)0, Math.Min(count, (short)FwlibNative.MAX_AXIS));
var result = new Dictionary<string, int>(clamped, StringComparer.OrdinalIgnoreCase);
for (var i = 0; i < clamped; i++)
{
var offset = i * 8;
if (offset + 2 > data.Length) break;
var dec = BinaryPrimitives.ReadInt16LittleEndian(data.AsSpan(offset, 2));
if (dec < 0 || dec > 9) dec = 0;
result[$"axis{i + 1}"] = dec;
}
return result;
}
/// <summary>
/// Decode + trim a Fanuc ANSI byte buffer. The CNC right-pads block text + opmsg
/// bodies with nulls or spaces; trim them so the round-trip through the OPC UA

44
src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/FwlibNative.cs
View File

@@ -157,6 +157,25 @@ internal static class FwlibNative
short length,
ref OPMSG3 buffer);
// ---- Figure (per-axis decimal scaling) ----
/// <summary>
/// <c>cnc_getfigure</c> — read per-axis figure info (decimal-place counts + units).
/// <paramref name="kind"/>: 0 = absolute / relative / machine position figures,
/// 1 = work-coord shift figures (per Fanuc reference). The reply struct holds
/// up to <see cref="MAX_AXIS"/> axis entries; the managed side reads the count
/// out via <paramref name="outCount"/>. Position values from <c>cnc_absolute</c>
/// / <c>cnc_machine</c> / <c>cnc_relative</c> / <c>cnc_distance</c> / <c>cnc_actf</c>
/// are scaled integers — divide by <c>10^figureinfo[axis].dec</c> for user units
/// (issue #262, plan PR F1-f).
/// </summary>
[DllImport(Library, EntryPoint = "cnc_getfigure", ExactSpelling = true)]
public static extern short GetFigure(
ushort handle,
short kind,
ref short outCount,
ref IODBAXIS figureinfo);
// ---- Currently-executing block ----
/// <summary>
@@ -298,6 +317,31 @@ internal static class FwlibNative
public byte[] Data;
}
/// <summary>
/// Maximum axis count per the FWLIB <c>fwlib32.h</c> ceiling for figure-info reads.
/// Real Fanuc CNCs cap at 8 simultaneous axes for most series; we marshal an
/// 8-entry array (matches <see cref="IODBAXIS"/>) so the call completes regardless
/// of the deployment's axis count (issue #262).
/// </summary>
public const int MAX_AXIS = 8;
/// <summary>
/// IODBAXIS — per-axis figure info read buffer for <c>cnc_getfigure</c>. Each
/// axis entry carries the decimal-place count (<c>dec</c>) the CNC reports for
/// that axis's increment system + a unit code. The managed side reads the first
/// <c>outCount</c> entries returned by FWLIB; we marshal a fixed 8-entry ceiling
/// (issue #262, plan PR F1-f).
/// </summary>
[StructLayout(LayoutKind.Sequential, Pack = 1)]
public struct IODBAXIS
{
// Each entry per fwlib32.h is { short dec, short unit, short reserved, short reserved2 }
// = 8 bytes. 8 axes * 8 bytes = 64 bytes; we marshal a fixed byte buffer + decode on
// the managed side so axis-count growth doesn't churn the P/Invoke surface.
[MarshalAs(UnmanagedType.ByValArray, SizeConst = 8 * 8)]
public byte[] Data;
}
/// <summary>ODBST — CNC status info. Machine state, alarm flags, automatic / edit mode.</summary>
[StructLayout(LayoutKind.Sequential, Pack = 1)]
public struct ODBST

13
src/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/IFocasClient.cs
View File

@@ -135,6 +135,19 @@ public interface IFocasClient : IDisposable
/// </summary>
Task<FocasCurrentBlockInfo?> GetCurrentBlockAsync(CancellationToken cancellationToken)
=> Task.FromResult<FocasCurrentBlockInfo?>(null);
/// <summary>
/// Read the per-axis decimal-place counts via <c>cnc_getfigure</c> (issue #262).
/// Returned dictionary maps axis name (or fallback <c>"axis{n}"</c> when
/// <c>cnc_rdaxisname</c> isn't available) to the decimal-place count the CNC
/// reports for that axis's increment system. Cached at bootstrap by the driver +
/// applied to position values before publishing — raw integer / 10^decimalPlaces.
/// Returns <c>null</c> when the wire client cannot supply the snapshot (older
/// transport variant) — the driver leaves the cache untouched and falls back to
/// publishing raw values.
/// </summary>
Task<IReadOnlyDictionary<string, int>?> GetFigureScalingAsync(CancellationToken cancellationToken)
=> Task.FromResult<IReadOnlyDictionary<string, int>?>(null);
}
/// <summary>