noisedestroyers/DP44
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
noisedestroyers
2026-04-17 14:55:32 -04:00
commit bc3ac1d4c9
18017 changed files with 4371742 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

311
enriched-partialglm/Common/DTS.Common.DAS.Concepts/DAS.md Normal file
View File

@@ -0,0 +1,311 @@
---
source_files:
- Common/DTS.Common.DAS.Concepts/DAS/DAS.Channel.cs
- Common/DTS.Common.DAS.Concepts/DAS/DAS.Channel.IIsoCodeAware.cs
- Common/DTS.Common.DAS.Concepts/DAS/DAS.Channel.ISerialNumberAware.cs
- Common/DTS.Common.DAS.Concepts/DAS/DAS.Channel.IEngineeringUnitAware.cs
- Common/DTS.Common.DAS.Concepts/DAS/DecimationMethod.cs
- Common/DTS.Common.DAS.Concepts/DAS/DAS.Channel.IInversionAware.cs
- Common/DTS.Common.DAS.Concepts/DAS/DTS.DAS.Concepts.IVoltageInsertAware.cs
- Common/DTS.Common.DAS.Concepts/DAS/DAS.Channel.ILevelTriggerable.cs
- Common/DTS.Common.DAS.Concepts/DAS/DAS.Channel.Data.cs
- Common/DTS.Common.DAS.Concepts/DAS/DAS.DAS.Concepts.IShuntAware.cs
- Common/DTS.Common.DAS.Concepts/DAS/DAS.Channel.IDecimatable.cs
- Common/DTS.Common.DAS.Concepts/DAS/DAS.Id.cs
generated_at: "2026-04-16T11:38:29.974640+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "f40aa120b967ad3e"
---
# DAS Concepts Module Documentation
## 1. Purpose
This module defines the core domain abstractions for a Data Acquisition System (DAS). It provides the foundational type hierarchy for representing DAS channels, their data containers, and various optional capabilities (metadata, calibration, triggering, decimation) that can be attached to channels via interfaces. The module serves as the conceptual model layer, establishing contracts and base types that concrete DAS implementations would extend.
---
## 2. Public Interface
### Classes
#### `Channel<DataType>` (Abstract)
**Namespace:** `DTS.DAS.Concepts.DAS`
**File:** `DAS.Channel.cs`
```csharp
public abstract class Channel<DataType> : Exceptional
```
- Abstract generic base class representing a DAS channel.
- Generic type parameter `DataType` defines the data type contained by channels of this DAS.
- Extends `Exceptional` from `DTS.Utilities`.
---
#### `Data<DatumType>` (Abstract)
**Namespace:** `DTS.DAS.Concepts.DAS.Channel`
**File:** `DAS.Channel.Data.cs`
```csharp
public abstract class Data<DatumType> : ExceptionalList<DatumType>
```
- Abstract generic base class representing a list of channel data.
- Extends `ExceptionalList<DatumType>` from `DTS.Utilities`.
- **Constructors:**
- `protected Data()` — Default constructor.
- `protected Data(int capacity)` — Initializes with specified capacity.
- `protected Data(IEnumerable<DatumType> collection)` — Initializes from an existing collection.
---
#### `Id` (Sealed)
**Namespace:** `DTS.Common.DAS.Concepts.DAS`
**File:** `DAS.Id.cs`
```csharp
public sealed class Id : Exceptional, IComparable<Id>, IEquatable<Id>
```
- Represents a DAS identifier, encapsulating a string value.
- **Constructor:** `public Id(string value)`
- **Properties/Methods:**
- `public static implicit operator string(Id id)` — Implicit conversion to string.
- `public static implicit operator Id(string id)` — Implicit conversion from string.
- `public override bool Equals(object obj)` — Equality check; compares strings ordinally case-insensitive.
- `public bool Equals(Id that)` — Typed equality check.
- `public int CompareTo(Id that)` — IComparable implementation.
- `public override string ToString()` — Returns the underlying string value.
- `public override int GetHashCode()` — Returns hash of the string value.
- **Operators:** `==`, `!=`, `<`, `>`, `<=`, `>=` — All use case-insensitive string comparison.
---
### Interfaces
#### `IIsoCodeAware`
**Namespace:** `DTS.DAS.Concepts.DAS.Channel`
**File:** `DAS.Channel.IIsoCodeAware.cs`
```csharp
public interface IIsoCodeAware
{
string IsoCode { get; set; }
}
```
- Defines ISO code awareness with a string property.
---
#### `ISerialNumberAware`
**Namespace:** `DTS.DAS.Concepts.DAS.Channel`
**File:** `DAS.Channel.ISerialNumberAware.cs`
```csharp
public interface ISerialNumberAware
{
string SerialNumber { get; set; }
}
```
- Defines serial number awareness with a string property.
---
#### `IEngineeringUnitAware`
**Namespace:** `DTS.DAS.Concepts.DAS.Channel`
**File:** `DAS.Channel.IEngineeringUnitAware.cs`
```csharp
public interface IEngineeringUnitAware
{
string EngineeringUnits { get; set; }
}
```
- Defines engineering unit awareness with a string property.
---
#### `IInversionAware`
**Namespace:** `DTS.DAS.Concepts.DAS.Channel`
**File:** `DAS.Channel.IInversionAware.cs`
```csharp
public interface IInversionAware
{
bool IsInverted { get; set; }
}
```
- Defines inversion state awareness with a boolean property.
---
#### `ILinearized`
**Namespace:** `DTS.DAS.Concepts.DAS.Channel`
**File:** `DAS.Channel.IInversionAware.cs`
```csharp
public interface ILinearized
{
LinearizationFormula LinearizationFormula { get; set; }
}
```
- Defines linearization formula awareness. (Note: `LinearizationFormula` type is not defined in provided sources.)
---
#### `IVoltageInsertionAware`
**Namespace:** `DTS.DAS.Concepts.DAS.Channel`
**File:** `DTS.DAS.Concepts.IVoltageInsertAware.cs`
```csharp
public interface IVoltageInsertionAware
{
double ExpectedGain { get; set; }
double MeasuredGain { get; set; }
}
```
- Defines shunt-check/voltage insertion awareness with gain properties.
---
#### `ILevelTriggerable`
**Namespace:** `DTS.DAS.Concepts.DAS.Channel`
**File:** `DAS.Channel.ILevelTriggerable.cs`
```csharp
public interface ILevelTriggerable
{
double? TriggerBelowThresholdEu { get; set; } // Set to null to deactivate
double? TriggerAboveThresholdEu { get; set; } // Set to null to deactivate
LevelTriggerTypes LevelTriggerType { get; set; }
}
```
- Defines level trigger capability with nullable threshold properties.
---
#### `IShuntAware`
**Namespace:** `DTS.DAS.Concepts.DAS.Channel`
**File:** `DAS.DAS.Concepts.IShuntAware.cs`
```csharp
public interface IShuntAware
{
double MeasuredShuntDeflectionMv { get; set; }
double TargetShuntDeflectionMv { get; set; }
}
```
- Defines shunt-check awareness with deflection values in millivolts.
---
#### `ICalSignalAware`
**Namespace:** `DTS.DAS.Concepts.DAS.Channel`
**File:** `DAS.DAS.Concepts.IShuntAware.cs`
```csharp
public interface ICalSignalAware
{
double MeasuredCalSignalMv { get; set; }
double TargetCalSignalMv { get; set; }
}
```
- Defines cal-signal awareness with values in millivolts.
---
#### `IDecimatable<out T>`
**Namespace:** `DTS.DAS.Concepts.DAS.Channel`
**File:** `DAS.Channel.IDecimatable.cs`
```csharp
public interface IDecimatable<out T>
{
uint PointsPerPoint { get; set; }
DecimationMethod DecimationType { get; set; }
T[] ToDecimatedArray();
T this[long i] { get; } // Returns decimated value at index
}
```
- Defines decimation capability for DAS channels.
- The indexer returns values from the decimated set based on `PointsPerPoint` and `DecimationType`.
---
### Enumerations
#### `DecimationMethod`
**Namespace:** `DTS.DAS.Concepts.DAS` (in `DecimationMethod.cs`)
**Namespace:** `DTS.DAS.Concepts.DAS.Channel` (in `DAS.Channel.IDecimatable.cs`)
```csharp
public enum DecimationMethod
{
Point, // Use PointsPerPoint-th point as representative
Average, // Use average of PointsPerPoint values
PeakMagnitude // Use peak magnitude of PointsPerPoint values
}
```
- **Note:** This enum is defined in two files with different namespaces. See Gotchas.
---
#### `LevelTriggerTypes` (Flags)
**Namespace:** `DTS.DAS.Concepts.DAS.Channel`
**File:** `DAS.Channel.ILevelTriggerable.cs`
```csharp
[Flags]
public enum LevelTriggerTypes
{
NONE = 0x00,
OutsideWindow = 0x01,
InsideWindow = 0x02,
LessThan = 0x04,
GreaterThan = 0x08
}
```
- Bitwise combinable flags for level trigger types.
---
## 3. Invariants
1. **`Id` immutability:** The `value` field in `Id` is `readonly`; once constructed, the underlying string cannot be changed.
2. **Case-insensitive comparison:** All `Id` equality and comparison operations use `StringComparison.OrdinalIgnoreCase`.
3. **Null handling in `Id`:** The `Id` class handles null values gracefully in `GetHashCode()` (returns 0) and comparison operators.
4. **Abstract instantiation prevention:** Both `Channel<DataType>` and `Data<DatumType>` are abstract and cannot be instantiated directly.
5. **Decimation indexer contract:** Implementing `IDecimatable<T>` implies the indexer returns decimated values, not raw values.
6. **Trigger deactivation:** Setting `TriggerBelowThresholdEu` or `TriggerAboveThresholdEu` to `null` deactivates that trigger threshold.
---
## 4. Dependencies
### This Module Depends On:
| Dependency | Usage |
|------------|-------|
| `DTS.Utilities.Exceptional` | Base class for `Channel<DataType>` and `Id` |
| `DTS.Utilities.ExceptionalList<T>` | Base class for `Data<DatumType>` |
| `DTS.Common.Utilities` | Referenced in `DAS.Id.cs` (specific type usage unclear from source) |
| `System.Collections.Generic.IEnumerable<T>` | Used in `Data<DatumType>` constructor |
| `System.IComparable<T>` | Implemented by `Id` |
| `System.IEquatable<T>` | Implemented by `Id` |
| `System.FlagsAttribute` | Applied to `LevelTriggerTypes` |
### What Depends On This Module:
*Cannot be determined from the provided source files alone.*
---
## 5. Gotchas
1. **Duplicate `DecimationMethod` enum definition:** This enum is defined in two separate files:
- `DecimationMethod.cs` in namespace `DTS.Common.DAS.Concepts.DAS`
- `DAS.Channel.IDecimatable.cs` in namespace `DTS.DAS.Concepts.DAS.Channel`
This may cause ambiguity or require explicit namespace qualification.
2. **Namespace inconsistency across files:**
- `DAS.Channel.cs` uses `DTS.DAS.Concepts.DAS`
- `DAS.Id.cs` and `DecimationMethod.cs` use `DTS.Common.DAS.Concepts.DAS`
- Interface files use `DTS.DAS.Concepts.DAS.Channel`
This suggests possible refactoring history or assembly boundary issues.
3. **`ILinearized` placement:** The `ILinearized` interface is defined in `DAS.Channel.IInversionAware.cs` rather than its own file, breaking the one-type-per-file pattern used elsewhere. The referenced `LinearizationFormula` type is not defined in any provided source.
4. **Developer comments questioning design:** The `Id` class contains comments: *"DTM - why does this class exist? it's only encapsulating a string"* and *"why does this class even exist?"* — indicating possible tech debt or design uncertainty.
5. **XML comment mismatch in `IVoltageInsertionAware`:** The interface summary mentions "shunt-check awareness" but the properties are named `ExpectedGain` and `MeasuredGain`, which may be confusing.
6. **File naming inconsistency:** `DTS.DAS.Concepts.IVoltageInsertAware.cs` uses a different naming pattern than other interface files (missing the `DAS.Channel.` prefix and has a typo: "Insert" vs "Insertion" in the interface name).

