DP44/enriched-partialglm/Common/DTS.Common.DAS.Concepts/Interfaces.md

---
source_files:
  - Common/DTS.Common.DAS.Concepts/Interfaces/ITriggerable.cs
  - Common/DTS.Common.DAS.Concepts/Interfaces/IDataCollectionEnabled.cs
  - Common/DTS.Common.DAS.Concepts/Interfaces/ICalibratable.cs
  - Common/DTS.Common.DAS.Concepts/Interfaces/ILargeDataAware.cs
  - Common/DTS.Common.DAS.Concepts/Interfaces/IRealtimeable.cs
  - Common/DTS.Common.DAS.Concepts/Interfaces/IGpioEnabled.cs
  - Common/DTS.Common.DAS.Concepts/Interfaces/IDownloadEnabled.cs
  - Common/DTS.Common.DAS.Concepts/Interfaces/IArmable.cs
generated_at: "2026-04-16T11:39:26.463455+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "097989360eebf93b"
---

# Documentation: DTS.Common.DAS.Concepts Interfaces

## 1. Purpose

This module defines a set of interfaces that describe the core capabilities of Data Acquisition System (DAS) hardware devices. It provides an abstraction layer for common operations such as arming, triggering, calibration, real-time data capture, GPIO control, and data download. These interfaces enable polymorphic treatment of different hardware models (TSR, HEADS, NASCAR variants) while exposing consistent behavioral contracts.

---

## 2. Public Interface

### Interfaces

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

| Member | Signature | Description |
|--------|-----------|-------------|
| `Trigger` | `void Trigger()` | Triggers the object to begin data capture or perform its primary action. |

---

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

| Member | Signature | Description |
|--------|-----------|-------------|
| `Arm` | `void Arm()` | Arms the device for data capture. |
| `Disarm` | `void Disarm()` | Disarms the device. |
| `ArmStatus` | `ArmStatus ArmStatus { get; }` | Returns the current arming status. Type `ArmStatus` is not defined in these source files. |
| `ArmMode` | `AvailableArmModes ArmMode { get; }` | Returns the available/configured arm mode. Type `AvailableArmModes` is not defined in these source files. |

---

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

| Member | Signature | Description |
|--------|-----------|-------------|
| `EventList` | `TsrEvent[] EventList { get; }` | Returns a list of `TsrEvent` objects available for download. Type `TsrEvent` is not defined in these source files. |
| `GetEventData` | `double[][] GetEventData(TsrEvent Event, ulong FirstSample, ulong LastSample)` | Retrieves event data for the specified sample range. Returns an array of data arrays per channel. |
| `DataHasBeenDownloaded` | `bool DataHasBeenDownloaded { get; }` | Indicates whether data has been downloaded from this entity. |

---

#### `IDataCollectionEnabled`
**Namespace:** `DTS.Common.DAS.Concepts`
**Inherits:** `IArmable`, `ITriggerable`, `IDownloadEnabled`

| Member | Signature | Description |
|--------|-----------|-------------|
| `AvailableSampleRates` | `double[] AvailableSampleRates { get; }` | Returns the array of supported sample rates. |
| `SampleRate` | `double SampleRate { get; set; }` | Gets or sets the current sample rate. |

---

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

| Member | Signature | Description |
|--------|-----------|-------------|
| `SerialNumber` | `string SerialNumber { get; set; }` | Device serial number for calibration tracking. |
| `Sensitivity` | `double Sensitivity { get; set; }` | Calibration sensitivity value. |
| `BatteryVolts` | `double BatteryVolts { get; set; }` | Battery voltage reading. |
| `VddVolts` | `double VddVolts { get; set; }` | Vdd supply voltage reading. |
| `SignalConditioningVolts` | `double SignalConditioningVolts { get; set; }` | Signal conditioning voltage reading. |

---

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

| Member | Signature | Description |
|--------|-----------|-------------|
| `StartRealtime` | `void StartRealtime(double sampleRate)` | Begins real-time data capture at the specified sample rate. |
| `StopRealtime` | `void StopRealtime()` | Stops real-time data capture. |
| `GetRealtimeSamples` | `RealtimeSample[] GetRealtimeSamples()` | Retrieves accumulated real-time samples. |

---

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

| Member | Signature | Description |
|--------|-----------|-------------|
| `IsDataArraySized` | `bool IsDataArraySized { get; }` | Indicates whether the data set is small enough to safely fit in an array for slice operations (filtering, viewer display, etc.). |

---

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

