Merge TwinCAT fixes ported from ignitionoee + live-validated on the Elma PLCs

src/Drivers/Cli/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Cli/Commands/ReadCommand.cs

@@ -14,7 +14,8 @@ public sealed class ReadCommand : TwinCATTagCommandBase
     /// <summary>Gets or sets the TwinCAT symbol path to read.</summary>
     [CommandOption("symbol", 's', Description =
         "Symbol path. Program scope: 'MAIN.bStart'. Global: 'GVL.Counter'. " +
-        "Nested UDT member: 'Motor1.Status.Running'. Array element: 'Recipe[3]'.",
+        "Nested UDT member: 'Motor1.Status.Running'. Array element: 'Recipe[3]'. " +
+        "TwinCAT 2 global (keep its leading dot): '.OPC_HEARTBEAT'.",
         IsRequired = true)]
     public string SymbolPath { get; init; } = default!;
 

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/AdsTwinCATClient.cs

@@ -41,6 +41,7 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
     private readonly CancellationTokenSource _dispatchCts = new();
     private readonly Task _dispatchLoop;
     private int _disposed;
+    private bool? _stringsAreUtf8;
 
     /// <summary>
     /// Initializes a new instance of the <see cref="AdsTwinCATClient"/> class.
@@ -125,6 +126,30 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
                 return (arrResult.Value, TwinCATStatusMapper.Good);
             }
 
+            // Scalar read: check the declared type against the PLC symbol first. The symbol is
+            // resolved through the Beckhoff symbol cache (the same lookup ReadValueAsync makes
+            // internally), so this costs no extra round trip after the first read.
+            var (shape, symbol, symbolStatus) = await DescribeSymbolAsync(symbolPath, cancellationToken)
+                .ConfigureAwait(false);
+            if (symbolStatus != TwinCATStatusMapper.Good) return (null, symbolStatus);
+            if (TwinCATTypeGuard.CheckRead(type, shape) is not null)
+                return (null, TwinCATStatusMapper.BadTypeMismatch);
+
+            // A STRING / WSTRING is read as its raw bytes at the PLC's own declared width and
+            // decoded here: it ends at the first NUL, and a STRING is Windows-1252 rather than the
+            // host culture's ANSI code page the Beckhoff marshaller would fall back to. The width is
+            // the RESOLVED type's (shape.ByteSize) and the read is addressed explicitly: asking the
+            // library for typeof(byte[]) slices by the symbol's own ByteSize, which a TwinCAT 2
+            // member symbol under-reports (STRING(80) → 11 B, live on a TC 2.11 CX).
+            if (type is TwinCATDataType.String or TwinCATDataType.WString)
+            {
+                var (bytes, readStatus) = await ReadRawAsync(symbolPath, symbol!, shape.ByteSize, cancellationToken)
+                    .ConfigureAwait(false);
+                return readStatus == TwinCATStatusMapper.Good
+                    ? (DecodeString(type, bytes, StringsAreUtf8()), TwinCATStatusMapper.Good)
+                    : (null, readStatus);
+            }
+
             var clrType = MapToClrType(type);
             var result = await _client.ReadValueAsync(symbolPath, clrType, cancellationToken)
                 .ConfigureAwait(false);
@@ -140,6 +165,87 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
         }
     }
 
