enriched-partialglm/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-16T12:11:59.143193+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "706013fcdffb7c0e"
---

# Hardware Interface Module Documentation

## 1. Purpose
This module defines the core contracts for hardware abstraction within the DTS (Data Acquisition System) ecosystem. It provides interfaces for managing monitor calibration data (`IDASMonitorInfo`), persisting hardware configuration records (`IISOHardware`), tracking the hierarchical connection and arming status of devices (`IATDArmStatus` and related types), and reporting detailed per-channel diagnostic results (`IDiagnosticResult`). These interfaces decouple the system logic from specific hardware implementations, enabling consistent data handling across different device types.

## 2. Public Interface

### `IDASMonitorInfo`
Defines accessors for monitor hardware configuration and calibration data, specifically for tilt sensors and channel offsets.

*   **Properties**:
    *   `string SerialNumber`: The hardware serial number.
    *   `double[] TiltSensorCals`: Calibration data for tilt sensors.
    *   `short[] TiltSensorDataPre`: Pre-calibration tilt sensor data.
    *   `DFConstantsAndEnums.TiltAxes TiltAxes`: The tilt axes configuration.
    *   `int AxisIgnored`: Identifier for which axis is ignored.
    *   `double MountOffsetAxisOne` / `MountOffsetAxisTwo`: Mounting offset values.
*   **Methods**:
    *   `string GetChannelName(int index)`: Retrieves the name of a channel by index.
    *   `double GetOffsetTolerancemVLow(int index)` / `GetOffsetTolerancemVHigh(int index)`: Retrieves voltage offset tolerances.
    *   `void ReadFromFile(string path)`: Populates the object from a file.
    *   `void WriteToFile(string path)`: Persists the object state to a file.

### `IISOHardware` (inherits `IDASDBRecord`)
Defines behavior for hardware entities that interact with a database and network configuration.

*   **Properties**:
    *   `HardwareTypes DASTypeEnum`: The specific hardware type enumeration.
    *   `string IPAddress`: The network IP address of the hardware.
*   **Methods**:
    *   `void GetChannelsString(...)`: Returns counts of various channel types (analog, digital, squib, UART, stream) via out parameters.
    *   `bool IsPseudoRackModule()`: Indicates if the hardware is capable of being a pseudo-rack module (e.g., SLICE slabs).
    *   `bool IsTSRAIR()`: Indicates specific hardware capability.
    *   `bool ValidateSerialNumber(ref List<string> errors)` / `ValidateIPAddress(...)`: Validates configuration, appending errors to the provided list.
    *   `void Insert()` / `Update()` / `Delete()`: Database CRUD operations.

### `IATDArmStatus` Hierarchy
A set of interfaces and enums defining the status of Arm/Trigger Devices (ATD) in a hierarchy: `IAllATDStatus` -> `IATDStatus` -> `IDistributorArmStatus` -> `IDeviceArmStatus`.

*   **`IAllATDStatus`**: Root container for ATD statuses.
    *   `IATDStatus[] ATDs`: Array of ATD devices.
    *   `AllATDStatuses OverallStatus`: Aggregate status enum (NotConnected, Connecting, AllConnected, AllArmed, Errors).
*   **`IATDStatus`**: Represents a single ATD unit.
    *   `IPAddress IP`: The IP address of the ATD.
    *   `IDistributorArmStatus[] Distributors`: Child distributors.
    *   `void UpdateAggregateStatus()`: Recalculates status based on children.
*   **`IDistributorArmStatus`**: Represents a distributor device.
    *   `DistributorStatuses DistributorStatus`: Enum (NotConnected, Connected, Armed, NotArmed, Errored).
    *   `IDeviceArmStatus[] Devices`: Child devices.
    *   `DateTime? LastSeen`, `float? InputVoltage`, `float? BackupVoltage`: Status metrics.
    *   `void UpdateStatusFromQATS(IUDPQATSEntry qats)`: Updates status from a QATS entry.
*   **`IDeviceArmStatus`**: Represents a specific data acquisition device.
    *   `DASStatuses DASStatus`: Enum (MissingNotBooted, BootedNotArmedYet, ArmedReady, etc.).
    *   `DiagStatuses DiagStatus`: Flags enum (Passed, NoResults, FailedShunt, FailedOffset, etc.).
    *   `IDASHardware Hardware`: Reference to the hardware interface.
    *   `string ShuntResults`, `OffsetResults`: Diagnostic result strings.
    *   `double? TiltX`, `TiltY`, `TiltZ`: Tilt sensor readings.
    *   `bool Triggered`: Indicates if the device triggered.

