fix(twincat): string subscriptions, Windows-1252 STRING decode, and declared-type kind checks (ignitionoee 0.19.2-0.19.4)
Port of the ignitionoee TwinCAT string + type-reconciliation fixes onto the Beckhoff-library client: - STRING/WSTRING subscriptions never worked: AddDeviceNotificationExAsync was called with typeof(string) and no length, and the Beckhoff any-type marshaller throws ArgumentNullException for a string without one, so one string tag tore down its whole subscribe call. A string now registers the PLC's own byte width as raw bytes (0.19.2: STRING(n) of any n). - Strings are read as raw bytes and decoded by TwinCATStringCodec. The Beckhoff marshaller already cut a read at the first NUL (0.19.3 / TwinCAT-007 were not defects on the read path); the codec keeps that rule for both STRING and WSTRING and extends it to the new notification path. A STRING now decodes as Windows-1252 (TwinCAT-010) - or UTF-8 when the target reports UTF-8 strings - instead of the host culture's ANSI code page the Beckhoff marshaller falls back to (1250 on a Polish host, 1251 Cyrillic, ...). - TwinCATTypeGuard (TwinCAT-002/-008): a read refuses a numeric tag over a PLC string (and vice versa / STRING vs WSTRING / string over a container) with BadTypeMismatch instead of handing back a string object at Good; a notification - raw bytes decoded as the DECLARED type - additionally refuses width and float/integer mismatches (DINT over REAL reinterpreted the bits). - A refused notification is isolated: that tag publishes BadTypeMismatch with one WARN, keeps a dead intent for the probe-tick retry, and the rest of the subscription registers.
This commit is contained in:
Joseph Doherty
@@ -116,6 +116,9 @@ internal class FakeTwinCATClient : ITwinCATClient
|
||||
public List<FakeNotification> Notifications { get; } = new();
|
||||
/// <summary>Gets or sets a value indicating whether AddNotificationAsync should throw.</summary>
|
||||
public bool ThrowOnAddNotification { get; set; }
|
||||
/// <summary>Per-symbol exceptions <see cref="AddNotificationAsync"/> throws (e.g. a
|
||||
/// <see cref="TwinCATTypeMismatchException"/> for one refused tag).</summary>
|
||||
public Dictionary<string, Exception> AddNotificationErrors { get; } = new(StringComparer.OrdinalIgnoreCase);
|
||||
/// <summary>Records the most recently-supplied <c>maxDelayMs</c> for Driver.TwinCAT-014 tests.</summary>
|
||||
public int LastMaxDelayMs { get; private set; }
|
||||
/// <summary>When set, <see cref="AddNotificationAsync"/> awaits this gate before creating the handle —
|
||||
@@ -137,6 +140,8 @@ internal class FakeTwinCATClient : ITwinCATClient
|
||||
{
|
||||
if (ThrowOnAddNotification)
|
||||
throw Exception ?? new InvalidOperationException("fake AddNotification failure");
|
||||
if (AddNotificationErrors.TryGetValue(symbolPath, out var perSymbol))
|
||||
throw perSymbol;
|
||||
|
||||
if (AddNotificationGate is { } gate)
|
||||
await gate.Task.ConfigureAwait(false);
|
||||
|
||||
+45
@@ -128,6 +128,51 @@ public sealed class TwinCATNativeNotificationTests
|
||||
fake.Notifications.Count.ShouldBe(0); // partial handle cleaned up
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A tag whose declared type cannot decode its PLC symbol (ignitionoee TwinCAT-002/-008) is refused
|
||||
/// by the client with <see cref="TwinCATTypeMismatchException"/>. The refusal is ISOLATED: that
|
||||
/// one tag goes Bad with <c>BadTypeMismatch</c> and every other tag in the same subscribe call
|
||||
/// still registers — before, the exception tore the whole subscription down.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public async Task Native_subscribe_isolates_a_type_mismatched_tag_to_BadTypeMismatch()
|
||||
{
|
||||
var fake = new FakeTwinCATClient();
|
||||
fake.AddNotificationErrors["MAIN.Order"] =
|
||||
new TwinCATTypeMismatchException("MAIN.Order", "declared DInt but the PLC symbol is the string STRING(3)");
|
||||
var factory = new FakeTwinCATClientFactory { Customise = () => fake };
|
||||
var drv = new TwinCATDriver(new TwinCATDriverOptions
|
||||
{
|
||||
Devices = [new TwinCATDeviceOptions("ads://5.23.91.23.1.1:851")],
|
||||
RawTags = TwinCATRawTags.Entries(
|
||||
[
|
||||
new TwinCATTagDefinition("Count", "ads://5.23.91.23.1.1:851", "MAIN.Count", TwinCATDataType.DInt),
|
||||
new TwinCATTagDefinition("Order", "ads://5.23.91.23.1.1:851", "MAIN.Order", TwinCATDataType.DInt),
|
||||
new TwinCATTagDefinition("Speed", "ads://5.23.91.23.1.1:851", "MAIN.Speed", TwinCATDataType.Real),
|
||||
]),
|
||||
Probe = new TwinCATProbeOptions { Enabled = false },
|
||||
UseNativeNotifications = true,
|
||||
}, "drv-1", factory);
|
||||
await drv.InitializeAsync("{}", CancellationToken.None);
|
||||
|
||||
var events = new ConcurrentQueue<DataChangeEventArgs>();
|
||||
drv.OnDataChange += (_, e) => events.Enqueue(e);
|
||||
|
||||
var handle = await drv.SubscribeAsync(["Count", "Order", "Speed"], TimeSpan.FromMilliseconds(100), CancellationToken.None);
|
||||
|
||||
fake.Notifications.Select(n => n.SymbolPath).ShouldBe(["MAIN.Count", "MAIN.Speed"], ignoreOrder: true);
|
||||
var refused = events.ShouldHaveSingleItem();
|
||||
refused.FullReference.ShouldBe("Order");
|
||||
refused.Snapshot.StatusCode.ShouldBe(TwinCATStatusMapper.BadTypeMismatch);
|
||||
refused.Snapshot.Value.ShouldBeNull();
|
||||
|
||||
// The good tags still deliver, and unsubscribe tears down cleanly.
|
||||
fake.FireNotification("MAIN.Count", 7);
|
||||
events.Last().Snapshot.Value.ShouldBe(7);
|
||||
await drv.UnsubscribeAsync(handle, CancellationToken.None);
|
||||
fake.Notifications.ShouldBeEmpty();
|
||||
}
|
||||
|
||||
private sealed class AbTagParamsIrrelevant { }
|
||||
|
||||
private sealed class FailAfterNAddsFake : FakeTwinCATClient
|
||||
|
||||
@@ -0,0 +1,82 @@
|
||||
using System.Text;
|
||||
using Shouldly;
|
||||
using Xunit;
|
||||
using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests;
|
||||
|
||||
/// <summary>
|
||||
/// Pins <see cref="TwinCATStringCodec"/> — how an IEC <c>STRING(n)</c> / <c>WSTRING(n)</c> buffer,
|
||||
/// read at the PLC's own declared width, becomes a value. Ported from the ignitionoee TwinCAT
|
||||
/// driver (0.19.3 first-NUL STRING, 0.19.4 TwinCAT-007 first-NUL WSTRING and TwinCAT-010
|
||||
/// Windows-1252), whose byte fixtures these reuse.
|
||||
/// </summary>
|
||||
[Trait("Category", "Unit")]
|
||||
public sealed class TwinCATStringCodecTests
|
||||
{
|
||||
/// <summary>
|
||||
/// An IEC STRING ends at its FIRST NUL; the buffer beyond keeps whatever a longer earlier value
|
||||
/// left there. Live on the Elma cleaner Z33856 (2026-09-24) a decoder that only trimmed trailing
|
||||
/// NULs published work order <c>67504440</c> as <c>"67504440\0" + "1"</c> and part
|
||||
/// <c>110032285</c> as <c>"110032285\0" + "1\0" + "30"</c> — a wrong value at Good quality.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public void String_stops_at_the_first_nul_and_ignores_stale_bytes_after_it()
|
||||
{
|
||||
byte[] workOrder = [(byte)'6', (byte)'7', (byte)'5', (byte)'0', (byte)'4', (byte)'4', (byte)'4', (byte)'0',
|
||||
0x00, (byte)'1', 0x00, (byte)'3', (byte)'0', 0x00];
|
||||
TwinCATStringCodec.DecodeString(workOrder, utf8: false).ShouldBe("67504440");
|
||||
|
||||
byte[] emptied = [0x00, (byte)'O', (byte)'L', (byte)'D'];
|
||||
TwinCATStringCodec.DecodeString(emptied, utf8: false).ShouldBe("");
|
||||
}
|
||||
|
||||
/// <summary>A buffer with no NUL at all (a full-length value) decodes whole.</summary>
|
||||
[Fact]
|
||||
public void String_without_a_nul_decodes_the_whole_buffer()
|
||||
=> TwinCATStringCodec.DecodeString("ABC"u8.ToArray(), utf8: false).ShouldBe("ABC");
|
||||
|
||||
/// <summary>
|
||||
/// An IEC STRING on TwinCAT is single-byte Windows-1252, not ASCII and not the host's culture
|
||||
/// code page: <c>°</c> (0xB0, an Elma alarm text), <c>ä</c> (0xE4) and <c>€</c> (0x80, the one
|
||||
/// byte where 1252 and ISO-8859-1 differ) must decode to themselves on any host.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public void String_decodes_windows_1252_high_bytes()
|
||||
{
|
||||
byte[] text = [(byte)'8', (byte)'0', 0xB0, (byte)'C', (byte)' ', 0xE4, 0x80, 0x00, 0xFF];
|
||||
TwinCATStringCodec.DecodeString(text, utf8: false).ShouldBe("80°C ä€");
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A TwinCAT 3.1 build 4026+ project with "UTF8 Encoding for STRING" on reports UTF-8 string
|
||||
/// data; the codec honours it (still ending at the first NUL).
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public void String_decodes_utf8_when_the_target_reports_utf8_strings()
|
||||
{
|
||||
var bytes = Encoding.UTF8.GetBytes("80°C ä€").Concat(new byte[] { 0x00, (byte)'X' }).ToArray();
|
||||
TwinCATStringCodec.DecodeString(bytes, utf8: true).ShouldBe("80°C ä€");
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A WSTRING ends at its first ALIGNED <c>U+0000</c> code unit (TwinCAT-007): <c>"NEW\0LD"</c>
|
||||
/// must publish <c>"NEW"</c>. A zero HIGH byte of a non-NUL unit (every ASCII character in
|
||||
/// UTF-16LE) is not a terminator.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public void WString_stops_at_the_first_aligned_nul_code_unit()
|
||||
{
|
||||
var bytes = Encoding.Unicode.GetBytes("NEW\0LD\0");
|
||||
TwinCATStringCodec.DecodeWString(bytes).ShouldBe("NEW");
|
||||
TwinCATStringCodec.DecodeWString(Encoding.Unicode.GetBytes("Grüße")).ShouldBe("Grüße");
|
||||
}
|
||||
|
||||
/// <summary>A trailing odd byte is not half a character — it is ignored.</summary>
|
||||
[Fact]
|
||||
public void WString_ignores_a_trailing_odd_byte()
|
||||
{
|
||||
var bytes = Encoding.Unicode.GetBytes("AB").Concat(new byte[] { 0x43 }).ToArray();
|
||||
TwinCATStringCodec.DecodeWString(bytes).ShouldBe("AB");
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,114 @@
|
||||
using Shouldly;
|
||||
using TwinCAT.TypeSystem;
|
||||
using Xunit;
|
||||
using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests;
|
||||
|
||||
/// <summary>
|
||||
/// Pins <see cref="TwinCATTypeGuard"/> — whether a tag's DECLARED <see cref="TwinCATDataType"/> may
|
||||
/// decode the PLC symbol it names. Ported from the ignitionoee TwinCAT driver's extra-type
|
||||
/// reconciliation (TwinCAT-002 width / float kind, TwinCAT-008 string kind): a refused pair leaves
|
||||
/// the node Bad (<c>BadTypeMismatch</c>) instead of publishing the PLC's bytes decoded as the wrong
|
||||
/// type at Good quality.
|
||||
/// </summary>
|
||||
[Trait("Category", "Unit")]
|
||||
public sealed class TwinCATTypeGuardTests
|
||||
{
|
||||
private static TwinCATPlcSymbolShape Plc(string typeName, int byteSize, DataTypeCategory? category = null)
|
||||
=> TwinCATPlcSymbolShape.Classify(typeName, category, byteSize);
|
||||
|
||||
// ---- classification ----
|
||||
|
||||
/// <summary>The PLC's type name / category classifies into the four kinds the guard reasons about.</summary>
|
||||
[Fact]
|
||||
public void Classify_recognises_string_kinds_scalars_and_containers()
|
||||
{
|
||||
Plc("STRING(80)", 81).Kind.ShouldBe(TwinCATPlcKind.String);
|
||||
Plc("STRING", 81).Kind.ShouldBe(TwinCATPlcKind.String);
|
||||
Plc("WSTRING(20)", 42).Kind.ShouldBe(TwinCATPlcKind.WString);
|
||||
Plc("T_MaxString", 256, DataTypeCategory.String).Kind.ShouldBe(TwinCATPlcKind.String);
|
||||
Plc("STRING_DATA", 40).Kind.ShouldBe(TwinCATPlcKind.Scalar); // a UDT named STRING_… is not a string
|
||||
Plc("ST_LOGDATA", 986, DataTypeCategory.Struct).Kind.ShouldBe(TwinCATPlcKind.NonScalar);
|
||||
Plc("ARRAY [0..12] OF DINT", 52).Kind.ShouldBe(TwinCATPlcKind.NonScalar);
|
||||
Plc("INT (VAR_IN_OUT)", 4).Kind.ShouldBe(TwinCATPlcKind.NonScalar);
|
||||
Plc("POINTER TO BYTE", 4, DataTypeCategory.Pointer).Kind.ShouldBe(TwinCATPlcKind.NonScalar);
|
||||
Plc("REAL", 4).IsFloat.ShouldBeTrue();
|
||||
Plc("INT16", 2).IsFloat.ShouldBeFalse();
|
||||
}
|
||||
|
||||
// ---- read path (symbol-aware: only the string kind can go wrong) ----
|
||||
|
||||
/// <summary>
|
||||
/// TwinCAT-008: before the fix only width separated a string from a number, so a numeric declared
|
||||
/// over a PLC string decoded the string's bytes as a number at Good. The Beckhoff read path hands
|
||||
/// a declared-numeric tag over a PLC <c>STRING(3)</c> back a <c>string</c> object at Good — refused.
|
||||
/// </summary>
|
||||
/// <param name="declared">The tag's declared type.</param>
|
||||
[Theory]
|
||||
[InlineData(TwinCATDataType.DInt)]
|
||||
[InlineData(TwinCATDataType.UDInt)]
|
||||
[InlineData(TwinCATDataType.Time)]
|
||||
[InlineData(TwinCATDataType.Int)]
|
||||
[InlineData(TwinCATDataType.LInt)]
|
||||
public void Read_refuses_a_numeric_declared_over_a_plc_string(TwinCATDataType declared)
|
||||
=> TwinCATTypeGuard.CheckRead(declared, Plc("STRING(3)", 4)).ShouldNotBeNull();
|
||||
|
||||
/// <summary>A string declared over a number, the other string kind, or a container is refused.</summary>
|
||||
[Fact]
|
||||
public void Read_refuses_a_string_over_anything_but_the_same_string_kind()
|
||||
{
|
||||
TwinCATTypeGuard.CheckRead(TwinCATDataType.String, Plc("DINT", 4)).ShouldNotBeNull();
|
||||
TwinCATTypeGuard.CheckRead(TwinCATDataType.WString, Plc("STRING(161)", 162)).ShouldNotBeNull();
|
||||
TwinCATTypeGuard.CheckRead(TwinCATDataType.String, Plc("WSTRING(80)", 162)).ShouldNotBeNull();
|
||||
TwinCATTypeGuard.CheckRead(TwinCATDataType.String, Plc("ST_LOGDATA", 81, DataTypeCategory.Struct)).ShouldNotBeNull();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 0.19.2: a STRING / WSTRING tag matches a PLC <c>STRING(n)</c> / <c>WSTRING(n)</c> of ANY length.
|
||||
/// A numeric-over-numeric pair is left to the symbol-aware read, which converts the value.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public void Read_accepts_same_kind_strings_of_any_length_and_numeric_pairs()
|
||||
{
|
||||
TwinCATTypeGuard.CheckRead(TwinCATDataType.String, Plc("STRING(8)", 9)).ShouldBeNull();
|
||||
TwinCATTypeGuard.CheckRead(TwinCATDataType.String, Plc("STRING(255)", 256)).ShouldBeNull();
|
||||
TwinCATTypeGuard.CheckRead(TwinCATDataType.WString, Plc("WSTRING(20)", 42)).ShouldBeNull();
|
||||
TwinCATTypeGuard.CheckRead(TwinCATDataType.DInt, Plc("REAL", 4)).ShouldBeNull();
|
||||
TwinCATTypeGuard.CheckRead(TwinCATDataType.DInt, Plc("E_STATE", 2, DataTypeCategory.Enum)).ShouldBeNull();
|
||||
}
|
||||
|
||||
// ---- notification path (raw bytes decoded as the declared type) ----
|
||||
|
||||
/// <summary>
|
||||
/// TwinCAT-002: an ADS notification carries raw bytes decoded as the DECLARED type, so a same-width
|
||||
/// float/integer clash reinterprets the bit pattern (DINT over REAL) and a width mismatch truncates
|
||||
/// (DINT over LINT) — both at Good before the guard.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public void Notification_refuses_width_and_float_kind_mismatches()
|
||||
{
|
||||
TwinCATTypeGuard.CheckNotification(TwinCATDataType.DInt, Plc("REAL", 4)).ShouldNotBeNull();
|
||||
TwinCATTypeGuard.CheckNotification(TwinCATDataType.Real, Plc("DINT", 4)).ShouldNotBeNull();
|
||||
TwinCATTypeGuard.CheckNotification(TwinCATDataType.DInt, Plc("LINT", 8)).ShouldNotBeNull();
|
||||
TwinCATTypeGuard.CheckNotification(TwinCATDataType.LReal, Plc("REAL", 4)).ShouldNotBeNull();
|
||||
TwinCATTypeGuard.CheckNotification(TwinCATDataType.DInt, Plc("ARRAY [0..12] OF DINT", 52)).ShouldNotBeNull();
|
||||
TwinCATTypeGuard.CheckNotification(TwinCATDataType.DInt, Plc("STRING(3)", 4)).ShouldNotBeNull();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A same-width, same-kind divergence (DINT vs UDINT, TIME vs a 4-byte integer, a TC2 INT16) is
|
||||
/// tolerated so a valid config is never refused; strings of the same kind match at any length.
|
||||
/// </summary>
|
||||
[Fact]
|
||||
public void Notification_tolerates_same_width_same_kind_and_same_kind_strings()
|
||||
{
|
||||
TwinCATTypeGuard.CheckNotification(TwinCATDataType.UDInt, Plc("DINT", 4)).ShouldBeNull();
|
||||
TwinCATTypeGuard.CheckNotification(TwinCATDataType.Time, Plc("UDINT", 4)).ShouldBeNull();
|
||||
TwinCATTypeGuard.CheckNotification(TwinCATDataType.Int, Plc("INT16", 2)).ShouldBeNull();
|
||||
TwinCATTypeGuard.CheckNotification(TwinCATDataType.Bool, Plc("BOOL", 1)).ShouldBeNull();
|
||||
TwinCATTypeGuard.CheckNotification(TwinCATDataType.Real, Plc("REAL", 4)).ShouldBeNull();
|
||||
TwinCATTypeGuard.CheckNotification(TwinCATDataType.String, Plc("STRING(14)", 15)).ShouldBeNull();
|
||||
TwinCATTypeGuard.CheckNotification(TwinCATDataType.WString, Plc("WSTRING(20)", 42)).ShouldBeNull();
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user