DP44/enriched-qwen3-coder-next/Common/DTS.Common.DAS.Concepts.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.DAS.Concepts/AvailableArmModes.cs Common/DTS.Common.DAS.Concepts/ArmStatus.cs Common/DTS.Common.DAS.Concepts/ITriggerable.cs Common/DTS.Common.DAS.Concepts/IDataCollectionEnabled.cs Common/DTS.Common.DAS.Concepts/ILargeDataAware.cs Common/DTS.Common.DAS.Concepts/ICalibratable.cs Common/DTS.Common.DAS.Concepts/IGpioEnabled.cs Common/DTS.Common.DAS.Concepts/IRealtimeable.cs Common/DTS.Common.DAS.Concepts/DataScaler.InvalidExcitationVoltageException.cs Common/DTS.Common.DAS.Concepts/ShuntModeType.cs Common/DTS.Common.DAS.Concepts/TsrEvent.cs Common/DTS.Common.DAS.Concepts/IDownloadEnabled.cs Common/DTS.Common.DAS.Concepts/IArmable.cs Common/DTS.Common.DAS.Concepts/LinearizationFormula.cs	2026-04-16T14:07:33.942936+00:00	zai-org/GLM-5-FP8	1	c415f64680b9e4be

Documentation: DTS.Common.DAS.Concepts

1. Purpose

This module defines the core conceptual interfaces, enumerations, and data structures for a Data Acquisition System (DAS). It establishes the abstract contracts for hardware capabilities such as arming, triggering, calibration, real-time data streaming, GPIO manipulation, and event downloading. The module serves as a shared vocabulary between hardware implementations and higher-level application logic, enabling polymorphic treatment of different DAS devices (e.g., TSR, HEADS, NASCAR hardware mentioned in comments).

2. Public Interface

Enumerations

• AvailableArmModes (Namespace: DTS.Common.DAS.Concepts & DTS.DAS.Concepts)
  • Values: LowPower, CircularBuffer.
• ArmStatus (Namespace: DTS.Common.DAS.Concepts & DTS.DAS.Concepts)
  • Values: Disarming, Disarmed, Arming, Armed, Recording.
• Directions (Namespace: DTS.DAS.Concepts.GPIOPin)
  • Values: Output (0x00), Peripheral (0x01), Input (0x02), InputPulledUp (0x03), InputPulledDown (0x04).
• ShuntModeType (Namespace: DTS.Common.DAS.Concepts.Test.Module.Channel.Sensor)
  • Values: Internal, External, Emulation, None. Decorated with DescriptionAttribute.

Interfaces

• IArmable (Namespace: DTS.DAS.Concepts)
  • void Arm(): Initiates the arming process.
  • void Disarm(): Initiates the disarming process.
  • ArmStatus ArmStatus { get; }: Gets the current status.
  • AvailableArmModes ArmMode { get; }: Gets the current mode.
• ITriggerable (Namespace: DTS.DAS.Concepts)
  • void Trigger(): Triggers the object.
• IDownloadEnabled (Namespace: DTS.DAS.Concepts)
  • TsrEvent[] EventList { get; }: List of available events.
  • double[][] GetEventData(TsrEvent Event, UInt64 FirstSample, UInt64 LastSample): Retrieves data for a specific sample range.
  • bool DataHasBeenDownloaded { get; }: Indicates if data has been downloaded.
• IDataCollectionEnabled (Namespace: DTS.DAS.Concepts)
  • Inherits: IArmable, ITriggerable, IDownloadEnabled.
  • double[] AvailableSampleRates { get; }: Supported sample rates.
  • double SampleRate { get; set; }: Current sample rate.
• ICalibratable (Namespace: DTS.DAS.Concepts)
  • Properties: SerialNumber, Sensitivity, BatteryVolts, VddVolts, SignalConditioningVolts.
• IGpioEnabled (Namespace: DTS.DAS.Concepts)
  • void SetGpio(uint Port, uint Pin, GPIOPin.Directions Direction, bool State): Configures a GPIO pin.
  • bool GetGpio(uint Port, uint Pin): Reads the state of a GPIO pin.