+    /// <summary>
+    ///     Resolves the PLC symbol behind <paramref name="symbolPath"/> into the facts
+    ///     <see cref="TwinCATTypeGuard"/> compares a declared type against. Uses the Beckhoff symbol
+    ///     cache (lookup on), so repeat calls are local.
+    /// </summary>
+    private async Task<(TwinCATPlcSymbolShape shape, IAdsSymbol? symbol, uint status)> DescribeSymbolAsync(
+        string symbolPath, CancellationToken cancellationToken)
+    {
+        var result = await _client.ReadSymbolAsync(symbolPath, cancellationToken).ConfigureAwait(false);
+        if (result.ErrorCode != AdsErrorCode.NoError)
+            return (default, null, MapAndSignal((uint)result.ErrorCode));
+        if (result.Value is not { } symbol)
+            return (default, null, TwinCATStatusMapper.BadNodeIdUnknown);
+
+        // Resolve aliases (T_MaxString → STRING(255)) so the guard sees the base type, and take the
+        // resolved type's byte size — a TwinCAT 2 member symbol's own ByteSize is under-reported.
+        var dataType = symbol.DataType?.Resolve();
+        var shape = TwinCATPlcSymbolShape.Classify(
+            dataType?.Name ?? symbol.TypeName, dataType?.Category, symbol.ByteSize, dataType?.ByteSize, symbol.TypeName);
+        return (shape, symbol, TwinCATStatusMapper.Good);
+    }
+
+    /// <summary>
+    ///     Reads exactly <paramref name="length"/> raw bytes of a resolved symbol: by its
+    ///     index group/offset, or — for a handle-addressed symbol (0xF005, whose offset is a handle
+    ///     that may be stale) — through a fresh variable handle.
+    /// </summary>
+    private async Task<(byte[] bytes, uint status)> ReadRawAsync(
+        string symbolPath, IAdsSymbol symbol, int length, CancellationToken cancellationToken)
+    {
+        const uint SymbolValueByHandle = 0xF005;
+        if (symbol.IndexGroup != SymbolValueByHandle)
+        {
+            var direct = await _client.ReadAsync(symbol.IndexGroup, symbol.IndexOffset, length, cancellationToken)
+                .ConfigureAwait(false);
+            return direct.ErrorCode == AdsErrorCode.NoError
+                ? (direct.Data.ToArray(), TwinCATStatusMapper.Good)
+                : ([], MapAndSignal((uint)direct.ErrorCode));
+        }
+
+        var handle = await _client.CreateVariableHandleAsync(symbolPath, cancellationToken).ConfigureAwait(false);
+        if (handle.ErrorCode != AdsErrorCode.NoError) return ([], MapAndSignal((uint)handle.ErrorCode));
+        try
+        {
+            var read = await _client.ReadAsync(handle.Handle, length, cancellationToken).ConfigureAwait(false);
+            return read.ErrorCode == AdsErrorCode.NoError
+                ? (read.Data.ToArray(), TwinCATStatusMapper.Good)
+                : ([], MapAndSignal((uint)read.ErrorCode));
+        }
+        finally
+        {
+            try { await _client.DeleteVariableHandleAsync(handle.Handle, CancellationToken.None).ConfigureAwait(false); }
+            catch { /* best-effort release */ }
+        }
+    }
+
+    /// <summary>
+    ///     True when the target reports UTF-8 STRING data (TwinCAT 3.1 4026+ "UTF8 Encoding for
+    ///     STRING"); otherwise a STRING is Windows-1252. Read once per client from the symbol upload
+    ///     info the Beckhoff client already fetches.
+    /// </summary>
+    private bool StringsAreUtf8()
+    {
+        if (_stringsAreUtf8 is bool known) return known;
+        try
+        {
+            var utf8 = _client.DefaultValueEncoding.CodePage == System.Text.Encoding.UTF8.CodePage;
+            _stringsAreUtf8 = utf8;
+            return utf8;
+        }
+        catch
+        {
+            return false; // not determinable yet (e.g. not connected) — Windows-1252, retry next time
+        }
+    }
+
+    private static string DecodeString(TwinCATDataType type, byte[] bytes, bool utf8) =>
+        type == TwinCATDataType.WString
+            ? TwinCATStringCodec.DecodeWString(bytes)
+            : TwinCATStringCodec.DecodeString(bytes, utf8);
+
     private static string StripBitSuffix(string symbolPath)
     {
         var lastDot = symbolPath.LastIndexOf('.');
@@ -197,6 +303,33 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
         CancellationToken cancellationToken)
     {
         var clrType = MapToClrType(type);
+        int[]? anyTypeArgs = null;
+        var stringsUtf8 = false;
+        if (bitIndex is null || type != TwinCATDataType.Bool)
+        {
+            // A notification carries raw bytes decoded as the DECLARED type, so a declared type that
+            // cannot decode the PLC symbol (width, float/integer or string kind differ) would publish
+            // wrong values at Good. Refuse it here; the driver isolates the one tag to Bad.
+            var (shape, _, symbolStatus) = await DescribeSymbolAsync(symbolPath, cancellationToken)
+                .ConfigureAwait(false);
+            if (symbolStatus != TwinCATStatusMapper.Good)
+                throw new InvalidOperationException(
+                    $"Resolving {symbolPath} for a notification failed with status 0x{symbolStatus:X8}");
+            if (TwinCATTypeGuard.CheckNotification(type, shape) is { } reason)
+                throw new TwinCATTypeMismatchException(symbolPath, reason);
+
+            // A string has no fixed width: the "any" type string needs an explicit length (the
+            // Beckhoff marshaller throws ArgumentNullException without one), and a STRING(n) is n+1
+            // bytes with n chosen per declaration. Register the PLC's own byte width as raw bytes
+            // and decode them in OnAdsNotificationEx with the same rules as a read.
+            if (type is TwinCATDataType.String or TwinCATDataType.WString)
+            {
+                clrType = typeof(byte[]);
+                anyTypeArgs = [shape.ByteSize];
+                stringsUtf8 = StringsAreUtf8();
+            }
+        }
+
         var cycleMs = (int)Math.Max(1, cycleTime.TotalMilliseconds);
         var settings = new NotificationSettings(AdsTransMode.OnChange, cycleMs, Math.Max(0, maxDelayMs));
 
@@ -204,13 +337,16 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
         // with the handle as part of the event args so we use the handle as the correlation
         // key into _notifications.
         var result = await _client.AddDeviceNotificationExAsync(
-            symbolPath, settings, userData: null, clrType, args: null, cancellationToken)
+            symbolPath, settings, userData: null, clrType, anyTypeArgs, cancellationToken)
             .ConfigureAwait(false);
         if (result.ErrorCode != AdsErrorCode.NoError)
             throw new InvalidOperationException(
                 $"AddDeviceNotificationExAsync failed with ADS error {result.ErrorCode} for {symbolPath}");
 
