DP44/enriched-qwen3-coder-next/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-16T02:19:24.711512+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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