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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Interface/Communication/ICommunicationReport.cs Common/DTS.Common/Interface/Communication/IDASConnectedDevice.cs Common/DTS.Common/Interface/Communication/ICommunication_DASInfo.cs	2026-04-16T03:03:06.051623+00:00	Qwen/Qwen3-Coder-Next-FP8	1	d690cf8a777399d3

Communication

Purpose

This module defines core interfaces for representing communication state and device metadata within the DTS (Data Acquisition System) framework. Specifically, it standardizes how communication results, data payloads, and device information (including device topology, identity, and capabilities) are exposed across the system—particularly for auto-discovery and status monitoring of DAS-connected hardware (e.g., S6 devices on an S6DB). These interfaces serve as contracts for implementations handling device communication, status reporting, and metadata management.

---

Public Interface

ICommunicationReport

Represents the outcome and associated data of a communication operation.

• object UserState { get; set; }
  Arbitrary user-defined state object, typically used to correlate asynchronous operations or pass context through callbacks.
• CommunicationConstantsAndEnums.CommunicationResult Result { get; set; }
  The result status of the communication operation (e.g., success, timeout, error). Note: CommunicationResult is defined in an external enum namespace.
• byte[] Data { get; set; }
  Raw byte payload returned or sent during the communication. May be null if no data is applicable (e.g., for command-only operations or failures).

IDASConnectedDevice

Describes a single device physically connected to a DAS (e.g., S6 on S6DB), including its location, identity, and network properties.

• HardwareTypes DeviceType { get; }
  The enumerated type of the device (e.g., S6, S6DB). Defined in DTS.Common.Enums.Hardware.
• int Port { get; }
  Zero-based port index on the DAS to which the device is connected.
• int SpotOnPort { get; }
  Zero-based position of the device along the chain or daisy chain on the given port.
• PhysicalAddress PhysicalAddress { get; }
  MAC address of the device (from System.Net.NetworkInformation).
• string IPAddress { get; }
  IPv4/IPv6 address string assigned to the device.
• string SerialNumber { get; }
  Unique hardware serial number.
• string Location { get; }
  Human-readable location identifier (e.g., "Lab A, Rack 2").
• string Version { get; }
  Firmware or software version string.

ICommunication_DASInfo

Encapsulates metadata about a DAS unit and its connected devices.

• IDASConnectedDevice[] ConnectedDevices { get; }
  Immutable array of devices currently connected to this DAS. Currently only populated for SLICE6DB.
• void SetConnectedDevices(IDASConnectedDevice[] devices)
  Mutator to populate ConnectedDevices. Intended for internal use during device enumeration/discovery.
• string[] SerialNumbers { get; set; }
  Parallel array of serial numbers for connected devices (index-aligned with ConnectedDevices).
• string[] FirmwareVersions { get; set; }
  Parallel array of firmware versions for connected devices (index-aligned with ConnectedDevices).
• string StackSerialNumber(int devid)
  Returns the serial number of the device at the specified devid index (0-based). Assumes devid is valid for the current ConnectedDevices array.
• DateTime? FirstUseDate { get; set; }
  Date of first operational use. null indicates the device has not been used since last calibration (or calibration is unsupported). Valid only when IsFirstUseDateSupported is true.
• bool IsFirstUseDateSupported { get; set; }
  Indicates whether the hardware supports tracking first-use date (requires firmware/user-attribute storage and calibration support per issue #15524).
• bool IsStreamingSupported { get; set; }
  Indicates whether the hardware supports streaming data (e.g., via system attribute DISABLE_STREAMING_FEATURE per issue #30429).

---

Invariants

• ConnectedDevices alignment: SerialNumbers[i] and FirmwareVersions[i] must correspond to ConnectedDevices[i] for all valid indices i.
• StackSerialNumber contract: Must return the serial number at index devid in ConnectedDevices; behavior is undefined if devid is out of bounds.
• FirstUseDate validity: FirstUseDate.HasValue is only meaningful when IsFirstUseDateSupported == true; otherwise, it should be ignored.
• Result semantics: The Result field in ICommunicationReport must accurately reflect the outcome of the operation; Data may be non-null only for successful or partial-success results (implementation-dependent).

---

Dependencies

• Depends on:
  • DTS.Common.Enums.Communication.CommunicationResult (external enum)
  • DTS.Common.Enums.Hardware.HardwareTypes (external enum)
  • System.Net.NetworkInformation.PhysicalAddress (BCL type)
• Depended on by:
  • Components implementing auto-discovery and device monitoring (e.g., DAS status monitors, network scanners).
  • Code handling device metadata aggregation (e.g., configuration managers, diagnostic tools).
  • Likely consumed by higher-level communication layers (e.g., ICommunicationService, DASController).

---

Gotchas

• ConnectedDevices is currently only populated for SLICE6DB: Other DAS types may return an empty or uninitialized array. Do not assume it is universally populated.
• SetConnectedDevices is a setter, not an adder: It replaces the entire array; incremental updates require manual reconstruction.
• StackSerialNumber uses devid as an array index: No bounds checking is specified; callers must ensure 0 ≤ devid < ConnectedDevices.Length.
• FirstUseDate semantics are conditional: A null value does not necessarily mean "never used"—it may also indicate lack of hardware support.
• IsStreamingSupported is hardware- and firmware-dependent: Support may be toggled via system attributes (e.g., DISABLE_STREAMING_FEATURE), so runtime checks may be necessary beyond this flag.
• No validation rules specified: Interfaces do not enforce non-null constraints (e.g., IPAddress or SerialNumber could be null or empty strings). Consumers must handle missing data defensively.
• No thread-safety guarantees: Interfaces are passive data contracts; thread-safety must be handled by implementations.

None of the interfaces define event handlers, async methods, or lifecycle management—these are handled elsewhere.