109
enriched-partialglm/Common/DTS.Common.DAS.Concepts/DAS/Channel.md Normal file
View File

@@ -0,0 +1,109 @@
---
source_files:
- Common/DTS.Common.DAS.Concepts/DAS/Channel/LevelTriggerTypes.cs
- Common/DTS.Common.DAS.Concepts/DAS/Channel/Channel.cs
- Common/DTS.Common.DAS.Concepts/DAS/Channel/TimestampPartTypes.cs
- Common/DTS.Common.DAS.Concepts/DAS/Channel/Data.cs
generated_at: "2026-04-16T11:40:17.653590+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "0f3b00d01b342d9f"
---
# Documentation: DTS.Common.DAS.Concepts.DAS.Channel
## 1. Purpose
This module provides core domain abstractions for a Data Acquisition System (DAS). It defines the foundational types for representing DAS channels, their data payloads, and associated metadata enums for trigger conditions and timestamp parsing. The module serves as the conceptual layer for the "Slice control app's internal abstract representation" of DAS hardware channels, enabling type-safe channel definitions via generics and supporting bitwise flag operations for trigger and timestamp configurations.
---
## 2. Public Interface
### `Channel<TDataType>` (abstract class)
**Namespace:** `DTS.Common.DAS.Concepts.DAS`
**Signature:** `public abstract class Channel<TDataType> : Exceptional`
Abstract base class representing a DAS channel. Generic parameter `TDataType` defines the data type contained by channels of this DAS. Inherits from `Exceptional` (from `DTS.Common.Utilities`). No public members are defined in this source file.
---
### `Data<TDatumType>` (abstract class)
**Namespace:** `DTS.Common.DAS.Concepts.DAS.Channel`
**Signature:** `public abstract class Data<TDatumType> : ExceptionalList<TDatumType>`
Abstract base class representing a list of channel data. Inherits from `ExceptionalList<TDatumType>` (from `DTS.Common.Utilities`).
**Constructors:**
| Signature | Description |
|-----------|-------------|
| `protected Data()` | Default constructor. |
| `protected Data(int capacity)` | Initializes with specified initial capacity. |
| `protected Data(IEnumerable<TDatumType> collection)` | Initializes with elements copied from the provided collection. |
---
### `LevelTriggerTypes` (flags enum)
**Namespace:** `DTS.Common.DAS.Concepts.DAS.Channel`
**Signature:** `[Flags] public enum LevelTriggerTypes`
Bitwise flags enum defining trigger conditions for level monitoring.
| Member | Value | Hex |
|--------|-------|-----|
| `NONE` | 0 | `0x00` |
| `OutsideWindow` | 1 | `0x01` |
| `InsideWindow` | 2 | `0x02` |
| `LessThan` | 4 | `0x04` |
| `GreaterThan` | 8 | `0x08` |
---
### `TimestampPartTypes` (flags enum)
**Namespace:** `DTS.Common.DAS.Concepts.DAS.Channel`
**Signature:** `[Flags] [TypeConverter(typeof(EnumDescriptionTypeConverter))] public enum TimestampPartTypes`
Bitwise flags enum defining components of a timestamp structure. Decorated with `EnumDescriptionTypeConverter` for UI/data-binding scenarios.
| Member | Value | Description Attribute |
|--------|-------|----------------------|
| `Marker` | `1 << 0` (1) | "Marker" |
| `Seconds_High` | `1 << 1` (2) | "Seconds" |
| `Seconds_Low` | `1 << 2` (4) | "Seconds" |
| `Nanoseconds_High` | `1 << 3` (8) | "Nanoseconds" |
| `Nanoseconds_Low` | `1 << 4` (16) | "Nanoseconds" |
| `Reserved` | `1 << 5` (32) | "Reserved" |
---
## 3. Invariants
- **`LevelTriggerTypes`** is a flags enum; values are designed to be combined via bitwise OR operations. The `NONE` member has value `0x00` and represents the absence of any trigger condition.
- **`TimestampPartTypes`** is a flags enum using bit-shift notation (`1 << n`); each value occupies a distinct bit position enabling arbitrary combinations.
- **`Channel<TDataType>`** and **`Data<TDatumType>`** are both abstract classes; they cannot be instantiated directly and must be subclassed.
- **`Data<TDatumType>`** constructors are `protected`, restricting instantiation to derived classes.
- The `OutsideWindow` and `InsideWindow` flags in `LevelTriggerTypes` are mutually exclusive conceptually (values `0x01` and `0x02`), but this is not enforced at the type level.
- Similarly, `LessThan` and `GreaterThan` in `LevelTriggerTypes` are conceptually mutually exclusive but can technically be combined.
---
## 4. Dependencies
### This module depends on:
- **`DTS.Common.Utilities`** — Provides base classes `Exceptional` and `ExceptionalList<T>` used by `Channel<TDataType>` and `Data<TDatumType>` respectively.
- **`DTS.Common.Converters`** — Provides `EnumDescriptionTypeConverter` used by `TimestampPartTypes`.
- **`System`** — For `FlagsAttribute`.
- **`System.Collections.Generic`** — For `IEnumerable<T>` used in `Data<TDatumType>` constructor.
- **`System.ComponentModel`** — For `TypeConverterAttribute` used by `TimestampPartTypes`.
### What depends on this module:
- Unknown from source alone. The abstract nature of `Channel<TDataType>` and `Data<TDatumType>` indicates they are intended to be subclassed by other modules in the DAS system.
---
## 5. Gotchas
- **`TimestampPartTypes` has duplicate Description attributes:** Both `Seconds_High` and `Seconds_Low` have the description "Seconds", and both `Nanoseconds_High` and `Nanoseconds_Low` have the description "Nanoseconds". When displayed via `EnumDescriptionTypeConverter`, these will appear identically, potentially causing UI confusion.
- **`LevelTriggerTypes.NONE` vs. no value set:** The `NONE` member is explicitly defined as `0x00`. Code checking for "no triggers" should compare against `NONE` or `0` consistently.
- **Abstract classes with no visible members:** Both `Channel<TDataType>` and `Data<TDatumType>` appear to be empty shells in this source, suggesting their behavior is defined entirely in derived classes or partial definitions not shown here.
- **Bitwise flag combinations:** The flags design allows semantically invalid combinations (e.g., `OutsideWindow | InsideWindow` or `LessThan | GreaterThan`). Validation logic, if any, is not present in these source files.