### `IDiagnosticResult`
Defines a data contract for the results of a channel diagnostic or calibration run.

*   **Identification**:
    *   `int DASChannelNumber`, `int EventNumber`.
*   **Scaling & Excitation**:
    *   `double ScalefactorMilliVoltsPerADC`: Mandatory factor to convert raw ADC data to voltage.
    *   `double ExpectedExcitationMilliVolts`, `double? MeasuredExcitationMilliVolts`.
    *   `bool NegativeExcitation`: Flag for legacy negative excitation handling.
*   **Offsets**:
    *   `double? MeasuredOffsetMilliVolts`, `double? MeasuredInternalOffsetMilliVolts`.
    *   `short? FinalOffsetADC`: Remaining offset after a removal attempt.
    *   `short WindowAverageADC`: Average ADC over a window.
*   **Shunt & Calibration**:
    *   `bool ShuntDeflectionFailed`, `bool CalSignalCheckFailed`.
    *   `double? MeasuredShuntDeflectionMv`, `double? TargetShuntDeflectionMv`.
    *   `double? BridgeResistance`: Measured sensor resistance.
*   **Squib (Explosive/Firing) Data**:
    *   `bool? SquibFirePassed`, `SquibDurationPassed`, `SquibDelayPassed`.
    *   `double[] SquibFireCurrentData`, `SquibFireVoltageData`, `SquibFireTimeAxis`.
*   **Methods**:
    *   `short GetExpectedDataZeroLevelADC(ZeroMethodType zeroMethod)`: Calculates expected zero level.

## 3. Invariants

*   **`IDiagnosticResult.WindowAverageADC`**: The value `short.MinValue` explicitly indicates an uninitialized or invalid state.
*   **`IDiagnosticResult` Nullability**: When reading specific properties (`MeasuredExcitationMilliVolts`, `MeasuredOffsetMilliVolts`, `NoisePercentFullScale`, `MeasuredShuntDeflectionMv`, `TargetShuntDeflectionMv`, `BridgeResistance`) from event attributes, a value of `0.0` may represent `null` (i.e., the value was not measured), rather than a literal zero measurement.
*   **`DiagStatuses`**: This is a `[Flags]` enum, meaning multiple failure conditions (e.g., `FailedShunt | FailedOffset`) can be set simultaneously.
*   **`IISOHardware.IsPseudoRackModule`**: This method indicates *capability* (e.g., SLICE slabs), not whether the hardware is currently serving that role.

## 4. Dependencies

*   **Internal Dependencies**:
    *   `DTS.Common.Enums.DASFactory` (for `DFConstantsAndEnums.TiltAxes`)
    *   `DTS.Common.Enums.Hardware` (for `HardwareTypes`)
    *   `DTS.Common.Enums.Sensors` (for `ZeroMethodType`)
    *   `DTS.Common.Converters` (for `EnumDescriptionTypeConverter`)
    *   `DTS.Common.Interface.DataRecorders` (for `IDASDBRecord`)
    *   `DTS.Common.Interface.DASFactory` (for `IDASHardware`, `IDASCommunication`)
    *   `DTS.Common.Interface.DASFactory.Diagnostics.HardwareList` (implied by namespace usage)
*   **External Dependencies**:
    *   `System`
    *   `System.Collections.Generic`
    *   `System.ComponentModel`
    *   `System.Net`

## 5. Gotchas

