feat(mtconnect): IMTConnectAgentClient seam + neutral parse DTOs (Task 5)
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,44 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.MTConnect;
|
||||
|
||||
/// <summary>
|
||||
/// The seam between the MTConnect driver and an MTConnect Agent's HTTP surface
|
||||
/// (<c>/probe</c>, <c>/current</c>, <c>/sample</c>). This interface is transport-neutral by
|
||||
/// design — every method returns/yields the plain DTOs in <c>MTConnectDtos.cs</c>, never a
|
||||
/// TrakHound type, an <c>XElement</c>, or any other wire/library artifact. That is what lets
|
||||
/// every driver behaviour above this seam (Tasks 6–13) be unit-tested against a fake serving
|
||||
/// canned probe/current/sample XML, with no sockets involved.
|
||||
/// </summary>
|
||||
/// <remarks>
|
||||
/// The production implementation (Task 6/7) is built on the TrakHound MTConnect.NET client
|
||||
/// libraries (Task 0's decision); a fake for tests only needs to implement these three members.
|
||||
/// </remarks>
|
||||
public interface IMTConnectAgentClient
|
||||
{
|
||||
/// <summary>
|
||||
/// Issues an Agent <c>/probe</c> request and returns the parsed device hierarchy. Called
|
||||
/// once at driver initialization; the result is cached and later walked to build the OPC UA
|
||||
/// browse tree, where each <see cref="MTConnectDataItem.Id"/> becomes a tag's FullName.
|
||||
/// </summary>
|
||||
/// <param name="ct">Cancellation token.</param>
|
||||
Task<MTConnectProbeModel> ProbeAsync(CancellationToken ct);
|
||||
|
||||
/// <summary>
|
||||
/// Issues an Agent <c>/current</c> request and returns the latest observed value for every
|
||||
/// data item. Used both to prime the observation index at startup and to re-baseline after
|
||||
/// a detected sequence gap in <see cref="SampleAsync"/>.
|
||||
/// </summary>
|
||||
/// <param name="ct">Cancellation token.</param>
|
||||
Task<MTConnectStreamsResult> CurrentAsync(CancellationToken ct);
|
||||
|
||||
/// <summary>
|
||||
/// Opens an Agent <c>/sample</c> long-poll stream starting at sequence <paramref name="from"/>
|
||||
/// and yields one <see cref="MTConnectStreamsResult"/> per multipart chunk the Agent sends,
|
||||
/// indefinitely, until <paramref name="ct"/> is cancelled. Each yielded result's
|
||||
/// <see cref="MTConnectStreamsResult.FirstSequence"/> is load-bearing — the caller compares
|
||||
/// it against the requested <paramref name="from"/> to detect a ring-buffer sequence gap and
|
||||
/// re-baseline via <see cref="CurrentAsync"/>.
|
||||
/// </summary>
|
||||
/// <param name="from">The sequence number to resume streaming from.</param>
|
||||
/// <param name="ct">Cancellation token; cancelling ends the stream.</param>
|
||||
IAsyncEnumerable<MTConnectStreamsResult> SampleAsync(long from, CancellationToken ct);
|
||||
}
|
||||
@@ -0,0 +1,170 @@
|
||||
namespace ZB.MOM.WW.OtOpcUa.Driver.MTConnect;
|
||||
|
||||
/// <summary>
|
||||
/// Result of an Agent <c>/probe</c> request: the full device hierarchy the Agent exposes.
|
||||
/// Produced by <see cref="IMTConnectAgentClient.ProbeAsync"/>. This is the neutral shape both
|
||||
/// the TrakHound-backed implementation and a hand-rolled XML fallback must produce — nothing
|
||||
/// downstream of <see cref="IMTConnectAgentClient"/> ever sees a TrakHound type or an
|
||||
/// <c>XElement</c>.
|
||||
/// </summary>
|
||||
/// <param name="Devices">Every device the Agent's probe response declares.</param>
|
||||
public sealed record MTConnectProbeModel(IReadOnlyList<MTConnectDevice> Devices);
|
||||
|
||||
/// <summary>
|
||||
/// Common shape shared by <see cref="MTConnectDevice"/> and <see cref="MTConnectComponent"/>:
|
||||
/// each may directly own data items and/or nest further components, to arbitrary depth. Backs
|
||||
/// the <see cref="MTConnectComponentTreeExtensions.AllDataItems"/> recursive walk.
|
||||
/// </summary>
|
||||
public interface IMTConnectComponentContainer
|
||||
{
|
||||
/// <summary>Components nested directly under this device/component (may be empty).</summary>
|
||||
IReadOnlyList<MTConnectComponent> Components { get; }
|
||||
|
||||
/// <summary>Data items declared directly on this device/component (may be empty).</summary>
|
||||
IReadOnlyList<MTConnectDataItem> DataItems { get; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// One MTConnect device from the Agent's probe response — the root of a nested
|
||||
/// component/data-item tree.
|
||||
/// </summary>
|
||||
/// <param name="Id">The device's <c>id</c> attribute.</param>
|
||||
/// <param name="Name">The device's <c>name</c> attribute, when the Agent supplies one.</param>
|
||||
/// <param name="Components">Child components declared directly under this device.</param>
|
||||
/// <param name="DataItems">Data items declared directly on this device (outside any component).</param>
|
||||
public sealed record MTConnectDevice(
|
||||
string Id,
|
||||
string? Name,
|
||||
IReadOnlyList<MTConnectComponent> Components,
|
||||
IReadOnlyList<MTConnectDataItem> DataItems) : IMTConnectComponentContainer;
|
||||
|
||||
/// <summary>
|
||||
/// One MTConnect component (e.g. <c>Axes</c>, <c>Controller</c>, <c>Path</c>) from the Agent's
|
||||
/// probe response. Components nest to arbitrary depth — a component may itself contain further
|
||||
/// child components as well as data items.
|
||||
/// </summary>
|
||||
/// <param name="Id">The component's <c>id</c> attribute.</param>
|
||||
/// <param name="Name">The component's <c>name</c> attribute, when the Agent supplies one.</param>
|
||||
/// <param name="Components">Child components nested directly under this component.</param>
|
||||
/// <param name="DataItems">Data items declared directly on this component.</param>
|
||||
public sealed record MTConnectComponent(
|
||||
string Id,
|
||||
string? Name,
|
||||
IReadOnlyList<MTConnectComponent> Components,
|
||||
IReadOnlyList<MTConnectDataItem> DataItems) : IMTConnectComponentContainer;
|
||||
|
||||
/// <summary>
|
||||
/// One MTConnect DataItem declaration from the Agent's probe response. This is pure metadata —
|
||||
/// it carries no observed value; values arrive separately via
|
||||
/// <see cref="IMTConnectAgentClient.CurrentAsync"/> / <see cref="IMTConnectAgentClient.SampleAsync"/>
|
||||
/// and are correlated back to a data item by <see cref="Id"/>.
|
||||
/// </summary>
|
||||
/// <param name="Id">
|
||||
/// The DataItem's <c>id</c> attribute — globally unique within the Agent's probe response and
|
||||
/// the correlation key used against <see cref="MTConnectObservation.DataItemId"/>.
|
||||
/// </param>
|
||||
/// <param name="Name">The DataItem's <c>name</c> attribute, when the Agent supplies one.</param>
|
||||
/// <param name="Category">The DataItem's <c>category</c> attribute — <c>SAMPLE</c>, <c>EVENT</c>, or <c>CONDITION</c>.</param>
|
||||
/// <param name="Type">The DataItem's <c>type</c> attribute (e.g. <c>POSITION</c>, <c>EXECUTION</c>).</param>
|
||||
/// <param name="SubType">The DataItem's <c>subType</c> attribute (e.g. <c>ACTUAL</c>, <c>COMMANDED</c>), when present.</param>
|
||||
/// <param name="Units">The DataItem's <c>units</c> attribute (e.g. <c>MILLIMETER</c>, <c>REVOLUTION/MINUTE</c>), when present.</param>
|
||||
/// <param name="Representation">
|
||||
/// The DataItem's <c>representation</c> attribute (e.g. <c>TIME_SERIES</c>, <c>DISCRETE</c>);
|
||||
/// absent means the MTConnect default (<c>VALUE</c>).
|
||||
/// </param>
|
||||
/// <param name="SampleCount">
|
||||
/// The DataItem's <c>sampleCount</c> attribute — element count for a <c>TIME_SERIES</c>
|
||||
/// representation. Present only on data items that carry one.
|
||||
/// </param>
|
||||
public sealed record MTConnectDataItem(
|
||||
string Id,
|
||||
string? Name,
|
||||
string Category,
|
||||
string Type,
|
||||
string? SubType,
|
||||
string? Units,
|
||||
string? Representation,
|
||||
int? SampleCount);
|
||||
|
||||
/// <summary>
|
||||
/// Result of an Agent <c>/current</c> request, or of a single multipart chunk from a
|
||||
/// <c>/sample</c> stream. Produced by <see cref="IMTConnectAgentClient.CurrentAsync"/> and
|
||||
/// <see cref="IMTConnectAgentClient.SampleAsync"/>.
|
||||
/// </summary>
|
||||
/// <param name="InstanceId">
|
||||
/// The Agent's current instance id (its MTConnectStreams header <c>instanceId</c>). Changes
|
||||
/// whenever the Agent restarts or its underlying device model changes; the driver watches this
|
||||
/// for change to raise rediscovery rather than trusting a stale observation snapshot.
|
||||
/// </param>
|
||||
/// <param name="NextSequence">
|
||||
/// The header <c>nextSequence</c> — the sequence number to resume a subsequent
|
||||
/// <see cref="IMTConnectAgentClient.SampleAsync"/> call <c>from</c>.
|
||||
/// </param>
|
||||
/// <param name="FirstSequence">
|
||||
/// The header <c>firstSequence</c> — the oldest sequence number still held in the Agent's
|
||||
/// circular buffer. Load-bearing for sequence-gap detection: a caller that requested
|
||||
/// <c>from</c> a sequence older than this chunk's <see cref="FirstSequence"/> has fallen out of
|
||||
/// the Agent's buffer and must re-baseline via <see cref="IMTConnectAgentClient.CurrentAsync"/>.
|
||||
/// </param>
|
||||
/// <param name="Observations">
|
||||
/// The observations carried in this snapshot/chunk, in Agent-supplied order. Never <c>null</c>;
|
||||
/// empty when the chunk carries no new observations (e.g. a heartbeat).
|
||||
/// </param>
|
||||
public sealed record MTConnectStreamsResult(
|
||||
long InstanceId,
|
||||
long NextSequence,
|
||||
long FirstSequence,
|
||||
IReadOnlyList<MTConnectObservation> Observations);
|
||||
|
||||
/// <summary>
|
||||
/// One observed value for a single DataItem, as reported in a <c>/current</c> snapshot or a
|
||||
/// <c>/sample</c> stream chunk. Deliberately dumb: <see cref="Value"/> is carried as the raw
|
||||
/// string the Agent reported (including the literal <c>UNAVAILABLE</c>) with no interpretation
|
||||
/// applied here — coercing <c>UNAVAILABLE</c> to a bad-quality status and converting the string
|
||||
/// to the tag's <c>DriverDataType</c> are the observation index's job, not this layer's.
|
||||
/// </summary>
|
||||
/// <param name="DataItemId">
|
||||
/// The reporting DataItem's <c>id</c> — correlates back to <see cref="MTConnectDataItem.Id"/>
|
||||
/// from the probe model.
|
||||
/// </param>
|
||||
/// <param name="Value">
|
||||
/// The observed value exactly as the Agent reported it, or the literal string
|
||||
/// <c>"UNAVAILABLE"</c> when the Agent has no current value for the data item. Never
|
||||
/// pre-parsed into a nullable or an enum at this layer.
|
||||
/// </param>
|
||||
/// <param name="TimestampUtc">
|
||||
/// The observation's Agent-reported timestamp, normalized to UTC (<see cref="DateTime.Kind"/>
|
||||
/// is always <see cref="DateTimeKind.Utc"/>). Becomes the OPC UA variable's SourceTimestamp.
|
||||
/// </param>
|
||||
public sealed record MTConnectObservation(
|
||||
string DataItemId,
|
||||
string Value,
|
||||
DateTime TimestampUtc);
|
||||
|
||||
/// <summary>
|
||||
/// Recursive helpers over the <see cref="IMTConnectComponentContainer"/> device/component tree.
|
||||
/// </summary>
|
||||
public static class MTConnectComponentTreeExtensions
|
||||
{
|
||||
/// <summary>
|
||||
/// Enumerates every data item owned by this device or component, plus every data item owned
|
||||
/// by any component nested beneath it, to arbitrary depth. Order is depth-first: a node's
|
||||
/// own data items first, then each child component's data items in turn.
|
||||
/// </summary>
|
||||
/// <param name="container">The device or component to walk.</param>
|
||||
public static IEnumerable<MTConnectDataItem> AllDataItems(this IMTConnectComponentContainer container)
|
||||
{
|
||||
foreach (var dataItem in container.DataItems)
|
||||
{
|
||||
yield return dataItem;
|
||||
}
|
||||
|
||||
foreach (var child in container.Components)
|
||||
{
|
||||
foreach (var dataItem in child.AllDataItems())
|
||||
{
|
||||
yield return dataItem;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user