DP44/enriched-qwen3-coder-next/DataPRO/ICommand/Classes.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/ICommand/Classes/UDPQATSEntry.cs DataPRO/ICommand/Classes/DiscoveredDevice.cs	2026-04-16T03:54:21.141771+00:00	Qwen/Qwen3-Coder-Next-FP8	1	cb106007262aa571

Classes

Documentation: UDPQATSEntry and DiscoveredDevice Classes

---

1. Purpose

This module defines two core data transfer classes used in the DAS (Data Acquisition System) autodiscovery and telemetry reporting subsystems. UDPQATSEntry encapsulates a single point-in-time telemetry snapshot received via UDP from a QATS (Quick Acquisition Test System) device, containing hardware state, configuration, and measurement data. DiscoveredDevice represents metadata about a device discovered via multicast autodiscovery, including network topology (parent/child relationships, port assignments), device identity, and configuration. Together, they support device enumeration, status monitoring, and UI binding in the DTS system.

---

2. Public Interface

UDPQATSEntry

Namespace: DTS.DASLib.Command.Classes
Implements: IUDPQATSEntry (interface not shown; assumed from usage)

A read-only data container for QATS telemetry. All properties have private set accessors; values are assigned only via the constructor.

Property	Type	Description
ResponseHostMac	string	MAC address of the host that sent the UDP response.
ResponseClientMacAddress	string	MAC address of the client (device) that sent the UDP response.
SerialNumber	string	Device serial number.
ArmState, ArmMode, Started, Triggered, FaultFlags, LegacyFaultFlags	byte / ushort	Device arming, start, trigger, and fault state flags (raw byte/ushort values).
SampleRate	uint	Sampling rate in Hz.
TotalSamples, CurrentSample, EventTriggerSample, FaultSampleNumber, EstimateMaxSamples	ulong	Sample counters and thresholds.
EventNumber	ushort	Event identifier.
InputVoltage, BackupVoltage, BatterySOC	float	Power supply voltages (V) and battery state of charge (%).
TiltSensorCh1, TiltSensorCh2, TiltSensorCh3	short	Raw tilt sensor channel readings (signed 16-bit).
SysTempC	float	System temperature in °C.
SyncClockEnable, ADCExtClockSyncEnable, SyncClockStatus, ADCExtClockSyncStatus	byte	Clock synchronization configuration and status flags.
ChannelOffsetMV	float[6]	Per-channel offset in millivolts (size fixed at 6).
ShuntDeviationPercent	float[6]	Per-channel shunt deviation in percent (size fixed at 6).
Timestamp	DateTime	Time of telemetry capture; defaults to DateTime.Now if not provided.

Constructor:

public UDPQATSEntry(
    string responseHostMac,
    string responseClientMacAddress,
    string serialNumber,
    byte armState,
    byte armMode,
    byte started,
    byte triggered,
    byte faultFlags,
    uint sampleRate,
    ulong totalSamples,
    ulong currentSample,
    ushort eventNumber,
    ulong faultSampleNumber,
    ushort legacyFaultFlags,
    float inputVoltage,
    float backupVoltage,
    float batterySOC,
    ulong estimateMaxSamples,
    short tiltSensorCh1,
    short tiltSensorCh2,
    short tiltSensorCh3,
    float sysTempC,
    byte syncClockEnable,
    byte adcExtClockSyncEnable,
    byte syncClockStatus,
    byte adcExtClockSyncStatus,
    ulong eventTriggerSample,
    float[] channelOffsetMV,
    float[] channelShuntDeviationPercent,
    DateTime timeStamp
)

---

DiscoveredDevice

Namespace: DTS.DASLib.Command.Classes
Implements: IDiscoveredDevice, IComparable<DiscoveredDevice>

A mutable data container for device discovery metadata. Properties have public set accessors.