184
enriched-partialglm/Common/DTS.Common.DAS.Concepts/Interfaces.md Normal file
View File

@@ -0,0 +1,184 @@
---
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.

174
enriched-partialglm/Common/DTS.Common.DAS.Concepts/Interfaces/DAS/Channel.md Normal file
View File

@@ -0,0 +1,174 @@
---
source_files:
- Common/DTS.Common.DAS.Concepts/Interfaces/DAS/Channel/ITimestampAware.cs
- Common/DTS.Common.DAS.Concepts/Interfaces/DAS/Channel/ILinearized.cs
- Common/DTS.Common.DAS.Concepts/Interfaces/DAS/Channel/IIsoCodeAware.cs
- Common/DTS.Common.DAS.Concepts/Interfaces/DAS/Channel/ISerialNumberAware.cs
- Common/DTS.Common.DAS.Concepts/Interfaces/DAS/Channel/IInversionAware.cs
- Common/DTS.Common.DAS.Concepts/Interfaces/DAS/Channel/IEngineeringUnitAware.cs
- Common/DTS.Common.DAS.Concepts/Interfaces/DAS/Channel/ICalSignalAware.cs
- Common/DTS.Common.DAS.Concepts/Interfaces/DAS/Channel/IVoltageInsertAware.cs
- Common/DTS.Common.DAS.Concepts/Interfaces/DAS/Channel/IShuntAware.cs
- Common/DTS.Common.DAS.Concepts/Interfaces/DAS/Channel/ILevelTriggerable.cs
- Common/DTS.Common.DAS.Concepts/Interfaces/DAS/Channel/IDecimatable.cs
generated_at: "2026-04-16T11:40:36.287986+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "b4d2ceb184c9ded4"
---
# Documentation: DAS Channel Concept Interfaces
## 1. Purpose
This module defines a set of granular interfaces representing behavioral "concepts" for Data Acquisition System (DAS) channels within the `DTS.Common.DAS.Concepts.DAS.Channel` namespace. These interfaces follow a mixin-style composition pattern, allowing channel implementations to adopt specific capabilities—such as timestamp handling, linearization, calibration awareness, and decimation—by implementing the relevant interfaces. This design enables flexible channel configuration without requiring deep inheritance hierarchies.
---
## 2. Public Interface
### `ITimestampAware`
Defines timestamp configuration capability for a channel.
| Member | Type | Description |
|--------|------|-------------|
| `TimestampPartType` | `TimestampPartTypes` (get/set) | Gets or sets the timestamp part type configuration. |
---
### `ILinearized`
Defines linearization capability for sensor data.
| Member | Type | Description |
|--------|------|-------------|
| `LinearizationFormula` | `DTS.Common.Classes.Sensors.LinearizationFormula` (get/set) | Gets or sets the linearization formula to be applied. |
---
### `IIsoCodeAware`
Defines ISO code awareness for an object.
| Member | Type | Description |
|--------|------|-------------|
| `IsoCode` | `string` (get/set) | Gets or sets the ISO code identifier. |
---
### `ISerialNumberAware`
Defines serial number awareness for an object.
| Member | Type | Description |
|--------|------|-------------|
| `SerialNumber` | `string` (get/set) | Gets or sets the serial number identifier. |
---
### `IInversionAware`
Defines inversion state awareness for a channel.
| Member | Type | Description |
|--------|------|-------------|
| `IsInverted` | `bool` (get/set) | Gets or sets the inversion state. |
---
### `IEngineeringUnitAware`
Defines engineering unit awareness for a channel.
| Member | Type | Description |
|--------|------|-------------|
| `EngineeringUnits` | `string` (get/set) | Gets or sets the engineering unit description. |
---
### `ICalSignalAware`
Defines calibration signal awareness for shunt calibration operations.
| Member | Type | Description |
|--------|------|-------------|
| `MeasuredCalSignalMv` | `double` (get/set) | Gets or sets the measured shunt deflection value in millivolts. |
| `TargetCalSignalMv` | `double` (get/set) | Gets or sets the target shunt deflection value in millivolts. |
---
### `IVoltageInsertionAware`
Defines voltage insertion/gain awareness for calibration operations.
| Member | Type | Description |
|--------|------|-------------|
| `ExpectedGain` | `double` (get/set) | Gets or sets the expected gain value. |
| `MeasuredGain` | `double` (get/set) | Gets or sets the measured gain value. |
---
### `IShuntAware`
Defines shunt-check awareness for calibration verification.
| Member | Type | Description |
|--------|------|-------------|
| `MeasuredShuntDeflectionMv` | `double` (get/set) | Gets or sets the measured shunt deflection value in millivolts. |
| `TargetShuntDeflectionMv` | `double` (get/set) | Gets or sets the target shunt deflection value in millivolts. |
---
### `ILevelTriggerable`
Defines level trigger capability for a channel.
| Member | Type | Description |
|--------|------|-------------|
| `SampleAverageADC` | `double?` (get/set) | Cached ADC value for use when calculating already level-triggered state (created for Flash Clear feature). |
| `TriggerBelowThresholdEu` | `double?` (get/set) | Gets or sets the "trigger below" threshold in engineering units. Set to `null` to deactivate. |
| `TriggerAboveThresholdEu` | `double?` (get/set) | Gets or sets the "trigger above" threshold in engineering units. Set to `null` to deactivate. |
| `LevelTriggerType` | `LevelTriggerTypes` (get/set) | Gets or sets the level trigger type configuration. |
---
### `IDecimatable<T>`
Defines decimation capability for channel data. Generic interface with covariant type parameter `T`.
| Member | Type | Description |
|--------|------|-------------|
| `PointsPerPoint` | `uint` (get/set) | Gets or sets the number of points to be compressed into a single index point. |
| `DecimationType` | `DecimationMethod` (get/set) | Gets or sets the decimation method to be applied. |
| `ToDecimatedArray()` | `T[]` | Generates a decimated array using the configured `DecimationMethod`. |
| `this[long i]` | `T` (get-only indexer) | Gets the value at the specified post-decimation index. |
---
## 3. Invariants
- **Nullable Thresholds**: For `ILevelTriggerable`, setting `TriggerBelowThresholdEu` or `TriggerAboveThresholdEu` to `null` explicitly deactivates that trigger threshold. Implementations must treat `null` as "inactive" rather than "uninitialized."
- **Indexer Behavior**: For `IDecimatable<T>`, the indexer `this[long i]` must return values from the **decimated** dataset, not the raw data. The index `i` refers to the post-decimation index.
- **Covariance**: `IDecimatable<out T>` uses covariant generic parameter, meaning `IDecimatable<DerivedType>` can be assigned to `IDecimatable<BaseType>` if `DerivedType` inherits from `BaseType`.
- **Decimation Configuration**: `PointsPerPoint` is a `uint`, implying it must be at least 1. Behavior when set to 0 is undefined from the source alone.
---
## 4. Dependencies
### External Types Referenced (not defined in provided source):
- `DTS.Common.Classes.Sensors.LinearizationFormula` — Used by `ILinearized`
- `TimestampPartTypes` — Used by `ITimestampAware`
- `DecimationMethod` — Used by `IDecimatable<T>`
- `LevelTriggerTypes` — Used by `ILevelTriggerable`
### Namespace:
All interfaces reside in `DTS.Common.DAS.Concepts.DAS.Channel`.
### Consumers:
Unknown from source alone. These are interface definitions intended to be implemented by concrete channel classes elsewhere in the codebase.
---
## 5. Gotchas
1. **Historical Comment in `ILevelTriggerable`**: The `SampleAverageADC` property includes a comment referencing "14042 Flash Clear turns off excitation for s6." This suggests the property was added for a specific workaround or feature related to hardware excitation control, and may have specialized usage not obvious from the interface alone.
2. **Indexer Semantics in `IDecimatable<T>`**: The indexer returns post-decimation values. Developers might incorrectly assume it indexes raw data. The remarks explicitly call this out, but it remains a potential source of confusion.
3. **Naming Inconsistency in `IVoltageInsertionAware`**: The filename is `IVoltageInsertAware.cs` (note: "Insert" without "ion"), but the XML summary refers to "shunt-check awareness" (copied from `IShuntAware`), while the interface name and properties relate to gain values. The summary documentation appears to be copy-paste residue and does not accurately describe the interface's purpose.
4. **Missing XML Comments**: `ITimestampAware` and `ILinearized` lack XML documentation comments present on other interfaces in this set.

