DP44/enriched-qwen3-coder-next/DataPRO/IService/Classes/Diagnostics.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/IService/Classes/Diagnostics/OptimizationValues.cs DataPRO/IService/Classes/Diagnostics/DiagnosticActions.cs DataPRO/IService/Classes/Diagnostics/DiagnosticsResultActions.cs DataPRO/IService/Classes/Diagnostics/DiagnosticsResult.cs	2026-04-16T03:59:21.765469+00:00	Qwen/Qwen3-Coder-Next-FP8	1	3fe2b63623721951

Documentation: Diagnostics Module

1. Purpose

This module provides the data structures and utility methods required to configure, execute, and store diagnostic tests for DAS (Data Acquisition System) channels. It defines how diagnostic actions are specified (DiagnosticsActions), what results are collected from those actions (DiagnosticsResult), and how to persist or clear diagnostics data in memory and the database (DiagnosticsResultActions). Its role is to enable pre-recording validation of sensor and channel configuration by comparing measured diagnostic values (e.g., excitation voltage, offset, noise, shunt deflection) against expected hardware specifications, thereby supporting system integrity checks before data acquisition begins.

2. Public Interface

DiagnosticsActions class (IDiagnosticActions implementation)

• int DASChannelNumber { get; set; }
  Identifies the DAS channel (0-indexed globally across the DAS unit) for which these diagnostic instructions apply.

• bool MeasureExcitation { get; set; }
  If true, measure the excitation voltage applied to the sensor.

• bool MeasureOffset { get; set; }
  If true, measure the sensor’s offset from 0 (in mV); can be validated against AnalogInputDASChannel offset limits.

• bool CheckDigitalState { get; set; }
  If true, check the open/closed/high/low state of a digital input channel.

• bool MeasureInternalOffset { get; set; }
  If true, measure internal offset (likely ADC or front-end offset).

• bool RemoveOffset { get; set; }
  If true, instruct firmware to compensate for and remove the measured offset.

• bool MeasureNoise { get; set; }
  If true, measure noise floor as a percentage of full-scale reading.

• bool PerformShuntCheck { get; set; }
  If true, perform an emulated shunt-check test.

• bool SquibFireCheck { get; set; } = false
  If true, run a squib fire check on the channel.

• bool PerformVoltageInsertCheck { get; set; }
  If true, perform a voltage insertion gain check (SLICE Pro-specific).

• bool PerformCalSignalCheck { get; set; }
  If true, perform a calibration signal-check test.

• bool MeasureBridgeResistance { get; set; }
  If true, measure the bridge resistance of the sensor.

• DiagnosticsActions()
  Default constructor initializes all action flags to false and DASChannelNumber to 0.

• bool AllActionsDisabled()
  Returns true if none of the diagnostic action flags are enabled.

• static void SetChannelDiagnosticActions(IDASCommunication unit, IDiagnosticActions[] actions, bool setInDb)
  Assigns the diagnostic action array to unit.ChannelDiagnostics. If setInDb is true and the database is connected, clears existing diagnostic actions for the record and inserts the new ones via Diagnostics.InsertDiagnosticAction.

DiagnosticsResult class (IDiagnosticResult implementation)

• int DASChannelNumber { get; set; }
  The DAS channel number for which this result applies.

• int EventNumber { get; set; }
  The event number associated with this diagnostic result.

• double ScalefactorMilliVoltsPerADC { get; set; } = 1
  Mandatory scale factor to convert raw ADC counts to millivolts. Required for post-download data scaling.

• double ScalefactorEngineeringUnitsPerADC { get; set; } = 1
  Scale factor to convert ADC counts to engineering units.

• double ExpectedExcitationMilliVolts { get; set; }
  Factory-set expected excitation voltage (mandatory).

• short GetExpectedDataZeroLevelADC(ZeroMethodType zeroMethod)
  Returns the expected zero-level ADC value based on the zeroing method:

  • ZeroMethodType.None: returns ZeroMVInADC
  • Otherwise: uses FinalOffsetADC if non-null, else converts MeasuredOffsetMilliVolts to ADC using ScalefactorMilliVoltsPerADC, else returns 0.

• double? MeasuredExcitationMilliVolts { get; set; }
  Measured excitation voltage (may be null if not measured; 0.0 in serialized data may indicate null).

• bool NegativeExcitation { get; set; }
  Flag indicating whether MeasuredExcitationMilliVolts was negative (legacy support for broken-sensor warnings).

• double? MeasuredOffsetMilliVolts { get; set; }
  Measured offset in mV (may be null).

• double? MeasuredInternalOffsetMilliVolts { get; set; }
  Measured internal offset in mV.

• double? MeasuredOffsetEngineeringUnits { get; set; }
  Measured offset in engineering units.

