238 lines
9.1 KiB
Markdown
238 lines
9.1 KiB
Markdown
---
|
|
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-16T13:24:49.910550+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 core interfaces that describe the capabilities of Data Acquisition System (DAS) hardware devices. These interfaces model behaviors such as arming, triggering, calibration, real-time data capture, data download, and GPIO manipulation. The design enables polymorphic treatment of different hardware models (TSR, HEADS, NASCAR variants) through capability-based composition rather than inheritance from a monolithic base class.
|
|
|
|
---
|
|
|
|
## 2. Public Interface
|
|
|
|
### `ITriggerable`
|
|
**Namespace:** `DTS.Common.DAS.Concepts`
|
|
|
|
```csharp
|
|
public interface ITriggerable
|
|
{
|
|
void Trigger();
|
|
}
|
|
```
|
|
A minimal interface representing an object that can be triggered. The `Trigger()` method initiates the trigger action on the implementing object.
|
|
|
|
---
|
|
|
|
### `IArmable`
|
|
**Namespace:** `DTS.Common.DAS.Concepts`
|
|
|
|
```csharp
|
|
public interface IArmable
|
|
{
|
|
void Arm();
|
|
void Disarm();
|
|
ArmStatus ArmStatus { get; }
|
|
AvailableArmModes ArmMode { get; }
|
|
}
|
|
```
|
|
Defines the ability to be armed and disarmed. Implementers must provide:
|
|
- `Arm()` — transitions the device to an armed state
|
|
- `Disarm()` — transitions the device to a disarmed state
|
|
- `ArmStatus` (read-only) — current arm status of type `ArmStatus`
|
|
- `ArmMode` (read-only) — available arm modes of type `AvailableArmModes`
|
|
|
|
**Note:** Types `ArmStatus` and `AvailableArmModes` are referenced but not defined in the provided source files.
|
|
|
|
---
|
|
|
|
### `IDownloadEnabled`
|
|
**Namespace:** `DTS.Common.DAS.Concepts`
|
|
|
|
```csharp
|
|
public interface IDownloadEnabled
|
|
{
|
|
TsrEvent[] EventList { get; }
|
|
double[][] GetEventData(TsrEvent Event, ulong FirstSample, ulong LastSample);
|
|
bool DataHasBeenDownloaded { get; }
|
|
}
|
|
```
|
|
Represents an object from which data can be downloaded:
|
|
- `EventList` (read-only) — array of `TsrEvent` objects available for download
|
|
- `GetEventData(TsrEvent Event, ulong FirstSample, ulong LastSample)` — retrieves event data for the specified sample range; returns a jagged array of `double[]` where each inner array corresponds to a channel
|
|
- `DataHasBeenDownloaded` (read-only) — indicates whether data has been downloaded
|
|
|
|
**Note:** Type `TsrEvent` is referenced but not defined in the provided source files.
|
|
|
|
---
|
|
|
|
### `IDataCollectionEnabled`
|
|
**Namespace:** `DTS.Common.DAS.Concepts`
|
|
|
|
```csharp
|
|
public interface IDataCollectionEnabled : IArmable, ITriggerable, IDownloadEnabled
|
|
{
|
|
double[] AvailableSampleRates { get; }
|
|
double SampleRate { get; set; }
|
|
}
|
|
```
|
|
Combines arming, triggering, and download capabilities with data collection-specific properties:
|
|
- `AvailableSampleRates` (read-only) — array of sample rates supported by the device
|
|
- `SampleRate` (read/write) — the currently configured sample rate
|
|
|
|
---
|
|
|
|
### `ICalibratable`
|
|
**Namespace:** `DTS.Common.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. All properties are read/write.
|
|
|
|
---
|
|
|
|
### `IRealtimeable`
|
|
**Namespace:** `DTS.Common.DAS.Concepts`
|
|
|
|
```csharp
|
|
public class RealtimeSample
|
|
{
|
|
public double[] DataEU; // Indexes by channel
|
|
public ulong SampleNumber;
|
|
}
|
|
|
|
public interface IRealtimeable
|
|
{
|
|
void StartRealtime(double sampleRate);
|
|
void StopRealtime();
|
|
RealtimeSample[] GetRealtimeSamples();
|
|
}
|
|
```
|
|
Represents the ability to perform real-time data capture:
|
|
- `StartRealtime(double sampleRate)` — begins real-time capture at the specified rate
|
|
- `StopRealtime()` — stops real-time capture
|
|
- `GetRealtimeSamples()` — retrieves an array of `RealtimeSample` objects captured since the last call
|
|
|
|
`RealtimeSample` is a companion class containing:
|
|
- `DataEU` — array of engineering unit values indexed by channel
|
|
- `SampleNumber` — the sample sequence number (`ulong`)
|
|
|
|
---
|
|
|
|
### `ILargeDataAware`
|
|
**Namespace:** `DTS.Common.DAS.Concepts.DAS.Channel`
|
|
|
|
```csharp
|
|
public interface ILargeDataAware
|
|
{
|
|
bool IsDataArraySized { get; }
|
|
}
|
|
```
|
|
Defines whether a DAS channel's data set is small enough to safely fit into an array within a "slice" application context (e.g., for filtering or viewer display).
|
|
|
|
---
|
|
|
|
### `IGpioEnabled`
|
|
**Namespace:** `DTS.Common.DAS.Concepts`
|
|
|
|
```csharp
|
|
public enum Directions
|
|
{
|
|
Output = 0x00,
|
|
Peripheral = 0x01,
|
|
Input = 0x02,
|
|
InputPulledUp = 0x03,
|
|
InputPulledDown = 0x04
|
|
}
|
|
|
|
public interface IGpioEnabled
|
|
{
|
|
void SetGpio(uint Port, uint Pin, Directions Direction, bool State);
|
|
bool GetGpio(uint Port, uint Pin);
|
|
}
|
|
```
|
|
Represents GPIO functionality:
|
|
- `SetGpio(uint Port, uint Pin, Directions Direction, bool State)` — configures a GPIO pin with the specified direction and state
|
|
- `GetGpio(uint Port, uint Pin)` — retrieves the state of the specified GPIO pin
|
|
|
|
The `Directions` enum is defined in `DTS.Common.Common.DAS.Concepts.GPIOPin` namespace.
|
|
|
|
---
|
|
|
|
## 3. Invariants
|
|
|
|
1. **Interface Composition:** `IDataCollectionEnabled` requires implementation of `IArmable`, `ITriggerable`, and `IDownloadEnabled`. Any class implementing `IDataCollectionEnabled` must provide all members from these three parent interfaces.
|
|
|
|
2. **Sample Rate Validity:** `SampleRate` on `IDataCollectionEnabled` should presumably be one of the values in `AvailableSampleRates`, though this constraint is not explicitly enforced in the interface.
|
|
|
|
3. **Sample Range Ordering:** `GetEventData(TsrEvent Event, ulong FirstSample, ulong LastSample)` implies `FirstSample <= LastSample`, but this is not documented.
|
|
|
|
4. **Realtime State Machine:** `IRealtimeable` implementations should require `StartRealtime()` to be called before `GetRealtimeSamples()` returns valid data, and `StopRealtime()` to halt sample accumulation.
|
|
|
|
5. **GPIO Pin Identification:** GPIO pins are identified by `(Port, Pin)` tuple; valid ranges for these parameters are not specified in the interface.
|
|
|
|
---
|
|
|
|
## 4. Dependencies
|
|
|
|
### External Types Referenced (Not Defined in Source)
|
|
| Type | Used In | Notes |
|
|
|------|---------|-------|
|
|
| `ArmStatus` | `IArmable` | Enum or class representing arm state |
|
|
| `AvailableArmModes` | `IArmable` | Enum or class representing arm mode options |
|
|
| `TsrEvent` | `IDownloadEnabled` | Class representing a downloadable event |
|
|
|
|
### Namespace Dependencies
|
|
- `DTS.Common.Common.DAS.Concepts.GPIOPin` — provides `Directions` enum used by `IGpioEnabled`
|
|
- `System` — referenced in `IRealtimeable` and `IDownloadEnabled`
|
|
|
|
### Interface Inheritance Hierarchy
|
|
```
|
|
ITriggerable
|
|
IArmable
|
|
IDownloadEnabled
|
|
└── IDataCollectionEnabled : IArmable, ITriggerable, IDownloadEnabled
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Gotchas
|
|
|
|
1. **Undefined Types:** The types `ArmStatus`, `AvailableArmModes`, and `TsrEvent` are referenced in interfaces 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 interface using it is in `DTS.Common.DAS.Concepts`. This appears to be a naming quirk.
|
|
|
|
3. **TODO Comments in `IGpioEnabled`:** The 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 GPIO interface may have been incomplete at the time of writing.
|
|
|
|
4. **Commented-Out Members in `IDownloadEnabled`:** Several properties are commented out with a TODO questioning their universal applicability:
|
|
- `MaximumStoredEventSizeSeconds`
|
|
- `DownloadIncrementSamples`
|
|
- `ChannelDescription`
|
|
- `TimeOffsetMilliseconds`
|
|
|
|
5. **Historical Context in `IArmable.cs`:** The file contains extensive email discussion comments regarding TSR model variants (NASCAR, TSRPRO, BlastTestTSR, TSRBasic, HEADSII, NGI) and their channel configurations. This suggests the interfaces were designed to accommodate multiple hardware variants with differing capabilities (e.g., mixed sample rates, varying channel counts and bit depths).
|
|
|
|
6. **RealtimeSample Fields Are Public:** The `RealtimeSample` class exposes `DataEU` and `SampleNumber` as public fields rather than properties, which is inconsistent with typical C# property conventions used elsewhere in these interfaces.
|
|
|
|
7. **Multi-Rate Data Handling:** Historical comments indicate that some systems (e.g., BlastTestTSR) have channels at different sample rates (40 ksps vs 1 ksps). The current interfaces do not explicitly address how multi-rate scenarios are handled; comments suggest interpolation may occur at a lower level. |