| Member | Signature | Description |
|--------|-----------|-------------|
| `SetGpio` | `void SetGpio(uint Port, uint Pin, Directions Direction, bool State)` | Configures a GPIO pin with specified port, pin number, direction, and state. |
| `GetGpio` | `bool GetGpio(uint Port, uint Pin)` | Reads the state of a GPIO pin at the specified port and pin. |

---

### Classes

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

| Field | Type | Description |
|-------|------|-------------|
| `DataEU` | `double[]` | Engineering unit data indexed by channel. **Note:** This is a public field, not a property. |
| `SampleNumber` | `ulong` | The sample number identifier. **Note:** This is a public field, not a property. |

---

### Enums

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

| Value | Hex | Description |
|-------|-----|-------------|
| `Output` | `0x00` | GPIO configured as output. |
| `Peripheral` | `0x01` | GPIO configured for peripheral function. |
| `Input` | `0x02` | GPIO configured as input (floating). |
| `InputPulledUp` | `0x03` | GPIO configured as input with pull-up resistor. |
| `InputPulledDown` | `0x04` | GPIO configured as input with pull-down resistor. |

---

## 3. Invariants

- **`IDataCollectionEnabled`** requires implementation of `IArmable`, `ITriggerable`, and `IDownloadEnabled` simultaneously—a data collection device must support all three capabilities.
- **`IGpioEnabled.SetGpio`**: When `Direction` is set to an input mode (`Input`, `InputPulledUp`, `InputPulledDown`), the `State` parameter is effectively a no-op (per source comments).
- **`IDownloadEnabled.GetEventData`**: The sample range is inclusive, specified by `FirstSample` and `LastSample` indices.
- **`RealtimeSample.DataEU`**: Array is indexed by channel number.
- **`ILargeDataAware.IsDataArraySized`**: Must accurately reflect whether data can safely fit in memory for processing operations.

---

## 4. Dependencies

### This module depends on:
- **`System`** namespace (used in `IRealtimeable.cs` and `IDownloadEnabled.cs` for `UInt64` and other base types)
- **`DTS.Common.Common.DAS.Concepts.GPIOPin`** namespace (defines `Directions` enum used by `IGpioEnabled`)

### External types referenced but not defined in these sources:
- `ArmStatus` — referenced by `IArmable.ArmStatus`
- `AvailableArmModes` — referenced by `IArmable.ArmMode`
- `TsrEvent` — referenced by `IDownloadEnabled.EventList` and `GetEventData` parameter

### What depends on this module:
- Cannot be determined from source alone; these are interface definitions intended to be implemented by concrete hardware abstraction classes.

---

## 5. Gotchas

1. **Missing Type Definitions**: The types `ArmStatus`, `AvailableArmModes`, and `TsrEvent` are referenced but not defined in the provided source files. Their definitions must exist elsewhere in the codebase.

2. **Namespace Inconsistency**: The `Directions` enum is defined in `DTS.Common.Common.DAS.Concepts.GPIOPin` (note the double "Common"), while the interfaces are in `DTS.Common.DAS.Concepts`. This appears to be a naming inconsistency.

3. **Public Fields in `RealtimeSample`**: The `DataEU` and `SampleNumber` members are public fields, not properties—unlike the rest of the API which uses properties consistently.

4. **`IGpioEnabled` TODO**: Source contains a TODO comment: *"Well have to bring these in as soon as we figure out where to get that enum from."* suggesting the `Directions` enum location was unsettled at time of writing.

5. **`IDownloadEnabled` Commented Members**: The interface contains commented-out properties (`MaximumStoredEventSizeSeconds`, `DownloadIncrementSamples`, `ChannelDescription`, `TimeOffsetMilliseconds`) with a TODO questioning their universal applicability.

6. **Calibration Interface Design Uncertainty**: Source comments indicate the `ICalibratable` interface design is unresolved: *"The question of a good interface for Calibration is still unanswered... I have a feeling that this is a place where we'll be hooking in model checks."*

7. **Arm State Granularity**: Comments suggest the arm state model may be incomplete: *"We need to think about the arm states a bit more. There have been a couple of cases where having a Disarming state, in addition to Disarmed, has been nice."*

8. **Multi-Rate Data Handling**: Extensive comments in `IArmable.cs` describe complex multi-sample-rate scenarios (e.g., BlastTestTSR with 4 channels at 40ksps and 3 channels at 1ksps) where interpolation is performed at the lower level, potentially creating edge cases for download chunk sizing.