• IRealtimeable (Namespace: DTS.DAS.Concepts)
  • void StartRealtime(double sampleRate): Starts real-time capture.
  • void StopRealtime(): Stops real-time capture.
  • RealtimeSample[] GetRealtimeSamples(): Retrieves buffered samples.
• ILargeDataAware (Namespace: DTS.DAS.Concepts.DAS.Channel)
  • bool IsDataArraySized { get; }: Indicates if data fits safely in an array for the application context.

Classes

• TsrEvent (Namespace: DTS.Common.DAS.Concepts & DTS.DAS.Concepts)
  • Abstract class inheriting from Exceptional and ICloneable.
  • Properties (all protected set): EventId (UInt64, 1-based), TimeStamp (DateTime), SerialNumber, AlternateSerialNumber, DurationSeconds, MaxSampleRate, TemperatureC, PreTriggerSeconds.
  • public abstract object Clone(): Creates a shallow copy.
• RealtimeSample (Namespace: DTS.DAS.Concepts)
  • Fields: double[] DataEU (indexed by channel), UInt64 SampleNumber.
• LinearizationFormula (Namespace: DTS.Common.DAS.Concepts)
  • Manages conversion of raw voltage to Engineering Units (EU).
  • Key Properties: NonLinearStyle (enum), PolynomialCoefficients, PolynomialExponents, PolynomialSensitivity, MMPerV, Slope, Intercept, CalibrationFactor.
  • Key Methods:
    • double GetLinearizedValue(double input, double excitation): Main conversion method.
    • void FromSerializeString(string s): Parses a string configuration.
    • string ToSerializeString(): Serializes configuration.
    • string ToDisplayString(): Human-readable representation.
• DataScaler.InvalidExcitationVoltageException (Namespace: DTS.Common.DAS.Concepts)
  • Nested class inside DataScaler (partial). Standard Exception implementation.

3. Invariants

• Identifiers: TsrEvent.EventId is defined as 1-based.
• Immutability: Properties on TsrEvent are read-only publicly (protected set).
• Input Units: LinearizationFormula.GetLinearizedValue assumes the input argument is in millivolts (mV); it divides by 1000 internally to convert to Volts.
• Data Bounds: In LinearizationFormula.GetLinearizedValue, if NonLinearStyle is not Polynomial and input <= 0, the input is coerced to 0.001 to prevent math errors.
• Polynomial Defaults: LinearizationFormula initializes with 4 coefficients and exponents (0, 1, 2, 3) by default.

4. Dependencies

• Internal Dependencies:
  • DTS.Common.Utilities: Used by TsrEvent (base class Exceptional).
  • DTS.Utilities: Referenced in IDownloadEnabled.cs (though TsrEvent in the same file inherits from Exceptional in DTS.Common.Utilities).
  • DTS.Common.Enums.Sensors: Used by LinearizationFormula for NonLinearStyles and NonLinearSLICEWareStyles.
• System Dependencies:
  • System, System.Collections.Generic, System.Text, System.Globalization, System.ComponentModel.

5. Gotchas

• Namespace Duplication: There is significant duplication of types across two namespaces: DTS.Common.DAS.Concepts and DTS.DAS.Concepts.
  • AvailableArmModes, ArmStatus, and TsrEvent are defined in both namespaces.
  • This may cause compiler ambiguity or maintenance confusion if both namespaces are imported.
• Duplicate Definitions: The enums AvailableArmModes and ArmStatus are defined in their own files and inside IArmable.cs. The class TsrEvent is defined in its own file and inside IDownloadEnabled.cs. The definitions appear identical but this violates DRY (Don't Repeat Yourself).
• Unit Assumptions in Linearization: The property MMPerV is documented in comments as "THIS IS MM/V", but the backing field is named _mmPerMV. The GetLinearizedValue method performs an implicit division by 1000 on the input, requiring callers to know the method expects mV, not V.
• Partial Classes: DataScaler and Test are defined as partial classes here. Their counterparts are located in other files not present in this source set (e.g., DTS.Slice.Control.DataScaler.cs, Test.cs).
• Historical Comments: IArmable.cs contains a large block of commented-out email correspondence discussing specific hardware models (NASCAR, TSRPRO, NGI, HEADSII) and design