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

---
source_files:
  - Common/DTS.CommonCore/Interface/Hardware/IDASMonitorInfo.cs
  - Common/DTS.CommonCore/Interface/Hardware/IISOHardware.cs
  - Common/DTS.CommonCore/Interface/Hardware/IATDArmStatus.cs
  - Common/DTS.CommonCore/Interface/Hardware/IDiagnosticResult.cs
generated_at: "2026-04-16T02:19:24.711512+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "706013fcdffb7c0e"
---

# Hardware

### **Purpose**  
This module defines a set of core interfaces for hardware monitoring, diagnostics, and status tracking within the DAS (Data Acquisition System) ecosystem. It provides abstractions for querying hardware metadata (e.g., `IDASMonitorInfo`), managing hardware lifecycle and validation (`IISOHardware`), tracking real-time arm/diagnostic status across distributed components (`IAllATDStatus`, `IATDStatus`, `IDistributorArmStatus`, `IDeviceArmStatus`), and encapsulating detailed diagnostic results for individual channels (`IDiagnosticResult`). Together, these interfaces enable consistent introspection, validation, and status reporting across physical and pseudo-rack hardware modules, distributors, and devices in the DAS system.

---

### **Public Interface**

#### **`IDASMonitorInfo`**
- `string SerialNumber { get; }`  
  Returns the hardware serial number.
- `double[] TiltSensorCals { get; }`  
  Returns calibration coefficients for tilt sensors (likely scale/offset per axis).
- `short[] TiltSensorDataPre { get; }`  
  Returns pre-calibrated raw tilt sensor ADC readings.
- `DFConstantsAndEnums.TiltAxes TiltAxes { get; }`  
  Indicates which tilt axes are physically present/active (e.g., X/Y/Z).
- `int AxisIgnored { get; }`  
  Index (0-based) of the tilt axis that is intentionally ignored (e.g., due to mounting).
- `double MountOffsetAxisOne { get; }`  
  Mechanical offset (in degrees or mm) applied to axis 1 during tilt computation.
- `double MountOffsetAxisTwo { get; }`  
  Mechanical offset (in degrees or mm) applied to axis 2 during tilt computation.
- `string GetChannelName(int index)`  
  Returns the human-readable name for channel `index` (e.g., `"CH01"`, `"TILT_X"`).
- `double GetOffsetTolerancemVLow(int index)`  
  Returns the lower bound (in mV) of acceptable offset for channel `index`.
- `double GetOffsetTolerancemVHigh(int index)`  
  Returns the upper bound (in mV) of acceptable offset for channel `index`.
- `void ReadFromFile(string path)`  
  Loads monitor info configuration from a file at `path`.