42
enriched-partialglm/Common/DTS.Common.DAS.Concepts/Properties.md Normal file
View File

@@ -0,0 +1,42 @@
---
source_files:
- Common/DTS.Common.DAS.Concepts/Properties/AssemblyInfo.cs
generated_at: "2026-04-16T11:38:34.097314+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "b609c89cbf8012d6"
---
# Documentation: DTS.Common.DAS.Concepts Assembly Metadata
## 1. Purpose
This file provides assembly-level metadata configuration for the `DTS.DAS.Concepts` library. It exists to embed version information, copyright details, and COM visibility settings into the compiled assembly during the build process. It does not contain executable application logic.
## 2. Public Interface
This file does not expose any public classes, methods, or functions. It applies the following assembly-level attributes:
* **`AssemblyTitle`**: Set to `"DTS.DAS.Concepts"`.
* **`AssemblyDescription`**: Empty.
* **`AssemblyConfiguration`**: Empty.
* **`AssemblyCompany`**: Set to `"DTS"`.
* **`AssemblyProduct`**: Set to `"DTS.DAS.Concepts"`.
* **`AssemblyCopyright`**: Set to `"Copyright © DTS 2008"`.
* **`AssemblyTrademark`**: Empty.
* **`AssemblyCulture`**: Empty.
* **`ComVisible`**: Set to `false`.
* **`Guid`**: Set to `"9b6f7402-27d3-4cc9-9ff3-3cfe16e0b429"`.
* **`AssemblyVersion`**: Set to `"1.06.0081"`.
* **`AssemblyFileVersion`**: Set to `"1.06.0081"`.
## 3. Invariants
* **COM Visibility**: The assembly is explicitly marked with `ComVisible(false)`, meaning types within this assembly are not visible to COM components by default.
* **Versioning**: Both the assembly version and file version are pinned to the specific build string `"1.06.0081"`. Automatic versioning (e.g., using wildcards) is not utilized for the revision or build numbers.
## 4. Dependencies
* **Internal Dependencies**: This file depends on `System.Reflection` and `System.Runtime.InteropServices` namespaces to define the attributes.
* **External Dependencies**: None identified from this source alone. As an assembly info file, it is a leaf node in the dependency graph; other projects may depend on the compiled `DTS.DAS.Concepts` assembly, but this specific file does not depend on other internal modules.
## 5. Gotchas
* **Naming Discrepancy**: The `AssemblyTitle` is defined as `"DTS.DAS.Concepts"`, but the file path indicates the project folder is named `DTS.Common.DAS.Concepts`. This may cause confusion when referencing the assembly by name versus the project or namespace structure.
* **Manual Versioning**: The `AssemblyVersion` and `AssemblyFileVersion` are hardcoded strings (`"1.06.0081"`). Developers must manually update these values for new releases; they will not auto-increment.
* **Legacy Format**: This uses the older `AssemblyInfo.cs` mechanism for defining metadata. In newer SDK-style projects, this is often implicit or generated automatically, which could lead to conflicts if the project style is upgraded without removing this file.

