init

enriched-qwen3-coder-next/Common/DTS.CommonCore/Interface/Communication.md

@@ -0,0 +1,103 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Interface/Communication/ICommunicationReport.cs
+  - Common/DTS.CommonCore/Interface/Communication/IDASConnectedDevice.cs
+  - Common/DTS.CommonCore/Interface/Communication/ICommunication_DASInfo.cs
+generated_at: "2026-04-16T02:23:54.710439+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "c40d100ec97fea56"
+---
+
+# Communication
+
+### **Purpose**  
+This module defines core interfaces for representing communication results, connected devices in a DAS (Data Acquisition System) network, and DAS-specific metadata. It serves as the foundational abstraction layer for device discovery, status monitoring, and communication state reporting—specifically supporting the auto-discovery and monitoring of DAS-connected hardware (e.g., SLICE6 devices connected to an SLICE6DB base station). These interfaces decouple communication logic from implementation details, enabling consistent handling of device properties, communication outcomes, and DAS-level state across the system.
+
+---
+
+### **Public Interface**
+
+#### **`ICommunicationReport`**
+- **`object UserState { get; set; }`**  
+  A user-defined object for associating custom state with a communication operation (e.g., tracking request context or correlation ID).  
+- **`CommunicationConstantsAndEnums.CommunicationResult Result { get; set; }`**  
+  The outcome of a communication operation (e.g., success, timeout, error). *Note: `CommunicationResult` is defined in an external enum namespace (`DTS.Common.Enums.Communication`), not included here.*  
+- **`byte[] Data { get; set; }`**  
+  Raw payload data received or transmitted during the communication. May be `null` or empty depending on the operation type and result.
+
+#### **`IDASConnectedDevice`**
+- **`HardwareTypes DeviceType { get; }`**  
+  The hardware type of the connected device (e.g., sensor, actuator), per the `HardwareTypes` enum (defined externally in `DTS.Common.Enums.Hardware`).  
+- **`int Port { get; }`**  
+  Zero-based port index on the DAS to which the device is physically connected.  
+- **`int SpotOnPort { get; }`**  
+  Zero-based position of the device on its port’s daisy chain (e.g., `0` = first device on the port).  
+- **`PhysicalAddress PhysicalAddress { get; }`**  
+  The device’s MAC address (from `System.Net.NetworkInformation`).  
+- **`string IPAddress { get; }`**  
+  The IPv4/IPv6 address assigned to the device (as a string).  
+- **`string SerialNumber { get; }`**  
+  Unique hardware serial number of the device.  
+- **`string Location { get; }`**  
+  Human-readable location descriptor (e.g., "Lab A, Rack 2").  
+- **`string Version { get; }`**  
+  Firmware version string of the device.
+
+#### **`ICommunication_DASInfo`**
+- **`IDASConnectedDevice[] ConnectedDevices { get; }`**  
+  Immutable array of devices currently connected to this DAS (read-only). *Currently only populated for SLICE6DB.*  
+- **`void SetConnectedDevices(IDASConnectedDevice[] devices)`**  
+  Updates the `ConnectedDevices` array. Intended for internal use by DAS implementations during discovery.  
+- **`string[] SerialNumbers { get; set; }`**  
+  Parallel array of serial numbers for connected devices (order matches `ConnectedDevices`).  
+- **`string[] FirmwareVersions { get; set; }`**  
+  Parallel array of firmware versions for connected devices (order matches `ConnectedDevices`).  
+- **`string StackSerialNumber(int devid)`**  
+  Returns the serial number of the device at index `devid` in the `ConnectedDevices` array. *Behavior for invalid `devid` is unspecified.*  
+- **`DateTime? FirstUseDate { get; set; }`**  
+  Date of the device’s first operational use. `null` indicates the hardware has never been used since calibration. Only valid when `IsFirstUseDateSupported` is `true`.  
+- **`bool IsFirstUseDateSupported { get; set; }`**  
+  Indicates whether the DAS hardware supports tracking first-use date (requires firmware/user-attribute storage and calibration support per ticket 15524).  
+- **`bool IsStreamingSupported { get; set; }`**  
+  Indicates whether the DAS supports streaming data (e.g., via ticket 30429, controllable via the `DISABLE_STREAMING_FEATURE` system attribute).
+
+---
+
+### **Invariants**
+- **`ICommunicationReport`**:  
+  - `Data` may be `null` or non-empty only if `Result` indicates success or partial success (implementation-dependent).  
+  - `UserState` is not interpreted by the interface; its lifecycle is managed by the caller.  
+- **`IDASConnectedDevice`**:  
+  - `Port` and `SpotOnPort` are zero-based indices.  
+  - `PhysicalAddress` is guaranteed non-null (as `PhysicalAddress` is a struct in .NET, but the interface implies it is initialized).  
+  - `SerialNumber`, `Location`, and `Version` are non-null strings (no explicit nullability annotation, but context implies required fields).  
+- **`ICommunication_DASInfo`**:  
+  - `ConnectedDevices`, `SerialNumbers`, and `FirmwareVersions` must have identical lengths when populated.  
+  - `FirstUseDate` is only meaningful when `IsFirstUseDateSupported` is `true`; otherwise, it should be ignored.  
+  - `StackSerialNumber(devid)` assumes `devid` is a valid index into `ConnectedDevices`; out-of-bounds behavior is undefined.
+
+---
+
+### **Dependencies**
+- **External Dependencies**:  
+  - `DTS.Common.Enums.Communication.CommunicationResult` (for `ICommunicationReport.Result`)  
+  - `DTS.Common.Enums.Hardware.HardwareTypes` (for `IDASConnectedDevice.DeviceType`)  
+  - `System.Net.NetworkInformation.PhysicalAddress` (for `IDASConnectedDevice.PhysicalAddress`)  
+- **Internal Dependencies**:  
+  - `ICommunication_DASInfo` is used by DAS implementations (e.g., SLICE6DB) to expose device metadata.  
+  - `IDASConnectedDevice` is consumed by higher-level discovery/monitoring logic (e.g., auto-discovery services).  
+- **Consumers**:  
+  - Likely used by DAS-specific communication layers (e.g., `DASCommunicationManager`) and device monitoring services.  
+  - `ICommunicationReport` is probably returned by asynchronous communication operations (e.g., `SendAsync`, `ReceiveAsync`).
+
+---
+
+### **Gotchas**
+- **`StackSerialNumber(int devid)`**: No validation or exception behavior is specified for invalid `devid` (e.g., negative or ≥ `ConnectedDevices.Length`). Implementations may throw `ArgumentOutOfRangeException` or return `null`—behavior is implementation-defined.  
+- **`ConnectedDevices` mutability**: While `ConnectedDevices` is read-only (`get` only), `SetConnectedDevices()` allows external mutation. Callers must ensure thread-safety if used concurrently.  
+- **`FirstUseDate` semantics**: A `null` value does *not* imply "never calibrated"—it means "never used since calibration." A calibrated but unused device may still have `FirstUseDate == null`.  
+- **`IsStreamingSupported`**: Support is hardware/firmware-dependent and may be toggled via system attributes (e.g., `DISABLE_STREAMING_FEATURE`). The interface does not enforce consistency with actual runtime streaming capability.  
+- **No error details**: `ICommunicationReport` lacks error codes, messages, or stack traces—only a high-level `Result` enum. Debugging requires correlating with logs or `UserState`.  
+- **Missing nullability annotations**: Properties like `Data`, `SerialNumber`, and `IPAddress` lack `?` for nullability despite potential `null` values in practice. This may cause confusion in nullable-enabled contexts.  
+- **No versioning guarantees**: Arrays (`SerialNumbers`, `FirmwareVersions`) are parallel to `ConnectedDevices` but have no explicit synchronization mechanism—out-of-sync arrays could occur if `SetConnectedDevices` is called without updating these arrays.