DP44/docs/ai/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-17T15:29:37.643636+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "9bfb99ec27f09c88"
---

# DTS.Common.DAS.Concepts Module Documentation

## 1. Purpose

This module defines core interfaces, enums, and classes that represent fundamental Data Acquisition System (DAS) concepts for DTS hardware. It provides the abstract contracts for device capabilities including arming, triggering, calibration, GPIO control, real-time data capture, event downloading, and sensor linearization. The module serves as the foundational abstraction layer for various TSR (Test System Recorder) and HEADS device implementations, enabling polymorphic treatment of different hardware models while maintaining type-safe contracts.

---

## 2. Public Interface

### Enums

#### `AvailableArmModes`
**Namespace:** `DTS.Common.DAS.Concepts` (also defined in `DTS.DAS.Concepts`)

| Member | Value |
|--------|-------|
| `LowPower` | 0 |
| `CircularBuffer` | 1 |

#### `ArmStatus`
**Namespace:** `DTS.Common.DAS.Concepts` (also defined in `DTS.DAS.Concepts`)

| Member | Value |
|--------|-------|
| `Disarming` | 0 |
| `Disarmed` | 1 |
| `Arming` | 2 |
| `Armed` | 3 |
| `Recording` | 4 |

#### `GPIOPin.Directions`
**Namespace:** `DTS.DAS.Concepts.GPIOPin`

| Member | Value |
|--------|-------|
| `Output` | 0x00 |
| `Peripheral` | 0x01 |
| `Input` | 0x02 |
| `InputPulledUp` | 0x03 |
| `InputPulledDown` | 0x04 |

#### `Test.Module.Channel.Sensor.ShuntModeType`
**Namespace:** `DTS.Common.DAS.Concepts`

| Member | Description |
|--------|-------------|
| `Internal` | "Internal" |
| `External` | "External" |
| `Emulation` | "Emulation" |
| `None` | "None" |

---

### Interfaces

#### `ITriggerable`
**Namespace:** `DTS.DAS.Concepts`

```csharp
public interface ITriggerable
{
    void Trigger();
}
```
Defines a contract for objects that can be triggered.

---

#### `IArmable`
**Namespace:** `DTS.DAS.Concepts`

```csharp
public interface IArmable
{
    void Arm();
    void Disarm();
    ArmStatus ArmStatus { get; }
    AvailableArmModes ArmMode { get; }
}
```
Defines the contract for objects that can be armed and disarmed.

---

#### `IDownloadEnabled`
**Namespace:** `DTS.DAS.Concepts`

```csharp
public interface IDownloadEnabled
{
    TsrEvent[] EventList { get; }
    double[][] GetEventData(TsrEvent Event, UInt64 FirstSample, UInt64 LastSample);
    bool DataHasBeenDownloaded { get; }
}
```
Defines the contract for objects that support downloading event data.

---

#### `IDataCollectionEnabled`
**Namespace:** `DTS.DAS.Concepts`

```csharp
public interface IDataCollectionEnabled : IArmable, ITriggerable, IDownloadEnabled
{
    double[] AvailableSampleRates { get; }
    double SampleRate { get; set; }
}
```
Aggregates `IArmable`, `ITriggerable`, and `IDownloadEnabled` with sample rate properties for rudimentary data collection.

---

#### `ICalibratable`
**Namespace:** `DTS.DAS.Concepts`

```csharp
public interface ICalibratable
{
    string SerialNumber { get; set; }
    double Sensitivity { get; set; }
    double BatteryVolts { get; set; }
    double VddVolts { get; set; }
    double SignalConditioningVolts { get; set; }
}
```
Defines properties required for rudimentary calibration.

---

#### `IGpioEnabled`
**Namespace:** `DTS.DAS.Concepts`

```csharp
public interface IGpioEnabled
{
    void SetGpio(uint Port, uint Pin, GPIOPin.Directions Direction, bool State);
    bool GetGpio(uint Port, uint Pin);
}
```
Defines GPIO control functionality.

---

#### `IRealtimeable`
**Namespace:** `DTS.DAS.Concepts`

```csharp
public interface IRealtimeable
{
    void StartRealtime(double sampleRate);
    void StopRealtime();
    RealtimeSample[] GetRealtimeSamples();
}
```
Defines real-time data capture capability.

---

#### `ILargeDataAware`
**Namespace:** `DTS.DAS.Concepts.DAS.Channel`