-        var reg = new NotificationRegistration(symbolPath, type, bitIndex, onChange, this, result.Handle);
+        var reg = new NotificationRegistration(symbolPath, type, bitIndex, onChange, this, result.Handle)
+        {
+            StringsUtf8 = stringsUtf8,
+        };
         _notifications[result.Handle] = reg;
         return reg;
     }
@@ -227,6 +363,8 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
         var value = args.Value;
         if (reg.BitIndex is int bit && reg.Type == TwinCATDataType.Bool && value is not bool)
             value = ExtractBit(value, bit);
+        else if (value is byte[] raw && reg.Type is TwinCATDataType.String or TwinCATDataType.WString)
+            value = DecodeString(reg.Type, raw, reg.StringsUtf8);
         _notificationQueue.Writer.TryWrite(new PendingNotification(reg, value));
     }
 
@@ -376,27 +514,36 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
         return (MapSymbolTypeName(dataType.Name), null);
     }
 
-    private static TwinCATDataType? MapSymbolTypeName(string? typeName)
+    internal static TwinCATDataType? MapSymbolTypeName(string? typeName)
     {
         if (typeName is null) return null;
+        // A TwinCAT 2 data-type upload pads some member type names with a trailing blank
+        // ("REAL ", "DINT " on a TC 2.11 CX) — trim before matching.
+        var name = typeName.Trim();
         // 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;
+        // String/WString atom the driver speaks. Only for the string kinds: any other
+        // parenthesised form ("INT (VAR_IN_OUT)" — a 4-byte reference on TC2) is not the
+        // scalar its prefix names and stays unsupported.
+        var paren = name.IndexOf('(');
+        var bare = paren > 0 ? name[..paren] : name;
+        if (paren > 0 && bare is not ("STRING" or "WSTRING")) return null;
         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,
+            // TwinCAT 2 reports top-level globals by their ADS base-type name (INT16 / UINT16 / …),
+            // and the Beckhoff type system keeps that spelling as a built-in primitive
+            // (AdsSymbolProvider.CreateBuildInTypes) — map each like its IEC twin.
+            "USINT" or "UINT8" => TwinCATDataType.USInt,
+            "INT" or "WORD" or "INT16" => TwinCATDataType.Int,
+            "UINT" or "UINT16" => TwinCATDataType.UInt,
+            "DINT" or "DWORD" or "INT32" => TwinCATDataType.DInt,
+            "UDINT" or "UINT32" => TwinCATDataType.UDInt,
             "LINT" or "LWORD" => TwinCATDataType.LInt,
             "ULINT" => TwinCATDataType.ULInt,
-            "REAL" => TwinCATDataType.Real,
-            "LREAL" => TwinCATDataType.LReal,
+            "REAL" or "FLOAT" => TwinCATDataType.Real,
+            "LREAL" or "DOUBLE" => TwinCATDataType.LReal,
             "STRING" => TwinCATDataType.String,
             "WSTRING" => TwinCATDataType.WString,
             "TIME" => TwinCATDataType.Time,
@@ -463,6 +610,11 @@ internal sealed class AdsTwinCATClient : ITwinCATClient
         /// </summary>
         public Action<string, object?> OnChange { get; } = onChange;
 
+        /// <summary>
+        /// Gets a value indicating whether a STRING notification decodes as UTF-8 (else Windows-1252).
+        /// </summary>
+        public bool StringsUtf8 { get; init; }
+
         /// <summary>
         /// Disposes the notification subscription.
         /// </summary>

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/ITwinCATClient.cs

@@ -94,6 +94,9 @@ public interface ITwinCATClient : IDisposable
     /// <param name="onChange">Invoked with <c>(symbolPath, boxedValue)</c> per notification.</param>
     /// <param name="cancellationToken">Cancels the initial registration; does not tear down an established notification.</param>
     /// <returns>A handle whose disposal tears the registered notification down.</returns>
+    /// <exception cref="TwinCATTypeMismatchException">The declared <paramref name="type"/> cannot decode
+    ///     the PLC symbol (width, float/integer or string kind differ) — the caller isolates that one tag
+    ///     to Bad rather than registering a notification that would publish wrong bytes at Good.</exception>
     Task<ITwinCATNotificationHandle> AddNotificationAsync(
         string symbolPath,
         TwinCATDataType type,

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATDriver.cs

@@ -276,9 +276,15 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
                     _health = new DriverHealth(DriverState.Healthy, now, null);
                 else
                 {
-                    _logger.LogWarning(
-                        "TwinCAT driver '{DriverInstanceId}' ADS read error 0x{Status:X8} for '{Reference}'",
-                        _driverInstanceId, status, reference);
+                    if (status == TwinCATStatusMapper.BadTypeMismatch)
+                        _logger.LogWarning(
+                            "TwinCAT driver '{DriverInstanceId}' refused '{Reference}': declared {DataType} " +
+                            "cannot decode the PLC symbol '{Symbol}' (string/numeric kind mismatch or a reference/container)",
+                            _driverInstanceId, reference, def.DataType, symbolName);
+                    else
+                        _logger.LogWarning(
+                            "TwinCAT driver '{DriverInstanceId}' ADS read error 0x{Status:X8} for '{Reference}'",
+                            _driverInstanceId, status, reference);
                     _health = new DriverHealth(DriverState.Degraded, _health.LastSuccessfulRead,
                         $"ADS status {status:X8} reading {reference}");
                 }
@@ -535,7 +541,22 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
                         new DataChangeEventArgs(handle, reference, new DataValueSnapshot(
                             null, TwinCATStatusMapper.BadCommunicationError, null, DateTime.UtcNow))));
 