159
enriched-partialglm/Common/DTS.Common.DAS.Concepts/Test.md Normal file
View File

@@ -0,0 +1,159 @@
---
source_files:
- Common/DTS.Common.DAS.Concepts/Test/Test.Module.cs
- Common/DTS.Common.DAS.Concepts/Test/Test.Module.Channel.cs
- Common/DTS.Common.DAS.Concepts/Test/Test.Module.Channel.Sensor.cs
- Common/DTS.Common.DAS.Concepts/Test/Test.Module.Channel.Sensor.Bridge.cs
- Common/DTS.Common.DAS.Concepts/Test/Test.Module.Channel.Sensor.SensorUnits.cs
- Common/DTS.Common.DAS.Concepts/Test/Test.Module.Channel.Sensor.ZeroMethod.cs
- Common/DTS.Common.DAS.Concepts/Test/Test.Module.RecordingMode.cs
- Common/DTS.Common.DAS.Concepts/Test/Test.Module.Channel.Sensor.ExcitationVoltage.cs
generated_at: "2026-04-16T11:38:00.583082+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "f6582d95b5debe26"
---
# Documentation: DTS.DAS.Concepts.Test Module Hierarchy
## 1. Purpose
This module provides a hierarchical container structure for Data Acquisition System (DAS) test-related concepts, specifically defining configuration enums and types for hardware modules, channels, and sensors. It serves as a static type definitions library for sensor configurations (bridge types, coupling modes, excitation voltages, sensitivity units, zero methods) and recording modes. The architecture uses nested partial classes (`Test.Module.Channel.Sensor`) as organizational containers—none of which are instantiable—to group related enums and their associated helper methods within the `DTS.DAS.Concepts` namespace.
---
## 2. Public Interface
### Container Classes (Non-instantiable)
| Class | Location | Description |
|-------|----------|-------------|
| `Test` | `DTS.DAS.Concepts` | Outer partial class container |
| `Test.Module` | `DTS.DAS.Concepts` | Container for DTS generic module concepts; private constructor |
| `Test.Module.Channel` | `DTS.DAS.Concepts` | Container for DTS generic channel concepts; private constructor |
| `Test.Module.Channel.Sensor` | `DTS.DAS.Concepts` | Container for DTS generic sensor concepts; private constructor |
### Enums
#### `Test.Module.Channel.Sensor.CouplingModes`
IEPE coupling modes.
- `AC` — Description: "AC"
- `DC` — Description: "AC/DC"
#### `Test.Module.Channel.Sensor.BridgeType`
Sensor bridge configuration types. Values are bitwise flags.
- `IEPE` = `1 << 0` (1) — Sensor uses IEPE setup
- `QuarterBridge` = `1 << 1` (2) — Quarter bridge setup
- `HalfBridge` = `1 << 2` (4) — Half bridge setup
- `FullBridge` = `1 << 3` (8) — Full bridge setup
- `DigitalInput` = `1 << 4` (16)
- `SQUIB` = `1 << 5` (32)
- `TOMDigital` = `1 << 6` (64)
#### `Test.Module.Channel.Sensor.SensUnits`
Sensitivity unit types.
- `NONE` = 0 — No sensitivity units (Polynomial Sensor)
- `mV` = 1 — Sensitivity in mV with output at Capacity EU
- `mVperV` = 2 — Excitation proportional sensitivity in mV/V at Capacity EU
- `mVperVperEU` = 3 — Excitation proportional sensitivity in mV/V/EU
- `mVperEU` = 4 — Sensitivity in mV/EU
#### `Test.Module.Channel.Sensor.ZeroMethodType`
Zero calculation methods. **Explicit values are critical for legacy compatibility.**
- `AverageOverTime` = 0 — Calculate electrical zero using average over time
- `UsePreEventDiagnosticsZero` = 1 — Calculate zero using time in pre-event
- `None` = 2 — Calculate zero using injected value (Absolute Zero)
#### `Test.Module.Channel.Sensor.OriginalZeroMethodType`
Legacy version of zero method types (for compatibility, e.g., importing GM ISF).
- `AverageOverTime` — (implicit 0)
- `UsePreCalZero` — (implicit 1)
- `None` — (implicit 2)
#### `Test.Module.RecordingMode`
Recording mode options for modules.
- `InvalidArmMode` = 0 — Invalid mode
- `CircularBuffer` = 1 — Circular buffer mode (constant recording, trigger)
- `RecorderMode` = 2 — Recorder mode (start, trigger)
- `AutoCircularBufferMode` = 4 — Circular buffer with auto-rearm
- `AutoRecorderMode` = 5 — Recorder mode with auto-rearm
- `ImmediateMode` = `0x06`
- `HighPowerRecorderMode` = `0x07`
- `LowPowerRecorderMode` = `0x08`
- `ContinuousRecorderMode` = `0x09`
- `HybridRecorderMode` = `0x0A`
- `MultiHybridRecorderMode` = `0x0B`
#### `Test.Module.Channel.Sensor.ExcitationVoltageOption`
Excitation voltage options with associated magnitude attributes.
- `Undefined` = 1 — `[VoltageMagnitude(0.0)]`
- `Volt2` = 2 — `[VoltageMagnitude(2.0)]`
- `Volt2_5` = 4 — `[VoltageMagnitude(2.5)]`
- `Volt3` = 8 — `[VoltageMagnitude(3.0)]`
- `Volt5` = 16 — `[VoltageMagnitude(5.0)]`
- `Volt10` = 32 — `[VoltageMagnitude(10.0)]`
- `Volt1` = 64 — `[VoltageMagnitude(1.0)]`
### Static Methods
#### `Test.Module.GetRecordingModeFromString(string recordingMode) → RecordingMode`
Converts a string representation to its corresponding `RecordingMode` enum value. Throws `Exception` if parsing fails or input is invalid.
#### `Test.Module.Channel.Sensor.GetExcitationVoltageMagnitudeFromEnum(ExcitationVoltageOption target) → double`
Extracts the numeric voltage magnitude from an `ExcitationVoltageOption` enum value by decoding the `VoltageMagnitudeAttribute`. Throws `Exception` on failure.
#### `Test.Module.Channel.Sensor.GetExcitationVoltageEnumFromMagnitude(double magnitude) → ExcitationVoltageOption`
Converts a voltage magnitude to the corresponding `ExcitationVoltageOption` enum. Throws `NotSupportedException` if no matching enum exists.
### Nested Types
#### `Test.Module.Channel.Sensor.VoltageMagnitudeAttribute`
Custom attribute for associating a numeric voltage magnitude with enum fields.
- **Property**: `Value` (double) — Returns the voltage magnitude.
- **Constructor**: `VoltageMagnitudeAttribute(double value)`
#### `Test.Module.Channel.Sensor.VoltageMagnitudeAttributeCoder`
Inherits from `AttributeCoder<ExcitationVoltageOption, VoltageMagnitudeAttribute, double>`. Used to encode/decode voltage magnitudes to/from `ExcitationVoltageOption` enum values.
- **Constructor**: `VoltageMagnitudeAttributeCoder()` — Initializes with extractor `attribute => attribute.Value`.
---
## 3. Invariants
1. **Non-instantiability**: `Test`, `Test.Module`, `Test.Module.Channel`, and `Test.Module.Channel.Sensor` are container classes with private constructors and cannot be instantiated.
2. **BridgeType bitwise flags**: `BridgeType` enum values are designed as bitwise flags (powers of 2), allowing combination via bitwise OR operations.
3. **ExcitationVoltageOption enum values are NOT bitwise flags**: Despite using powers of 2, these values represent mutually exclusive voltage options; the numeric values appear to be legacy bit positions rather than combinable flags.
4. **ZeroMethodType value stability**: The explicit integer values (0, 1, 2) for `ZeroMethodType` must remain unchanged for legacy compatibility with GM ISF imports.
5. **RecordingMode value gaps**: `RecordingMode` enum has non-contiguous values (e.g., 3 is missing between 2 and 4); code should not assume sequential ordering.
---
## 4. Dependencies
### This module depends on:
- `System` — For `Exception`, `NotSupportedException`, `Attribute` base class, `Enum.Parse`
- `System.ComponentModel` — For `DescriptionAttribute` used on enum members
- `DTS.Utilities` — For `AttributeCoder<TEnum, TAttribute, TValue>` base class (used by `VoltageMagnitudeAttributeCoder`)
### What depends on this module:
- **Unclear from source alone** — The source files contain no references to external consumers. The comment referencing "GM ISF" suggests integration with General Motors Import/Export functionality, but this is not visible in the provided sources.
---
## 5. Gotchas
1. **Legacy ZeroMethodType enum values are critical**: The comment in `Test.Module.Channel.Sensor.ZeroMethod.cs` explicitly warns: *"Lots of legacy compatibility (e.g. importing GM ISF) depends on the order/value of this enum."* Modifying these values will break backward compatibility.
2. **Duplicate zero method enums exist**: Both `ZeroMethodType` and `OriginalZeroMethodType` exist with slightly different member names (`UsePreEventDiagnosticsZero` vs `UsePreCalZero`). The relationship between them and which to use for new code is unclear from source alone.
3. **ExcitationVoltageOption enum values are non-sequential and start at 1**: The values (1, 2, 4, 8, 16, 32, 64) appear to be legacy bit positions but are not combinable flags. Code should not cast arbitrary integers to this enum.
4. **RecordingMode documentation gaps**: Several enum members (`ImmediateMode`, `HighPowerRecorderMode`, `LowPowerRecorderMode`, `ContinuousRecorderMode`, `HybridRecorderMode`, `MultiHybridRecorderMode`) have XML comments containing only `"???"`, indicating incomplete documentation.
5. **File header comment mismatch**: `Test.Module.Channel.Sensor.SensorUnits.cs` has a file header comment referencing `"Test.Module.Channel.Sensor.ExcitationVoltage.cs"` — appears to be a copy-paste error.
6. **Sensor class visibility inconsistency**: In `Test.Module.Channel.Sensor.cs`, the `Sensor` class is declared as `sealed partial class Sensor` (no explicit accessibility, defaulting to `private`), whereas in `Test.Module.Channel.Sensor.Bridge.cs` it is `public partial class Sensor`. This may cause compilation issues or indicate partial class visibility conflicts.