```csharp
public interface ILargeDataAware
{
    bool IsDataArraySized { get; }
}
```
Indicates whether a data set is small enough to safely fit into an array for slice applications.

---

### Classes

#### `RealtimeSample`
**Namespace:** `DTS.DAS.Concepts`

```csharp
public class RealtimeSample
{
    public double[] DataEU;      // Indexes by channel
    public UInt64 SampleNumber;
}
```
Represents a real-time data sample with engineering unit data per channel.

---

#### `TsrEvent`
**Namespace:** `DTS.Common.DAS.Concepts` and `DTS.DAS.Concepts` (defined in both)

```csharp
public abstract class TsrEvent : Exceptional, ICloneable
{
    public virtual UInt64 EventId { get; protected set; }
    public virtual DateTime TimeStamp { get; protected set; }
    public virtual string SerialNumber { get; protected set; }
    public virtual string AlternateSerialNumber { get; protected set; }
    public virtual double DurationSeconds { get; protected set; }
    public virtual double MaxSampleRate { get; protected set; }
    public virtual float TemperatureC { get; protected set; }
    public virtual double PreTriggerSeconds { get; protected set; }
    public abstract object Clone();
}
```
Abstract base class representing TSR event data and metadata. Inherits from `Exceptional` (defined externally) and implements `ICloneable`.

---

#### `DataScaler.InvalidExcitationVoltageException`
**Namespace:** `DTS.Common.DAS.Concepts`

```csharp
public partial class DataScaler
{
    public class InvalidExcitationVoltageException : Exception
    {
        public InvalidExcitationVoltageException();
        public InvalidExcitationVoltageException(string msg);
        public InvalidExcitationVoltageException(string msg, Exception innerEx);
        protected InvalidExcitationVoltageException(
            System.Runtime.Serialization.SerializationInfo info,
            System.Runtime.Serialization.StreamingContext context);
    }
}
```
Exception class for invalid excitation voltage conditions. Part of a partial `DataScaler` class.

---

#### `LinearizationFormula`
**Namespace:** `DTS.Common.DAS.Concepts`

```csharp
public class LinearizationFormula
{
    // Properties
    public NonLinearSLICEWareStyles NonLinearSliceWareStyle { get; set; }
    public NonLinearStyles NonLinearStyle { get; set; }
    public double PolynomialSensitivity { get; set; }
    public double LinearizationExponent { get; set; }
    public double MMPerV { get; set; }
    public double MVAt0MM { get; set; }
    public double Slope { get; set; }
    public double Intercept { get; set; }
    public double CalibrationFactor { get; set; }
    public double ZeroPositionIntercept { get; set; }
    public bool UsemVOverVForPolys { get; set; }
    public double[] PolynomialCoefficients { get; set; }
    public double[] PolynomialExponents { get; set; }

    // Methods
    public bool IsValid();
    public void MarkValid(bool bValid);
    public double GetCoefficient(double exponent);
    public void SetCoefficient(double exponent, double coefficient);
    public double GetLinearizedValue(double input, double excitation);
    public string ToSLICEWareSerializeString();
    public string ToSerializeString();
    public void FromSerializeString(string s);
    public void FromSerializeString(string s, CultureInfo culture);
    public void FromTDCSerializeString();
    public string ToDisplayString();
    public string ToDisplayString(string nonlinearFormat);

    // Serialization helpers (partial list)
    public string ToIRTraccDiagnosticZeroString();
    public string ToIRTraccCalFactorString();
    public string ToIRTraccManualString();
    public string ToIRTraccZeroMMmVString();
    public string ToIRTraccAverageOverTimeString();
    public string ToPolynomialString();
    public string ToSLICEWarePolynomialString();
    public void FromIRTraccCalFactorString(string s, CultureInfo culture);
    public void FromIRTraccDiagnosticZeroString(string s, CultureInfo culture);
    public void FromIRTraccManualString(string s, CultureInfo culture);
    public void FromIRTraccZeroMMmVString(string s, CultureInfo culture);
    public void FromIRTraccAverageOverTimeString(string s, CultureInfo culture);
    public void FromPolynomialString(string s, CultureInfo culture);
}
```
Handles sensor linearization with support for multiple `NonLinearStyles` including Polynomial, IRTracc variants, and calibration factors. Supports serialization to/from SLICEWare and internal formats.

---

## 3. Invariants

1. **EventId is 1-based**: The `TsrEvent.EventId` property documentation explicitly states it is a 1-based identifier.

