--- 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.