• double? AutoZeroPercentDeviation { get; set; }
  Deviation from zero after auto-zeroing (absolute value enforced on set). Reflects deviation in ADC counts (±5% check).

• short? FinalOffsetADC { get; set; }
  Offset remaining after firmware offset removal (if RemoveOffset was enabled).

• int? RemovedOffsetADC { get; set; }
  Amount of offset removed (in ADC counts).

• int? RemovedInternalOffsetADC { get; set; }
  Amount of internal offset removed.

• double? NoisePercentFullScale { get; set; }
  Noise floor as % of full-scale reading.

• bool ShuntDeflectionFailed { get; set; }
true if shunt-check failed.

• bool CalSignalCheckFailed { get; set; }
true if calibration signal check failed.

• double? MeasuredShuntDeflectionMv { get; set; }
  Measured shunt deflection in mV (if PerformShuntCheck was enabled).

• double? MeasuredCalSignalMv { get; set; }
  Measured calibration signal in mV.

• double? TargetCalSignalMv { get; set; }
  Expected calibration signal in mV.

• double? MeasuredDurationMS { get; set; }
  Measured squib fire duration (ms).

• double? MeasuredDelayMS { get; set; }
  Measured squib fire delay (ms).

• bool? SquibFirePassed { get; set; }
true if squib fire test passed.

• bool? SquibDurationPassed { get; set; }
true if squib duration passed.

• bool? SquibDelayPassed { get; set; }
true if squib delay passed.

• double[] SquibFireCurrentData { get; set; }
  Raw current data from squib fire test.

• double[] SquibFireVoltageData { get; set; }
  Raw voltage data from squib fire test.

• double[] SquibFireTimeAxis { get; set; }
  Time axis (ms) for squib fire test.

• double SquibThreshold { get; set; }
  Squib fire threshold (likely current or voltage).

• double SquibVoltageScaler { get; set; }
  Voltage scaler used in squib test.

• double SquibCurrentScaler { get; set; }
  Current scaler used in squib test.

• double? TargetGain { get; set; }
  Expected gain (e.g., for voltage insertion check).

• double? MeasuredGain { get; set; }
  Measured gain.

• double? QueriedGain { get; set; }
  Gain value queried from firmware/config.

• double? TargetShuntDeflectionMv { get; set; }
  Expected shunt deflection in mV.

• double? BridgeResistance { get; set; }
  Measured bridge resistance in ohms (if MeasureBridgeResistance enabled).

• short ZeroMVInADC { get; set; } = 0
  ADC value corresponding to 0 mV input.

• short WindowAverageADC { get; set; } = short.MinValue
  Average ADC over the configured window. short.MinValue indicates uninitialized/invalid.

• bool DigitalInputActiveState { get; set; }
  Current active state of digital input (true = active/high, false = inactive/low).

DiagnosticsResultActions static class

• static void ClearChannelDiagnosticsResults(IDASCommunication unit, bool bClearDb = true)
  Clears unit.ChannelDiagnosticsResults and unit.ChannelDiagnostics arrays. If bClearDb is true and DB is connected, clears diagnostics from the database.

• static void SetChannelDiagnosticsResults(IDASCommunication unit, IDiagnosticResult[] results, bool setInDb)
  Assigns results to unit.ChannelDiagnosticsResults. If setInDb is true, writes each result to the DB using type-specific methods:

  • InsertDigitalDiagnosticResult for digital channels
  • InsertAnalogDiagnosticResult for analog channels
  • InsertSquibDiagnosticResult for squib channels
    Channel type is determined via unit.DASInfo.MapDASChannelNumber2ModuleArrayIndex and MapDASChannelNumber2ModuleChannelNumber.

• private static void InsertDiagnosticsResultDigital(...)
  Writes digital diagnostic result to DB.

• private static void InsertDiagnosticsResultAnalog(...)
  Writes analog diagnostic result to DB (18 parameters).

• private static void InsertDiagnosticsResultsSquib(...)
  Writes squib diagnostic result to DB (14 parameters). Exceptions are silently swallowed.

OptimizationValues class

• float TransferSpeed { get; set; }
  Holds a single float value representing transfer speed (likely for optimization tuning). No further behavior or usage context provided.

3. Invariants

• DiagnosticsActions.AllActionsDisabled() returns true only when all action flags are false.

  • Includes: MeasureExcitation, MeasureOffset, RemoveOffset, MeasureNoise, PerformShuntCheck, MeasureBridgeResistance, PerformCalSignalCheck, PerformVoltageInsertCheck, MeasureInternalOffset, SquibFireCheck, CheckDigitalState.

• DiagnosticsResult.ScalefactorMilliVoltsPerADC is mandatory for scaling raw ADC data to real-world voltages; no fallback is provided if missing.