-                await RegisterNotificationAsync(device, reg, cancellationToken).ConfigureAwait(false);
+                try
+                {
+                    await RegisterNotificationAsync(device, reg, cancellationToken).ConfigureAwait(false);
+                }
+                catch (TwinCATTypeMismatchException mismatch)
+                {
+                    // The declared type cannot decode this PLC symbol (ignitionoee TwinCAT-002/-008):
+                    // isolate THIS tag to Bad — one WARN, one BadTypeMismatch snapshot — and keep the
+                    // rest of the subscription. Its intent stays on the device with no live handle,
+                    // so the probe-tick retry re-checks it after a PLC program change.
+                    _logger.LogWarning(
+                        "TwinCAT driver '{DriverInstanceId}' refused native notification for '{Reference}': {Reason}",
+                        _driverInstanceId, reference, mismatch.Message);
+                    OnDataChange?.Invoke(this, new DataChangeEventArgs(handle, reference, new DataValueSnapshot(
+                        null, TwinCATStatusMapper.BadTypeMismatch, null, DateTime.UtcNow)));
+                }
                 registrations.Add(reg);
             }
         }
@@ -569,9 +590,20 @@ public sealed class TwinCATDriver : IDriver, IReadable, IWritable, ITagDiscovery
         try
         {
             var client = await EnsureConnectedUnderGateAsync(device, ct, timeoutOverride: null).ConfigureAwait(false);
-            var newHandle = await client.AddNotificationAsync(
-                reg.SymbolName, reg.DataType, reg.BitIndex, reg.Interval,
-                _options.NotificationMaxDelayMs, reg.OnChange, ct).ConfigureAwait(false);
+            ITwinCATNotificationHandle newHandle;
+            try
+            {
+                newHandle = await client.AddNotificationAsync(
+                    reg.SymbolName, reg.DataType, reg.BitIndex, reg.Interval,
+                    _options.NotificationMaxDelayMs, reg.OnChange, ct).ConfigureAwait(false);
+            }
+            catch (TwinCATTypeMismatchException)
+            {
+                // Keep the intent with no live handle (a "dead" registration) so the probe-tick
+                // retry re-checks it and UnsubscribeAsync still removes it; the caller isolates it.
+                device.NativeRegistrations[reg.Id] = reg;
+                throw;
+            }
             reg.SwapHandle(newHandle); // initial set — previous handle is null
             device.NativeRegistrations[reg.Id] = reg;
         }

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATStringCodec.cs

