DP44/enriched-partialglm/Common/DTS.CommonCore/Interface/Hardware.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T12:11:59.143193+00:00	zai-org/GLM-5-FP8	1	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.