feat(heidenhain): PLC/DATA parity with pyLSV2 — FF bits, INPUT/OUTPUT_DWORD, PLCDEBUG write-up

- PLC bit areas (MARKER/INPUT/OUTPUT/COUNTER/TIMER) accept 00/01/FF: real iTNC 530s
  return FF for the same operands over R_DP, and pyLSV2 decodes them as non-zero = true.
  02..FE stay BadDecodingError.
- New PLC:INPUT_DWORD / PLC:OUTPUT_DWORD areas (pyLSV2 MemoryType 13/12): signed
  int32le, element index x 4 over the input/output-word byte pools.
- R_PR offsets agree with pyLSV2. Its count units (BYTE x2, WORD/IW as word counts)
  conflict with the captured controls, so we keep the captures and pin them in a test.
- Docs: pyLSV2 correspondence table, native-operand mapping (no aliases), and why
  raw R_MB is refused (pyLSV2 logs in as the write-capable PLCDEBUG role). That stays
  an owner decision; Lsv2ReadOnlyPolicy is unchanged.

Claude-Session: https://claude.ai/code/session_01GT67AD99zQQqpLCVm3p7xk
This commit is contained in:
Joseph Doherty
2026-11-12 23:53:16 -05:00
parent d9b2381235
commit 50933d57fc
7 changed files with 271 additions and 9 deletions
@@ -0,0 +1,162 @@
using System.Buffers.Binary;
using System.Text;
using Shouldly;
using Xunit;
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
using ZB.MOM.WW.OtOpcUa.Driver.Heidenhain.Lsv2;
using ZB.MOM.WW.OtOpcUa.Driver.Heidenhain.Tests.Simulator;
namespace ZB.MOM.WW.OtOpcUa.Driver.Heidenhain.Tests;
/// <summary>
/// PLC-memory (<c>R_PR</c>/<c>R_MB</c>) and DATA-path (<c>R_DP</c>) parity with pyLSV2 (MIT). Where pyLSV2
/// disagrees with a real iTNC 530 capture the capture wins and the test pins the capture (see
/// <c>docs/drivers/Heidenhain.md</c> §"pyLSV2 correspondence").
/// </summary>
[Trait("Category", "Unit")]
public sealed class HeidenhainPyLsv2ParityTests
{
[Theory]
[InlineData(HeidenhainPlcArea.Marker)]
[InlineData(HeidenhainPlcArea.Input)]
[InlineData(HeidenhainPlcArea.Output)]
[InlineData(HeidenhainPlcArea.Counter)]
[InlineData(HeidenhainPlcArea.Timer)]
public void Plc_bit_areas_accept_the_ff_true_byte_real_controls_return_for_the_same_operands(HeidenhainPlcArea area)
{
// R_DP /PLC/memory/I/999 answered type 11 + FF on hermle59; pyLSV2 read_plc_memory unpacks "?" (non-zero = true).
HeidenhainBindingCodec.DecodePlc(area, [0xFF], DriverDataType.Boolean).ShouldBe(true);
HeidenhainBindingCodec.DecodePlc(area, [0x01], DriverDataType.Boolean).ShouldBe(true);
HeidenhainBindingCodec.DecodePlc(area, [0x00], DriverDataType.Boolean).ShouldBe(false);
// Still strict: pyLSV2 would call 0x02 true, but no control has been seen to send it.
Should.Throw<Lsv2DecodeException>(() => HeidenhainBindingCodec.DecodePlc(area, [0x02], DriverDataType.Boolean));
Should.Throw<Lsv2DecodeException>(() => HeidenhainBindingCodec.DecodePlc(area, [0x00, 0x00], DriverDataType.Boolean));
}
[Fact]
public void The_captured_ff_bit_is_the_same_byte_the_r_mb_decoder_now_accepts()
{
var f = Fixtures.Load("plc-count-units.properties");
var reply = f["hermle59.I.999"]; // S_DP:0000000bff
var value = Convert.FromHexString(reply["S_DP:".Length..]);
Lsv2Data.DataPath(value).ShouldBe(true);
HeidenhainBindingCodec.DecodePlc(HeidenhainPlcArea.Input, value.AsSpan(4), DriverDataType.Boolean).ShouldBe(true);
}
[Theory]
[InlineData("PLC:INPUT_DWORD:3", HeidenhainPlcArea.InputDword)]
[InlineData("PLC:OUTPUT_DWORD:0", HeidenhainPlcArea.OutputDword)]
public void Input_and_output_dword_areas_parse_as_element_indexes(string address, HeidenhainPlcArea area)
{
HeidenhainTagDefinitionFactory.TryFromTagConfig("p", "d", TestTags.Config(address, "Int32"), out var d, out var error)
.ShouldBeTrue(error);
d!.Address.Area.ShouldBe(area);
d.Address.Text.ShouldBe(address);
HeidenhainTagDefinitionFactory.TryFromTagConfig("p", "d", TestTags.Config(address, "Int64"), out _, out _).ShouldBeTrue();
// int32 must not be narrowed into Int16; it is not a Boolean/String area.
HeidenhainTagDefinitionFactory.TryFromTagConfig("p", "d", TestTags.Config(address, "Int16"), out _, out _).ShouldBeFalse();
HeidenhainTagDefinitionFactory.TryFromTagConfig("p", "d", TestTags.Config(address, "Boolean"), out _, out _).ShouldBeFalse();
HeidenhainAddress.AreaTokens.ShouldContain(address.Split(':')[1]);
}
[Fact]
public void Dword_io_views_share_the_word_pools_with_element_index_times_four()
{
var layout = Lsv2Data.Layout(SimulatedControl.LayoutBytes(10));
var iw = layout.Region(HeidenhainPlcArea.InputWord)!;
var ow = layout.Region(HeidenhainPlcArea.OutputWord)!;
HeidenhainBindingCodec.Range(HeidenhainPlcArea.InputDword, 1, layout).ShouldBe(new HeidenhainMemoryRange(iw.Base + 4, 4));
HeidenhainBindingCodec.Range(HeidenhainPlcArea.OutputDword, 1, layout).ShouldBe(new HeidenhainMemoryRange(ow.Base + 4, 4));
Should.Throw<HeidenhainRangeException>(() => HeidenhainBindingCodec.Range(HeidenhainPlcArea.InputDword, 2, layout));
Should.Throw<HeidenhainRangeException>(() => HeidenhainBindingCodec.Range(HeidenhainPlcArea.OutputDword, 2, layout));
}
[Theory]
[InlineData("hermle59")]
[InlineData("hermle70")]
[InlineData("hermle29")]
public void Captured_layouts_give_dword_io_views_a_quarter_of_the_byte_pool(string machine)
{
// The input/output word pools are 1000 BYTES on these controls (IW998 is the last valid R_DP word); a
// DWORD view therefore holds 250 elements. pyLSV2 caps INPUT_DWORD at count/4 too.
var f = Fixtures.Load("plc-count-units.properties");
var layout = Lsv2Data.Layout(Convert.FromHexString(f[machine + ".layout"]));
var iw = layout.Region(HeidenhainPlcArea.InputWord)!;
HeidenhainBindingCodec.Range(HeidenhainPlcArea.InputDword, 249, layout).Address.ShouldBe(iw.Base + 996);
Should.Throw<HeidenhainRangeException>(() => HeidenhainBindingCodec.Range(HeidenhainPlcArea.InputDword, 250, layout));
var ow = layout.Region(HeidenhainPlcArea.OutputWord)!;
HeidenhainBindingCodec.Range(HeidenhainPlcArea.OutputDword, 249, layout).Address.ShouldBe(ow.Base + 996);
Should.Throw<HeidenhainRangeException>(() => HeidenhainBindingCodec.Range(HeidenhainPlcArea.OutputDword, 250, layout));
}
[Theory]
[InlineData("hermle59")]
[InlineData("hermle70")]
[InlineData("hermle29")]
public void Captured_layouts_contradict_pyLSV2_word_count_units(string machine)
{
// pyLSV2 read_plc_memory: BYTE max = count×2, WORD max = count, INPUT_WORD max = count (count read as words).
// The real controls refuse B10000 / W10000 / IW1000 over R_DP, and each advertised base + count is exactly
// the next advertised base — the counts are bytes. Pin the capture, not pyLSV2.
var f = Fixtures.Load("plc-count-units.properties");
var layout = Lsv2Data.Layout(Convert.FromHexString(f[machine + ".layout"]));
var words = layout.Region(HeidenhainPlcArea.Word)!;
var iw = layout.Region(HeidenhainPlcArea.InputWord)!;
var ow = layout.Region(HeidenhainPlcArea.OutputWord)!;
var markers = layout.Region(HeidenhainPlcArea.Marker)!;
(words.Base + words.Bytes).ShouldBe(iw.Base);
(iw.Base + iw.Bytes).ShouldBe(ow.Base);
(ow.Base + ow.Bytes).ShouldBe(markers.Base);
f[machine + ".B.10000"].ShouldStartWith("T_ER");
f[machine + ".W.9998"].ShouldStartWith("S_DP");
f[machine + ".IW.998"].ShouldStartWith("S_DP");
f[machine + ".IW.1000"].ShouldStartWith("T_ER");
Should.Throw<HeidenhainRangeException>(() => HeidenhainBindingCodec.Range(HeidenhainPlcArea.Byte, 10000, layout));
Should.Throw<HeidenhainRangeException>(() => HeidenhainBindingCodec.Range(HeidenhainPlcArea.Word, 5000, layout));
Should.Throw<HeidenhainRangeException>(() => HeidenhainBindingCodec.Range(HeidenhainPlcArea.InputWord, 500, layout));
}
[Fact]
public void Dword_io_decodes_signed_int32_little_endian()
{
HeidenhainBindingCodec.DecodePlc(HeidenhainPlcArea.InputDword, [0xFE, 0xFF, 0xFF, 0xFF], DriverDataType.Int32).ShouldBe(-2);
HeidenhainBindingCodec.DecodePlc(HeidenhainPlcArea.OutputDword, [0x01, 0x02, 0x03, 0x04], DriverDataType.Int64).ShouldBe(0x04030201L);
Should.Throw<Lsv2DecodeException>(() => HeidenhainBindingCodec.DecodePlc(HeidenhainPlcArea.InputDword, [0, 0], DriverDataType.Int32));
}
[Fact]
public void Plc_request_is_element_index_times_width_plus_base_like_pyLSV2()
{
// pyLSV2 read_plc_memory: address = start + first_element × mem_byte_count; count byte = width for one element.
var layout = Lsv2Data.Layout(SimulatedControl.LayoutBytes(10));
var w = layout.Region(HeidenhainPlcArea.Word)!;
var range = HeidenhainBindingCodec.Range(HeidenhainPlcArea.Word, 3, layout);
range.ShouldBe(new HeidenhainMemoryRange(w.Base + 6, 2));
var payload = Lsv2ReadOnlyPolicy.MemoryPayload(range.Address, range.Bytes);
BinaryPrimitives.ReadUInt32BigEndian(payload).ShouldBe((uint)(w.Base + 6));
payload[4].ShouldBe((byte)2);
}
[Fact]
public void Data_path_request_matches_pyLSV2_formatting()
{
// pyLSV2 read_data_path: four 0x00 bytes + path with / → \ and " → ' + NUL.
var payload = Lsv2ReadOnlyPolicy.DataPathPayload("/TABLE/TOOL/T/1/\"DOC\"");
payload[..4].ShouldBe(new byte[4]);
Encoding.Latin1.GetString(payload, 4, payload.Length - 4).ShouldBe("\\TABLE\\TOOL\\T\\1\\'DOC'\0");
}
[Fact]
public void Data_path_value_types_match_pyLSV2_table()
{
Lsv2Data.DataPath([0, 0, 0, 2, 0xFF, 0xFE]).ShouldBe(-2); // !h
Lsv2Data.DataPath([0, 0, 0, 3, 0xFF, 0xFF, 0xFF, 0xFE]).ShouldBe(-2); // !l
var dbl = new byte[12];
dbl[3] = 5;
BinaryPrimitives.WriteDoubleLittleEndian(dbl.AsSpan(4), 1.25); // <d
Lsv2Data.DataPath(dbl).ShouldBe(1.25);
Lsv2Data.DataPath([0, 0, 0, 8, (byte)'A', 0]).ShouldBe("A");
Lsv2Data.DataPath([0, 0, 0, 16, 0xFF]).ShouldBe(-1); // !b
Lsv2Data.DataPath([0, 0, 0, 17, 0xFF]).ShouldBe(255); // !B
}
}
@@ -153,7 +153,7 @@ public sealed class Lsv2DataTests
HeidenhainBindingCodec.DecodePlc(HeidenhainPlcArea.InputWord, [0xFF, 0xFF], DriverDataType.Int32).ShouldBe(65535);
HeidenhainBindingCodec.DecodePlc(HeidenhainPlcArea.Word, [0xFF, 0xFF], DriverDataType.Int16).ShouldBe((short)-1);
HeidenhainBindingCodec.DecodePlc(HeidenhainPlcArea.Marker, [1], DriverDataType.Boolean).ShouldBe(true);
Should.Throw<Lsv2DecodeException>(() => HeidenhainBindingCodec.DecodePlc(HeidenhainPlcArea.Marker, [0xFF], DriverDataType.Boolean));
Should.Throw<Lsv2DecodeException>(() => HeidenhainBindingCodec.DecodePlc(HeidenhainPlcArea.Marker, [0x02], DriverDataType.Boolean));
Should.Throw<Lsv2DecodeException>(() => HeidenhainBindingCodec.DecodePlc(HeidenhainPlcArea.Dword, new byte[3], DriverDataType.Int64));
Should.Throw<HeidenhainTypeMismatchException>(() => HeidenhainBindingCodec.Coerce(1.5, DriverDataType.Int32));
Should.Throw<HeidenhainTypeMismatchException>(() => HeidenhainBindingCodec.Coerce(32768, DriverDataType.Int16));