• DiagnosticsResult.ZeroMVInADC defaults to 0, and WindowAverageADC defaults to short.MinValue to indicate uninitialized/invalid state.

• DiagnosticsResult.AutoZeroPercentDeviation enforces non-negativity: setter applies Math.Abs().

• DiagnosticsResult.GetExpectedDataZeroLevelADC() uses a priority order:
  ZeroMethodType.None → ZeroMVInADC;
  otherwise → FinalOffsetADC (if non-null) → MeasuredOffsetMilliVolts (converted) → 0.

• DiagnosticsResultActions.SetChannelDiagnosticsResults() determines channel type via mapping and type-checks against AnalogInputDASChannel or OutputSquibChannel. If the channel is neither, no DB insertion occurs (no exception thrown, but no logging either).

• Database writes in SetChannelDiagnosticActions and DiagnosticsResultActions are guarded by DASFactoryDb.DbWrapper.Connected and setInDb/bClearDb flags. Exceptions during DB operations are logged via APILogger.Log(ex) (except squib result insertion, which silently swallows exceptions).

4. Dependencies

Imports / External Types Used

• DTS.Common.Interface.DASFactory
  Provides IDASCommunication, IDiagnosticActions, IDiagnosticResult, AnalogInputDASChannel, OutputSquibChannel.

• DTS.Common.Interface.DASFactory.Diagnostics
  Defines IOptimizationValues, IDiagnosticActions, IDiagnosticResult.

• DTS.Common.Enums.Sensors
  Provides ZeroMethodType enum used in GetExpectedDataZeroLevelADC.

• DTS.Common.Utilities.Logging
  Provides APILogger for exception logging.

• DASFactoryDb.Diagnostics
  Provides Diagnostics class with methods:

  • ClearDiagnosticActionsAllChannels
  • InsertDiagnosticAction
  • ClearExistingDiagnosticsAllChannels
  • InsertDigitalDiagnosticResult
  • InsertAnalogDiagnosticResult
  • InsertSquibDiagnosticResult

• DASFactoryDb.DbWrapper
  Provides Connected property to check DB connectivity.

Inferred Usage

• Consumers: Likely DiagnosticsService (referenced in DiagnosticsResult XML comments) and ConfigureService (for populating AnalogInputDASChannel specs).
• Dependencies on other modules:
  • DiagnosticsService (for calibration/diagnostics execution)
  • ConfigureService (to populate sensor specs like offset limits in AnalogInputDASChannel)
  • DASFactoryDb (for persistence)
  • APILogger (for error logging)

5. Gotchas

• MeasuredExcitationMilliVolts, MeasuredOffsetMilliVolts, and other nullable fields: A value of 0.0 read from event attributes may actually mean null (i.e., not measured). Callers must treat 0.0 as ambiguous and not assume it indicates a valid zero reading.

• WindowAverageADC default value: short.MinValue is used as a sentinel for uninitialized/invalid values. Code must check for this explicitly rather than assuming 0 is valid.

• AutoZeroPercentDeviation setter: Automatically applies Math.Abs(). Setting a negative value will silently flip the sign.

• DiagnosticsResultActions.SetChannelDiagnosticsResults(): If a channel is neither AnalogInputDASChannel nor OutputSquibChannel, no DB insertion occurs and no error is logged. This may silently skip unsupported channel types.

• Squib result insertion: Exceptions during InsertSquibDiagnosticResult are silently swallowed (no logging). This is explicitly noted in source comments as temporary.

• DiagnosticsActions.SetChannelDiagnosticActions(): Clears all existing diagnostic actions for the record before inserting new ones. If called with actions == null, it clears the DB but inserts nothing.

• Channel mapping: Relies on unit.DASInfo.MapDASChannelNumber2ModuleArrayIndex and MapDASChannelNumber2ModuleChannelNumber. Incorrect mapping could lead to DB writes to wrong channels or index-out-of-range errors.

• OptimizationValues: Only contains TransferSpeed. No usage context or integration points are visible in the provided source. Its purpose and consumers are unclear.

• No validation in constructors: DiagnosticsActions and DiagnosticsResult do not validate property values (e.g., negative DASChannelNumber, out-of-range EventNumber). Validation is deferred to downstream logic.

• No thread-safety guarantees: All methods are non-atomic and share mutable state (e.g., unit.ChannelDiagnostics, unit.ChannelDiagnosticsResults). Concurrent access may cause race conditions.

• Legacy flag NegativeExcitation: Introduced to preserve legacy TDC/TDAS behavior for broken-sensor warnings. Its presence suggests historical quirks in excitation reading that may affect interpretation of MeasuredExcitationMilliVolts.

None identified from source alone.