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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T13:24:49.910550+00:00	zai-org/GLM-5-FP8	1	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

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

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

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

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

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

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

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

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.