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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T02:59:35.943426+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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