298 lines
14 KiB
Markdown
298 lines
14 KiB
Markdown
---
|
||
source_files:
|
||
- DataPRO/IService/Classes/Diagnostics/OptimizationValues.cs
|
||
- DataPRO/IService/Classes/Diagnostics/DiagnosticActions.cs
|
||
- DataPRO/IService/Classes/Diagnostics/DiagnosticsResultActions.cs
|
||
- DataPRO/IService/Classes/Diagnostics/DiagnosticsResult.cs
|
||
generated_at: "2026-04-16T03:59:21.765469+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "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. |