278
enriched-partialglm/Common/DTS.Common.DAS.Concepts/Test/Module.md Normal file
View File

@@ -0,0 +1,278 @@
---
source_files:
- Common/DTS.Common.DAS.Concepts/Test/Module/RecordingMode.cs
- Common/DTS.Common.DAS.Concepts/Test/Module/TiltAxes.cs
generated_at: "2026-04-16T11:39:41.280506+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "d40daed59089dfb4"
---
# Documentation: DTS.Common.DAS.Concepts.Test.Module
## 1. Purpose
This module provides utilities for handling tilt sensor data and recording mode configurations within the DTS data acquisition system. It contains classes and methods for converting raw ADC tilt sensor readings into engineering units (degrees), managing tilt axis configurations and polarities, and parsing string representations of enumeration values. The module serves as a bridge between hardware-level sensor data and application-level tilt calculations, supporting multiple axis orientations and calibration parameters.
---
## 2. Public Interface
### Classes
#### `Test.Module.TiltAxis`
A data container class representing a single tilt axis configuration.
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `AxisNumber` | `int` | - | The axis identifier number |
| `CurrentTilt` | `double` | - | The current tilt value |
| `Label` | `string` | - | The axis label (e.g., "X", "Y", "Z") |
| `Inversion` | `int` | `1` | Polarity multiplier (-1 or 1) |
| `IsIgnored` | `bool` | `false` | Whether this axis is excluded from calculations |
| `MountedOffset` | `double` | `0.0` | Mount offset in degrees |
| `TargetOffset` | `double` | `0.0` | Target offset in degrees |
#### `Test.Module.TiltAxesHelper`
A helper class for managing tilt axis configurations parsed from firmware attributes.
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `AxisConfigurations` | `Dictionary<int, TiltAxis>` | Empty dict with keys 0,1,2 | Collection of axis configurations |
| `AxisOne` | `TiltAxis` | - | Reference to the first active axis |
| `AxisTwo` | `TiltAxis` | - | Reference to the second active axis |
| `LevelTolerance` | `double` | `0.5` | Tolerance for level detection |
**Constructors:**
- `TiltAxesHelper()` - Default constructor initializing 3 axis configurations
- `TiltAxesHelper(string TiltAxes, double MountOffsetAxisOne, double MountOffsetAxisTwo, double TargetAxisOne, double TargetAxisTwo, double LevelTolerance, int AxisIgnored, bool UseForTiltCalculation)` - Constructs from firmware attributes
**Methods:**
- `string AxesToString()` - Returns a string representation of axis labels with polarity indicators (e.g., "IXPYP")
---
### Enumerations
#### `Test.Module.TiltAxesSimple`
Simplified tilt axis orderings (6 permutations).
| Value | Name |
|-------|------|
| 0 | `XYZ` |
| 1 | `XZY` |
| 2 | `YXZ` |
| 3 | `YZX` |
| 4 | `ZXY` |
| 5 | `ZYX` |
#### `Test.Module.TiltAxesPolarity`
Polarity combinations for three axes (8 combinations).
| Value | Name |
|-------|------|
| 0 | `PPP` |
| 1 | `PPN` |
| 2 | `PNP` |
| 3 | `PNN` |
| 4 | `NPP` |
| 5 | `NPN` |
| 6 | `NNP` |
| 7 | `NNN` |
#### `Test.Module.TiltSensorCalAttributes`
18 calibration attribute indices for tilt sensor calibration data.
| Value | Name |
|-------|------|
| 0 | `TILTSENSOR_CAL_1_GainAxis1` |
| 1 | `TILTSENSOR_CAL_2_ZeroAxis1` |
| 2 | `TILTSENSOR_CAL_3_ZeroDomAxis2PosAxis1` |
| 3 | `TILTSENSOR_CAL_4_ZeroDomAxis2NegAxis1` |
| ... | (continues through index 17) |
| 17 | `TILTSENSOR_CAL_18_ZeroDomAxis2NegAxis3` |
#### `Test.Module.AxisLabel`
| Value | Name |
|-------|------|
| 0 | `X` |
| 1 | `Y` |
| 2 | `Z` |
---
### Static Methods
#### Recording Mode Methods
```csharp
public static DFConstantsAndEnums.RecordingMode GetRecordingModeFromString(string recordingMode)
```
Converts a string representation to a `DFConstantsAndEnums.RecordingMode` enum value. Throws `Exception` with descriptive message if parsing fails.
---
#### Tilt Axes Parsing Methods
```csharp
public static TiltAxes GetTiltAxesFromString(string tiltAxes)
```
Converts a string representation to a `TiltAxes` enum value. Throws `Exception` with descriptive message if parsing fails.
```csharp
public static TiltAxesSimple SimplifyTiltAxes(TiltAxes axes)
```
Converts a `TiltAxes` enum to its simplified form by removing "I" (inversion) prefixes.
```csharp
public static int[] GetPolaritiesFromTiltAxes(TiltAxes ta)
```
Returns an array of polarity values (-1 or 1) for each axis based on the `TiltAxes` enum.
```csharp
public static bool[] GetBoolPolaritiesFromTiltAxes(TiltAxes tiltAxes)
```
Returns a boolean array indicating inversion state for each axis. `true` indicates inverted.
```csharp
public static AxisLabel[] GetAxisLabelFromTiltAxes(TiltAxes tiltAxes)
public static AxisLabel[] GetAxisLabelFromTiltAxes(string tiltAxes)
```
Extracts axis labels from a `TiltAxes` enum or string representation.
---
#### Tilt Calculation Methods
```csharp
public static double[] GetTiltDegreesEU(short[] tiltSensorADC, double[] tiltSensorCals)
```
Overload that uses default parameters: `TiltAxes.IXYZ`, ignored axis 3, and zero mount offsets.
```csharp
public static double[] GetTiltDegreesEU(short[] tiltSensorADC, double[] tiltSensorCals, TiltAxes axes, int ignoredAxis, float[] mountOffsetAxis)
```
Converts raw ADC tilt sensor readings to engineering units (degrees). Returns a `double[3]` containing X, Y, Z tilt values in degrees. The ignored axis value is set to `double.NaN`.
```csharp
public static double[] GetTiltZeroData(short[] tiltSensorADC, double[] tiltSensorCals, int dominantAxis)
```
Calculates zero offset data based on the dominant axis and its polarity.
```csharp
public static int GetDominantTiltAxis(short[] tiltSensorADC)
```
Returns the index of the axis with the largest absolute ADC value.
```csharp
public static double[] GetTiltGains(double[] tiltSensorCals)
```
Extracts gain values from calibration data. Returns `1.0` for any gain that is `0.0`.
---
#### Utility Methods
```csharp
public static string ConvertBoolToInvertString(bool isInverted)
```
Returns `"I"` if `isInverted` is true, otherwise empty string.
```csharp
public static string GetOrientationLabelFromAxisInfo(string[] axisLabels, bool[] invertAxis)
```
Builds an orientation label string from axis labels and inversion flags.
```csharp
public static TiltAxes GetTiltAxesFromAxisInfo(string[] axisLabels, bool[] invertAxis)
```
Constructs a `TiltAxes` enum from axis labels and inversion flags.
```csharp
public static float[] GetMountOffsetsOrTargetsFromAxisInfo(float[] perAxisValue, int axisToIgnore)
```
Extracts a 2-element array of values for the non-ignored axes (1-indexed: 1, 2, or 3).
---
## 3. Invariants
1. **Array Size Requirements:**
- `tiltSensorADC` must be a 3-element array (indices 0, 1, 2 correspond to axes)
- `tiltSensorCals` must be an 18-element array (indexed by `TiltSensorCalAttributes`)
- `mountOffsetAxis` must be a 2-element array
- `perAxisValue` in `GetMountOffsetsOrTargetsFromAxisInfo` must be a 3-element array
2. **Ignored Axis Values:**
- Valid values are 1, 2, or 3 (1-indexed)
- A value of 0 is silently converted to 3 in `GetTiltDegreesEU`
3. **Gain Default Behavior:**
- Any gain value of `0.0` is replaced with `1.0` in `GetTiltGains`
4. **Output Format:**
- `GetTiltDegreesEU` returns degrees rounded to 3 decimal places (via `SIGNIFICANT_DIGITS = 1000`)
- Ignored axis values are set to `double.NaN`
5. **TiltAxesHelper Dictionary Keys:**
- The default constructor initializes `AxisConfigurations` with keys 0, 1, 2 (not 1, 2, 3)
---
## 4. Dependencies
### External Dependencies (Imports)
- `DTS.Common.Enums.DASFactory` - Provides `DFConstantsAndEnums.RecordingMode` and `TiltAxes` enumerations
- `DTS.Common.Utilities` - Provides `DegreesFromADC.GetDegrees()` method
- `System` - Core .NET types
- `System.Collections.Generic` - `Dictionary<TKey, TValue>`, `List<T>`
- `System.ComponentModel` - Component model infrastructure
- `System.Linq` - LINQ extension methods (`Max()`, `Min()`, `IndexOf()`)
- `System.Text` - `StringBuilder`
### Consumers
- Unknown from source alone. The partial class structure (`Test.cs`, `Test.Module`) suggests this is part of a larger test configuration system.
---
## 5. Gotchas
### Critical Bugs in `TiltAxesHelper` Constructor
1. **Dictionary Key Mismatch:** The constructor parses `TiltAxes` string using indices 0, 1, 2:
```csharp
for (int i = 0; i < 3; i++)
{
AxisConfigurations[i].Label = TiltAxes[i * 2].ToString();
}
```
However, the conditional logic references keys 1, 2, 3:
```csharp
AxisOne = AxisConfigurations[2];
AxisTwo = AxisConfigurations[3]; // Key 3 does not exist!
```
This will throw a `KeyNotFoundException` at runtime when `AxisIgnored == 1`.
2. **Duplicate Assignment Bug:** In the `else` branch (when `AxisIgnored` is not 1 or 2):
```csharp
AxisOne = AxisConfigurations[1];
AxisOne = AxisConfigurations[2]; // Overwrites previous line
```
`AxisOne` is assigned twice and `AxisTwo` is never assigned (remains `null`).
3. **TargetOffset Assignment Bug:**
```csharp
AxisOne.TargetOffset = TargetAxisOne;
AxisOne.TargetOffset = TargetAxisTwo; // Overwrites previous line
```
`TargetAxisTwo` overwrites `TargetAxisOne`, and `AxisTwo.TargetOffset` is never set.
### Other Issues
4. **Misleading Comments:** Comments in `GetTiltDegreesEU` state "1 decimal place" but the code uses `SIGNIFICANT_DIGITS = 1000` which provides 3 decimal places.
5. **Inconsistent Mount Offset Usage:** In `GetTiltDegreesEU`, some switch cases use `mountOffsetAxisOne` twice for different axes (e.g., case 2 in XYZ uses `mountOffsetAxisOne` for both X and Z calculations). This may be intentional but appears inconsistent.
6. **Silent Normalization:** `ignoredAxis == 0` is silently converted to `3` without documentation or validation of other invalid values.
7. **Unused Property:** `UseForTiltCalculation` property in `TiltAxesHelper` is set in the constructor but never used elsewhere in the visible code.

