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

---
source_files:
  - 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
generated_at: "2026-04-16T14:07:33.942936+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "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