Joseph Doherty
279 lines
15 KiB
C#
279 lines
15 KiB
C#
using System.Buffers.Binary;
|
||
using System.Text;
|
||
using Shouldly;
|
||
using TwinCAT.TypeSystem;
|
||
using Xunit;
|
||
using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
|
||
|
||
namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests;
|
||
|
||
/// <summary>
|
||
/// Pins the array half of the raw-bytes model: <see cref="TwinCATTypeGuard.CheckArray"/> decides
|
||
/// whether an authored array tag (element type + <c>ArrayLength</c>) may decode a PLC array and
|
||
/// plans the byte layout, and <see cref="TwinCATArrayCodec.Decode"/> turns the PLC's raw bytes into
|
||
/// the element-typed CLR array both the poll read and the native notification publish.
|
||
/// </summary>
|
||
/// <remarks>
|
||
/// The raw-bytes model replaced the Beckhoff typed array read after the 2026-10-07 live gate on the
|
||
/// TwinCAT 2.11 Elma cleaner Z33856, where that read failed for most real arrays: the CLR element
|
||
/// type had to match exactly (<c>ARRAY OF TIME</c> as <c>uint[]</c> threw), a multi-dimensional
|
||
/// array demanded a rank-2 CLR array, and a dotted MEMBER array was sliced by the under-reported
|
||
/// symbol size (<c>P_INPUTVALUESFILTER.FBUSPWR1G1.SAMPLE</c>, <c>ARRAY [1..20] OF REAL</c>, symbol
|
||
/// 10 B vs type 80 B → <c>ArgumentOutOfRangeException</c>).
|
||
/// </remarks>
|
||
[Trait("Category", "Unit")]
|
||
public sealed class TwinCATArrayCodecTests
|
||
{
|
||
private static TwinCATPlcSymbolShape Elem(string typeName, int byteSize, DataTypeCategory? category = DataTypeCategory.Primitive)
|
||
=> TwinCATPlcSymbolShape.Classify(typeName, category, byteSize);
|
||
|
||
private static TwinCATPlcArrayShape Arr(TwinCATPlcSymbolShape element, params int[] dims)
|
||
=> new(dims, dims.Aggregate(1, (a, b) => a * b) * element.ByteSize, element);
|
||
|
||
private static TwinCATPlcSymbolShape ArraySymbol(string typeName, int byteSize)
|
||
=> TwinCATPlcSymbolShape.Classify(typeName, DataTypeCategory.Array, byteSize);
|
||
|
||
private static string? Check(TwinCATDataType declared, int declaredLength, TwinCATPlcArrayShape? array,
|
||
out TwinCATArrayLayout layout, string typeName = "ARRAY")
|
||
=> TwinCATTypeGuard.CheckArray(declared, declaredLength,
|
||
ArraySymbol(typeName, array?.ByteSize ?? 4), array, out layout);
|
||
|
||
// ---- guard: plan + validate ----
|
||
|
||
/// <summary>A matching element type and length plans the whole array at element-size stride.</summary>
|
||
[Fact]
|
||
public void CheckArray_plans_a_matching_numeric_array_at_its_element_stride()
|
||
{
|
||
Check(TwinCATDataType.UInt, 13, Arr(Elem("UINT", 2), 13), out var layout).ShouldBeNull();
|
||
layout.ShouldBe(new TwinCATArrayLayout(13, 2));
|
||
layout.ByteLength.ShouldBe(26);
|
||
}
|
||
|
||
/// <summary>
|
||
/// A multi-dimensional array (<c>ARRAY [1..3, 1..2] OF REAL</c>, live on Z33856) is published
|
||
/// flattened in PLC memory order; its ArrayLength is the TOTAL element count. Lower bounds play
|
||
/// no part — the published index is 0-based.
|
||
/// </summary>
|
||
[Fact]
|
||
public void CheckArray_flattens_a_multi_dimensional_array_to_its_total_count()
|
||
{
|
||
Check(TwinCATDataType.Real, 6, Arr(Elem("REAL", 4), 3, 2), out var layout).ShouldBeNull();
|
||
layout.ShouldBe(new TwinCATArrayLayout(6, 4));
|
||
}
|
||
|
||
/// <summary>
|
||
/// An authored ArrayLength SHORTER than the PLC array reads the leading sub-range only: the first
|
||
/// N elements in PLC memory order, at N × stride bytes from the array start — cheap (a smaller
|
||
/// notification) and well-defined, and it matches the node's advertised ArrayDimensions.
|
||
/// </summary>
|
||
[Fact]
|
||
public void CheckArray_plans_a_leading_sub_range_when_the_authored_length_is_shorter()
|
||
{
|
||
Check(TwinCATDataType.Real, 5, Arr(Elem("REAL", 4), 20), out var layout).ShouldBeNull();
|
||
layout.ShouldBe(new TwinCATArrayLayout(5, 4));
|
||
layout.ByteLength.ShouldBe(20);
|
||
}
|
||
|
||
/// <summary>An authored ArrayLength LONGER than the PLC array would read past it — refused.</summary>
|
||
[Fact]
|
||
public void CheckArray_refuses_an_authored_length_longer_than_the_plc_array()
|
||
=> Check(TwinCATDataType.UInt, 14, Arr(Elem("UINT", 2), 13), out _)!.ShouldContain("13");
|
||
|
||
/// <summary>A zero or negative authored length is not an array.</summary>
|
||
[Fact]
|
||
public void CheckArray_refuses_a_non_positive_authored_length()
|
||
=> Check(TwinCATDataType.UInt, 0, Arr(Elem("UINT", 2), 13), out _).ShouldNotBeNull();
|
||
|
||
/// <summary>
|
||
/// The element is checked with the same rules as a scalar notification (TwinCAT-002/-008): width,
|
||
/// float/integer kind and string kind must agree; a same-width, same-kind divergence is tolerated.
|
||
/// </summary>
|
||
[Fact]
|
||
public void CheckArray_checks_the_element_like_a_scalar_notification()
|
||
{
|
||
Check(TwinCATDataType.DInt, 4, Arr(Elem("REAL", 4), 4), out _).ShouldNotBeNull(); // float kind
|
||
Check(TwinCATDataType.Int, 4, Arr(Elem("DINT", 4), 4), out _).ShouldNotBeNull(); // width
|
||
Check(TwinCATDataType.DInt, 4, Arr(Elem("STRING(80)", 81, DataTypeCategory.String), 4), out _).ShouldNotBeNull();
|
||
Check(TwinCATDataType.String, 4, Arr(Elem("INT", 2), 4), out _).ShouldNotBeNull();
|
||
Check(TwinCATDataType.WString, 4, Arr(Elem("STRING(80)", 81, DataTypeCategory.String), 4), out _).ShouldNotBeNull();
|
||
|
||
Check(TwinCATDataType.Int, 4, Arr(Elem("UINT", 2), 4), out _).ShouldBeNull(); // same width, same kind
|
||
Check(TwinCATDataType.Time, 13, Arr(Elem("TIME", 4), 13), out _).ShouldBeNull();
|
||
Check(TwinCATDataType.USInt, 6, Arr(Elem("USINT", 1), 6), out _).ShouldBeNull();
|
||
Check(TwinCATDataType.SInt, 13, Arr(Elem("BYTE", 1), 13), out _).ShouldBeNull();
|
||
Check(TwinCATDataType.Bool, 19, Arr(Elem("BOOL", 1), 19), out _).ShouldBeNull();
|
||
Check(TwinCATDataType.LReal, 32, Arr(Elem("LREAL", 8), 32), out _).ShouldBeNull();
|
||
}
|
||
|
||
/// <summary>A STRING(n) / WSTRING(n) element is laid out at the PLC's own width: n+1 / 2(n+1).</summary>
|
||
[Fact]
|
||
public void CheckArray_strides_a_string_array_by_the_plc_element_width()
|
||
{
|
||
Check(TwinCATDataType.String, 10, Arr(Elem("STRING(80)", 81, DataTypeCategory.String), 10), out var s).ShouldBeNull();
|
||
s.ShouldBe(new TwinCATArrayLayout(10, 81));
|
||
Check(TwinCATDataType.WString, 3, Arr(Elem("WSTRING(20)", 42, DataTypeCategory.String), 3), out var w).ShouldBeNull();
|
||
w.ShouldBe(new TwinCATArrayLayout(3, 42));
|
||
}
|
||
|
||
/// <summary>
|
||
/// Arrays of structs / UDTs / FBs, of pointers, and arrays of arrays (jagged) have no scalar element
|
||
/// the driver can decode — refused with a reason that says so.
|
||
/// </summary>
|
||
[Fact]
|
||
public void CheckArray_refuses_struct_pointer_and_nested_array_elements()
|
||
{
|
||
Check(TwinCATDataType.DInt, 13, Arr(Elem("ST_CARRIERDATA", 120, DataTypeCategory.Struct), 13), out _).ShouldNotBeNull();
|
||
Check(TwinCATDataType.DInt, 4, Arr(Elem("POINTER TO BYTE", 4, DataTypeCategory.Pointer), 4), out _).ShouldNotBeNull();
|
||
Check(TwinCATDataType.Int, 2, Arr(Elem("ARRAY [0..2] OF INT", 6, DataTypeCategory.Array), 2), out _).ShouldNotBeNull();
|
||
}
|
||
|
||
/// <summary>
|
||
/// An array tag over a PLC symbol that is not an array (a scalar, a string, an element path such
|
||
/// as <c>Arr[3]</c>) is refused: there is no array to read.
|
||
/// </summary>
|
||
[Fact]
|
||
public void CheckArray_refuses_a_plc_symbol_that_is_not_an_array()
|
||
{
|
||
TwinCATTypeGuard.CheckArray(TwinCATDataType.DInt, 4, Elem("DINT", 4), null, out _).ShouldNotBeNull();
|
||
TwinCATTypeGuard.CheckArray(TwinCATDataType.String, 4,
|
||
Elem("STRING(80)", 81, DataTypeCategory.String), null, out _).ShouldNotBeNull();
|
||
}
|
||
|
||
/// <summary>A <c>VAR_IN_OUT</c> array member is a reference, not the array — refused.</summary>
|
||
[Fact]
|
||
public void CheckArray_refuses_a_var_in_out_reference()
|
||
{
|
||
var symbol = TwinCATPlcSymbolShape.Classify("ARRAY [1..3] OF INT", DataTypeCategory.Array, 4,
|
||
dataTypeByteSize: 6, symbolTypeName: "ARRAY [1..3] OF INT (VAR_IN_OUT)");
|
||
TwinCATTypeGuard.CheckArray(TwinCATDataType.Int, 3, symbol, Arr(Elem("INT", 2), 3), out _).ShouldNotBeNull();
|
||
}
|
||
|
||
/// <summary>
|
||
/// A layout whose element count × element size disagrees with the array's own byte size is not
|
||
/// a packed array the driver understands (padding, a mis-resolved element) — refused rather than
|
||
/// decoded at the wrong offsets.
|
||
/// </summary>
|
||
[Fact]
|
||
public void CheckArray_refuses_an_array_whose_size_is_not_count_times_element_size()
|
||
{
|
||
var padded = new TwinCATPlcArrayShape([4], 32, Elem("INT", 2));
|
||
Check(TwinCATDataType.Int, 4, padded, out _).ShouldNotBeNull();
|
||
}
|
||
|
||
// ---- guard: notification size ----
|
||
|
||
/// <summary>
|
||
/// A native notification is capped at <see cref="TwinCATTypeGuard.MaxNotificationArrayBytes"/>
|
||
/// (128 KiB — the largest registration proven on a real target: a TC 2.11
|
||
/// <c>ARRAY [0..65535] OF UINT</c>). Above it the tag is refused with a reason pointing at polling.
|
||
/// </summary>
|
||
[Fact]
|
||
public void CheckNotificationSize_caps_a_native_array_at_128_KiB()
|
||
{
|
||
TwinCATTypeGuard.MaxNotificationArrayBytes.ShouldBe(128 * 1024);
|
||
TwinCATTypeGuard.CheckNotificationSize(new TwinCATArrayLayout(65536, 2)).ShouldBeNull();
|
||
TwinCATTypeGuard.CheckNotificationSize(new TwinCATArrayLayout(65537, 2))!.ShouldContain("UseNativeNotifications");
|
||
}
|
||
|
||
// ---- codec: decode ----
|
||
|
||
/// <summary>Each numeric element type decodes little-endian into its CLR array, in PLC memory order.</summary>
|
||
[Fact]
|
||
public void Decode_numeric_elements_little_endian_into_the_declared_clr_array()
|
||
{
|
||
Decode<short>(TwinCATDataType.Int, 2, [-1, 300], (b, v) => BinaryPrimitives.WriteInt16LittleEndian(b, v));
|
||
Decode<ushort>(TwinCATDataType.UInt, 2, [65535, 7], (b, v) => BinaryPrimitives.WriteUInt16LittleEndian(b, v));
|
||
Decode<int>(TwinCATDataType.DInt, 4, [-123456, 42], (b, v) => BinaryPrimitives.WriteInt32LittleEndian(b, v));
|
||
Decode<uint>(TwinCATDataType.UDInt, 4, [4_000_000_000, 1], (b, v) => BinaryPrimitives.WriteUInt32LittleEndian(b, v));
|
||
Decode<long>(TwinCATDataType.LInt, 8, [long.MinValue, 9], (b, v) => BinaryPrimitives.WriteInt64LittleEndian(b, v));
|
||
Decode<ulong>(TwinCATDataType.ULInt, 8, [ulong.MaxValue, 3], (b, v) => BinaryPrimitives.WriteUInt64LittleEndian(b, v));
|
||
Decode<float>(TwinCATDataType.Real, 4, [949.2f, -0.5f], (b, v) => BinaryPrimitives.WriteSingleLittleEndian(b, v));
|
||
Decode<double>(TwinCATDataType.LReal, 8, [Math.PI, -1e300], (b, v) => BinaryPrimitives.WriteDoubleLittleEndian(b, v));
|
||
Decode<sbyte>(TwinCATDataType.SInt, 1, [-128, 127], (b, v) => b[0] = unchecked((byte)v));
|
||
Decode<byte>(TwinCATDataType.USInt, 1, [0, 255], (b, v) => b[0] = v);
|
||
}
|
||
|
||
/// <summary>
|
||
/// TIME / TOD elements publish as Double milliseconds and DATE / DT as UTC DateTime (#306) — the same
|
||
/// CLR shape a scalar publishes. Live: <c>.THROTTLE_MODE_DEFAULT</c> (<c>ARRAY [0..12] OF TIME</c>)
|
||
/// begins <c>0, 10, 20</c> ms.
|
||
/// </summary>
|
||
[Theory]
|
||
[InlineData(TwinCATDataType.Time)]
|
||
[InlineData(TwinCATDataType.TimeOfDay)]
|
||
public void Decode_duration_elements_as_double_ms(TwinCATDataType type)
|
||
=> TwinCATArrayCodec.Decode(type, [0, 0, 0, 0, 10, 0, 0, 0, 20, 0, 0, 0], new TwinCATArrayLayout(3, 4), utf8: false)
|
||
.ShouldBe(new double[] { 0, 10, 20 });
|
||
|
||
/// <summary>DATE / DT elements decode to UTC DateTime from seconds since 1970.</summary>
|
||
[Theory]
|
||
[InlineData(TwinCATDataType.Date)]
|
||
[InlineData(TwinCATDataType.DateTime)]
|
||
public void Decode_date_elements_as_utc_datetime(TwinCATDataType type)
|
||
=> TwinCATArrayCodec.Decode(type, [0, 0, 0, 0, 60, 0, 0, 0], new TwinCATArrayLayout(2, 4), utf8: false)
|
||
.ShouldBe(new[]
|
||
{
|
||
new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc),
|
||
new DateTime(1970, 1, 1, 0, 1, 0, DateTimeKind.Utc),
|
||
});
|
||
|
||
/// <summary>A BOOL element is one byte; any non-zero byte is TRUE (live: <c>.ARGTYPE_IS_BIT_TYPE</c>).</summary>
|
||
[Fact]
|
||
public void Decode_bool_elements_one_byte_each_non_zero_is_true()
|
||
=> TwinCATArrayCodec.Decode(TwinCATDataType.Bool, [0, 1, 1, 0xFF, 0], new TwinCATArrayLayout(5, 1), utf8: false)
|
||
.ShouldBe(new[] { false, true, true, true, false });
|
||
|
||
/// <summary>
|
||
/// Each STRING(n) element sits at a fixed n+1 stride and ends at ITS first NUL — the stale tail a
|
||
/// longer earlier value left (live on Z33856) never leaks into the element, nor into the next one.
|
||
/// Windows-1252 unless the target reports UTF-8, exactly like a scalar string.
|
||
/// </summary>
|
||
[Fact]
|
||
public void Decode_string_elements_at_their_stride_each_ending_at_its_first_nul()
|
||
{
|
||
var bytes = new byte[3 * 6]; // STRING(5)
|
||
"RUN"u8.CopyTo(bytes.AsSpan(0));
|
||
bytes[4] = (byte)'T'; // stale tail after the NUL
|
||
"MON_O"u8.CopyTo(bytes.AsSpan(6)); // full-length, no NUL before the stride end
|
||
bytes[12] = 0xB0; // '°' in Windows-1252
|
||
TwinCATArrayCodec.Decode(TwinCATDataType.String, bytes, new TwinCATArrayLayout(3, 6), utf8: false)
|
||
.ShouldBe(new[] { "RUN", "MON_O", "°" });
|
||
|
||
var utf8 = new byte[2 * 4];
|
||
"°C"u8.CopyTo(utf8.AsSpan(0));
|
||
TwinCATArrayCodec.Decode(TwinCATDataType.String, utf8, new TwinCATArrayLayout(2, 4), utf8: true)
|
||
.ShouldBe(new[] { "°C", "" });
|
||
}
|
||
|
||
/// <summary>Each WSTRING(n) element is UTF-16LE at a 2(n+1) stride, ending at its first aligned U+0000.</summary>
|
||
[Fact]
|
||
public void Decode_wstring_elements_at_their_stride()
|
||
{
|
||
var bytes = new byte[2 * 8]; // WSTRING(3)
|
||
Encoding.Unicode.GetBytes("Ab").CopyTo(bytes, 0);
|
||
Encoding.Unicode.GetBytes("Zürn").CopyTo(bytes, 8); // 4 chars fill the whole stride
|
||
TwinCATArrayCodec.Decode(TwinCATDataType.WString, bytes, new TwinCATArrayLayout(2, 8), utf8: false)
|
||
.ShouldBe(new[] { "Ab", "Zürn" });
|
||
}
|
||
|
||
/// <summary>A sub-range layout decodes only its leading elements, even from a longer buffer.</summary>
|
||
[Fact]
|
||
public void Decode_honours_the_layout_count_not_the_buffer_length()
|
||
=> TwinCATArrayCodec.Decode(TwinCATDataType.Int, [1, 0, 2, 0, 3, 0], new TwinCATArrayLayout(2, 2), utf8: false)
|
||
.ShouldBe(new short[] { 1, 2 });
|
||
|
||
/// <summary>A buffer shorter than the layout is a protocol fault, never a silently-short array.</summary>
|
||
[Fact]
|
||
public void Decode_refuses_a_buffer_shorter_than_the_layout()
|
||
=> Should.Throw<ArgumentException>(() =>
|
||
TwinCATArrayCodec.Decode(TwinCATDataType.Int, [1, 0, 2], new TwinCATArrayLayout(2, 2), utf8: false));
|
||
|
||
private static void Decode<T>(TwinCATDataType type, int stride, T[] values, Action<Span<byte>, T> write)
|
||
{
|
||
var bytes = new byte[values.Length * stride];
|
||
for (var i = 0; i < values.Length; i++) write(bytes.AsSpan(i * stride, stride), values[i]);
|
||
var decoded = TwinCATArrayCodec.Decode(type, bytes, new TwinCATArrayLayout(values.Length, stride), utf8: false);
|
||
decoded.ShouldBeOfType<T[]>().ShouldBe(values);
|
||
}
|
||
}
|