task-galaxy-e2e branch — non-FOCAS work-in-progress snapshot

Catch-all commit for pending work on the task-galaxy-e2e branch that wasn't part of the FOCAS migration. Grouping by topic so future per-topic commits can be cherry-picked if needed. TwinCAT - src/.../Driver.TwinCAT/AdsTwinCATClient.cs + TwinCATDriverFactoryExtensions.cs: factory-registration extensions + ADS client refinements. - src/.../Driver.TwinCAT.Cli/Commands/BrowseCommand.cs: new browse command for the TwinCAT test-client CLI. - tests/.../Driver.TwinCAT.IntegrationTests/TwinCAT3SmokeTests.cs + TwinCatProject/: fixture scaffold with a minimal POU + README pointing at the TCBSD/ESXi VM for e2e. - docs/Driver.TwinCAT.Cli.md + docs/drivers/TwinCAT-Test-Fixture.md: documentation for the above. - docs/v3/twincat-backlog.md: forward-looking backlog seed. Admin UI + fleet status - src/.../Admin/Components/Pages/Clusters/DriversTab.razor + Hosts.razor: UI refresh for fleet-status rendering. - src/.../Admin/Hubs/FleetStatusHub.cs + FleetStatusPoller.cs + Admin/Program.cs: SignalR hub + poller plumbing for live fleet data. - tests/.../Admin.Tests/FleetStatusPollerTests.cs: poller coverage. Server + redundancy runtime (Phase 6.3 follow-ups) - src/.../Server/Hosting/RedundancyPublisherHostedService.cs: HostedService that owns the RedundancyStatePublisher lifecycle + wires peer reachability. - src/.../Server/Redundancy/ServerRedundancyNodeWriter.cs: OPC UA variable-node writer binding ServiceLevel + ServerUriArray to the publisher's events. - src/.../Server/Program.cs + Server.csproj: hosted-service registration. - tests/.../Server.Tests/ServerRedundancyNodeWriterTests.cs + Server.Tests.csproj: coverage for the above. Configuration - src/.../Configuration/Validation/DraftValidator.cs + tests/.../Configuration.Tests/DraftValidatorTests.cs: draft-validation refinements. E2E scripts (shared infrastructure) - scripts/e2e/README.md + _common.ps1 + test-all.ps1: shared helpers + the all-drivers test-all runner. - scripts/e2e/test-opcuaclient.ps1: OPC UA Client e2e runner. Docs - docs/v2/implementation/phase-6-{1,2,3,4}*.md + exit-gate-phase-{3,7}.md: phase-gate + implementation doc updates. - docs/v2/plan.md: top-level plan refresh. - docs/v2/redundancy-interop-playbook.md: client interop playbook for the Phase 6.3 redundancy-runtime work. Two orphan FOCAS docs remain on disk but deliberately unstaged — docs/v2/focas-deployment.md and docs/v2/implementation/focas-simulator-plan.md describe the now-retired Tier-C topology and should either be rewritten or deleted in a follow-up. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-24 14:12:19 -04:00
parent 4b0664bd55
commit 69e0d02c72
58 changed files with 3070 additions and 247 deletions
--- a/src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs
+++ b/src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs
@@ -48,6 +48,22 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
    {
        try
        {
+            // Bit-indexed BOOL — TwinCAT's symbol table doesn't expose "WordVar.N" as its
+            // own symbolic entry (ADS returns DeviceSymbolNotFound), so we read the parent
+            // container as its widest unsigned primitive and extract the bit locally. The
+            // .N suffix added by TwinCATSymbolPath.ToAdsSymbolName needs to come back off
+            // first. uint covers WORD / DWORD containers; BYTE-sized bit containers are
+            // rare in real code and promoting to uint is harmless for them.
+            if (bitIndex is int bit && type == TwinCATDataType.Bool)
+            {
+                var parent = StripBitSuffix(symbolPath);
+                var parentResult = await _client.ReadValueAsync(parent, typeof(uint), cancellationToken)
+                    .ConfigureAwait(false);
+                if (parentResult.ErrorCode != AdsErrorCode.NoError)
+                    return (null, TwinCATStatusMapper.MapAdsError((uint)parentResult.ErrorCode));
+                return (ExtractBit(parentResult.Value, bit), TwinCATStatusMapper.Good);
+            }
+
            var clrType = MapToClrType(type);
            var result = await _client.ReadValueAsync(symbolPath, clrType, cancellationToken)
                .ConfigureAwait(false);
@@ -55,11 +71,7 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
            if (result.ErrorCode != AdsErrorCode.NoError)
                return (null, TwinCATStatusMapper.MapAdsError((uint)result.ErrorCode));

-            var value = result.Value;
-            if (bitIndex is int bit && type == TwinCATDataType.Bool && value is not bool)
-                value = ExtractBit(value, bit);
-
-            return (value, TwinCATStatusMapper.Good);
+            return (result.Value, TwinCATStatusMapper.Good);
        }
        catch (AdsErrorException ex)
        {
@@ -67,6 +79,15 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
        }
    }

