201 lines
10 KiB
Markdown
201 lines
10 KiB
Markdown
---
|
||
source_files:
|
||
- DataPRO/ICommand/Classes/UDPQATSEntry.cs
|
||
- DataPRO/ICommand/Classes/DiscoveredDevice.cs
|
||
generated_at: "2026-04-16T03:54:21.141771+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "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:**
|
||
```csharp
|
||
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:**
|
||
```csharp
|
||
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. |