103 lines
7.5 KiB
Markdown
103 lines
7.5 KiB
Markdown
|
---
|
|||
|
|
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.
|