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

---
source_files:
  - Common/DTS.Common/Interface/Hardware/IDASMonitorInfo.cs
  - Common/DTS.Common/Interface/Hardware/IISOHardware.cs
  - Common/DTS.Common/Interface/Hardware/IATDArmStatus.cs
  - Common/DTS.Common/Interface/Hardware/IDiagnosticResult.cs
generated_at: "2026-04-16T02:59:35.943426+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "1012dc34e8e71120"
---

# Hardware

### **Purpose**  
This module defines core interfaces for hardware monitoring, diagnostics, and status tracking within the DAS (Data Acquisition System) ecosystem. It establishes contracts for representing physical hardware components (e.g., DAS units, distributors, ATDs), their calibration and diagnostic metadata, and real-time operational status (e.g., connection, arming, fault states). These interfaces decouple domain logic from concrete implementations—enabling database persistence (`IISOHardware`), hardware-specific diagnostics (`IDASMonitorInfo`, `IDiagnosticResult`), and distributed system status aggregation (`IAllATDStatus`, `IATDStatus`, `IDistributorArmStatus`, `IDeviceArmStatus`)—while supporting both live monitoring (via UDP QATS entries) and offline analysis (via file I/O and database operations).

---

### **Public Interface**

#### **`IDASMonitorInfo`**
- `string SerialNumber { get; }`  
  Returns the hardware serial number.
- `double[] TiltSensorCals { get; }`  
  Returns calibration coefficients for tilt sensors (e.g., scale, offset).
- `short[] TiltSensorDataPre { get; }`  
  Returns pre-calibrated tilt sensor ADC readings.
- `DFConstantsAndEnums.TiltAxes TiltAxes { get; }`  
  Indicates which axes (e.g., X, Y, Z) are configured for tilt measurement.
- `int AxisIgnored { get; }`  
  Index of the tilt axis excluded from diagnostics or operation.
- `double MountOffsetAxisOne { get; }`  
  Mounting offset (in engineering units) for axis 1 (e.g., mechanical misalignment).
- `double MountOffsetAxisTwo { get; }`  
  Mounting offset (in engineering units) for axis 2.
- `string GetChannelName(int index)`  
  Returns the human-readable name of the channel at `index`.
- `double GetOffsetTolerancemVLow(int index)`  
  Returns the lower bound (mV) of acceptable offset tolerance for channel `index`.
- `double GetOffsetTolerancemVHigh(int index)`  
  Returns the upper bound (mV) of acceptable offset tolerance for channel `index`.
- `void ReadFromFile(string path)`  
  Loads monitor info from a file at `path`.
- `void WriteToFile(string path)`  
  Persists monitor info to a file at `path`.

#### **`IISOHardware`**
- `void GetChannelsString(out int analog, out int digitalIn, out int digitalOut, out int squib, out int uart, out int streamOut, out int streamIn, out int can)`  
  Outputs counts of each channel type (analog, digital I/O, squib, UART, etc.) for this hardware.
- `HardwareTypes DASTypeEnum { get; set; }`  
  Gets/sets the hardware type (e.g., `TDA`, `SLICE`, `SLICE6`).
- `string IPAddress { get; set; }`  
  Gets/sets the network address of the hardware.
- `bool IsPseudoRackModule()`  
  Returns `true` if the hardware is a pseudo-rack module (e.g., SLICE slab, S6DB).
- `bool IsTSRAIR()`  
  Returns `true` if the hardware is a TSRAIR unit.
- `bool ValidateSerialNumber(ref List<string> errors)`  
  Validates the serial number; appends human-readable errors to `errors` if invalid.
- `bool ValidateIPAddress(ref List<string> errors)`  
  Validates the IP address format; appends errors to `errors` if invalid.
- `void Insert()`  
  Persists this hardware record to the database.
- `void Update()`  
  Updates the database record for this hardware.
- `void Delete()`  
  Removes this hardware record from the database.

#### **`IAllATDStatus`**
- `IATDStatus[] ATDs { get; }`  
  Returns an array of ATD (Arming and Test Device) status objects.
- `void AddDevice(IDeviceArmStatus device, string parent)`  
  Registers a device (e.g., DAS unit) under a named parent (e.g., distributor serial).
- `void PopulateFromHardware(IDASHardware[] hardware)`  
  Initializes ATD status from an array of `IDASHardware` instances.
