d78a471e90
Closes #226 Adds nullable StringLength to AbCipTagDefinition + AbCipStructureMember so STRING_20 / STRING_40 / STRING_80 UDT variants decode against the right DATA-array capacity. The configured length threads through a new StringMaxCapacity field on AbCipTagCreateParams and lands on the libplctag Tag.StringMaxCapacity attribute (verified property on libplctag 1.5.2). Null leaves libplctag's default 82-byte STRING in place for back-compat. Driver gates on DataType == String so a stray StringLength on a DINT tag doesn't reshape that buffer. UDT member fan-out copies StringLength from the AbCipStructureMember onto the synthesised member tag definition. Tests: 4 new in AbCipDriverReadTests covering threaded StringMaxCapacity, the null back-compat path, the non-String gate, and the UDT-member fan-out.
80 lines
3.9 KiB
C#
80 lines
3.9 KiB
C#
namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip;
|
|
|
|
/// <summary>
|
|
/// Thin wire-layer abstraction over a single CIP tag. The driver holds one instance per
|
|
/// <c>(device, tag path)</c> pair; the default implementation delegates to
|
|
/// <see cref="LibplctagTagRuntime"/>. Tests swap in a fake via
|
|
/// <see cref="IAbCipTagFactory"/> so the driver's read / write / status-mapping logic can
|
|
/// be exercised without a running PLC or the native libplctag binary.
|
|
/// </summary>
|
|
public interface IAbCipTagRuntime : IDisposable
|
|
{
|
|
/// <summary>Create the underlying native tag (equivalent to libplctag's <c>plc_tag_create</c>).</summary>
|
|
Task InitializeAsync(CancellationToken cancellationToken);
|
|
|
|
/// <summary>Issue a read; on completion the local buffer holds the current PLC value.</summary>
|
|
Task ReadAsync(CancellationToken cancellationToken);
|
|
|
|
/// <summary>Flush the local buffer to the PLC.</summary>
|
|
Task WriteAsync(CancellationToken cancellationToken);
|
|
|
|
/// <summary>
|
|
/// Raw libplctag status code — mapped to an OPC UA StatusCode via
|
|
/// <see cref="AbCipStatusMapper.MapLibplctagStatus"/>. Zero on success, negative on error.
|
|
/// </summary>
|
|
int GetStatus();
|
|
|
|
/// <summary>
|
|
/// Decode the local buffer into a boxed .NET value per the tag's configured type.
|
|
/// <paramref name="bitIndex"/> is non-null only for BOOL-within-DINT tags captured in
|
|
/// the <c>.N</c> syntax at parse time.
|
|
/// </summary>
|
|
object? DecodeValue(AbCipDataType type, int? bitIndex);
|
|
|
|
/// <summary>
|
|
/// Decode a value at an arbitrary byte offset in the local buffer. Task #194 —
|
|
/// whole-UDT reads perform one <see cref="ReadAsync"/> on the parent UDT tag then
|
|
/// call this per declared member with its computed offset, avoiding one libplctag
|
|
/// round-trip per member. Implementations that do not support offset-aware decoding
|
|
/// may fall back to <see cref="DecodeValue"/> when <paramref name="offset"/> is zero;
|
|
/// offsets greater than zero against an unsupporting runtime should return <c>null</c>
|
|
/// so the planner can skip grouping.
|
|
/// </summary>
|
|
object? DecodeValueAt(AbCipDataType type, int offset, int? bitIndex);
|
|
|
|
/// <summary>
|
|
/// Encode <paramref name="value"/> into the local buffer per the tag's type. Callers
|
|
/// pair this with <see cref="WriteAsync"/>.
|
|
/// </summary>
|
|
void EncodeValue(AbCipDataType type, int? bitIndex, object? value);
|
|
}
|
|
|
|
/// <summary>
|
|
/// Factory for per-tag runtime handles. Instantiated once per driver, consumed per
|
|
/// <c>(device, tag path)</c> pair at the first read/write.
|
|
/// </summary>
|
|
public interface IAbCipTagFactory
|
|
{
|
|
IAbCipTagRuntime Create(AbCipTagCreateParams createParams);
|
|
}
|
|
|
|
/// <summary>Everything libplctag needs to materialise a tag handle.</summary>
|
|
/// <param name="Gateway">Gateway IP / hostname parsed from <see cref="AbCipHostAddress.Gateway"/>.</param>
|
|
/// <param name="Port">EtherNet/IP TCP port — default 44818.</param>
|
|
/// <param name="CipPath">CIP route path, e.g. <c>1,0</c>. Empty for Micro800.</param>
|
|
/// <param name="LibplctagPlcAttribute">libplctag <c>plc=...</c> attribute, per family profile.</param>
|
|
/// <param name="TagName">Logix symbolic tag name as emitted by <see cref="AbCipTagPath.ToLibplctagName"/>.</param>
|
|
/// <param name="Timeout">libplctag operation timeout (applies to Initialize / Read / Write).</param>
|
|
/// <param name="StringMaxCapacity">Optional Logix STRINGnn DATA-array capacity (e.g. 20 / 40 / 80
|
|
/// for <c>STRING_20</c> / <c>STRING_40</c> / <c>STRING_80</c> UDTs). Threads through libplctag's
|
|
/// <c>str_max_capacity</c> attribute. <c>null</c> keeps libplctag's default 82-byte STRING
|
|
/// behaviour for back-compat.</param>
|
|
public sealed record AbCipTagCreateParams(
|
|
string Gateway,
|
|
int Port,
|
|
string CipPath,
|
|
string LibplctagPlcAttribute,
|
|
string TagName,
|
|
TimeSpan Timeout,
|
|
int? StringMaxCapacity = null);
|