TwinCAT PR 1 — Scaffolding + Core (TwinCATDriver + AMS address + symbolic path). New Driver.TwinCAT project referencing Beckhoff.TwinCAT.Ads 7.0.172 (the official Beckhoff .NET client — 1.6M+ downloads, actively maintained by Beckhoff + community). Package compiles without a local AMS router; wire calls need a running router (TwinCAT XAR on dev Windows, or the standalone Beckhoff.TwinCAT.Ads.TcpRouter embedded package for headless/CI). Same Core.Abstractions-only project shape as Modbus / AbCip / AbLegacy. TwinCATAmsAddress parses ads://{netId}:{port} canonical form — NetId is 6 dot-separated octets (NOT an IP; AMS router translates), port defaults to 851 (TC3 PLC runtime 1). Validates octet range 0-255 and port 1-65535. Case-insensitive scheme. Default-port stripping in canonical form for roundtrip stability. Rejects wrong scheme, missing //, 5-or-7-octet NetId, out-of-range octets/ports, non-numeric fragments. TwinCATSymbolPath handles IEC 61131-3 symbolic names — single-segment (Counter), POU.variable (MAIN.bStart), GVL.variable (GVL.Counter), structured member access (Motor1.Status.Running), array subscripts (Data[5]), multi-dim arrays (Matrix[1,2]), bit-access (Flags.3, GVL.Status.7), combined scope/member/subscript/bit (MAIN.Motors[0].Status.5). Roundtrip-safe ToAdsSymbolName produces the exact string AdsClient.ReadValue consumes. Rejects leading/trailing dots, space in idents, digit-prefix idents, empty/negative/non-numeric subscripts, unbalanced brackets. Underscore-prefix idents accepted per IEC. TwinCATDataType — BOOL / SINT / USINT / INT / UINT / DINT / UDINT / LINT / ULINT / REAL / LREAL / STRING / WSTRING (UTF-16) / TIME / DATE / DateTime (DT) / TimeOfDay (TOD) / Structure. Wider than Logix's surface — IEC adds WSTRING + TIME/DATE/DT/TOD variants. ToDriverDataType widens unsigned + 64-bit to Int32 matching the Modbus/AbCip/AbLegacy Int64-gap convention. TwinCATStatusMapper — Good / BadInternalError / BadNodeIdUnknown / BadNotWritable / BadOutOfRange / BadNotSupported / BadDeviceFailure / BadCommunicationError / BadTimeout / BadTypeMismatch. MapAdsError covers the ADS error codes a driver actually encounters — 6/7 port unreachable, 1792 service not supported, 1793/1794 invalid index group/offset, 1798 symbol not found (→ BadNodeIdUnknown), 1807 invalid state, 1808 access denied (→ BadNotWritable), 1811/1812 size mismatch (→ BadOutOfRange), 1861 sync timeout, unknown → BadCommunicationError. TwinCATDriverOptions + TwinCATDeviceOptions + TwinCATTagDefinition + TwinCATProbeOptions — one instance supports N AMS targets, Tags cross-key by HostAddress, Probe defaults to 5s interval (unlike AbLegacy there's no default probe address — ADS probe reads AmsRouterState not a user tag, so probe address is implicit). TwinCATDriver IDriver skeleton — InitializeAsync parses each device HostAddress + fails fast on malformed strings → Faulted. 61 new unit tests across 3 files — TwinCATAmsAddressTests (6 valid shapes + 12 invalid shapes + 2 ToString canonicalisation + roundtrip stability), TwinCATSymbolPathTests (9 valid shapes + 12 invalid shapes + underscore prefix + 8-case roundtrip), TwinCATDriverTests (DriverType + multi-device init + malformed-address fault + shutdown + reinit + data-type mapping theory + ADS error-code theory). Total project count 30 src + 19 tests; full solution builds 0 errors; Modbus / AbCip / AbLegacy / other drivers untouched.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,59 @@
|
||||
using Shouldly;
|
||||
using Xunit;
|
||||
using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests;
|
||||
|
||||
[Trait("Category", "Unit")]
|
||||
public sealed class TwinCATAmsAddressTests
|
||||
{
|
||||
[Theory]
|
||||
[InlineData("ads://5.23.91.23.1.1:851", "5.23.91.23.1.1", 851)]
|
||||
[InlineData("ads://5.23.91.23.1.1:852", "5.23.91.23.1.1", 852)]
|
||||
[InlineData("ads://5.23.91.23.1.1", "5.23.91.23.1.1", 851)] // default port
|
||||
[InlineData("ads://127.0.0.1.1.1:851", "127.0.0.1.1.1", 851)]
|
||||
[InlineData("ADS://5.23.91.23.1.1:851", "5.23.91.23.1.1", 851)] // case-insensitive scheme
|
||||
[InlineData("ads://10.0.0.1.1.1:10000", "10.0.0.1.1.1", 10000)] // system service port
|
||||
public void TryParse_accepts_valid_ams_addresses(string input, string netId, int port)
|
||||
{
|
||||
var parsed = TwinCATAmsAddress.TryParse(input);
|
||||
parsed.ShouldNotBeNull();
|
||||
parsed.NetId.ShouldBe(netId);
|
||||
parsed.Port.ShouldBe(port);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[InlineData(null)]
|
||||
[InlineData("")]
|
||||
[InlineData(" ")]
|
||||
[InlineData("tcp://5.23.91.23.1.1:851")] // wrong scheme
|
||||
[InlineData("ads:5.23.91.23.1.1:851")] // missing //
|
||||
[InlineData("ads://")] // empty body
|
||||
[InlineData("ads://5.23.91.23.1:851")] // only 5 octets
|
||||
[InlineData("ads://5.23.91.23.1.1.1:851")] // 7 octets
|
||||
[InlineData("ads://5.23.91.256.1.1:851")] // octet > 255
|
||||
[InlineData("ads://5.23.91.23.1.1:0")] // port 0
|
||||
[InlineData("ads://5.23.91.23.1.1:65536")] // port out of range
|
||||
[InlineData("ads://5.23.91.23.1.1:abc")] // non-numeric port
|
||||
[InlineData("ads://a.b.c.d.e.f:851")] // non-numeric octets
|
||||
public void TryParse_rejects_invalid_forms(string? input)
|
||||
{
|
||||
TwinCATAmsAddress.TryParse(input).ShouldBeNull();
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[InlineData("5.23.91.23.1.1", 851, "ads://5.23.91.23.1.1")] // default port stripped
|
||||
[InlineData("5.23.91.23.1.1", 852, "ads://5.23.91.23.1.1:852")]
|
||||
public void ToString_canonicalises(string netId, int port, string expected)
|
||||
{
|
||||
new TwinCATAmsAddress(netId, port).ToString().ShouldBe(expected);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void RoundTrip_is_stable()
|
||||
{
|
||||
const string input = "ads://5.23.91.23.1.1:852";
|
||||
var parsed = TwinCATAmsAddress.TryParse(input)!;
|
||||
TwinCATAmsAddress.TryParse(parsed.ToString()).ShouldBe(parsed);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,105 @@
|
||||
using Shouldly;
|
||||
using Xunit;
|
||||
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
||||
using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests;
|
||||
|
||||
[Trait("Category", "Unit")]
|
||||
public sealed class TwinCATDriverTests
|
||||
{
|
||||
[Fact]
|
||||
public void DriverType_is_TwinCAT()
|
||||
{
|
||||
var drv = new TwinCATDriver(new TwinCATDriverOptions(), "drv-1");
|
||||
drv.DriverType.ShouldBe("TwinCAT");
|
||||
drv.DriverInstanceId.ShouldBe("drv-1");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task InitializeAsync_parses_device_addresses()
|
||||
{
|
||||
var drv = new TwinCATDriver(new TwinCATDriverOptions
|
||||
{
|
||||
Devices =
|
||||
[
|
||||
new TwinCATDeviceOptions("ads://5.23.91.23.1.1:851"),
|
||||
new TwinCATDeviceOptions("ads://10.0.0.1.1.1:852", DeviceName: "Machine2"),
|
||||
],
|
||||
}, "drv-1");
|
||||
|
||||
await drv.InitializeAsync("{}", CancellationToken.None);
|
||||
|
||||
drv.DeviceCount.ShouldBe(2);
|
||||
drv.GetDeviceState("ads://5.23.91.23.1.1:851")!.ParsedAddress.Port.ShouldBe(851);
|
||||
drv.GetDeviceState("ads://10.0.0.1.1.1:852")!.Options.DeviceName.ShouldBe("Machine2");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task InitializeAsync_malformed_address_faults()
|
||||
{
|
||||
var drv = new TwinCATDriver(new TwinCATDriverOptions
|
||||
{
|
||||
Devices = [new TwinCATDeviceOptions("not-an-address")],
|
||||
}, "drv-1");
|
||||
|
||||
await Should.ThrowAsync<InvalidOperationException>(
|
||||
() => drv.InitializeAsync("{}", CancellationToken.None));
|
||||
drv.GetHealth().State.ShouldBe(DriverState.Faulted);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task ShutdownAsync_clears_devices()
|
||||
{
|
||||
var drv = new TwinCATDriver(new TwinCATDriverOptions
|
||||
{
|
||||
Devices = [new TwinCATDeviceOptions("ads://5.23.91.23.1.1:851")],
|
||||
}, "drv-1");
|
||||
await drv.InitializeAsync("{}", CancellationToken.None);
|
||||
|
||||
await drv.ShutdownAsync(CancellationToken.None);
|
||||
drv.DeviceCount.ShouldBe(0);
|
||||
drv.GetHealth().State.ShouldBe(DriverState.Unknown);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public async Task ReinitializeAsync_cycles_devices()
|
||||
{
|
||||
var drv = new TwinCATDriver(new TwinCATDriverOptions
|
||||
{
|
||||
Devices = [new TwinCATDeviceOptions("ads://5.23.91.23.1.1:851")],
|
||||
}, "drv-1");
|
||||
await drv.InitializeAsync("{}", CancellationToken.None);
|
||||
await drv.ReinitializeAsync("{}", CancellationToken.None);
|
||||
|
||||
drv.DeviceCount.ShouldBe(1);
|
||||
drv.GetHealth().State.ShouldBe(DriverState.Healthy);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void DataType_mapping_covers_atomic_iec_types()
|
||||
{
|
||||
TwinCATDataType.Bool.ToDriverDataType().ShouldBe(DriverDataType.Boolean);
|
||||
TwinCATDataType.DInt.ToDriverDataType().ShouldBe(DriverDataType.Int32);
|
||||
TwinCATDataType.Real.ToDriverDataType().ShouldBe(DriverDataType.Float32);
|
||||
TwinCATDataType.LReal.ToDriverDataType().ShouldBe(DriverDataType.Float64);
|
||||
TwinCATDataType.String.ToDriverDataType().ShouldBe(DriverDataType.String);
|
||||
TwinCATDataType.WString.ToDriverDataType().ShouldBe(DriverDataType.String);
|
||||
TwinCATDataType.Time.ToDriverDataType().ShouldBe(DriverDataType.Int32);
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[InlineData(0u, TwinCATStatusMapper.Good)]
|
||||
[InlineData(1798u, TwinCATStatusMapper.BadNodeIdUnknown)] // symbol not found
|
||||
[InlineData(1808u, TwinCATStatusMapper.BadNotWritable)] // access denied
|
||||
[InlineData(1861u, TwinCATStatusMapper.BadTimeout)] // sync timeout
|
||||
[InlineData(1793u, TwinCATStatusMapper.BadOutOfRange)] // invalid index group
|
||||
[InlineData(1794u, TwinCATStatusMapper.BadOutOfRange)] // invalid index offset
|
||||
[InlineData(1792u, TwinCATStatusMapper.BadNotSupported)] // service not supported
|
||||
[InlineData(7u, TwinCATStatusMapper.BadCommunicationError)] // port unreachable
|
||||
[InlineData(99999u, TwinCATStatusMapper.BadCommunicationError)] // unknown → generic comm fail
|
||||
public void StatusMapper_covers_known_ads_error_codes(uint adsError, uint expected)
|
||||
{
|
||||
TwinCATStatusMapper.MapAdsError(adsError).ShouldBe(expected);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,138 @@
|
||||
using Shouldly;
|
||||
using Xunit;
|
||||
using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
|
||||
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests;
|
||||
|
||||
[Trait("Category", "Unit")]
|
||||
public sealed class TwinCATSymbolPathTests
|
||||
{
|
||||
[Fact]
|
||||
public void Single_segment_global_variable_parses()
|
||||
{
|
||||
var p = TwinCATSymbolPath.TryParse("Counter");
|
||||
p.ShouldNotBeNull();
|
||||
p.Segments.Single().Name.ShouldBe("Counter");
|
||||
p.ToAdsSymbolName().ShouldBe("Counter");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void POU_dot_variable_parses()
|
||||
{
|
||||
var p = TwinCATSymbolPath.TryParse("MAIN.bStart");
|
||||
p.ShouldNotBeNull();
|
||||
p.Segments.Select(s => s.Name).ShouldBe(["MAIN", "bStart"]);
|
||||
p.ToAdsSymbolName().ShouldBe("MAIN.bStart");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void GVL_reference_parses()
|
||||
{
|
||||
var p = TwinCATSymbolPath.TryParse("GVL.Counter");
|
||||
p.ShouldNotBeNull();
|
||||
p.Segments.Select(s => s.Name).ShouldBe(["GVL", "Counter"]);
|
||||
p.ToAdsSymbolName().ShouldBe("GVL.Counter");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Structured_member_access_splits()
|
||||
{
|
||||
var p = TwinCATSymbolPath.TryParse("Motor1.Status.Running");
|
||||
p.ShouldNotBeNull();
|
||||
p.Segments.Select(s => s.Name).ShouldBe(["Motor1", "Status", "Running"]);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Array_subscript_parses()
|
||||
{
|
||||
var p = TwinCATSymbolPath.TryParse("Data[5]");
|
||||
p.ShouldNotBeNull();
|
||||
p.Segments.Single().Subscripts.ShouldBe([5]);
|
||||
p.ToAdsSymbolName().ShouldBe("Data[5]");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Multi_dim_array_subscript_parses()
|
||||
{
|
||||
var p = TwinCATSymbolPath.TryParse("Matrix[1,2]");
|
||||
p.ShouldNotBeNull();
|
||||
p.Segments.Single().Subscripts.ShouldBe([1, 2]);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Bit_access_captured_as_bit_index()
|
||||
{
|
||||
var p = TwinCATSymbolPath.TryParse("Flags.3");
|
||||
p.ShouldNotBeNull();
|
||||
p.Segments.Single().Name.ShouldBe("Flags");
|
||||
p.BitIndex.ShouldBe(3);
|
||||
p.ToAdsSymbolName().ShouldBe("Flags.3");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Bit_access_after_member_path()
|
||||
{
|
||||
var p = TwinCATSymbolPath.TryParse("GVL.Status.7");
|
||||
p.ShouldNotBeNull();
|
||||
p.Segments.Select(s => s.Name).ShouldBe(["GVL", "Status"]);
|
||||
p.BitIndex.ShouldBe(7);
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Combined_scope_member_subscript_bit()
|
||||
{
|
||||
var p = TwinCATSymbolPath.TryParse("MAIN.Motors[0].Status.5");
|
||||
p.ShouldNotBeNull();
|
||||
p.Segments.Select(s => s.Name).ShouldBe(["MAIN", "Motors", "Status"]);
|
||||
p.Segments[1].Subscripts.ShouldBe([0]);
|
||||
p.BitIndex.ShouldBe(5);
|
||||
p.ToAdsSymbolName().ShouldBe("MAIN.Motors[0].Status.5");
|
||||
}
|
||||
|
||||
[Theory]
|
||||
[InlineData(null)]
|
||||
[InlineData("")]
|
||||
[InlineData(" ")]
|
||||
[InlineData(".Motor")] // leading dot
|
||||
[InlineData("Motor.")] // trailing dot
|
||||
[InlineData("Motor.[0]")] // empty segment
|
||||
[InlineData("1bad")] // ident starts with digit
|
||||
[InlineData("Bad Name")] // space in ident
|
||||
[InlineData("Motor[]")] // empty subscript
|
||||
[InlineData("Motor[-1]")] // negative subscript
|
||||
[InlineData("Motor[a]")] // non-numeric subscript
|
||||
[InlineData("Motor[")] // unbalanced bracket
|
||||
[InlineData("Flags.32")] // bit out of range (treated as ident → invalid shape)
|
||||
public void Invalid_shapes_return_null(string? input)
|
||||
{
|
||||
TwinCATSymbolPath.TryParse(input).ShouldBeNull();
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void Underscore_prefix_idents_accepted()
|
||||
{
|
||||
TwinCATSymbolPath.TryParse("_internal_var")!.Segments.Single().Name.ShouldBe("_internal_var");
|
||||
}
|
||||
|
||||
[Fact]
|
||||
public void ToAdsSymbolName_roundtrips()
|
||||
{
|
||||
var cases = new[]
|
||||
{
|
||||
"Counter",
|
||||
"MAIN.bStart",
|
||||
"GVL.Counter",
|
||||
"Motor1.Status.Running",
|
||||
"Data[5]",
|
||||
"Matrix[1,2]",
|
||||
"Flags.3",
|
||||
"MAIN.Motors[0].Status.5",
|
||||
};
|
||||
foreach (var c in cases)
|
||||
{
|
||||
var parsed = TwinCATSymbolPath.TryParse(c);
|
||||
parsed.ShouldNotBeNull(c);
|
||||
parsed.ToAdsSymbolName().ShouldBe(c);
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,31 @@
|
||||
<Project Sdk="Microsoft.NET.Sdk">
|
||||
|
||||
<PropertyGroup>
|
||||
<TargetFramework>net10.0</TargetFramework>
|
||||
<Nullable>enable</Nullable>
|
||||
<ImplicitUsings>enable</ImplicitUsings>
|
||||
<IsPackable>false</IsPackable>
|
||||
<IsTestProject>true</IsTestProject>
|
||||
<RootNamespace>ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests</RootNamespace>
|
||||
</PropertyGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<PackageReference Include="xunit.v3" Version="1.1.0"/>
|
||||
<PackageReference Include="Shouldly" Version="4.3.0"/>
|
||||
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0"/>
|
||||
<PackageReference Include="xunit.runner.visualstudio" Version="3.0.2">
|
||||
<PrivateAssets>all</PrivateAssets>
|
||||
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
|
||||
</PackageReference>
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<ProjectReference Include="..\..\src\ZB.MOM.WW.OtOpcUa.Driver.TwinCAT\ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.csproj"/>
|
||||
</ItemGroup>
|
||||
|
||||
<ItemGroup>
|
||||
<NuGetAuditSuppress Include="https://github.com/advisories/GHSA-37gx-xxp4-5rgx"/>
|
||||
<NuGetAuditSuppress Include="https://github.com/advisories/GHSA-w3x6-4m5h-cxqf"/>
|
||||
</ItemGroup>
|
||||
|
||||
</Project>
|
||||
Reference in New Issue
Block a user