- `AllATDStatuses OverallStatus { get; }`  
  Returns the aggregate status of all ATDs (e.g., `AllConnected`, `Errors`).

#### **`IATDStatus`**
- `AllATDStatuses Status { get; }`  
  Returns the current status of this ATD (e.g., `Connecting`, `AllArmed`).
- `IDistributorArmStatus[] Distributors { get; }`  
  Returns child distributors managed by this ATD.
- `void AddDistributor(IDistributorArmStatus distributor)`  
  Adds a distributor to this ATD.
- `IPAddress IP { get; }`  
  Returns the IP address of the ATD.
- `void SetIP(IPAddress ip)`  
  Sets the IP address of the ATD.
- `void UpdateAggregateStatus()`  
  Recalculates the `Status` based on distributor/device states.

#### **`IDistributorArmStatus`**
- `bool EmptyDistributor { get; }`  
  Returns `true` if no devices are assigned to this distributor.
- `IDeviceArmStatus Distributor { get; }`  
  Returns the distributor’s own device status (circular reference for hierarchy).
- `void SetDistributor(IDeviceArmStatus distributor)`  
  Sets the distributor’s device status.
- `DistributorStatuses DistributorStatus { get; }`  
  Returns the distributor’s current status (`NotConnected`, `Connected`, `Armed`, etc.).
- `void SetDistributorStatus(DistributorStatuses status)`  
  Sets the distributor’s status.
- `AllATDStatuses AggregateStatus { get; }`  
  Returns the combined status of this distributor and its devices.
- `IDeviceArmStatus[] Devices { get; }`  
  Returns child devices (e.g., DAS units) under this distributor.
- `void AddDevice(IDeviceArmStatus device)`  
  Adds a device to this distributor.
- `string SerialNumber { get; }`  
  Returns the distributor’s serial number.
- `void SetSerialNumber(string serial)`  
  Sets the distributor’s serial number.
- `void UpdateAggregateStatus()`  
  Recalculates `AggregateStatus` from device states.
- `DateTime? LastSeen { get; }`  
  Timestamp of last communication; `null` if never seen.
- `float? InputVoltage { get; }`  
  Measured input voltage (V); `null` if unavailable.
- `float? BackupVoltage { get; }`  
  Measured backup voltage (V); `null` if unavailable.
- `void UpdateStatusFromQATS(IUDPQATSEntry qats)`  
  Updates status using data from a QATS UDP packet.

#### **`IDeviceArmStatus`**
- `bool HasArmed { get; set; }`  
  Gets/sets whether the device has been armed.
- `DASStatuses DASStatus { get; }`  
  Returns the DAS unit’s operational status (`BootedNotArmedYet`, `ArmedReady`, etc.).
- `void SetDASStatus(DASStatuses status)`  
  Sets the DAS unit’s status.
- `DiagStatuses DiagStatus { get; }`  
  Returns diagnostic pass/fail state (`Passed`, `FailedShunt`, `NoResults`, etc.).
- `void SetDiagStatus(DiagStatuses status)`  
  Sets the diagnostic status.
- `IDistributorArmStatus Distributor { get; }`  
  Returns the parent distributor.
- `void SetDistributor(IDistributorArmStatus distributor)`  
  Sets the parent distributor.
- `IDASHardware Hardware { get; }`  
  Returns the associated hardware record.
- `void SetHardware(IDASHardware hardware)`  
  Sets the hardware record.
- `IDASCommunication DASCommunication { get; }`  
  Returns the communication channel object.
- `void SetDASCommunication(IDASCommunication das)`  
  Sets the communication channel.
- `string SerialNumber { get; }`  
  Returns the device’s serial number.
- `void SetSerialNumber(string serial)`  
  Sets the device’s serial number.
- `DateTime? LastSeen { get; }`  
  Timestamp of last communication; `null` if never seen.
- `float? InputVoltage { get; }`  
  Measured input voltage (V); `null` if unavailable.
- `float? BackupVoltage { get; }`  
  Measured backup voltage (V); `null` if unavailable.
- `void UpdateStatusFromQATS(IUDPQATSEntry qats)`  
  Updates status using QATS data.
- `string ShuntResults { get; }`  
  Human-readable shunt test results (e.g., "PASS", "FAIL: >5% deviation").