@@ -0,0 +1,69 @@
+using System.Text;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+/// <summary>
+///     Decodes an IEC <c>STRING(n)</c> / <c>WSTRING(n)</c> buffer read at the PLC's own declared width.
+///     The driver reads string symbols as raw bytes and decodes them here instead of letting the
+///     Beckhoff marshaller pick an encoding, because that marshaller falls back to the HOST's ANSI code
+///     page (<c>CultureInfo.CurrentCulture.TextInfo.ANSICodePage</c>) for a non-UTF-8 target — so a
+///     TwinCAT 2 string would decode differently on a Polish (1250) or Cyrillic (1251) server.
+/// </summary>
+/// <remarks>
+///     Two rules, both ported from the ignitionoee TwinCAT driver and both found on a real PLC:
+///     <list type="bullet">
+///         <item>A value ENDS at its first NUL — <c>0x00</c> for a STRING, an aligned <c>0x00 0x00</c>
+///         code unit for a WSTRING. Whatever follows is stale content a longer earlier value left in the
+///         buffer (live on the Elma cleaner Z33856: work order <c>67504440</c> read back with a stale
+///         <c>"\0" + "1"</c> tail).</item>
+///         <item>A STRING is single-byte <b>Windows-1252</b> (umlauts, <c>°</c> in alarm texts), unless
+///         the target reports UTF-8 string data (TwinCAT 3.1 4026+ "UTF8 Encoding for STRING").
+///         ISO-8859-1 is the fallback on a runtime without code-page support — identical outside
+///         0x80–0x9F.</item>
+///     </list>
+/// </remarks>
+internal static class TwinCATStringCodec
+{
+    private static readonly Encoding Windows1252 = CreateWindows1252();
+
+    private static Encoding CreateWindows1252()
+    {
+        try
+        {
+            Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);
+            return Encoding.GetEncoding(1252);
+        }
+        catch (Exception)
+        {
+            return Encoding.Latin1;
+        }
+    }
+
+    /// <summary>Decodes an IEC <c>STRING(n)</c> buffer: ends at the first NUL, Windows-1252 unless <paramref name="utf8"/>.</summary>
+    /// <param name="bytes">The raw symbol bytes (n+1 for a <c>STRING(n)</c>).</param>
+    /// <param name="utf8">True when the target reports UTF-8 string data.</param>
+    /// <returns>The decoded value.</returns>
+    public static string DecodeString(ReadOnlySpan<byte> bytes, bool utf8)
+    {
+        var end = bytes.IndexOf((byte)0);
+        if (end >= 0) bytes = bytes[..end];
+        return (utf8 ? Encoding.UTF8 : Windows1252).GetString(bytes);
+    }
+
+    /// <summary>Decodes an IEC <c>WSTRING(n)</c> buffer (UTF-16LE): ends at the first aligned <c>U+0000</c>.</summary>
+    /// <param name="bytes">The raw symbol bytes (2(n+1) for a <c>WSTRING(n)</c>).</param>
+    /// <returns>The decoded value.</returns>
+    public static string DecodeWString(ReadOnlySpan<byte> bytes)
+    {
+        var end = bytes.Length & ~1; // whole UTF-16 code units only — a trailing odd byte is ignored
+        for (var i = 0; i + 1 < end; i += 2)
+        {
+            if (bytes[i] == 0 && bytes[i + 1] == 0)
+            {
+                end = i;
+                break;
+            }
+        }
+        return Encoding.Unicode.GetString(bytes[..end]);
+    }
+}

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATSymbolPath.cs

@@ -11,6 +11,12 @@ namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
 ///     grammar maps cleanly onto the AbCip Logix path parser, but without Logix's
 ///     <c>Program:</c> scope prefix. The leading segment is the namespace (POU name /
 ///     GVL name) and subsequent segments walk into struct/array members.</para>