80
enriched-partialglm/Common/DTS.Common.DAS.Concepts/Test/Module/Channel/Sensor.md Normal file
View File

@@ -0,0 +1,80 @@
---
source_files:
- Common/DTS.Common.DAS.Concepts/Test/Module/Channel/Sensor/SensorUnits.cs
- Common/DTS.Common.DAS.Concepts/Test/Module/Channel/Sensor/ExcitationVoltage.cs
generated_at: "2026-04-16T11:39:55.789807+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "00bbefe8072cdb62"
---
# Documentation: Test.Module.Channel.Sensor
## 1. Purpose
This module defines sensor-related concepts within the DAS (Data Acquisition System) domain model. Specifically, it provides an enumeration for sensitivity unit types (`SensUnits`) and utility methods for converting between excitation voltage enum values and their numeric magnitudes. The module is part of a larger nested class hierarchy representing test configuration concepts for channel/sensor setup.
## 2. Public Interface
### Enum: `Test.Module.Channel.Sensor.SensUnits`
Defines all available sensitivity unit types for sensor configuration.
| Member | Value | Description Attribute | Purpose |
|--------|-------|----------------------|---------|
| `NONE` | 0 | "NONE" | No Sensitivity Units (Polynomial Sensor) |
| `mV` | 1 | "mV" | Sensitivity expressed in mV with output at Capacity EU |
| `mVperV` | 2 | "mV/V" | Excitation proportional sensitivity expressed in mV/V with output at Capacity EU |
| `mVperVperEU` | 3 | "mV/V/EU" | Excitation proportional sensitivity expressed in mV/V/EU |
| `mVperEU` | 4 | "mV/EU" | Sensitivity expressed in mV/EU |
---
### Method: `GetExcitationVoltageMagnitudeFromEnum`
**Signature:**
```csharp
public static double GetExcitationVoltageMagnitudeFromEnum(
ExcitationVoltageOptions.ExcitationVoltageOption target)
```
**Behavior:** Converts an `ExcitationVoltageOptions.ExcitationVoltageOption` enum value to its associated numeric voltage magnitude (in volts) using a `VoltageMagnitudeAttributeCoder`. Throws `ArgumentException` if the conversion fails.
---
### Method: `GetExcitationVoltageEnumFromMagnitude`
**Signature:**
```csharp
public static ExcitationVoltageOptions.ExcitationVoltageOption GetExcitationVoltageEnumFromMagnitude(
double magnitude)
```
**Behavior:** Converts a numeric voltage magnitude to the corresponding `ExcitationVoltageOptions.ExcitationVoltageOption` enum value. On failure, logs the exception via `APILogger.Log` and returns `ExcitationVoltageOptions.ExcitationVoltageOption.Undefined` rather than throwing.
## 3. Invariants
- The `SensUnits` enum values are explicitly assigned sequential integers starting at 0.
- The `Module` class is declared `sealed`, preventing further inheritance.
- The `ExcitationVoltageOptions.ExcitationVoltageOption` type (defined externally in `DTS.Common.Enums`) is expected to have an associated `VoltageMagnitudeAttribute` for each enum member that these methods can decode/encode.
- The two conversion methods have asymmetric error handling: `GetExcitationVoltageMagnitudeFromEnum` throws on failure, while `GetExcitationVoltageEnumFromMagnitude` returns `Undefined` and logs.
## 4. Dependencies
### This module depends on:
- `System` - Core .NET types
- `System.ComponentModel` - `DescriptionAttribute` used on enum members
- `DTS.Common.Enums` - Provides `ExcitationVoltageOptions.ExcitationVoltageOption` and `ExcitationVoltageOptions.VoltageMagnitudeAttributeCoder`
- `DTS.Common.Utilities` - Likely provides the base `AttributeCoder<TEnum, TAttribute, TValue>` pattern (inferred from usage)
- `DTS.Common.Utilities.Logging` - Provides `APILogger` for error logging
### What depends on this module:
- Cannot be determined from source alone. The partial class structure suggests other files extend `Test`, `Test.Module`, `Test.Module.Channel`, and `Test.Module.Channel.Sensor`.
## 5. Gotchas
1. **Commented-out code suggests refactoring:** The `ExcitationVoltage.cs` file contains a fully commented-out `ExcitationVoltageOption` enum and related classes (`VoltageMagnitudeAttribute`, `VoltageMagnitudeAttributeCoder`). The active methods reference `ExcitationVoltageOptions.ExcitationVoltageOption` from `DTS.Common.Enums`, indicating this functionality was moved to a different namespace. The commented code may cause confusion about where the enum is actually defined.
2. **Asymmetric error handling:** The two conversion methods handle errors differently. `GetExcitationVoltageMagnitudeFromEnum` throws an `ArgumentException` (wrapping the inner exception), while `GetExcitationVoltageEnumFromMagnitude` silently logs and returns `Undefined`. Callers must handle both throwing and non-throwing failure modes.
3. **Partial class structure:** The `Test`, `Module`, `Channel`, and `Sensor` classes are all partial, spread across multiple files (indicated by comments like `// *** see Test.cs ***`). The full API surface requires examining all partial file definitions.