- `string OffsetResults { get; }`  
  Human-readable offset test results.
- `double? TiltX { get; }`  
  Measured tilt on X-axis (degrees); `null` if unavailable.
- `double? TiltY { get; }`  
  Measured tilt on Y-axis (degrees); `null` if unavailable.
- `double? TiltZ { get; }`  
  Measured tilt on Z-axis (degrees); `null` if unavailable.
- `string IPAddress { get; }`  
  Returns the device’s IP address.
- `bool Triggered { get; }`  
  Returns `true` if the device triggered an event.

#### **`IDiagnosticResult`**
- `int DASChannelNumber { get; set; }`  
  Channel index this diagnostic applies to.
- `int EventNumber { get; set; }`  
  Event ID associated with this diagnostic.
- `double ScalefactorMilliVoltsPerADC { get; set; }`  
  Factory-calibrated scale factor (mV/ADC count); mandatory for data scaling.
- `double ExpectedExcitationMilliVolts { get; set; }`  
  Nominal excitation voltage (mV) for the sensor.
- `short GetExpectedDataZeroLevelADC(ZeroMethodType zeroMethod)`  
  Returns expected zero-level ADC for the given zeroing method.
- `double? MeasuredExcitationMilliVolts { get; set; }`  
  Actual measured excitation (mV); `null` if unmeasured.
- `bool NegativeExcitation { get; set; }`  
  `true` if `MeasuredExcitationMilliVolts` was negative (legacy flag).
- `double? MeasuredOffsetMilliVolts { get; set; }`  
  Measured sensor offset (mV); `null` if unmeasured.
- `double? MeasuredInternalOffsetMilliVolts { get; set; }`  
  Internal offset (mV) measured by firmware.
- `double? AutoZeroPercentDeviation { get; set; }`  
  Deviation (%) from 0 after auto-zero (target: ±5%).
- `short? FinalOffsetADC { get; set; }`  
  Offset (ADC) after offset-removal calibration.
- `int? RemovedOffsetADC { get; set; }`  
  Offset (ADC) removed during calibration.
- `int? RemovedInternalOffsetADC { get; set; }`  
  Internal offset (ADC) removed during calibration.
- `double? NoisePercentFullScale { get; set; }`  
  Full-scale signal-to-noise ratio (%); `null` if unmeasured.
- `bool ShuntDeflectionFailed { get; set; }`  
  `true` if shunt test failed.
- `bool CalSignalCheckFailed { get; set; }`  
  `true` if calibration signal check failed.
- `double? MeasuredShuntDeflectionMv { get; set; }`  
  Measured shunt deflection (mV) during emulated test.
- `double? MeasuredCalSignalMv { get; set; }`  
  Measured calibration signal (mV).
- `double? TargetCalSignalMv { get; set; }`  
  Expected calibration signal (mV).
- `double? MeasuredDurationMS { get; set; }`  
  Measured squib fire duration (ms).
- `double? MeasuredDelayMS { get; set; }`  
  Measured squib delay (ms).
- `bool? SquibFirePassed { get; set; }`  
  `true` if squib fire test passed.
- `bool? SquibDurationPassed { get; set; }`  
  `true` if squib duration test passed.
- `bool? SquibDelayPassed { get; set; }`  
  `true` if squib delay test passed.
- `double[] SquibFireCurrentData { get; set; }`  
  Squib current waveform samples.
- `double[] SquibFireVoltageData { get; set; }`  
  Squib voltage waveform samples.
- `double[] SquibFireTimeAxis { get; set; }`  
  Time axis (ms) for squib waveforms.
- `double SquibThreshold { get; set; }`  
  Squib fire threshold (mA).
- `double SquibVoltageScaler { get; set; }`  
  Voltage waveform scaler.
- `double SquibCurrentScaler { get; set; }`  
  Current waveform scaler.
- `double? TargetGain { get; set; }`  
  Expected gain (e.g., from calibration).
- `double? MeasuredGain { get; set; }`  
  Measured gain.
- `double? QueriedGain { get; set; }`  
  Gain value queried from hardware.
- `double? TargetShuntDeflectionMv { get; set; }`  
  Expected shunt deflection (mV).
- `double? BridgeResistance { get; set; }`  
  Measured bridge resistance (Ω); `null` if unmeasured.
- `short ZeroMVInADC { get; set; }`  
  Zero-voltage ADC reading.
