Joseph Doherty
f2f6eeb74e
Adds a uniform [Range(1, 60)] ProbeTimeoutSeconds property to all 9 driver Options classes (Modbus 5s, AbCip 5s, AbLegacy 5s, S7 5s, TwinCAT 10s, FOCAS 10s, OpcUaClient 15s, Galaxy 30s, Historian 15s). Powers the AdminUI Test Connect button (Phase 7 of the plan).
192 lines
11 KiB
C#
192 lines
11 KiB
C#
using System.ComponentModel.DataAnnotations;
|
||
|
||
namespace ZB.MOM.WW.OtOpcUa.Driver.AbCip;
|
||
|
||
/// <summary>
|
||
/// AB CIP / EtherNet-IP driver configuration, bound from the driver's <c>DriverConfig</c>
|
||
/// JSON at <c>DriverHost.RegisterAsync</c>. One instance supports N devices (PLCs) behind
|
||
/// the same driver; per-device routing is keyed on <see cref="AbCipDeviceOptions.HostAddress"/>
|
||
/// via <c>IPerCallHostResolver</c>.
|
||
/// </summary>
|
||
/// <remarks>
|
||
/// Per v2 plan decisions #11 (libplctag), #41 (AbCip vs AbLegacy split), #143–144 (per-call
|
||
/// host resolver + resilience keys), #144 (bulkhead keyed on <c>(DriverInstanceId, HostName)</c>).
|
||
/// </remarks>
|
||
public sealed class AbCipDriverOptions
|
||
{
|
||
/// <summary>
|
||
/// PLCs this driver instance talks to. Each device contributes its own <see cref="AbCipHostAddress"/>
|
||
/// string as the <c>hostName</c> key used by resilience pipelines and the Admin UI.
|
||
/// </summary>
|
||
public IReadOnlyList<AbCipDeviceOptions> Devices { get; init; } = [];
|
||
|
||
/// <summary>
|
||
/// Pre-declared tag map across all devices. Pre-declared tags always emit during
|
||
/// discovery; opt in to controller-side discovery via
|
||
/// <see cref="EnableControllerBrowse"/>.
|
||
/// </summary>
|
||
public IReadOnlyList<AbCipTagDefinition> Tags { get; init; } = [];
|
||
|
||
/// <summary>Per-device probe settings. Falls back to defaults when omitted.</summary>
|
||
public AbCipProbeOptions Probe { get; init; } = new();
|
||
|
||
/// <summary>
|
||
/// Default libplctag call timeout applied to reads/writes/discovery when the caller does
|
||
/// not pass a more specific value. Matches the Modbus driver's 2-second default.
|
||
/// </summary>
|
||
public TimeSpan Timeout { get; init; } = TimeSpan.FromSeconds(2);
|
||
|
||
/// <summary>
|
||
/// When <c>true</c>, <c>DiscoverAsync</c> walks each device's Logix symbol table via
|
||
/// the <c>@tags</c> pseudo-tag + surfaces controller-resident globals under a
|
||
/// <c>Discovered/</c> sub-folder. Pre-declared tags always emit regardless. Default
|
||
/// <c>false</c> to keep the strict-config path for deployments where only declared tags
|
||
/// should appear in the address space.
|
||
/// </summary>
|
||
public bool EnableControllerBrowse { get; init; }
|
||
|
||
/// <summary>
|
||
/// Task #177 — when <c>true</c>, declared ALMD tags are surfaced as alarm conditions
|
||
/// via <c>IAlarmSource</c>; the driver polls each subscribed
|
||
/// alarm's <c>InFaulted</c> + <c>Severity</c> members + fires <c>OnAlarmEvent</c> on
|
||
/// state transitions. Default <c>false</c> — operators explicitly opt in because
|
||
/// projection semantics don't exactly mirror Rockwell FT Alarm & Events; shops
|
||
/// running FT Live should keep this off + take alarms through the native route.
|
||
/// </summary>
|
||
public bool EnableAlarmProjection { get; init; }
|
||
|
||
/// <summary>
|
||
/// Poll interval for the ALMD projection loop. Shorter intervals catch faster edges
|
||
/// at the cost of PLC round-trips; edges shorter than this interval are invisible to
|
||
/// the projection (a 0→1→0 transition within one tick collapses to no event). Default
|
||
/// 1 second — matches typical SCADA alarm-refresh conventions.
|
||
/// </summary>
|
||
public TimeSpan AlarmPollInterval { get; init; } = TimeSpan.FromSeconds(1);
|
||
|
||
/// <summary>
|
||
/// Opt-in for the declaration-only whole-UDT read fast path. When <c>false</c> (the
|
||
/// default) a batch of UDT members is always read per-member, because the byte offsets
|
||
/// computed by <see cref="AbCipUdtMemberLayout"/> assume the controller lays members
|
||
/// out in declaration order — and the Studio 5000 compiler does NOT guarantee that
|
||
/// (it reorders for largest-first packing, BOOL host bytes, nested-struct padding).
|
||
/// Decoding at declaration-order offsets against a reordered controller layout yields
|
||
/// silently-plausible wrong numbers. Set <c>true</c> only when the operator has
|
||
/// hand-verified that every configured UDT's member declaration order matches the
|
||
/// controller's compiled layout; in that case whole-UDT grouping collapses N member
|
||
/// reads into one. The richer CIP Template Object path remains the long-term fix.
|
||
/// </summary>
|
||
public bool EnableDeclarationOnlyUdtGrouping { get; init; }
|
||
|
||
/// <summary>
|
||
/// Timeout for the AdminUI Test Connect probe, in seconds. The AdminUI clamps to a
|
||
/// 60s server-side maximum; this default is what the form pre-fills for new instances.
|
||
/// </summary>
|
||
[Display(Name = "Probe timeout (seconds)", Description = "Connection test timeout. Default 5s.", GroupName = "Diagnostics")]
|
||
[Range(1, 60)]
|
||
public int ProbeTimeoutSeconds { get; init; } = 5;
|
||
}
|
||
|
||
/// <summary>
|
||
/// One PLC endpoint. <see cref="HostAddress"/> must parse via
|
||
/// <see cref="AbCipHostAddress.TryParse"/>; misconfigured devices fail driver
|
||
/// initialization rather than silently connecting to nothing.
|
||
/// </summary>
|
||
/// <param name="HostAddress">Canonical <c>ab://gateway[:port]/cip-path</c> string.</param>
|
||
/// <param name="PlcFamily">Which per-family profile to apply. Determines the family
|
||
/// <c>AllowPacking</c> default, <c>ConnectionSize</c> default, unconnected-only hint, and
|
||
/// other quirks; per-device overrides via <see cref="AllowPacking"/> and
|
||
/// <see cref="ConnectionSize"/> take precedence when set.</param>
|
||
/// <param name="DeviceName">Optional display label for Admin UI. Falls back to <see cref="HostAddress"/>.</param>
|
||
/// <param name="AllowPacking">Driver.AbCip-013 — per-device override for CIP request-packing
|
||
/// (firmware 20+). <c>null</c> (the default) inherits the family profile's
|
||
/// <c>SupportsRequestPacking</c>; set explicitly to opt a single device in or out without
|
||
/// touching every other device on the same family.</param>
|
||
/// <param name="ConnectionSize">Driver.AbCip-013 — per-device override for the Forward Open
|
||
/// ConnectionSize (Large Forward Open packet size in bytes). <c>null</c> inherits the family
|
||
/// profile's <c>DefaultConnectionSize</c>. Honoured by the driver layer; the underlying
|
||
/// libplctag 1.5.2 wrapper has no direct <c>ConnectionSize</c> property, so the value is
|
||
/// plumbed through <see cref="AbCipTagCreateParams"/> for forward-compat with future wrapper
|
||
/// versions or a custom tag-attribute path; current builds use the family profile default at
|
||
/// the wire layer regardless.</param>
|
||
public sealed record AbCipDeviceOptions(
|
||
string HostAddress,
|
||
AbCipPlcFamily PlcFamily = AbCipPlcFamily.ControlLogix,
|
||
string? DeviceName = null,
|
||
bool? AllowPacking = null,
|
||
int? ConnectionSize = null);
|
||
|
||
/// <summary>
|
||
/// One AB-backed OPC UA variable. Mirrors the <c>ModbusTagDefinition</c> shape.
|
||
/// </summary>
|
||
/// <param name="Name">Tag name; becomes the OPC UA browse name and full reference.</param>
|
||
/// <param name="DeviceHostAddress">Which device (<see cref="AbCipDeviceOptions.HostAddress"/>) this tag lives on.</param>
|
||
/// <param name="TagPath">Logix symbolic path (controller or program scope).</param>
|
||
/// <param name="DataType">Logix atomic type, or <see cref="AbCipDataType.Structure"/> for UDT-typed tags.</param>
|
||
/// <param name="Writable">When <c>true</c> and the tag's ExternalAccess permits writes, IWritable routes writes here.</param>
|
||
/// <param name="WriteIdempotent">Per plan decisions #44–#45, #143 — safe to replay on write timeout. Default <c>false</c>.</param>
|
||
/// <param name="Members">For <see cref="AbCipDataType.Structure"/>-typed tags, the declared UDT
|
||
/// member layout. When supplied, discovery fans out the UDT into a folder + one Variable per
|
||
/// member (member TagPath = <c>{tag.TagPath}.{member.Name}</c>). When <c>null</c> on a Structure
|
||
/// tag, the driver treats it as a black-box and relies on downstream configuration to address
|
||
/// members individually via dotted <see cref="AbCipTagPath"/> syntax. Ignored for atomic types.</param>
|
||
/// <param name="SafetyTag">GuardLogix safety-partition tag hint. When <c>true</c>, the driver
|
||
/// forces <c>SecurityClassification.ViewOnly</c> on discovery regardless of
|
||
/// <paramref name="Writable"/> — safety tags can only be written from the safety task of a
|
||
/// GuardLogix controller; non-safety writes violate the safety-partition isolation and are
|
||
/// rejected by the PLC anyway. Surfaces the intent explicitly instead of relying on the
|
||
/// write attempt failing at runtime.</param>
|
||
public sealed record AbCipTagDefinition(
|
||
string Name,
|
||
string DeviceHostAddress,
|
||
string TagPath,
|
||
AbCipDataType DataType,
|
||
bool Writable = true,
|
||
bool WriteIdempotent = false,
|
||
IReadOnlyList<AbCipStructureMember>? Members = null,
|
||
bool SafetyTag = false);
|
||
|
||
/// <summary>
|
||
/// One declared member of a UDT tag. Name is the member identifier on the PLC (e.g. <c>Speed</c>,
|
||
/// <c>Status</c>), DataType is the atomic Logix type, Writable/WriteIdempotent mirror
|
||
/// <see cref="AbCipTagDefinition"/>. Declaration-driven — the real CIP Template Object reader
|
||
/// (class 0x6C) that would auto-discover member layouts lands as a follow-up PR.
|
||
/// </summary>
|
||
public sealed record AbCipStructureMember(
|
||
string Name,
|
||
AbCipDataType DataType,
|
||
bool Writable = true,
|
||
bool WriteIdempotent = false);
|
||
|
||
/// <summary>Which AB PLC family the device is — selects the profile applied to connection params.</summary>
|
||
public enum AbCipPlcFamily
|
||
{
|
||
ControlLogix,
|
||
CompactLogix,
|
||
Micro800,
|
||
GuardLogix,
|
||
}
|
||
|
||
/// <summary>
|
||
/// Background connectivity-probe settings. Enabled by default; the probe reads a cheap tag
|
||
/// on the PLC at the configured interval to drive <c>IHostConnectivityProbe</c>
|
||
/// state transitions + Admin UI health status.
|
||
/// </summary>
|
||
public sealed class AbCipProbeOptions
|
||
{
|
||
/// <summary>Gets a value indicating whether the probe is enabled.</summary>
|
||
public bool Enabled { get; init; } = true;
|
||
/// <summary>Gets the interval at which the probe reads the probe tag.</summary>
|
||
public TimeSpan Interval { get; init; } = TimeSpan.FromSeconds(5);
|
||
/// <summary>Gets the timeout for each probe read operation.</summary>
|
||
public TimeSpan Timeout { get; init; } = TimeSpan.FromSeconds(2);
|
||
|
||
/// <summary>
|
||
/// Tag path used for the probe. When <see cref="Enabled"/> is <c>true</c> but this is
|
||
/// <c>null</c>/blank, the driver logs a warning and runs no probe loops (Driver.AbCip-011);
|
||
/// <c>GetHostStatuses()</c> will then report every device as <c>Unknown</c>. A family-default
|
||
/// system-tag fallback (e.g. <c>@raw_cpu_type</c> on ControlLogix) is a deferred follow-up;
|
||
/// today an operator opting into the probe must supply a tag path explicitly.
|
||
/// </summary>
|
||
public string? ProbeTagPath { get; init; }
|
||
}
|