+    private static string StripBitSuffix(string symbolPath)
+    {
+        var lastDot = symbolPath.LastIndexOf('.');
+        if (lastDot < 0) return symbolPath;
+        return int.TryParse(symbolPath.AsSpan(lastDot + 1), out _)
+            ? symbolPath[..lastDot]
+            : symbolPath;
+    }
+
    public async Task<uint> WriteValueAsync(
        string symbolPath,
        TwinCATDataType type,
@@ -115,12 +136,13 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
        CancellationToken cancellationToken)
    {
        var clrType = MapToClrType(type);
-        // NotificationSettings takes cycle + max-delay in 100ns units. AdsTransMode.OnChange
-        // fires when the value differs; OnCycle fires every cycle. OnChange is the right default
-        // for OPC UA data-change semantics — the PLC already has the best view of "has this
+        // NotificationSettings takes cycle + max-delay in milliseconds (Beckhoff InfoSys
+        // tcadsnetref/7313319051 — "The unit is 1ms"). AdsTransMode.OnChange fires when
+        // the value differs; OnCycle fires every cycle. OnChange is the right default for
+        // OPC UA data-change semantics — the PLC already has the best view of "has this
        // changed" so we let it decide.
-        var cycleTicks = (uint)Math.Max(1, cycleTime.Ticks / TimeSpan.TicksPerMillisecond * 10_000);
-        var settings = new NotificationSettings(AdsTransMode.OnChange, (int)cycleTicks, 0);
+        var cycleMs = (int)Math.Max(1, cycleTime.TotalMilliseconds);
+        var settings = new NotificationSettings(AdsTransMode.OnChange, cycleMs, 0);

        // AddDeviceNotificationExAsync returns Task<ResultHandle>; AdsNotificationEx fires
        // with the handle as part of the event args so we use the handle as the correlation
@@ -172,27 +194,36 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
        }
    }