- `short WindowAverageADC { get; set; }`  
  Average ADC over the sampling window; `short.MinValue` if invalid/uninitialized.
- `bool DigitalInputActiveState { get; set; }`  
  Current state of digital input (active/inactive).

---

### **Invariants**
- **`IDASMonitorInfo`**:  
  - `TiltSensorCals.Length` and `TiltSensorDataPre.Length` must match the number of configured tilt axes.  
  - `AxisIgnored` must be a valid index (0–2) if tilt axes are enabled; otherwise, it may be `-1` (uninitialized).  
  - `GetOffsetTolerancemVLow(index)` ≤ `GetOffsetTolerancemVHigh(index)` for all valid `index`.

- **`IISOHardware`**:  
  - `DASTypeEnum` must be consistent with `IsPseudoRackModule()` and `IsTSRAIR()` results (e.g., `SLICE` → `IsPseudoRackModule() == true`).  
  - `ValidateSerialNumber` and `ValidateIPAddress` must return `false` if `errors` is non-empty after validation.

- **`IDeviceArmStatus`/`IDistributorArmStatus`/`IATDStatus`**:  
  - `LastSeen` must be `null` only if the device has never communicated.  
  - `DASStatus` and `DistributorStatus` must be consistent with `HasArmed` and `Status`/`AggregateStatus`.  
  - `UpdateAggregateStatus()` must propagate status upward (device → distributor → ATD → `IAllATDStatus.OverallStatus`).  
  - `EmptyDistributor` must be `true` iff `Devices.Length == 0`.

- **`IDiagnosticResult`**:  
  - `ScalefactorMilliVoltsPerADC` is mandatory and must be non-zero for valid data scaling.  
  - `MeasuredExcitationMilliVolts == 0.0` implies `null` (unmeasured); `NegativeExcitation` must be `true` if the original value was negative.  
  - `WindowAverageADC == short.MinValue` indicates uninitialized/invalid data.  
  - `BridgeResistance`, `MeasuredExcitationMilliVolts`, `MeasuredOffsetMilliVolts`, etc., may be `null` if not measured during calibration.

---

### **Dependencies**
- **Depends on**:  
  - `DTS.Common.Enums.DASFactory` (e.g., `DFConstantsAndEnums.TiltAxes`, `ZeroMethodType`).  
  - `DTS.Common.Enums.Hardware` (`HardwareTypes`).  
  - `DTS.Common.Interface.DataRecorders` (e.g., `IDASHardware`, `IDASCommunication`).  
  - `DTS.Common.Interface.DASFactory.Diagnostics` (e.g., `IDASDBRecord` base interface for `IISOHardware`).  
  - `System.Net` (`IPAddress`).  
  - `System.ComponentModel` (`TypeConverter` for enum descriptions).  
  - `DTS.Common.Converters` (`EnumDescriptionTypeConverter`).  
  - `IUDPQATSEntry` (from QATS UDP packet handling, inferred from `UpdateStatusFromQATS`).

- **Depended on by**:  
  - `DTS.DASLib.Service.DiagnosticsService` (for `Calibrate`, `MeasureBridgeResistance`, `PerformShuntCheck`).  
  - `DTS.DASLib.Service.DiagnosticsActions` (for shunt/diagnostic actions).  
  - UI layers (e.g., status dashboards consuming `IAllATDStatus`/`IATDStatus`).  
  - Database persistence layers (e.g., `Insert`/`Update`/`Delete` in `IISOHardware`).

---

### **Gotchas**
- **`IDiagnosticResult.MeasuredExcitationMilliVolts == 0.0` is ambiguous**: It may mean "unmeasured" (null) or an actual 0.0 mV reading. Use `NegativeExcitation` to infer legacy negative readings (see comment on line 36–38).  
- **`WindowAverageADC == short.MinValue` indicates invalid data**: Not `0` or `null`—a sentinel value for uninitialized state.  
- **`IDASMonitorInfo.GetOffsetTolerancemVLow/High(index)`**: Index bounds are not enforced in the interface; callers must ensure `index` is within valid channel range.  
- **`IDistributorArmStatus.Distributor`**: Circular reference to `IDeviceArmStatus` (the distributor itself is a device); avoid infinite recursion in serialization.  
- **`DASStatuses` enum has duplicate `[Description]` values**: `Bo