*   **Ambiguous Zero Values**: In `IDiagnosticResult`, developers must be aware that `0.0` does not always mean "zero volts"; it often serves as a sentinel for "not measured" when read from event attributes. Logic checking for `> 0` may need to handle this distinction.
*   **Legacy Excitation Handling**: The `NegativeExcitation` boolean in `IDiagnosticResult` exists specifically to handle legacy TDC/TDAS hardware behavior regarding broken sensor/wire warnings. This suggests newer implementations should not rely on sign checks alone for error detection without consulting this flag.
*   **Pseudo-Rack Definition**: The comment in `IISOHardware` clarifies that "Pseudo racks" are collections of hardware like SLICE slabs. The method `IsPseudoRackModule()` returns true based on hardware type capability, regardless of its current configuration context.
init 2026-04-17 14:55:32 -04:00			`---`
			`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-16T12:11:59.143193+00:00"`
			`model: "zai-org/GLM-5-FP8"`
			`schema_version: 1`
			`sha256: "706013fcdffb7c0e"`
			`---`

			`# Hardware Interface Module Documentation`

			`## 1. Purpose`
			This module defines the core contracts for hardware abstraction within the DTS (Data Acquisition System) ecosystem. It provides interfaces for managing monitor calibration data (`IDASMonitorInfo`), persisting hardware configuration records (`IISOHardware`), tracking the hierarchical connection and arming status of devices (`IATDArmStatus` and related types), and reporting detailed per-channel diagnostic results (`IDiagnosticResult`). These interfaces decouple the system logic from specific hardware implementations, enabling consistent data handling across different device types.

			`## 2. Public Interface`

			### `IDASMonitorInfo`
			`Defines accessors for monitor hardware configuration and calibration data, specifically for tilt sensors and channel offsets.`

			`* Properties:`
			* `string SerialNumber`: The hardware serial number.
			* `double[] TiltSensorCals`: Calibration data for tilt sensors.
			* `short[] TiltSensorDataPre`: Pre-calibration tilt sensor data.
			* `DFConstantsAndEnums.TiltAxes TiltAxes`: The tilt axes configuration.
			* `int AxisIgnored`: Identifier for which axis is ignored.
			* `double MountOffsetAxisOne` / `MountOffsetAxisTwo`: Mounting offset values.
			`* Methods:`
			* `string GetChannelName(int index)`: Retrieves the name of a channel by index.
			* `double GetOffsetTolerancemVLow(int index)` / `GetOffsetTolerancemVHigh(int index)`: Retrieves voltage offset tolerances.
			* `void ReadFromFile(string path)`: Populates the object from a file.
			* `void WriteToFile(string path)`: Persists the object state to a file.

			### `IISOHardware` (inherits `IDASDBRecord`)
			`Defines behavior for hardware entities that interact with a database and network configuration.`

			`* Properties:`
			* `HardwareTypes DASTypeEnum`: The specific hardware type enumeration.
			* `string IPAddress`: The network IP address of the hardware.
			`* Methods:`
			* `void GetChannelsString(...)`: Returns counts of various channel types (analog, digital, squib, UART, stream) via out parameters.
			* `bool IsPseudoRackModule()`: Indicates if the hardware is capable of being a pseudo-rack module (e.g., SLICE slabs).
			* `bool IsTSRAIR()`: Indicates specific hardware capability.
			* `bool ValidateSerialNumber(ref List<string> errors)` / `ValidateIPAddress(...)`: Validates configuration, appending errors to the provided list.
			* `void Insert()` / `Update()` / `Delete()`: Database CRUD operations.

			### `IATDArmStatus` Hierarchy
			A set of interfaces and enums defining the status of Arm/Trigger Devices (ATD) in a hierarchy: `IAllATDStatus` -> `IATDStatus` -> `IDistributorArmStatus` -> `IDeviceArmStatus`.

			* `IAllATDStatus`: Root container for ATD statuses.
			* `IATDStatus[] ATDs`: Array of ATD devices.
			* `AllATDStatuses OverallStatus`: Aggregate status enum (NotConnected, Connecting, AllConnected, AllArmed, Errors).
			* `IATDStatus`: Represents a single ATD unit.
			* `IPAddress IP`: The IP address of the ATD.
			* `IDistributorArmStatus[] Distributors`: Child distributors.
			* `void UpdateAggregateStatus()`: Recalculates status based on children.
			* `IDistributorArmStatus`: Represents a distributor device.
			* `DistributorStatuses DistributorStatus`: Enum (NotConnected, Connected, Armed, NotArmed, Errored).
			* `IDeviceArmStatus[] Devices`: Child devices.
			* `DateTime? LastSeen`, `float? InputVoltage`, `float? BackupVoltage`: Status metrics.
			* `void UpdateStatusFromQATS(IUDPQATSEntry qats)`: Updates status from a QATS entry.
			* `IDeviceArmStatus`: Represents a specific data acquisition device.
			* `DASStatuses DASStatus`: Enum (MissingNotBooted, BootedNotArmedYet, ArmedReady, etc.).
			* `DiagStatuses DiagStatus`: Flags enum (Passed, NoResults, FailedShunt, FailedOffset, etc.).
			* `IDASHardware Hardware`: Reference to the hardware interface.
			* `string ShuntResults`, `OffsetResults`: Diagnostic result strings.
			* `double? TiltX`, `TiltY`, `TiltZ`: Tilt sensor readings.
			* `bool Triggered`: Indicates if the device triggered.

			### `IDiagnosticResult`
			`Defines a data contract for the results of a channel diagnostic or calibration run.`

			`* Identification:`
			* `int DASChannelNumber`, `int EventNumber`.
			`* Scaling & Excitation:`
			* `double ScalefactorMilliVoltsPerADC`: Mandatory factor to convert raw ADC data to voltage.
			* `double ExpectedExcitationMilliVolts`, `double? MeasuredExcitationMilliVolts`.
			* `bool NegativeExcitation`: Flag for legacy negative excitation handling.
			`* Offsets:`
			* `double? MeasuredOffsetMilliVolts`, `double? MeasuredInternalOffsetMilliVolts`.
			* `short? FinalOffsetADC`: Remaining offset after a removal attempt.
			* `short WindowAverageADC`: Average ADC over a window.
			`* Shunt & Calibration:`
			* `bool ShuntDeflectionFailed`, `bool CalSignalCheckFailed`.
			* `double? MeasuredShuntDeflectionMv`, `double? TargetShuntDeflectionMv`.
			* `double? BridgeResistance`: Measured sensor resistance.
			`* Squib (Explosive/Firing) Data:`
			* `bool? SquibFirePassed`, `SquibDurationPassed`, `SquibDelayPassed`.
			* `double[] SquibFireCurrentData`, `SquibFireVoltageData`, `SquibFireTimeAxis`.
			`* Methods:`
			* `short GetExpectedDataZeroLevelADC(ZeroMethodType zeroMethod)`: Calculates expected zero level.

			`## 3. Invariants`

			* `IDiagnosticResult.WindowAverageADC`: The value `short.MinValue` explicitly indicates an uninitialized or invalid state.
			* `IDiagnosticResult` Nullability: When reading specific properties (`MeasuredExcitationMilliVolts`, `MeasuredOffsetMilliVolts`, `NoisePercentFullScale`, `MeasuredShuntDeflectionMv`, `TargetShuntDeflectionMv`, `BridgeResistance`) from event attributes, a value of `0.0` may represent `null` (i.e., the value was not measured), rather than a literal zero measurement.
			* `DiagStatuses`: This is a `[Flags]` enum, meaning multiple failure conditions (e.g., `FailedShunt \| FailedOffset`) can be set simultaneously.
			* `IISOHardware.IsPseudoRackModule`: This method indicates capability (e.g., SLICE slabs), not whether the hardware is currently serving that role.

			`## 4. Dependencies`

			`* Internal Dependencies:`
			* `DTS.Common.Enums.DASFactory` (for `DFConstantsAndEnums.TiltAxes`)
			* `DTS.Common.Enums.Hardware` (for `HardwareTypes`)
			* `DTS.Common.Enums.Sensors` (for `ZeroMethodType`)
			* `DTS.Common.Converters` (for `EnumDescriptionTypeConverter`)
			* `DTS.Common.Interface.DataRecorders` (for `IDASDBRecord`)
			* `DTS.Common.Interface.DASFactory` (for `IDASHardware`, `IDASCommunication`)
			* `DTS.Common.Interface.DASFactory.Diagnostics.HardwareList` (implied by namespace usage)
			`* External Dependencies:`
			* `System`
			* `System.Collections.Generic`
			* `System.ComponentModel`
			* `System.Net`

			`## 5. Gotchas`

			* Ambiguous Zero Values: In `IDiagnosticResult`, developers must be aware that `0.0` does not always mean "zero volts"; it often serves as a sentinel for "not measured" when read from event attributes. Logic checking for `> 0` may need to handle this distinction.
			* Legacy Excitation Handling: The `NegativeExcitation` boolean in `IDiagnosticResult` exists specifically to handle legacy TDC/TDAS hardware behavior regarding broken sensor/wire warnings. This suggests newer implementations should not rely on sign checks alone for error detection without consulting this flag.
			* Pseudo-Rack Definition: The comment in `IISOHardware` clarifies that "Pseudo racks" are collections of hardware like SLICE slabs. The method `IsPseudoRackModule()` returns true based on hardware type capability, regardless of its current configuration context.