- `void WriteToFile(string path)`  
  Saves current monitor info configuration 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)`  
  Outputs counts of each channel type supported by this hardware (analog, digital I/O, squib, UART, stream in/out).
- `HardwareTypes DASTypeEnum { get; set; }`  
  Gets/sets the hardware type (e.g., `ISO`, `SLICE`, `SLICE6`) as a strongly-typed enum.
- `string IPAddress { get; set; }`  
  Gets/sets the network IP address assigned to the hardware.
- `bool IsPseudoRackModule()`  
  Returns `true` if this hardware is a pseudo-rack module (e.g., SLICE slab or SLICE6 with S6DB).
- `bool IsTSRAIR()`  
  Returns `true` if this hardware is a TSRAIR module.
- `bool ValidateSerialNumber(ref List<string> errors)`  
  Validates the serial number; appends human-readable error messages to `errors` if invalid; returns `true` if valid.
- `bool ValidateIPAddress(ref List<string> errors)`  
  Validates the `IPAddress`; appends error messages to `errors` if invalid; returns `true` if valid.
- `void Insert()`  
  Persists this hardware record to the database (e.g., creates a new row).
- `void Update()`  
  Updates the existing database record for this hardware.
- `void Delete()`  
  Removes this hardware record from the database.

#### **`IAllATDStatus`**
- `IATDStatus[] ATDs { get; }`  
  Returns an array of all ATD (Arm/Telemetry/Diagnostics) devices being monitored.
- `void AddDevice(IDeviceArmStatus device, string parent)`  
  Registers a device (e.g., a DAS unit) under a named parent (e.g., `"Rack1"` or `"DistributorSN123"`).
- `void PopulateFromHardware(IDASHardware[] hardware)`  
  Initializes or refreshes the ATD status tree using an array of `IDASHardware` instances.
- `AllATDStatuses OverallStatus { get; }`  
  Returns the aggregate status across 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 the list of distributors managed by this ATD.
- `void AddDistributor(IDistributorArmStatus distributor)`  
  Registers a distributor with this ATD.
- `IPAddress IP { get; }`  
  Returns the IP address of this ATD.
- `void SetIP(IPAddress ip)`  
  Sets the IP address of this ATD.
- `void UpdateAggregateStatus()`  
  Recalculates the `Status` based on distributor/device states.

#### **`IDistributorArmStatus`**
- `bool EmptyDistributor { get; }`  
  Returns `true` if this distributor has no attached devices.
- `IDeviceArmStatus Distributor { get; }`  
  Returns the underlying device representing this distributor (e.g., a hardware unit acting as a distributor).
- `void SetDistributor(IDeviceArmStatus distributor)`  
  Associates a device instance as this distributor.
- `DistributorStatuses DistributorStatus { get; }`  
  Returns the distributor’s current status (e.g., `Connected`, `Errored`).
- `void SetDistributorStatus(DistributorStatuses status)`  
  Sets the distributor’s status.
- `AllATDStatuses AggregateStatus { get; }`  
  Returns the status of this distributor’s subtree (e.g., `AllConnected`).
- `IDeviceArmStatus[] Devices { get; }`  
  Returns the list of devices (e.g., DAS units) attached to 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 attached devices.
- `DateTime? LastSeen { get; }`  
  Returns the last timestamp the distributor reported telemetry.
- `float? InputVoltage { get; }`  
  Returns the current input voltage (in V) measured by the distributor.
- `float? BackupVoltage { get; }`  
  Returns the current backup voltage (in V) measured by the distributor.
- `void UpdateStatusFromQATS(IUDPQATSEntry qats)`  
  Updates status fields (e.g., `LastSeen`, `InputVoltage`) from a QATS telemetry entry.

#### **`IDeviceArmStatus`**
- `bool HasArmed { get; set; }`  
  Gets/sets whether this device has successfully armed.
- `DASStatuses DASStatus { get; }`  
  Returns the device’s operational status (e.g., `BootedNotArmedYet`, `ArmedReady`).
- `void SetDASStatus(DASStatuses status)`  
  Sets the device’s `DASStatus`.
- `DiagStatuses DiagStatus { get; }`  
  Returns the device’s diagnostic status (e.g., `Passed`, `FailedShunt`).
- `void SetDiagStatus(DiagStatuses status)`  
  Sets the device’s `DiagStatus`.
- `IDistributorArmStatus Distributor { get; }`  
  Returns the parent distributor of this device.
- `void SetDistributor(IDistributorArmStatus distributor)`  
  Sets the parent distributor.
- `IDASHardware Hardware { get; }`  
  Returns the hardware instance associated with this device.
- `void SetHardware(IDASHardware hardware)`  
  Sets the hardware instance.
- `IDASCommunication DASCommunication { get; }`  
  Returns the communication interface used to interact with this device.
- `void SetDASCommunication(IDASCommunication das)`  
  Sets the communication interface.
- `string SerialNumber { get; }`  
  Returns the device’s serial number.
- `void SetSerialNumber(string serial)`  
  Sets the device’s serial number.
- `DateTime? LastSeen { get; }`  
  Returns the last timestamp the device reported telemetry.
- `float? InputVoltage { get; }`  
  Returns the device’s input voltage (in V).
- `float? BackupVoltage { get; }`  
  Returns the device’s backup voltage (in V).
- `void UpdateStatusFromQATS(IUDPQATSEntry qats)`  
  Updates status fields from a QATS telemetry entry.
- `string ShuntResults { get; }`  
  Returns a human-readable string summarizing shunt test results (e.g., `"PASS"` or `"FAIL: >5% deviation"`).
- `string OffsetResults { get; }`  
  Returns a human-readable string summarizing offset test results.
- `double? TiltX { get; }`  
  Returns the measured tilt on the X-axis (in degrees or mm).
- `double? TiltY { get; }`  
  Returns the measured tilt on the Y-axis.
- `double? TiltZ { get; }`  
  Returns the measured tilt on the Z-axis.
- `string IPAddress { get; }`  
  Returns the device’s IP address.
- `bool Triggered { get; }`  
  Returns `true` if the device has triggered an event.

#### **`IDiagnosticResult`**
- `int DASChannelNumber { get; set; }`  
  Channel number (0-based) this diagnostic result applies to.
- `int EventNumber { get; set; }`  
  Event ID this diagnostic result is associated with.
- `double ScalefactorMilliVoltsPerADC { get; set; }`  
  **Mandatory** scale factor to convert raw ADC counts to mV (from factory calibration).
- `double ExpectedExcitationMilliVolts { get; set; }`  
  **Mandatory** nominal excitation voltage (mV) expected by the sensor.
- `short GetExpectedDataZeroLevelADC(ZeroMethodType zeroMethod)`  
  Returns the expected zero-level ADC value for the given zeroing method (e.g., `AutoZero`, `ManualZero`).
- `double? MeasuredExcitationMilliVolts { get; set; }`  
  Actual excitation voltage measured during calibration (`null` if unmeasured).
- `bool NegativeExcitation { get; set; }`  
  `true` if `MeasuredExcitationMilliVolts` was negative (legacy flag for broken sensor/wire warnings).
- `double? MeasuredOffsetMilliVolts { get; set; }`  
  Measured sensor offset (mV) during calibration (`null` if unmeasured).
- `double? MeasuredInternalOffsetMilliVolts { get; set; }`  
  Internal DAS offset (mV) measured during calibration (`null` if unmeasured).
- `double? AutoZeroPercentDeviation { get; set; }`  
  Deviation (±% of full-scale) from 0 after auto-zeroing (e.g., `3.2` means 3.2% off).
- `short? FinalOffsetADC { get; set; }`  
  Offset remaining after offset-removal calibration (ADC counts).
- `int? RemovedOffsetADC { get; set; }`  
  Offset removed during calibration (ADC counts).
- `int? RemovedInternalOffsetADC { get; set; }`  
  Internal offset removed during calibration (ADC counts).
- `double? NoisePercentFullScale { get; set; }`  
  Full-scale signal-to-noise ratio as a percentage (`null` if unmeasured).
- `bool ShuntDeflectionFailed { get; set; }`  
  `true` if the emulated shunt test failed (deflection outside tolerance).
- `bool CalSignalCheckFailed { get; set; }`  
  `true` if the calibration signal check failed.
- `double? MeasuredShuntDeflectionMv { get; set; }`  
  Measured shunt deflection (mV) during emulated shunt test (`null` if unmeasured).
- `double? MeasuredCalSignalMv { get; set; }`  
  Measured calibration signal (mV).
- `double? TargetCalSignalMv { get; set; }`  
  Expected calibration signal (mV).
- `double? MeasuredDurationMS { get; set; }`  
  Measured duration of a test (e.g., squib fire) in milliseconds.
- `double? MeasuredDelayMS { get; set; }`  
  Measured delay (e.g., squib delay) in milliseconds.
- `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; }`  
  Raw current samples during squib fire test.
- `double[] SquibFireVoltageData { get; set; }`  
  Raw voltage samples during squib fire test.
- `double[] SquibFireTimeAxis { get; set; }`  
  Time axis (ms) corresponding to `SquibFireCurrentData`/`SquibFireVoltageData`.
- `double SquibThreshold { get; set; }`  
  Threshold current (mA) used to detect squib fire start.
- `double SquibVoltageScaler { get; set; }`  
  Scaling factor to convert raw squib voltage ADC to mV.
- `double SquibCurrentScaler { get; set; }`  
  Scaling factor to convert raw squib current ADC to mA.
- `double? TargetGain { get; set; }`  
  Expected gain (e.g., from calibration spec).
- `double? MeasuredGain { get; set; }`  
  Measured gain (e.g., from calibration test).
- `double? QueriedGain { get; set; }`  
  Gain value retrieved from hardware/firmware.
- `double? TargetShuntDeflectionMv { get; set; }`  
  Expected shunt deflection (mV) for emulated shunt test.
- `double? BridgeResistance { get; set; }`  
  Measured sensor bridge resistance (Ω) (`null` if unmeasured).
- `short ZeroMVInADC { get; set; }`  
  ADC value corresponding to 0 mV input (from factory calibration).
- `short WindowAverageADC { get; set; }`  
  Average ADC over the configured averaging window (`short.MinValue` = uninitialized).
- `bool DigitalInputActiveState { get; set; }`  
  Current active state of the digital input (`true` = high, `false` = low).

---

### **Invariants**
- **`IDASMonitorInfo`**:  
  - `TiltSensorCals.Length` must equal `TiltSensorDataPre.Length`.  
  - `AxisIgnored` must be in the range `[0, TiltAxes.Length - 1]` (if tilt axes exist).  
  - `GetChannelName(index)` must return a non-null, non-empty string for all valid `index` values (0 ≤ `index` < channel count).  
- **`IDiagnosticResult`**:  
  - `ScalefactorMilliVoltsPerADC` is **mandatory** and must be non-zero for valid data scaling.  
  - `ExpectedExcitationMilliVolts` is **mandatory** and must be > 0 for valid sensor operation.  
  - `WindowAverageADC == short.MinValue` indicates uninitialized/invalid data.  
  - `MeasuredExcitationMilliVolts == 0.0` or `null` may indicate "not measured" (legacy behavior).  
- **`IDeviceArmStatus`/`IDistributorArmStatus`**:  
  - `LastSeen` may be `null` if the device has never reported telemetry.  
  - `InputVoltage`/`BackupVoltage` may be `null` if not measured.  
  - `DASStatus` and `DiagStatus` must be consistent with `HasArmed` and `ShuntDeflectionFailed`/`CalSignalCheckFailed`.  
- **`IISOHardware`**:  
  - `ValidateSerialNumber`/`ValidateIPAddress` must not mutate the hardware object; errors are appended to the passed `List<string>`.  
  - `IsPseudoRackModule()` and `IsTSRAIR()` are mutually exclusive (a module cannot be both).

---

### **Dependencies**
- **Imports/Usings**:  
  - `DTS.Common.Enums.DASFactory`, `DTS.Common.Enums.Hardware`, `DTS.Common.Enums.Sensors` (for `ZeroMethodType`, `HardwareTypes`, `DistributorStatuses`, etc.).  
  - `DTS.Common.Interface.DataRecorders` (for `IDASHardware`, `IDASCommunication`).  
  - `DTS.Common.Interface.DASFactory.Diagnostics.HardwareList` (for `IDeviceArmStatus` in `IAllATDStatus`).  
  - `System.Net` (`IPAddress`), `System.ComponentModel` (`TypeConverter`), `System.Collections.Generic`.  
- **Inferred Consumers**:  
  - `DTS.DASLib.Service.DiagnosticsService` (for `Calibrate`, `PerformShuntCheck`, `MeasureBridgeResistance`).  
  - `DTS.DASLib.Service.DiagnosticsActions` (for `PerformShuntCheck`).  
  - UI layers or telemetry services that consume `IAllATDStatus`/`IATDStatus` for real-time status dashboards.  
  - Database persistence layers (for `IISOHardware.Insert`/`Update`/`Delete`).  
- **Inferred Providers**:  
  - Concrete implementations of `IDASMonitorInfo` (e.g., `DASMonitorInfo` class) likely read from `.ini` or XML config files.  
  - `IDASHardware` implementations (e.g., `ISOHardware`, `SLICE