+///     <para><b>TwinCAT 2 globals</b> are named with ONE leading dot (<c>.OPC_HEARTBEAT</c>,
+///     <c>.OPC_MACHINEDATA.PROCESSSTATUS</c>) and the PLC requires it — without the dot
+///     <c>SYM_HNDBYNAME</c> answers 0x710 (symbol not found), observed live on a TC 2.11 CX. The dot
+///     is kept on the ROOT segment's <see cref="TwinCATSymbolSegment.Name"/> so
+///     <see cref="ToAdsSymbolName"/> round-trips it unchanged; it is not a separator and never yields
+///     an empty segment. Exactly one dot: <c>..x</c>, <c>.</c> and <c>.[1]</c> stay invalid.</para>
 /// </remarks>
 public sealed record TwinCATSymbolPath(
     IReadOnlyList<TwinCATSymbolSegment> Segments,
@@ -41,6 +47,11 @@ public sealed record TwinCATSymbolPath(
         if (string.IsNullOrWhiteSpace(value)) return null;
         var src = value.Trim();
 
+        // A TwinCAT 2 global's single leading dot belongs to the root segment, not before it.
+        // Strip it for the split and put it back on segment 0 below.
+        var tc2Global = src.StartsWith('.');
+        if (tc2Global) src = src[1..];
+
         var parts = new List<string>();
         var depth = 0;
         var start = 0;
@@ -91,6 +102,7 @@ public sealed record TwinCATSymbolPath(
             segments.Add(new TwinCATSymbolSegment(name, subs));
         }
         if (segments.Count == 0) return null;
+        if (tc2Global) segments[0] = segments[0] with { Name = "." + segments[0].Name };
 
         return new TwinCATSymbolPath(segments, bitIndex);
     }

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATTypeGuard.cs

@@ -0,0 +1,164 @@
+using System.Text.RegularExpressions;
+using TwinCAT.TypeSystem;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+/// <summary>What kind of value a PLC symbol holds, as far as the type guard is concerned.</summary>
+internal enum TwinCATPlcKind
+{
+    /// <summary>A primitive / enum / alias-of-primitive — a single fixed-width value.</summary>
+    Scalar,
+
+    /// <summary>An IEC <c>STRING(n)</c> (any n, incl. an alias such as <c>T_MaxString</c>).</summary>
+    String,
+
+    /// <summary>An IEC <c>WSTRING(n)</c>.</summary>
+    WString,
+
+    /// <summary>A struct / FB / array / pointer / reference / <c>VAR_IN_OUT</c> — no scalar value.</summary>
+    NonScalar,
+}
+
+/// <summary>The facts about a PLC symbol the type guard compares a declared type against.</summary>
+/// <param name="Kind">The symbol's kind.</param>
+/// <param name="ByteSize">The symbol's byte size as the PLC reports it.</param>
+/// <param name="IsFloat">True for a REAL / LREAL scalar.</param>
+/// <param name="TypeName">The (alias-resolved) PLC type name, for log messages.</param>
+internal readonly record struct TwinCATPlcSymbolShape(TwinCATPlcKind Kind, int ByteSize, bool IsFloat, string TypeName)
+{
+    private static readonly Regex StringTypeName =
+        new(@"^(W?)STRING(\s*\(\s*\d+\s*\))?$", RegexOptions.IgnoreCase | RegexOptions.CultureInvariant);
+
+    /// <summary>
+    ///     Classifies a PLC symbol from its (alias-resolved) type name, its Beckhoff
+    ///     <see cref="DataTypeCategory"/> when the type system resolved one, and its byte size.
+    /// </summary>
+    /// <param name="typeName">The PLC type name (<c>STRING(80)</c>, <c>INT16</c>, <c>ST_LOGDATA</c>, …).</param>
+    /// <param name="category">The resolved type category, or null when the type system has none.</param>
+    /// <param name="byteSize">The symbol's byte size.</param>
+    /// <param name="dataTypeByteSize">The resolved data type's byte size, when the type system has one.
+    ///     It wins over <paramref name="byteSize"/>: on a TwinCAT 2 target the Beckhoff library reports a
+    ///     dotted MEMBER symbol's size as if the PLC's byte count were a bit count (STRING(80) → 11,
+    ///     INT → 1, UDINT → 1; live on a TC 2.11 CX), while the resolved type carries the true size.</param>
+    /// <param name="symbolTypeName">The symbol's OWN type name, when it differs from the resolved one. A
+    ///     TwinCAT 2 <c>VAR_IN_OUT</c> member is named <c>STRING(20) (VAR_IN_OUT)</c> — a 4-byte reference —
+    ///     while the library resolves its data type to the plain <c>STRING(20)</c>; the reference marker
+    ///     wins, so the symbol is never read as the value it points at.</param>
+    /// <returns>The classified shape.</returns>
+    public static TwinCATPlcSymbolShape Classify(
+        string? typeName, DataTypeCategory? category, int byteSize, int? dataTypeByteSize = null,
+        string? symbolTypeName = null)
+    {
+        if (symbolTypeName?.Contains("VAR_IN_OUT", StringComparison.OrdinalIgnoreCase) == true
+            || typeName?.Contains("VAR_IN_OUT", StringComparison.OrdinalIgnoreCase) == true)
+            return new(TwinCATPlcKind.NonScalar, byteSize, false, (symbolTypeName ?? typeName)!.Trim());
+
+        if (dataTypeByteSize is > 0) byteSize = dataTypeByteSize.Value;
+        var name = (typeName ?? string.Empty).Trim();
+        var match = StringTypeName.Match(name);
+        if (match.Success || category == DataTypeCategory.String)
+        {
+            var wide = match.Success
+                ? match.Groups[1].Length > 0
+                : name.StartsWith("WSTRING", StringComparison.OrdinalIgnoreCase);
+            return new(wide ? TwinCATPlcKind.WString : TwinCATPlcKind.String, byteSize, false, name);
+        }
+
+        if (category is DataTypeCategory.Array or DataTypeCategory.Struct or DataTypeCategory.FunctionBlock
+                or DataTypeCategory.Program or DataTypeCategory.Pointer or DataTypeCategory.Reference
+                or DataTypeCategory.Union or DataTypeCategory.Interface
+            || name.StartsWith("ARRAY", StringComparison.OrdinalIgnoreCase)
+            || name.StartsWith("POINTER TO", StringComparison.OrdinalIgnoreCase)
+            || name.StartsWith("REFERENCE TO", StringComparison.OrdinalIgnoreCase)
+            || name.Contains("VAR_IN_OUT", StringComparison.OrdinalIgnoreCase))
+            return new(TwinCATPlcKind.NonScalar, byteSize, false, name);
+
+        var mapped = AdsTwinCATClient.MapSymbolTypeName(name);
+        return new(TwinCATPlcKind.Scalar, byteSize, mapped is TwinCATDataType.Real or TwinCATDataType.LReal, name);
+    }
+}
+
+/// <summary>
+///     Decides whether a tag's DECLARED <see cref="TwinCATDataType"/> may decode the PLC symbol it names —
+///     the port of the ignitionoee TwinCAT driver's extra-type reconciliation (TwinCAT-002, -008). A
+///     refused pair leaves the node Bad (<see cref="TwinCATStatusMapper.BadTypeMismatch"/>) instead of
+///     publishing the PLC's bytes decoded as the wrong type at Good quality. A <c>null</c> result means
+///     compatible; otherwise it is a one-line reason for the log.
+/// </summary>
+/// <remarks>
+///     The two paths need different rules because they decode differently:
+///     <list type="bullet">
+///         <item><b>Read</b> (<see cref="CheckRead"/>) goes through the Beckhoff symbol cache, which
+///         decodes by the PLC's OWN type and converts the value to the declared CLR type — a numeric
+///         pair is value-converted, never reinterpreted. Only string-ness can go wrong there: a
+///         numeric tag over a PLC string got a <c>string</c> object back at Good.</item>
+///         <item><b>Notification</b> (<see cref="CheckNotification"/>) registers raw bytes decoded as the
+///         DECLARED type, so a width mismatch truncates/over-reads and a same-width float/integer clash
+///         reinterprets the bit pattern — both at Good.</item>
+///     </list>
+///     String-ness is a KIND (TwinCAT-008): a STRING/WSTRING tag matches only a PLC string of the SAME
+///     kind, at any declared length (0.19.2). A same-width, same-kind numeric divergence
+///     (<c>DINT</c> vs <c>UDINT</c>, <c>TIME</c> vs a 4-byte integer) is tolerated so a valid config is
+///     never refused.
+/// </remarks>
+internal static class TwinCATTypeGuard
+{
+    /// <summary>Checks a declared type against a PLC symbol for a symbol-aware READ.</summary>
+    /// <param name="declared">The tag's declared type.</param>
+    /// <param name="plc">The PLC symbol's shape.</param>
+    /// <returns><c>null</c> when compatible; otherwise the reason.</returns>
+    public static string? CheckRead(TwinCATDataType declared, TwinCATPlcSymbolShape plc)
+    {
+        var declaredKind = StringKindOf(declared);
+        if (declaredKind is not null)
+        {
+            return plc.Kind == declaredKind
+                ? null
+                : $"declared {declared} but the PLC symbol is {plc.TypeName} ({plc.ByteSize} B) — a string tag " +
+                  $"matches only a PLC {declaredKind.Value.ToString().ToUpperInvariant()} of any length";
+        }
+        return plc.Kind is TwinCATPlcKind.String or TwinCATPlcKind.WString
+            ? $"declared {declared} but the PLC symbol is the string {plc.TypeName} — declare it String/WString"
+            : null;
+    }
+
+    /// <summary>Checks a declared type against a PLC symbol for a raw-bytes NOTIFICATION.</summary>
+    /// <param name="declared">The tag's declared type.</param>
+    /// <param name="plc">The PLC symbol's shape.</param>
+    /// <returns><c>null</c> when compatible; otherwise the reason.</returns>
+    public static string? CheckNotification(TwinCATDataType declared, TwinCATPlcSymbolShape plc)
+    {
+        var reason = CheckRead(declared, plc);
+        if (reason is not null || StringKindOf(declared) is not null) return reason;
+
+        if (plc.Kind == TwinCATPlcKind.NonScalar)
+            return $"declared scalar {declared} but the PLC symbol is {plc.TypeName} ({plc.ByteSize} B) — not a scalar";
+
+        var size = DeclaredByteSize(declared);
+        if (size != plc.ByteSize)
+            return $"declared {declared} ({size} B) but the PLC symbol {plc.TypeName} is {plc.ByteSize} B";
+
+        var declaredFloat = declared is TwinCATDataType.Real or TwinCATDataType.LReal;
+        return declaredFloat == plc.IsFloat
+            ? null
+            : $"declared {declared} but the PLC symbol is {plc.TypeName} — float/integer kinds differ";
+    }
+
+    /// <summary>The byte width the declared type decodes from a notification buffer.</summary>
+    /// <param name="type">The declared type.</param>
+    /// <returns>The width in bytes.</returns>
+    internal static int DeclaredByteSize(TwinCATDataType type) => type switch
+    {
+        TwinCATDataType.Bool or TwinCATDataType.SInt or TwinCATDataType.USInt => 1,
+        TwinCATDataType.Int or TwinCATDataType.UInt => 2,
+        TwinCATDataType.LInt or TwinCATDataType.ULInt or TwinCATDataType.LReal => 8,
+        _ => 4, // DInt / UDInt / Real / Time / Date / DateTime / TimeOfDay
+    };
+
+    private static TwinCATPlcKind? StringKindOf(TwinCATDataType type) => type switch
+    {
+        TwinCATDataType.String => TwinCATPlcKind.String,
+        TwinCATDataType.WString => TwinCATPlcKind.WString,
+        _ => null,
+    };
+}

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATTypeMismatchException.cs

@@ -0,0 +1,22 @@
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+/// <summary>
+///     Thrown by <see cref="ITwinCATClient.AddNotificationAsync"/> when a tag's declared
+///     <see cref="TwinCATDataType"/> cannot decode the PLC symbol it names (see
+///     <see cref="TwinCATTypeGuard"/>). The driver isolates the one tag to
+///     <see cref="TwinCATStatusMapper.BadTypeMismatch"/> and keeps the rest of the subscription.
+/// </summary>
+internal sealed class TwinCATTypeMismatchException : Exception
+{
+    /// <summary>Initializes a new instance of the <see cref="TwinCATTypeMismatchException"/> class.</summary>
+    /// <param name="symbolPath">The ADS symbol the tag names.</param>
+    /// <param name="reason">The guard's one-line reason.</param>
+    public TwinCATTypeMismatchException(string symbolPath, string reason)
+        : base($"TwinCAT symbol '{symbolPath}': {reason}")
+    {
+        SymbolPath = symbolPath;
+    }
+
+    /// <summary>Gets the ADS symbol the refused tag names.</summary>
+    public string SymbolPath { get; }
+}