Joseph Doherty
b66972b6f5
On a wire the native PCCC path is proven only for N-file reads/writes and one F8 read (ab_server). An absent transport key now resolves to Libplctag for every family; explicit Native still wins and still warns once per instance on PLC-5/LogixPccc. AdminUI dropdown, CLI help, evidence claims (PcccFileType, AbLegacy.md wire-evidence table, release note) corrected: S:0 (default probe) and B/T/C/R/S/L/ST/A/O/I are unverified natively. Claude-Session: https://claude.ai/code/session_01Ef2ozxS7QPanGT8uoATbTe
219 lines
10 KiB
C#
219 lines
10 KiB
C#
using System.Text.Json;
|
|
using System.Text.Json.Serialization;
|
|
using Microsoft.Extensions.Logging;
|
|
using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
|
|
using ZB.MOM.WW.OtOpcUa.Core.Hosting;
|
|
using ZB.MOM.WW.OtOpcUa.Driver.AbLegacy.PlcFamilies;
|
|
|
|
namespace ZB.MOM.WW.OtOpcUa.Driver.AbLegacy;
|
|
|
|
/// <summary>
|
|
/// Static factory registration helper for <see cref="AbLegacyDriver"/>. Server's Program.cs
|
|
/// calls <see cref="Register"/> once at startup; the bootstrapper then
|
|
/// materialises AB Legacy DriverInstance rows from the central config DB into live
|
|
/// driver instances. Mirrors <c>GalaxyProxyDriverFactoryExtensions</c>.
|
|
/// </summary>
|
|
public static class AbLegacyDriverFactoryExtensions
|
|
{
|
|
public const string DriverTypeName = "AbLegacy";
|
|
|
|
/// <summary>
|
|
/// Register the AbLegacy factory with the driver registry. The optional
|
|
/// <paramref name="loggerFactory"/> is captured at registration time and used to
|
|
/// construct an <see cref="ILogger{AbLegacyDriver}"/> per driver instance — without it,
|
|
/// the driver runs with the null logger (existing tests and standalone callers stay
|
|
/// unchanged). Mirrors the Modbus driver registration pattern.
|
|
/// </summary>
|
|
/// <param name="registry">The driver factory registry to register with.</param>
|
|
/// <param name="loggerFactory">Optional logger factory for driver instances.</param>
|
|
public static void Register(DriverFactoryRegistry registry, ILoggerFactory? loggerFactory = null)
|
|
{
|
|
ArgumentNullException.ThrowIfNull(registry);
|
|
registry.Register(DriverTypeName, (id, json) => CreateInstance(id, json, loggerFactory));
|
|
}
|
|
|
|
/// <summary>
|
|
/// Creates an instance of the AB Legacy driver from configuration.
|
|
/// </summary>
|
|
/// <param name="driverInstanceId">The unique identifier for this driver instance.</param>
|
|
/// <param name="driverConfigJson">The driver configuration as a JSON string.</param>
|
|
/// <returns>A configured <see cref="AbLegacyDriver"/> instance.</returns>
|
|
internal static AbLegacyDriver CreateInstance(string driverInstanceId, string driverConfigJson)
|
|
=> CreateInstance(driverInstanceId, driverConfigJson, loggerFactory: null);
|
|
|
|
/// <summary>
|
|
/// Creates an instance of the AB Legacy driver with optional logger.
|
|
/// </summary>
|
|
/// <param name="driverInstanceId">The unique identifier for this driver instance.</param>
|
|
/// <param name="driverConfigJson">The driver configuration as a JSON string.</param>
|
|
/// <param name="loggerFactory">Optional logger factory for the driver instance.</param>
|
|
/// <returns>A configured <see cref="AbLegacyDriver"/> instance.</returns>
|
|
internal static AbLegacyDriver CreateInstance(string driverInstanceId, string driverConfigJson, ILoggerFactory? loggerFactory)
|
|
{
|
|
return new AbLegacyDriver(
|
|
ParseOptions(driverInstanceId, driverConfigJson), driverInstanceId,
|
|
tagFactory: null,
|
|
logger: loggerFactory?.CreateLogger<AbLegacyDriver>());
|
|
}
|
|
|
|
/// <summary>
|
|
/// Parses an AB Legacy <c>DriverConfig</c> JSON document into typed options. Extracted so
|
|
/// <see cref="AbLegacyDriver.InitializeAsync"/> can re-parse a CHANGED config on reinitialize
|
|
/// (Gitea #516) instead of serving the options it was constructed with — which silently discarded
|
|
/// every operator edit while the deployment still sealed green.
|
|
/// </summary>
|
|
/// <param name="driverInstanceId">The unique driver instance identifier.</param>
|
|
/// <param name="driverConfigJson">The driver configuration as a JSON string.</param>
|
|
/// <returns>The parsed <see cref="AbLegacyDriverOptions"/>.</returns>
|
|
internal static AbLegacyDriverOptions ParseOptions(string driverInstanceId, string driverConfigJson)
|
|
{
|
|
ArgumentException.ThrowIfNullOrWhiteSpace(driverInstanceId);
|
|
ArgumentException.ThrowIfNullOrWhiteSpace(driverConfigJson);
|
|
|
|
var dto = JsonSerializer.Deserialize<AbLegacyDriverConfigDto>(driverConfigJson, JsonOptions)
|
|
?? throw new InvalidOperationException(
|
|
$"AB Legacy driver config for '{driverInstanceId}' deserialised to null");
|
|
|
|
var options = new AbLegacyDriverOptions
|
|
{
|
|
Devices = dto.Devices is { Count: > 0 }
|
|
? [.. dto.Devices.Select(d => new AbLegacyDeviceOptions(
|
|
HostAddress: d.HostAddress ?? throw new InvalidOperationException(
|
|
$"AB Legacy config for '{driverInstanceId}' has a device missing HostAddress"),
|
|
PlcFamily: ParseEnum<AbLegacyPlcFamily>(d.PlcFamily, driverInstanceId, "PlcFamily",
|
|
fallback: AbLegacyPlcFamily.Slc500),
|
|
DeviceName: d.DeviceName))]
|
|
: [],
|
|
// v3: the deploy artifact (Wave C) populates rawTags with the cluster's authored raw AbLegacy
|
|
// tags (RawPath + TagConfig blob + WriteIdempotent + owning DeviceName). The driver maps each
|
|
// RawTagEntry's TagConfig blob through AbLegacyTagDefinitionFactory at Initialize and routes it
|
|
// to its device by DeviceName; the legacy pre-declared DTO tag path is retired.
|
|
RawTags = dto.RawTags is { Count: > 0 } ? [.. dto.RawTags] : [],
|
|
Probe = new AbLegacyProbeOptions
|
|
{
|
|
Enabled = dto.Probe?.Enabled ?? true,
|
|
Interval = TimeSpan.FromMilliseconds(dto.Probe?.IntervalMs ?? 5_000),
|
|
Timeout = PositiveTimeoutOrDefault(dto.Probe?.TimeoutMs, 2_000),
|
|
ProbeAddress = dto.Probe?.ProbeAddress ?? "S:0",
|
|
},
|
|
Timeout = PositiveTimeoutOrDefault(dto.TimeoutMs, 2_000),
|
|
// Absent ⇒ null ("use the default" = Libplctag, resolved by AbLegacyTransportResolver);
|
|
// a bad value still fails exactly as any other bad enum field does.
|
|
Transport = string.IsNullOrWhiteSpace(dto.Transport)
|
|
? null
|
|
: ParseEnum<AbLegacyTransport>(dto.Transport, driverInstanceId, "Transport"),
|
|
};
|
|
|
|
return options;
|
|
}
|
|
|
|
/// <summary>
|
|
/// Maps an operator-supplied timeout (ms) to a positive <see cref="TimeSpan"/>, substituting
|
|
/// <paramref name="defaultMs"/> for a null / zero / negative value. libplctag's managed
|
|
/// <c>Tag.Timeout</c> setter throws <see cref="ArgumentOutOfRangeException"/> for a
|
|
/// non-positive value, which would otherwise fault tag creation on every read/write; clamping
|
|
/// here keeps a misconfigured <c>TimeoutMs: 0</c> running on the default bound instead. (Driver
|
|
/// timeout hardening, sibling of the S7 R2-01 read-leg fix.)
|
|
/// </summary>
|
|
/// <param name="ms">The operator-supplied timeout in milliseconds, or null.</param>
|
|
/// <param name="defaultMs">The default applied when <paramref name="ms"/> is null or non-positive.</param>
|
|
/// <returns>A strictly positive timeout.</returns>
|
|
private static TimeSpan PositiveTimeoutOrDefault(int? ms, int defaultMs) =>
|
|
TimeSpan.FromMilliseconds(ms is int v and > 0 ? v : defaultMs);
|
|
|
|
private static T ParseEnum<T>(string? raw, string driverInstanceId, string field,
|
|
string? tagName = null, T? fallback = null) where T : struct, Enum
|
|
{
|
|
if (string.IsNullOrWhiteSpace(raw))
|
|
{
|
|
if (fallback.HasValue) return fallback.Value;
|
|
throw new InvalidOperationException(
|
|
$"AB Legacy {(tagName is null ? "config" : $"tag '{tagName}'")} in '{driverInstanceId}' missing {field}");
|
|
}
|
|
// Enum.TryParse also accepts any integer string ("7"), defined or not (Task 22 review r1 M2).
|
|
return Enum.TryParse<T>(raw, ignoreCase: true, out var v) && Enum.IsDefined(v)
|
|
? v
|
|
: throw new InvalidOperationException(
|
|
$"AB Legacy {(tagName is null ? "config" : $"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 AbLegacyDriverConfigDto
|
|
{
|
|
/// <summary>
|
|
/// Gets or sets the timeout in milliseconds for operations.
|
|
/// </summary>
|
|
public int? TimeoutMs { get; init; }
|
|
|
|
/// <summary>
|
|
/// Gets or sets the transport (<c>Libplctag</c> or <c>Native</c>, case-insensitive); absent means Libplctag (the default).
|
|
/// </summary>
|
|
public string? Transport { get; init; }
|
|
|
|
/// <summary>
|
|
/// Gets or sets the list of devices to connect to.
|
|
/// </summary>
|
|
public List<AbLegacyDeviceDto>? Devices { get; init; }
|
|
|
|
/// <summary>
|
|
/// Gets or sets the authored raw tags (RawPath + TagConfig blob + WriteIdempotent + owning
|
|
/// DeviceName) the deploy artifact delivers. The driver maps each through
|
|
/// <see cref="AbLegacyTagDefinitionFactory.FromTagConfig"/> at Initialize.
|
|
/// </summary>
|
|
public List<RawTagEntry>? RawTags { get; init; }
|
|
|
|
/// <summary>
|
|
/// Gets or sets the probe configuration.
|
|
/// </summary>
|
|
public AbLegacyProbeDto? Probe { get; init; }
|
|
}
|
|
|
|
internal sealed class AbLegacyDeviceDto
|
|
{
|
|
/// <summary>
|
|
/// Gets or sets the host address of the device.
|
|
/// </summary>
|
|
public string? HostAddress { get; init; }
|
|
|
|
/// <summary>
|
|
/// Gets or sets the PLC family.
|
|
/// </summary>
|
|
public string? PlcFamily { get; init; }
|
|
|
|
/// <summary>
|
|
/// Gets or sets the device name.
|
|
/// </summary>
|
|
public string? DeviceName { get; init; }
|
|
}
|
|
|
|
internal sealed class AbLegacyProbeDto
|
|
{
|
|
/// <summary>
|
|
/// Gets or sets 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 address.
|
|
/// </summary>
|
|
public string? ProbeAddress { get; init; }
|
|
}
|
|
}
|