-    private static TwinCATDataType? MapSymbolTypeName(string? typeName) => typeName switch
+    private static TwinCATDataType? MapSymbolTypeName(string? typeName)
    {
-        "BOOL" or "BIT" => TwinCATDataType.Bool,
-        "SINT" or "BYTE" => TwinCATDataType.SInt,
-        "USINT" => TwinCATDataType.USInt,
-        "INT" or "WORD" => TwinCATDataType.Int,
-        "UINT" => TwinCATDataType.UInt,
-        "DINT" or "DWORD" => TwinCATDataType.DInt,
-        "UDINT" => TwinCATDataType.UDInt,
-        "LINT" or "LWORD" => TwinCATDataType.LInt,
-        "ULINT" => TwinCATDataType.ULInt,
-        "REAL" => TwinCATDataType.Real,
-        "LREAL" => TwinCATDataType.LReal,
-        "STRING" => TwinCATDataType.String,
-        "WSTRING" => TwinCATDataType.WString,
-        "TIME" => TwinCATDataType.Time,
-        "DATE" => TwinCATDataType.Date,
-        "DT" or "DATE_AND_TIME" => TwinCATDataType.DateTime,
-        "TOD" or "TIME_OF_DAY" => TwinCATDataType.TimeOfDay,
-        _ => null, // UDTs / FB instances / arrays / pointers — out of atomic scope
-    };
+        if (typeName is null) return null;
+        // SymbolLoader emits STRING(80) / WSTRING(80) with the declared bound baked into
+        // the type name — strip the "(...)" suffix so sized strings map onto the bare
+        // String/WString atom the driver speaks.
+        var paren = typeName.IndexOf('(');
+        var bare = paren > 0 ? typeName[..paren] : typeName;
+        return bare switch
+        {
+            "BOOL" or "BIT" => TwinCATDataType.Bool,
+            "SINT" or "BYTE" => TwinCATDataType.SInt,
+            "USINT" => TwinCATDataType.USInt,
+            "INT" or "WORD" => TwinCATDataType.Int,
+            "UINT" => TwinCATDataType.UInt,
+            "DINT" or "DWORD" => TwinCATDataType.DInt,
+            "UDINT" => TwinCATDataType.UDInt,
+            "LINT" or "LWORD" => TwinCATDataType.LInt,
+            "ULINT" => TwinCATDataType.ULInt,
+            "REAL" => TwinCATDataType.Real,
+            "LREAL" => TwinCATDataType.LReal,
+            "STRING" => TwinCATDataType.String,
+            "WSTRING" => TwinCATDataType.WString,
+            "TIME" => TwinCATDataType.Time,
+            "DATE" => TwinCATDataType.Date,
+            "DT" or "DATE_AND_TIME" => TwinCATDataType.DateTime,
+            "TOD" or "TIME_OF_DAY" => TwinCATDataType.TimeOfDay,
+            _ => null, // UDTs / FB instances / arrays / pointers — out of atomic scope
+        };
+    }

    private static bool IsSymbolWritable(ISymbol symbol)
    {
--- a/src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriverFactoryExtensions.cs
+++ b/src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriverFactoryExtensions.cs
@@ -0,0 +1,120 @@
+using System.Text.Json;
+using ZB.MOM.WW.OtOpcUa.Core.Hosting;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+/// <summary>
+///     Static factory registration helper for <see cref="TwinCATDriver"/>. Server's Program.cs
+///     calls <see cref="Register"/> once at startup; the bootstrapper materialises TwinCAT
+///     DriverInstance rows from the central config DB into live driver instances. Mirrors
+///     <c>S7DriverFactoryExtensions</c> / <c>AbCipDriverFactoryExtensions</c>.
+/// </summary>
+public static class TwinCATDriverFactoryExtensions
+{
+    public const string DriverTypeName = "TwinCAT";
+
+    public static void Register(DriverFactoryRegistry registry)
+    {
+        ArgumentNullException.ThrowIfNull(registry);
+        registry.Register(DriverTypeName, CreateInstance);
+    }
+
+    internal static TwinCATDriver CreateInstance(string driverInstanceId, string driverConfigJson)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(driverInstanceId);
+        ArgumentException.ThrowIfNullOrWhiteSpace(driverConfigJson);
+
+        var dto = JsonSerializer.Deserialize<TwinCATDriverConfigDto>(driverConfigJson, JsonOptions)
+            ?? throw new InvalidOperationException(
+                $"TwinCAT driver config for '{driverInstanceId}' deserialised to null");
+
+        var options = new TwinCATDriverOptions
+        {
+            Devices = dto.Devices is { Count: > 0 }
+                ? [.. dto.Devices.Select(d => new TwinCATDeviceOptions(
+                    HostAddress: d.HostAddress ?? throw new InvalidOperationException(
+                        $"TwinCAT config for '{driverInstanceId}' has a device missing HostAddress"),
+                    DeviceName: d.DeviceName))]
+                : [],
+            Tags = dto.Tags is { Count: > 0 }
+                ? [.. dto.Tags.Select(t => BuildTag(t, driverInstanceId))]
+                : [],
+            Probe = new TwinCATProbeOptions
+            {
+                Enabled = dto.Probe?.Enabled ?? true,
+                Interval = TimeSpan.FromMilliseconds(dto.Probe?.IntervalMs ?? 5_000),
+                Timeout = TimeSpan.FromMilliseconds(dto.Probe?.TimeoutMs ?? 2_000),
+            },
+            Timeout = TimeSpan.FromMilliseconds(dto.TimeoutMs ?? 2_000),
+            UseNativeNotifications = dto.UseNativeNotifications ?? true,
+            EnableControllerBrowse = dto.EnableControllerBrowse ?? false,
+        };
+
+        return new TwinCATDriver(options, driverInstanceId);
+    }
+
+    private static TwinCATTagDefinition BuildTag(TwinCATTagDto t, string driverInstanceId) =>
+        new(
+            Name: t.Name ?? throw new InvalidOperationException(
+                $"TwinCAT config for '{driverInstanceId}' has a tag missing Name"),
+            DeviceHostAddress: t.DeviceHostAddress ?? throw new InvalidOperationException(
+                $"TwinCAT tag '{t.Name}' in '{driverInstanceId}' missing DeviceHostAddress"),
+            SymbolPath: t.SymbolPath ?? throw new InvalidOperationException(
+                $"TwinCAT tag '{t.Name}' in '{driverInstanceId}' missing SymbolPath"),
+            DataType: ParseEnum<TwinCATDataType>(t.DataType, t.Name, driverInstanceId, "DataType"),
+            Writable: t.Writable ?? true,
+            WriteIdempotent: t.WriteIdempotent ?? false);
+
+    private static T ParseEnum<T>(string? raw, string? tagName, string driverInstanceId, string field)
+        where T : struct, Enum
+    {
+        if (string.IsNullOrWhiteSpace(raw))
+            throw new InvalidOperationException(
+                $"TwinCAT tag '{tagName ?? "<unnamed>"}' in '{driverInstanceId}' missing {field}");
+        return Enum.TryParse<T>(raw, ignoreCase: true, out var v)
+            ? v
+            : throw new InvalidOperationException(
+                $"TwinCAT tag '{tagName}' has unknown {field} '{raw}'. " +
+                $"Expected one of {string.Join(", ", Enum.GetNames<T>())}");
+    }
+
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        PropertyNameCaseInsensitive = true,
+        ReadCommentHandling = JsonCommentHandling.Skip,
+        AllowTrailingCommas = true,
+    };
+
+    internal sealed class TwinCATDriverConfigDto
+    {
+        public int? TimeoutMs { get; init; }
+        public bool? UseNativeNotifications { get; init; }
+        public bool? EnableControllerBrowse { get; init; }
+        public List<TwinCATDeviceDto>? Devices { get; init; }
+        public List<TwinCATTagDto>? Tags { get; init; }
+        public TwinCATProbeDto? Probe { get; init; }
+    }
+
+    internal sealed class TwinCATDeviceDto
+    {
+        public string? HostAddress { get; init; }
+        public string? DeviceName { get; init; }
+    }
+
+    internal sealed class TwinCATTagDto
+    {
+        public string? Name { get; init; }
+        public string? DeviceHostAddress { get; init; }
+        public string? SymbolPath { get; init; }
+        public string? DataType { get; init; }
+        public bool? Writable { get; init; }
+        public bool? WriteIdempotent { get; init; }
+    }
+
+    internal sealed class TwinCATProbeDto
+    {
+        public bool? Enabled { get; init; }
+        public int? IntervalMs { get; init; }
+        public int? TimeoutMs { get; init; }
+    }
+}
--- a/src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.csproj
+++ b/src/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.csproj
@@ -14,6 +14,7 @@

    <ItemGroup>
        <ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Core.Abstractions\ZB.MOM.WW.OtOpcUa.Core.Abstractions.csproj"/>
+        <ProjectReference Include="..\ZB.MOM.WW.OtOpcUa.Core\ZB.MOM.WW.OtOpcUa.Core.csproj"/>
    </ItemGroup>

    <ItemGroup>
@@ -26,6 +27,7 @@

    <ItemGroup>
        <InternalsVisibleTo Include="ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests"/>
+        <InternalsVisibleTo Include="ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.IntegrationTests"/>
    </ItemGroup>

 </Project>