2. **Protected setters on TsrEvent**: All properties on `TsrEvent` have `protected set` accessors, meaning derived classes can modify them but external code cannot.

3. **LinearizationFormula default style**: `NonLinearStyle` defaults to `NonLinearStyles.Polynomial` to avoid locking a specific zero-method (per comment referencing FB 10323).

4. **LinearizationFormula input handling**: When `NonLinearStyle` is not `Polynomial` and input is ≤ 0, the input is treated as 0.001 to handle noise/negative readings for IR-Tracc sensors.

5. **LinearizationFormula coefficient/exponent lists**: Initialized with 4 elements (indices 0-3) by default, with exponents pre-set to [0, 1, 2, 3].

6. **Shallow clone requirement**: `TsrEvent.Clone()` is documented to return a shallow copy.

---

## 4. Dependencies

### External Dependencies (Inferred from imports)

| Dependency | Used By |
|------------|---------|
| `System` | `IRealtimeable`, `TsrEvent`, `IDownloadEnabled`, `LinearizationFormula`, `DataScaler.InvalidExcitationVoltageException` |
| `System.Collections.Generic` | `LinearizationFormula` |
| `System.ComponentModel` | `ShuntModeType` (for `[Description]` attribute) |
| `System.Text` | `LinearizationFormula` |
| `System.Globalization` | `LinearizationFormula` (via inline usage) |
| `System.Runtime.Serialization` | `DataScaler.InvalidExcitationVoltageException` |
| `DTS.Common.Utilities` | `TsrEvent` (inherits from `Exceptional`) |
| `DTS.Utilities` | `IDownloadEnabled` (inherits from `Exceptional`) |
| `DTS.Common.Enums.Sensors` | `LinearizationFormula` (for `NonLinearStyles` and `NonLinearSLICEWareStyles` enums) |

### Consumers

Unknown from source alone. This module defines foundational interfaces and types that would be implemented by concrete device classes and consumed by higher-level application code.

---

## 5. Gotchas

### Duplicate Definitions
- **`AvailableArmModes` enum** is defined in both `DTS.Common.DAS.Concepts` (file: `AvailableArmModes.cs`) and `DTS.DAS.Concepts` (file: `IArmable.cs`).
- **`ArmStatus` enum** is defined in both `DTS.Common.DAS.Concepts` (file: `ArmStatus.cs`) and `DTS.DAS.Concepts` (file: `IArmable.cs`).
- **`TsrEvent` class** is defined in both `DTS.Common.DAS.Concepts` (file: `TsrEvent.cs`) and `DTS.DAS.Concepts` (file: `IDownloadEnabled.cs`).

These duplicates may cause ambiguity or require extern alias configuration if both namespaces are imported.

### Namespace Inconsistency
The module uses multiple root namespaces:
- `DTS.Common.DAS.Concepts`
- `DTS.DAS.Concepts`
- `DTS.DAS.Concepts.DAS.Channel`
- `DTS.DAS.Concepts.GPIOPin`

This suggests an incomplete refactoring or historical naming drift.

### Incomplete GPIO Implementation Note
`IGpioEnabled` contains a TODO comment: *"Well have to bring these in as soon as we figure out where to get that enum from."* The `GPIOPin.Directions` enum is defined in a separate namespace (`DTS.DAS.Concepts.GPIOPin`), which may or may not resolve this.

### Commented-Out Interface Members
`IDownloadEnabled` contains commented-out properties (`MaximumStoredEventSizeSeconds`, `DownloadIncrementSamples`, `ChannelDescription`, `TimeOffsetMilliseconds`) with a TODO questioning their universal applicability.

### Historical Email Comments
`IArmable.cs` contains extensive historical email discussions about device types (NASCAR, TSRPRO, BlastTestTSR, TSRBasic, HEADSII, NGI) and multi-sample-rate handling. This is technical debt that should be removed from production code.

### LinearizationFormula Serialization Format Changes
The polynomial serialization format differs between `ToSLICEWarePolynomialString()` (reverse order) and `ToPolynomialString()` (standard order). Additionally, `IRTraccCalFactor` is explicitly not supported in SLICEWare serialization.

### Partial Class Dependencies
- `DataScaler.InvalidExcitationVoltageException` is a nested class within a partial `DataScaler` class. The main `DataScaler` implementation is not present in these files.
- `ShuntModeType` is nested within `Test.Module.Channel.Sensor`, which are all partial class containers. The main implementations are elsewhere.