From 3fcbc70cbac1ff38d270982cf95f560b6557cf4f Mon Sep 17 00:00:00 2001
From: Joseph Doherty <dohejw01@gmail.com>
Date: Tue, 16 Jun 2026 19:38:49 -0400
Subject: [PATCH] feat(focas): add cnc_getfigure per-axis position-figure
 client binding

---
 .../ZB.MOM.WW.OtOpcUa.Driver.FOCAS/IFocasClient.cs  | 13 +++++++++++--
 .../Wire/WireFocasClient.cs                         | 12 ++++++++++++
 .../FakeFocasClient.cs                              |  7 +++++++
 3 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/IFocasClient.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/IFocasClient.cs
index fedca8d4..ce5486c1 100644
--- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/IFocasClient.cs
+++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/IFocasClient.cs
@@ -153,6 +153,15 @@ public interface IFocasClient : IDisposable
     /// </summary>
     /// <param name="cancellationToken">The cancellation token.</param>
     Task<IReadOnlyList<int>> GetSpindleMaxRpmsAsync(CancellationToken cancellationToken);
+
+    /// <summary>
+    ///     Read the per-axis position decimal-place figure via <c>cnc_getfigure</c>. The returned
+    ///     list is parallel to <see cref="GetAxisNamesAsync"/> (index = axis). An EMPTY list means the
+    ///     CNC/backend does not report figures — the driver then falls back to the configured
+    ///     <c>PositionDecimalPlaces</c>. Values are clamped non-negative.
+    /// </summary>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    Task<IReadOnlyList<int>> GetPositionFiguresAsync(CancellationToken cancellationToken);
 }
 
 /// <summary>One servo-meter entry — one axis's current load percentage.</summary>
@@ -217,8 +226,8 @@ public sealed record FocasSpindleName(string Name, string Suffix1, string Suffix
 /// <summary>
 ///     Fast-poll bundle for one axis. Position values are scaled integers; the caller
 ///     divides by <c>10^DecimalPlaces</c> to get the decimal value. DecimalPlaces is
-///     currently left to the caller to supply (via device config or a future
-///     <c>cnc_getfigure</c> path once that export lands).
+///     supplied by the caller — either via device config (<c>PositionDecimalPlaces</c>) or
+///     the per-axis <see cref="IFocasClient.GetPositionFiguresAsync"/> (<c>cnc_getfigure</c>) path.
 /// </summary>
 /// <summary>
 ///     Program + operation-mode snapshot. Name is the currently-executing
diff --git a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Wire/WireFocasClient.cs b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Wire/WireFocasClient.cs
index 58eb4682..003a146e 100644
--- a/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Wire/WireFocasClient.cs
+++ b/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS/Wire/WireFocasClient.cs
@@ -284,6 +284,18 @@ public sealed class WireFocasClient : IFocasClient
     public Task<IReadOnlyList<int>> GetSpindleMaxRpmsAsync(CancellationToken cancellationToken) =>
         ReadSpindleMetricAsync((sel, ct) => _wire.ReadSpindleMaxRpmAsync(sel, ct), cancellationToken);
 
+    /// <summary>Gets the per-axis position decimal-place figures via <c>cnc_getfigure</c>.</summary>
+    /// <param name="cancellationToken">Cancellation token for the operation.</param>
+    /// <returns>
+    ///     An empty list — the managed FOCAS/2 Ethernet wire client (<see cref="FocasWireClient"/>)
+    ///     does not currently expose the <c>cnc_getfigure</c> command, so this backend reports no
+    ///     per-axis figures. Per the <see cref="IFocasClient.GetPositionFiguresAsync"/> contract an
+    ///     empty list signals the driver to fall back to the configured <c>PositionDecimalPlaces</c>.
+    ///     Never throws — figure reads degrade to the config knob rather than faulting.
+    /// </returns>
+    public Task<IReadOnlyList<int>> GetPositionFiguresAsync(CancellationToken cancellationToken) =>
+        Task.FromResult<IReadOnlyList<int>>(Array.Empty<int>());
+
     private static async Task<IReadOnlyList<int>> ReadSpindleMetricAsync(
         Func<short, CancellationToken, Task<FocasResult<IReadOnlyList<WireSpindleMetric>>>> call,
         CancellationToken cancellationToken)
diff --git a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FakeFocasClient.cs b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FakeFocasClient.cs
index 3cd1ed28..a488df99 100644
--- a/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FakeFocasClient.cs
+++ b/tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.FOCAS.Tests/FakeFocasClient.cs
@@ -153,6 +153,13 @@ internal class FakeFocasClient : IFocasClient
     public virtual Task<IReadOnlyList<int>> GetSpindleMaxRpmsAsync(CancellationToken ct) =>
         Task.FromResult<IReadOnlyList<int>>([.. SpindleMaxRpms]);
 
+    /// <summary>Gets or sets the per-axis position decimal-place figures returned by <see cref="GetPositionFiguresAsync"/>.</summary>
+    public IReadOnlyList<int> PositionFigures { get; set; } = [];
+    /// <summary>Gets the per-axis position decimal-place figures asynchronously.</summary>
+    /// <param name="ct">The cancellation token.</param>
+    public virtual Task<IReadOnlyList<int>> GetPositionFiguresAsync(CancellationToken ct) =>
+        Task.FromResult(PositionFigures);
+
     /// <summary>Disposes the client.</summary>
     public virtual void Dispose()
     {