Property	Type	Description
Serial	string	Device serial number.
DevClass	MultiCastDeviceClasses	Device type enum (from DTS.Common.Enums.DASFactory).
Mac	string	Device MAC address.
Parent	IDiscoveredDevice	Reference to parent device in topology (e.g., SLICE6DB for modules).
IsModule	bool	Indicates if device is a module (e.g., SLICE6) attached to a distributor.
Port	int	Physical port number on parent (e.g., SLICE6DB port 1–6).
PositionOnDistributor	int	Logical position in flattened chain across all ports/chains.
PositionOnChain	int	Position within a daisy-chained group of devices (e.g., SLICE6 chain).
Dhcp	bool	Whether DHCP is enabled.
Ip, Subnet, Gateway, Dns	string	Network configuration.
Connected, ConnectedIp, ConnectedHost	bool / string	Host connectivity status and details.
SystemId	ushort	User-assigned distributor ID.
Location	string	User-assigned location string.
FirmwareVersion	string	Firmware version string (format: [Product Name]-[FW/BL]-[REL/DBG]-[Board #]-[FW Ver Name]).
BuildId	string	Build server number for firmware.
Connections	IConnectedEthernetDevice[]	List of devices connected to this device (e.g., downstream modules).

Key Methods:

• bool IsParent(IDiscoveredDevice possibleChild)
  Returns true if possibleChild is a direct child on the same port and no other devices share that port.
• int GetPort(IDiscoveredDevice device)
  Returns the port number on this device to which device is connected; -1 if not connected.
• int GetSlot(IDiscoveredDevice child, Dictionary<string, IDiscoveredDevice> lookup)
  Returns 1-based slot index of child among this device’s connected devices, sorted by port then by number of downstream connections.
• int GetSlotOnPort(IDiscoveredDevice child, Dictionary<string, IDiscoveredDevice> lookup)
  Returns 1-based slot index of child among devices on the same port.
• int CompareTo(DiscoveredDevice other)
  Implements ordering:
  1. Devices without parents (e.g., SLICE6DBs) sort by Serial.
  2. Devices with parents sort by:
     • Ultimate parent’s Serial,
     • Then Port,
     • Then PositionOnDistributor.

Nested Class:

• DiscoveredChildrenSorter : IComparer<IDiscoveredDevice>
  Sorts devices by Port ascending, then by Connections.Length descending (more connected devices first).

---

ConnectedEthernetDevice

Namespace: DTS.DASLib.Command.Classes
Implements: IConnectedEthernetDevice

Represents a downstream connection from a DiscoveredDevice. Immutable MAC/port pair.

Property	Type	Description
MACAddress	string	MAC of connected device (read-only).
Port	int	Port number on parent device (read-only).
SerialNumber	string	Serial number of connected device (mutable).

Constructor:

public ConnectedEthernetDevice(string macAddress, int port)

---

3. Invariants

• UDPQATSEntry

  • ChannelOffsetMV and ShuntDeviationPercent arrays are always initialized to length 6 (default in declaration).
  • Timestamp defaults to DateTime.Now if not explicitly provided in constructor.
  • No validation is performed on input values (e.g., SampleRate may be 0; FaultFlags may be nonsensical).

• DiscoveredDevice

  • Connections is always initialized to an empty array (via constructor).
  • IsParent and GetSlot methods assume Connections is populated and consistent with Parent references.
  • CompareTo ordering relies on Serial being non-null and comparable; behavior is undefined if Serial is null.
  • GetSlot and GetSlotOnPort cache _orderedList on first call; subsequent calls use cached order.

---

4. Dependencies

Imports/Usings:

• DTS.Common.Interface.DASFactory → Provides IUDPQATSEntry, IDiscoveredDevice, IConnectedEthernetDevice interfaces.
• DTS.Common.Enums.DASFactory.DFConstantsAndEnums → Provides MultiCastDeviceClasses enum.
• System, System.Collections.Generic, System.Linq → Standard .NET dependencies.

Consumers (inferred):

• Multicast autodiscovery logic (e.g., DASFactory implementation) likely instantiates DiscoveredDevice and UDPQATSEntry.
• UI layer (e.g., SortableBindingList mentioned in comments) consumes DiscoveredDevice for ordering.
• UDPQATSEntry is likely used by telemetry processing pipelines (e.g., to populate logs, UI grids, or analysis tools).

---

5. Gotchas

• UDPQATSEntry

  • No null-safety: channelOffsetMV/channelShuntDeviationPercent arrays are assigned directly (caller must ensure non-null).
  • Timestamp defaults to construction time, not UDP receipt time—may misrepresent actual sample time if constructor is called later.
  • LegacyFaultFlags suggests a deprecated field; no guidance on when to use it vs. FaultFlags.

• DiscoveredDevice

  • IsParent logic is fragile: assumes Connections is populated and that possibleChild.Connections.Length is accurate. If possibleChild.Connections is empty, IsParent may incorrectly return true.
  • GetSlot caches _orderedList on first call; if Connections changes after first call, cached order becomes stale.
  • CompareTo ordering is complex and may produce inconsistent results if Serial is null or if Parent references form cycles.
  • PositionOnDistributor and PositionOnChain are user-assigned (not computed), so they require external coordination to remain valid.
  • ConnectedEthernetDevice.SerialNumber is mutable but not used in equality/comparison logic—risk of inconsistency if updated after discovery.

• General

  • No documentation on units for TiltSensorCh* (assumed raw ADC counts, but not specified).
  • No validation of MAC/IP strings (e.g., empty strings allowed).
  • No thread-safety guarantees (mutable properties in DiscoveredDevice).

None identified from source alone. → Correction: Gotchas identified above are apparent from source code structure and logic.