Joseph Doherty
64e3fbe035
v2-ci / build (push) Failing after 1m43s
v2-ci / unit-tests (tests/Core/ZB.MOM.WW.OtOpcUa.Cluster.Tests) (push) Has been skipped
v2-ci / unit-tests (tests/Server/ZB.MOM.WW.OtOpcUa.ControlPlane.Tests) (push) Has been skipped
v2-ci / unit-tests (tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.Tests) (push) Has been skipped
v2-ci / unit-tests (tests/Server/ZB.MOM.WW.OtOpcUa.Runtime.Tests) (push) Has been skipped
v2-ci / unit-tests (tests/Server/ZB.MOM.WW.OtOpcUa.Security.Tests) (push) Has been skipped
v2-ci / integration (tests/Server/ZB.MOM.WW.OtOpcUa.Host.IntegrationTests) (push) Has been skipped
v2-ci / integration (tests/Server/ZB.MOM.WW.OtOpcUa.OpcUaServer.IntegrationTests) (push) Has been skipped
Adds <summary>, <param>, <typeparam>, and <inheritdoc/> tags to public members surfaced by commentchecker — resolves 5,847 of 5,869 issues (99.6%) across three /fixdocs passes.
333 lines
18 KiB
C#
333 lines
18 KiB
C#
using System.Text.Json;
|
|
using System.Text.Json.Serialization;
|
|
using Microsoft.Extensions.Logging;
|
|
using ZB.MOM.WW.OtOpcUa.Core.Hosting;
|
|
|
|
namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus;
|
|
|
|
/// <summary>
|
|
/// Static factory registration helper for <see cref="ModbusDriver"/>. Server's Program.cs
|
|
/// calls <see cref="Register"/> once at startup; the bootstrapper (task #248) then
|
|
/// materialises Modbus DriverInstance rows from the central config DB into live driver
|
|
/// instances. Mirrors <c>GalaxyProxyDriverFactoryExtensions</c> / <c>FocasDriverFactoryExtensions</c>.
|
|
/// </summary>
|
|
public static class ModbusDriverFactoryExtensions
|
|
{
|
|
public const string DriverTypeName = "Modbus";
|
|
|
|
/// <summary>
|
|
/// Register the Modbus factory with the driver registry. The optional
|
|
/// <paramref name="loggerFactory"/> is captured at registration time and used to
|
|
/// construct an <see cref="ILogger{ModbusDriver}"/> per driver instance — without it,
|
|
/// the driver runs with the null logger (existing tests and standalone callers stay
|
|
/// unchanged).
|
|
/// </summary>
|
|
/// <param name="registry">The driver factory registry to register with.</param>
|
|
/// <param name="loggerFactory">Optional logger factory for creating loggers per driver instance.</param>
|
|
public static void Register(DriverFactoryRegistry registry, ILoggerFactory? loggerFactory = null)
|
|
{
|
|
ArgumentNullException.ThrowIfNull(registry);
|
|
registry.Register(DriverTypeName, (id, json) => CreateInstance(id, json, loggerFactory));
|
|
}
|
|
|
|
/// <summary>Public for the Server-side bootstrapper + test consumers (Admin.Tests, etc.).</summary>
|
|
/// <param name="driverInstanceId">The unique identifier for the driver instance.</param>
|
|
/// <param name="driverConfigJson">The JSON configuration string for the driver.</param>
|
|
public static ModbusDriver CreateInstance(string driverInstanceId, string driverConfigJson)
|
|
=> CreateInstance(driverInstanceId, driverConfigJson, loggerFactory: null);
|
|
|
|
/// <summary>Logger-aware overload — used by <see cref="Register"/>'s closure when wired through DI.</summary>
|
|
/// <param name="driverInstanceId">The unique identifier for the driver instance.</param>
|
|
/// <param name="driverConfigJson">The JSON configuration string for the driver.</param>
|
|
/// <param name="loggerFactory">Optional logger factory for creating loggers per driver instance.</param>
|
|
public static ModbusDriver CreateInstance(string driverInstanceId, string driverConfigJson, ILoggerFactory? loggerFactory)
|
|
{
|
|
ArgumentException.ThrowIfNullOrWhiteSpace(driverInstanceId);
|
|
ArgumentException.ThrowIfNullOrWhiteSpace(driverConfigJson);
|
|
|
|
var dto = JsonSerializer.Deserialize<ModbusDriverConfigDto>(driverConfigJson, JsonOptions)
|
|
?? throw new InvalidOperationException(
|
|
$"Modbus driver config for '{driverInstanceId}' deserialised to null");
|
|
|
|
if (string.IsNullOrWhiteSpace(dto.Host))
|
|
throw new InvalidOperationException(
|
|
$"Modbus driver config for '{driverInstanceId}' missing required Host");
|
|
|
|
var options = new ModbusDriverOptions
|
|
{
|
|
Host = dto.Host!,
|
|
Port = dto.Port ?? 502,
|
|
UnitId = dto.UnitId ?? 1,
|
|
Timeout = TimeSpan.FromMilliseconds(dto.TimeoutMs ?? 2_000),
|
|
MaxRegistersPerRead = dto.MaxRegistersPerRead ?? 125,
|
|
MaxRegistersPerWrite = dto.MaxRegistersPerWrite ?? 123,
|
|
MaxCoilsPerRead = dto.MaxCoilsPerRead ?? 2000,
|
|
UseFC15ForSingleCoilWrites = dto.UseFC15ForSingleCoilWrites ?? false,
|
|
UseFC16ForSingleRegisterWrites = dto.UseFC16ForSingleRegisterWrites ?? false,
|
|
DisableFC23 = dto.DisableFC23 ?? false,
|
|
WriteOnChangeOnly = dto.WriteOnChangeOnly ?? false,
|
|
MaxReadGap = dto.MaxReadGap ?? 0,
|
|
Family = dto.Family is null ? ModbusFamily.Generic
|
|
: ParseEnum<ModbusFamily>(dto.Family, "<driver-level>", driverInstanceId, "Family"),
|
|
MelsecSubFamily = dto.MelsecSubFamily is null ? MelsecFamily.Q_L_iQR
|
|
: ParseEnum<MelsecFamily>(dto.MelsecSubFamily, "<driver-level>", driverInstanceId, "MelsecSubFamily"),
|
|
AutoProhibitReprobeInterval = dto.AutoProhibitReprobeMs is { } reprobeMs ? TimeSpan.FromMilliseconds(reprobeMs) : null,
|
|
AutoReconnect = dto.AutoReconnect ?? true,
|
|
Tags = dto.Tags is { Count: > 0 }
|
|
? [.. dto.Tags.Select(t => BuildTag(
|
|
t, driverInstanceId,
|
|
dto.Family is null ? ModbusFamily.Generic
|
|
: ParseEnum<ModbusFamily>(dto.Family, "<driver-level>", driverInstanceId, "Family"),
|
|
dto.MelsecSubFamily is null ? MelsecFamily.Q_L_iQR
|
|
: ParseEnum<MelsecFamily>(dto.MelsecSubFamily, "<driver-level>", driverInstanceId, "MelsecSubFamily")))]
|
|
: [],
|
|
Probe = new ModbusProbeOptions
|
|
{
|
|
Enabled = dto.Probe?.Enabled ?? true,
|
|
Interval = TimeSpan.FromMilliseconds(dto.Probe?.IntervalMs ?? 5_000),
|
|
Timeout = TimeSpan.FromMilliseconds(dto.Probe?.TimeoutMs ?? 2_000),
|
|
ProbeAddress = dto.Probe?.ProbeAddress ?? 0,
|
|
},
|
|
KeepAlive = dto.KeepAlive is null ? new ModbusKeepAliveOptions() : new ModbusKeepAliveOptions
|
|
{
|
|
Enabled = dto.KeepAlive.Enabled ?? true,
|
|
Time = TimeSpan.FromMilliseconds(dto.KeepAlive.TimeMs ?? 30_000),
|
|
Interval = TimeSpan.FromMilliseconds(dto.KeepAlive.IntervalMs ?? 10_000),
|
|
RetryCount = dto.KeepAlive.RetryCount ?? 3,
|
|
},
|
|
IdleDisconnectTimeout = dto.IdleDisconnectMs is { } ms ? TimeSpan.FromMilliseconds(ms) : null,
|
|
Reconnect = dto.Reconnect is null ? new ModbusReconnectOptions() : new ModbusReconnectOptions
|
|
{
|
|
InitialDelay = TimeSpan.FromMilliseconds(dto.Reconnect.InitialDelayMs ?? 0),
|
|
MaxDelay = TimeSpan.FromMilliseconds(dto.Reconnect.MaxDelayMs ?? 30_000),
|
|
BackoffMultiplier = dto.Reconnect.BackoffMultiplier ?? 2.0,
|
|
},
|
|
};
|
|
|
|
return new ModbusDriver(
|
|
options, driverInstanceId,
|
|
transportFactory: null,
|
|
logger: loggerFactory?.CreateLogger<ModbusDriver>());
|
|
}
|
|
|
|
private static ModbusTagDefinition BuildTag(ModbusTagDto t, string driverInstanceId)
|
|
=> BuildTag(t, driverInstanceId, ModbusFamily.Generic, MelsecFamily.Q_L_iQR);
|
|
|
|
private static ModbusTagDefinition BuildTag(ModbusTagDto t, string driverInstanceId, ModbusFamily family, MelsecFamily melsecSubFamily)
|
|
{
|
|
var name = t.Name ?? throw new InvalidOperationException(
|
|
$"Modbus config for '{driverInstanceId}' has a tag missing Name");
|
|
|
|
// Driver.Modbus-009: a String tag with StringLength = 0 yields RegisterCount = 0, which
|
|
// turns into an FC03/FC04 with quantity 0 — a spec-illegal request the PLC rejects with
|
|
// exception 03. Catch the misconfiguration at bind time with a clear diagnostic instead
|
|
// of waiting for the cryptic Illegal Data Value to surface at runtime.
|
|
|
|
// AddressString takes precedence over the structured fields (Region/Address/DataType/
|
|
// ByteOrder/BitIndex/StringLength/ArrayCount). Tags can mix forms freely — newer pasted
|
|
// rows use the grammar string, legacy rows keep the structured form. Fields not derivable
|
|
// from the grammar (Writable, WriteIdempotent, StringByteOrder) always come from the DTO.
|
|
ModbusTagDefinition tag;
|
|
if (!string.IsNullOrWhiteSpace(t.AddressString))
|
|
{
|
|
if (!ModbusAddressParser.TryParse(t.AddressString, family, melsecSubFamily, out var parsed, out var parseError))
|
|
throw new InvalidOperationException(
|
|
$"Modbus tag '{name}' in '{driverInstanceId}' has invalid AddressString '{t.AddressString}': {parseError}");
|
|
tag = new ModbusTagDefinition(
|
|
Name: name,
|
|
Region: parsed!.Region,
|
|
Address: parsed.Offset,
|
|
DataType: parsed.DataType,
|
|
Writable: t.Writable ?? true,
|
|
ByteOrder: parsed.ByteOrder,
|
|
BitIndex: parsed.Bit ?? 0,
|
|
StringLength: parsed.StringLength,
|
|
StringByteOrder: t.StringByteOrder is null
|
|
? ModbusStringByteOrder.HighByteFirst
|
|
: ParseEnum<ModbusStringByteOrder>(t.StringByteOrder, name, driverInstanceId, "StringByteOrder"),
|
|
WriteIdempotent: t.WriteIdempotent ?? false,
|
|
ArrayCount: parsed.ArrayCount,
|
|
Deadband: t.Deadband,
|
|
UnitId: t.UnitId);
|
|
}
|
|
else
|
|
{
|
|
tag = new ModbusTagDefinition(
|
|
Name: name,
|
|
Region: ParseEnum<ModbusRegion>(t.Region, t.Name, driverInstanceId, "Region"),
|
|
Address: t.Address ?? throw new InvalidOperationException(
|
|
$"Modbus tag '{t.Name}' in '{driverInstanceId}' missing Address"),
|
|
DataType: ParseEnum<ModbusDataType>(t.DataType, t.Name, driverInstanceId, "DataType"),
|
|
Writable: t.Writable ?? true,
|
|
ByteOrder: t.ByteOrder is null
|
|
? ModbusByteOrder.BigEndian
|
|
: ParseEnum<ModbusByteOrder>(t.ByteOrder, t.Name, driverInstanceId, "ByteOrder"),
|
|
BitIndex: t.BitIndex ?? 0,
|
|
StringLength: t.StringLength ?? 0,
|
|
StringByteOrder: t.StringByteOrder is null
|
|
? ModbusStringByteOrder.HighByteFirst
|
|
: ParseEnum<ModbusStringByteOrder>(t.StringByteOrder, t.Name, driverInstanceId, "StringByteOrder"),
|
|
WriteIdempotent: t.WriteIdempotent ?? false,
|
|
ArrayCount: t.ArrayCount,
|
|
Deadband: t.Deadband,
|
|
UnitId: t.UnitId);
|
|
}
|
|
|
|
ValidateStringLength(tag, driverInstanceId);
|
|
return tag;
|
|
}
|
|
|
|
/// <summary>
|
|
/// Driver.Modbus-009: reject <c>StringLength = 0</c> for <c>String</c>-typed tags. The
|
|
/// driver computes <c>RegisterCount = (StringLength + 1) / 2</c> which would emit an
|
|
/// FC03/FC04 with <c>quantity = 0</c>, a spec-illegal request the PLC rejects with
|
|
/// exception 03 (Illegal Data Value). Surface as a clear bind-time error.
|
|
/// </summary>
|
|
private static void ValidateStringLength(ModbusTagDefinition tag, string driverInstanceId)
|
|
{
|
|
if (tag.DataType == ModbusDataType.String && tag.StringLength < 1)
|
|
throw new InvalidOperationException(
|
|
$"Modbus tag '{tag.Name}' in '{driverInstanceId}' has DataType=String but StringLength={tag.StringLength}. " +
|
|
$"String tags must declare StringLength >= 1 (the number of ASCII characters, packed 2 per register).");
|
|
}
|
|
|
|
private static T ParseEnum<T>(string? raw, string? tagName, string driverInstanceId, string field) where T : struct, Enum
|
|
{
|
|
if (string.IsNullOrWhiteSpace(raw))
|
|
throw new InvalidOperationException(
|
|
$"Modbus tag '{tagName ?? "<unnamed>"}' in '{driverInstanceId}' missing {field}");
|
|
return Enum.TryParse<T>(raw, ignoreCase: true, out var v)
|
|
? v
|
|
: throw new InvalidOperationException(
|
|
$"Modbus tag '{tagName}' has unknown {field} '{raw}'. " +
|
|
$"Expected one of {string.Join(", ", Enum.GetNames<T>())}");
|
|
}
|
|
|
|
private static readonly JsonSerializerOptions JsonOptions = new()
|
|
{
|
|
PropertyNameCaseInsensitive = true,
|
|
ReadCommentHandling = JsonCommentHandling.Skip,
|
|
AllowTrailingCommas = true,
|
|
};
|
|
|
|
internal sealed class ModbusDriverConfigDto
|
|
{
|
|
/// <summary>Gets or sets the host address.</summary>
|
|
public string? Host { get; init; }
|
|
/// <summary>Gets or sets the port number.</summary>
|
|
public int? Port { get; init; }
|
|
/// <summary>Gets or sets the unit identifier.</summary>
|
|
public byte? UnitId { get; init; }
|
|
/// <summary>Gets or sets the timeout in milliseconds.</summary>
|
|
public int? TimeoutMs { get; init; }
|
|
/// <summary>Gets or sets the maximum number of registers per read operation.</summary>
|
|
public ushort? MaxRegistersPerRead { get; init; }
|
|
/// <summary>Gets or sets the maximum number of registers per write operation.</summary>
|
|
public ushort? MaxRegistersPerWrite { get; init; }
|
|
/// <summary>Gets or sets the maximum number of coils per read operation.</summary>
|
|
public ushort? MaxCoilsPerRead { get; init; }
|
|
/// <summary>Gets or sets a value indicating whether to use function code 15 for single coil writes.</summary>
|
|
public bool? UseFC15ForSingleCoilWrites { get; init; }
|
|
/// <summary>Gets or sets a value indicating whether to use function code 16 for single register writes.</summary>
|
|
public bool? UseFC16ForSingleRegisterWrites { get; init; }
|
|
/// <summary>Gets or sets a value indicating whether to disable function code 23.</summary>
|
|
public bool? DisableFC23 { get; init; }
|
|
/// <summary>Gets or sets a value indicating whether to write only on change.</summary>
|
|
public bool? WriteOnChangeOnly { get; init; }
|
|
/// <summary>Gets or sets the maximum gap between register addresses for coalescing.</summary>
|
|
public ushort? MaxReadGap { get; init; }
|
|
/// <summary>Gets or sets the Modbus family type.</summary>
|
|
public string? Family { get; init; }
|
|
/// <summary>Gets or sets the Melsec subfamily.</summary>
|
|
public string? MelsecSubFamily { get; init; }
|
|
/// <summary>Gets or sets the automatic prohibition reprobei interval in milliseconds.</summary>
|
|
public int? AutoProhibitReprobeMs { get; init; }
|
|
/// <summary>Gets or sets a value indicating whether automatic reconnection is enabled.</summary>
|
|
public bool? AutoReconnect { get; init; }
|
|
/// <summary>Gets or sets the collection of tag definitions.</summary>
|
|
public List<ModbusTagDto>? Tags { get; init; }
|
|
/// <summary>Gets or sets the probe configuration.</summary>
|
|
public ModbusProbeDto? Probe { get; init; }
|
|
|
|
/// <summary>Gets or sets the keep-alive configuration (connection-layer knob #139).</summary>
|
|
public ModbusKeepAliveDto? KeepAlive { get; init; }
|
|
/// <summary>Gets or sets the idle disconnect timeout in milliseconds.</summary>
|
|
public int? IdleDisconnectMs { get; init; }
|
|
/// <summary>Gets or sets the reconnect configuration.</summary>
|
|
public ModbusReconnectDto? Reconnect { get; init; }
|
|
}
|
|
|
|
internal sealed class ModbusKeepAliveDto
|
|
{
|
|
/// <summary>Gets or sets a value indicating whether keep-alive is enabled.</summary>
|
|
public bool? Enabled { get; init; }
|
|
/// <summary>Gets or sets the keep-alive time in milliseconds.</summary>
|
|
public int? TimeMs { get; init; }
|
|
/// <summary>Gets or sets the keep-alive interval in milliseconds.</summary>
|
|
public int? IntervalMs { get; init; }
|
|
/// <summary>Gets or sets the retry count.</summary>
|
|
public int? RetryCount { get; init; }
|
|
}
|
|
|
|
internal sealed class ModbusReconnectDto
|
|
{
|
|
/// <summary>Gets or sets the initial reconnect delay in milliseconds.</summary>
|
|
public int? InitialDelayMs { get; init; }
|
|
/// <summary>Gets or sets the maximum reconnect delay in milliseconds.</summary>
|
|
public int? MaxDelayMs { get; init; }
|
|
/// <summary>Gets or sets the backoff multiplier for exponential reconnect delays.</summary>
|
|
public double? BackoffMultiplier { get; init; }
|
|
}
|
|
|
|
internal sealed class ModbusTagDto
|
|
{
|
|
/// <summary>Gets or sets the tag name.</summary>
|
|
public string? Name { get; init; }
|
|
|
|
/// <summary>
|
|
/// Address grammar string per <c>ModbusAddressParser</c> — when present, takes
|
|
/// precedence over the structured Region/Address/DataType/ByteOrder/BitIndex/
|
|
/// StringLength/ArrayCount fields. Examples: <c>"40001"</c>, <c>"40001:F"</c>,
|
|
/// <c>"40001:F:CDAB:5"</c>, <c>"HR1:I"</c>, <c>"C100"</c>.
|
|
/// </summary>
|
|
public string? AddressString { get; init; }
|
|
|
|
/// <summary>Gets or sets the register region.</summary>
|
|
public string? Region { get; init; }
|
|
/// <summary>Gets or sets the starting address.</summary>
|
|
public ushort? Address { get; init; }
|
|
/// <summary>Gets or sets the data type.</summary>
|
|
public string? DataType { get; init; }
|
|
/// <summary>Gets or sets a value indicating whether the tag is writable.</summary>
|
|
public bool? Writable { get; init; }
|
|
/// <summary>Gets or sets the byte order.</summary>
|
|
public string? ByteOrder { get; init; }
|
|
/// <summary>Gets or sets the bit index for bit-level tags.</summary>
|
|
public byte? BitIndex { get; init; }
|
|
/// <summary>Gets or sets the string length for string-typed tags.</summary>
|
|
public ushort? StringLength { get; init; }
|
|
/// <summary>Gets or sets the byte order for string values.</summary>
|
|
public string? StringByteOrder { get; init; }
|
|
/// <summary>Gets or sets a value indicating whether writes are idempotent.</summary>
|
|
public bool? WriteIdempotent { get; init; }
|
|
/// <summary>Gets or sets the array count for array-typed tags.</summary>
|
|
public int? ArrayCount { get; init; }
|
|
/// <summary>Gets or sets the deadband for change detection.</summary>
|
|
public double? Deadband { get; init; }
|
|
/// <summary>Gets or sets the unit identifier for this tag.</summary>
|
|
public byte? UnitId { get; init; }
|
|
}
|
|
|
|
internal sealed class ModbusProbeDto
|
|
{
|
|
/// <summary>Gets or sets a value indicating whether probing is enabled.</summary>
|
|
public bool? Enabled { get; init; }
|
|
/// <summary>Gets or sets the probe interval in milliseconds.</summary>
|
|
public int? IntervalMs { get; init; }
|
|
/// <summary>Gets or sets the probe timeout in milliseconds.</summary>
|
|
public int? TimeoutMs { get; init; }
|
|
/// <summary>Gets or sets the probe register address.</summary>
|
|
public ushort? ProbeAddress { get; init; }
|
|
}
|
|
}
|