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

35
docs/ai/Common/DTS.Common.Serialization/Control.md Normal file
View File

@@ -0,0 +1,35 @@
---
source_files:
- Common/DTS.Common.Serialization/Control/ReviewableAttribute.cs
- Common/DTS.Common.Serialization/Control/IntervalSec.cs
generated_at: "2026-04-17T15:41:51.560483+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "cb4c6675adecfb5e"
---
# Documentation: DTS.Slice.Control
## 1. Purpose
This module provides core data structures for the DTS Slice Control subsystem. It defines `ReviewableAttribute`, an abstract base class for attributes that can be displayed on a "review tab" with dynamically computed values, and `IntervalSec`, a simple value type representing time intervals in seconds with bidirectional implicit conversion to a serialization counterpart. Both classes extend `Exceptional`, indicating a pattern of comprehensive exception handling throughout the inheritance hierarchy.
---
## 2. Public Interface
### ReviewableAttribute (abstract class)
**Namespace:** `DTS.Slice.Control`
**Base Class:** `Exceptional`
Represents an attribute that can be displayed on a review tab, with its value computed on-demand via a delegate.
#### Constructor
```csharp
public ReviewableAttribute(string name, DetermineValueString calculateValue)
```
Initializes a new instance with the specified name and value calculation delegate. Throws `ReviewableAttribute.Exception` on construction failure.
####

26
docs/ai/Common/DTS.Common.Serialization/Control/DAS.md Normal file
View File

@@ -0,0 +1,26 @@
---
source_files:
- Common/DTS.Common.Serialization/Control/DAS/IFilterable.cs
- Common/DTS.Common.Serialization/Control/DAS/IFilter.cs
generated_at: "2026-04-17T16:08:03.377171+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "9a73128b86fcf306"
---
# DAS
### 1. Purpose
This module defines the core interfaces for filtering data within a Data Acquisition System (DAS) channel architecture. It establishes the contract for filterable channels (`IFilterable`) and the filters themselves (`IFilter`), enabling a strategy pattern where different filter implementations can be applied to channel data. It handles filter management, caching controls, and the application of filtering algorithms to raw or channel-based data.
### 2. Public Interface
**`interface IFilterable`**
* `bool UseFilterCaching { get; set; }` - Gets or sets a flag to enable or disable filter caching.
* `List<IFilter> AvailableFilters { get; }` - Gets the list of `IFilter` objects available for this channel.
* `IFilter CurrentFilter { get; set; }` - Gets or sets the currently active filter.
* `double[] GetDataFilteredBy(IFilter filter, Event.Module.Channel.DataDisplayUnits displayUnits)` - Retrieves data filtered by the specified `filter` and converted to the specified `displayUnits`.
**`interface IFilter`**
* `string Name { get; }` - Returns the descriptive name of the filter.
* `bool IsCfc { get; }` - Indicates whether the filter represents a cardinal CFC (Channel Filter Class) value.

158
docs/ai/Common/DTS.Common.Serialization/Control/Event.md Normal file
View File

@@ -0,0 +1,158 @@
---
source_files:
- Common/DTS.Common.Serialization/Control/Event/DasModuleAccessor.cs
- Common/DTS.Common.Serialization/Control/Event/DasChannelAccessor.cs
- Common/DTS.Common.Serialization/Control/Event/ChannelAccessor.cs
- Common/DTS.Common.Serialization/Control/Event/ModuleChannelAccessor.cs
- Common/DTS.Common.Serialization/Control/Event/DasModuleChannelAccessor.cs
- Common/DTS.Common.Serialization/Control/Event/TestInformation.cs
- Common/DTS.Common.Serialization/Control/Event/Event.cs
generated_at: "2026-04-17T15:34:59.374836+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "e395c2fc0bedf773"
---
# Documentation: DTS.Slice.Control.Event
## 1. Purpose
This module provides the core `Event` class for the Slice Control subsystem, representing all information related to a data acquisition system (DAS) event. It serves as the primary data structure for managing test events, including their modules, channels, and associated metadata. The module provides multiple nested accessor classes for efficient lookup of modules and channels by DAS identifiers, and supports bidirectional conversion between Slice Control event representations and `DTS.Serialization.Test` objects for persistence and interchange.
---
## 2. Public Interface
### Event Class (`DTS.Slice.Control.Event`)
**Inheritance:** `Exceptional`, `Test.IConvertable`
#### Constructors
| Signature | Description |
|-----------|-------------|
| `Event()` | Default constructor. |
| `Event(string id, string description)` | Initializes with specified ID and description. |
| `Event(string id, string description, List<Module> modules)` | Initializes with ID, description, and module list. |
| `Event(Test test, Test.ReportErrors reportErrors)` | Initializes from a `DTS.Serialization.Test` object. |
| `Event(List<IDASCommunication> dases, EventInfoAggregate info)` | Initializes from a list of connected DAS devices; builds internal accessor structures. |
#### Properties
| Name | Type | Access | Description |
|------|------|--------|-------------|
| `Id` | `string` | get/set | Event identifier string. |
| `Description` | `string` | get/set | Event description string. |
| `Guid` | `Guid` | get/set | Globally unique identifier; defaults to empty GUID. |
| `FaultFlags` | `UInt16` | get/set | Global fault flags; defaults to `0`. |
| `InceptionDate` | `DateTime` | get/private set | Creation date; defaults to `DateTime.Now`. |
| `Modules` | `List<Module>` | get/set | List of modules associated with this event. |
| `CalculatedChannels` | `List<Module.Channel>` | get/set | List of calculated channels. |
| `DasModules` | `DasModuleAccessor` | get/private set | Accessor for modules keyed by DAS ID. |
| `DasChannels` | `DasChannelAccessor` | get/private set | Accessor for channels keyed by DAS ID. |
| `DasModuleChannels` | `DasModuleChannelAccessor` | get/private set | Accessor for channels keyed by DAS ID/module number/channel number triplet. |
| `LastAbsoluteChannelNumberInEvent` | `int` | get | Highest absolute channel number in the event; returns `-1` if none found. |
| `TooLargeFor32BitVisualizationBytesPerSampleThreshold` | `double` | get/private set | Threshold for 32-bit visualization check; defaults to `2.0`. |
| `IsTooLargeFor32BitVisualization` | `bool` | get | Indicates if combined channel data exceeds 32-bit addressable memory. |
| `ContainsChannelsActiveInvalidZeroingWindows` | `bool` | get | Indicates if any channels have active but invalid zeroing windows. |
| `ChannelsWithActiveInvalidZeroingWindows` | `List<Module.Channel>` | get | List of channels with invalid zeroing window configurations. |
| `BaseSerializationDirectory` | `string` | get/set (static) | Base path for event serialization directories. |
#### Methods
| Signature | Description |
|-----------|-------------|
| `static bool IsG5(IDASCommunication idas)` | Returns `true` if DAS serial number starts with `"5M"`. |
| `static bool IsSlice6DBModule(Module module)` | Returns `true` if module description equals `"slice6db module"` (case-insensitive). |
| `Test ToDtsSerializationTest()` | Converts this event to a `DTS.Serialization.Test` object; purges unconfigured channels. |
| `void FromDtsSerializationTest(Test that, Test.ReportErrors reportErrors)` | Populates this event from a `DTS.Serialization.Test` object. |
| `static implicit operator Test(Event sliceControlEvent)` | Implicit conversion to `DTS.Serialization.Test`. |
| `static string GetEventSerializationDirectory(string eventId)` | Returns the serialization directory path for a given event ID. |
| `override bool Equals(object obj)` | Memberwise equality comparison. |
| `override int GetHashCode()` | Returns base hash code. |
---
### Nested Accessor Classes
#### DasModuleAccessor
```
Inherits: ExceptionalDictionary<Common.DAS.Concepts.DAS.Id, List<Module>>
```
- **Constructor:** `DasModuleAccessor()`
- **Purpose:** Provides access to event modules by DAS ID/module number pair.
#### DasChannelAccessor
```
Inherits: ExceptionalDictionary<Common.DAS.Concepts.DAS.Id, List<Module.Channel>>
```
- **Constructor:** `DasChannelAccessor()`
- **Purpose:** Provides access to event channels by DAS ID/channel number pair.
#### ChannelAccessor
```
Inherits: ExceptionalDictionary<int, Module.Channel>
```
- **Constructor:** `ChannelAccessor()`
- **Purpose:** Component of `DasModuleChannelAccessor`; maps channel numbers to channels.
#### ModuleChannelAccessor
```
Inherits: ExceptionalDictionary<int, ChannelAccessor>
```
- **Constructor:** `ModuleChannelAccessor()`
- **Purpose:** Component of `DasModuleChannelAccessor`; maps module numbers to `ChannelAccessor` instances.
#### DasModuleChannelAccessor
```
Inherits: ExceptionalDictionary<Common.DAS.Concepts.DAS.Id, ModuleChannelAccessor>
```
- **Constructor:** `DasModuleChannelAccessor()`
- **Purpose:** Provides access to channels by DAS ID/module number/channel number triplet.
---
### TestInformation (Private Nested Class)
- **Access:** `private`
- **Inheritance:** `Exceptional`
- **Properties:** `Id` (string), `Description` (string)
- **Constructors:**
- `TestInformation()` — leaves properties uninitialized
- `TestInformation(string id, string description)`
---
## 3. Invariants
1. **GUID Default:** The `Guid` property initializes to `00000000-0000-0000-0000-000000000000` when unset.
2. **FaultFlags Default:** The `FaultFlags` property initializes to `0`.
3. **InceptionDate Default:** The `InceptionDate` property initializes to `DateTime.Now` at construction time.
4. **Visualization Threshold:** `TooLargeFor32BitVisualizationBytesPerSampleThreshold` defaults to `2.0` bytes per sample.
5. **Test ID Consistency:** When constructing from multiple DAS devices, all devices must report matching test IDs (case-insensitive comparison); otherwise an exception is thrown.
6. **Module Array Alignment:** The constructor maintains the invariant `DasModules[das.SerialNumber].Count - 1 == dasModule.ModuleArrayIndex` (enforced via `Debug.Assert`).
7. **Empty Slot Handling:** Empty slots in TDAS racks are filled with placeholder `Module` instances to maintain correct array indexing.
8. **Invalid Window Average Sentinel:** The constant `InvalidWindowAverage = short.MinValue` is used to detect uninitialized window averages.
---
## 4. Dependencies
### This Module Depends On
| Namespace/Assembly | Usage |
|--------------------|-------|
| `System` | Core types, `Guid`, `DateTime`, `InvalidOperationException` |
| `System.Collections.Generic` | `List<T>` collections |
| `System.Diagnostics` | `Debug.Assert` |
| `DTS.DASLib.Service` | `IDASCommunication`, `DASModule`, `DASChannel`, `EthernetTDAS`, `OutputSquibChannel` |
| `DTS.Serialization` | `Test` class, serialization types |
| `DTS.Common.Utilities` | `Exceptional` base class, `Exception`, `UserException` |
| `DTS.Common.Utilities.DotNetProgrammingConstructs` | `Property<T>` wrapper |
| `DTS.Common.Utilities.Logging` | `APILogger.Log` |
| `DTS.Serialization.StringResources` | Localized error strings (`Strings` class) |
| `DTS.Common.DAS.Concepts` | `DAS.Id`, `Test.Module.Channel.Sensor.ZeroMethodType` |
### Consumers (Inferred)
- Test serialization/deserialization systems (via

184
docs/ai/Common/DTS.Common.Serialization/Control/Event/Module.md Normal file
View File

@@ -0,0 +1,184 @@
---
source_files:
- Common/DTS.Common.Serialization/Control/Event/Module/ReviewableDasSerialNumberAttribute.cs
- Common/DTS.Common.Serialization/Control/Event/Module/ReviewableAttribute.cs
- Common/DTS.Common.Serialization/Control/Event/Module/ReviewableSampleRateAttribute.cs
- Common/DTS.Common.Serialization/Control/Event/Module/Module.cs
generated_at: "2026-04-17T15:39:09.615523+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "474439030090ef0a"
---
# Documentation: DTS.Slice.Control.Event.Module
## 1. Purpose
This module provides the `Event.Module` class, which represents a data acquisition system (DAS) module within a Slice Control event. It serves as a container for channel configurations, timing information, sensor readings (tilt and temperature), and metadata about the recording hardware. The module also provides a set of reviewable attributes (`ReviewableAttribute` subclasses) that expose specific module properties in a standardized format for review/display purposes, and implements bidirectional conversion between runtime objects and serialization formats.
---
## 2. Public Interface
### Event.Module Class
**Namespace:** `DTS.Slice.Control`
**Inheritance:** `Exceptional`, implements `Serialization.Test.Module.IConvertable`
#### Constructors
| Signature | Description |
|-----------|-------------|
| `Module()` | Default constructor. Initializes a new instance with empty channels list. |
| `Module(Event parentEvent)` | Initializes with a parent `Event` reference. |
| `Module(Serialization.Test.Module that, Event parent, Serialization.Test.ReportErrors reportErrors)` | Initializes from a serialization object, populating all properties from the source. |
#### Properties
| Property | Type | Description |
|----------|------|-------------|
| `ParentEvent` | `Event` | The parent `Event` containing this module. Has `SetParentEvent(Event e)` setter method. |
| `Channels` | `List<Channel>` | List of channels on this event module. |
| `Number` | `int` | Module number identifier. |
| `DasSerialNumber` | `string` | DAS serial number string. |
| `Description` | `string` | Module description. |
| `BaseSerialNumber` | `string` | Base serial number for this DAS. |
| `RequestedPreTriggerSeconds` | `double` | Requested pre-trigger duration in seconds. |
| `RequestedPostTriggerSeconds` | `double` | Requested post-trigger duration in seconds. |
| `PreTriggerSeconds` | `double` | Actual pre-trigger duration in seconds. |
| `PostTriggerSeconds` | `double` | Actual post-trigger duration in seconds. |
| `NumberOfSamples` | `UInt64` | Number of samples in this module. |
| `UnsubsampledNumberOfSamples` | `UInt64` | Number of unsubsampled samples. |
| `TriggerSampleNumbers` | `List<UInt64>` | Trigger sample numbers. |
| `UnsubsampledTriggerSampleNumbers` | `List<UInt64>` | Unsubsampled trigger sample numbers. |
| `StartRecordSampleNumber` | `UInt64` | Start record sample number. |
| `SampleRateHz` | `float` | Sample rate in Hz. |
| `StartRecordTimestampSec` | `double` | Start record timestamp (seconds component). |
| `StartRecordTimestampNanoSec` | `double` | Start record timestamp (nanoseconds component). |
| `TriggerTimestampSec` | `double` | Trigger timestamp (seconds component). |
| `TriggerTimestampNanoSec` | `double` | Trigger timestamp (nanoseconds component). |
| `PTPMasterSync` | `bool` | Whether PTP master sync is used. |
| `TiltSensorAxisXDegreesPre` / `TiltSensorAxisYDegreesPre` / `TiltSensorAxisZDegreesPre` | `double` | Pre-trigger tilt sensor axis values in degrees. |
| `TiltSensorAxisXDegreesPost` / `TiltSensorAxisYDegreesPost` / `TiltSensorAxisZDegreesPost` | `double` | Post-trigger tilt sensor axis values in degrees. |
| `TemperatureLocation1Pre` through `TemperatureLocation4Pre` | `float` | Pre-trigger temperature sensor values at 4 locations. |
| `TemperatureLocation1Post` through `TemperatureLocation4Post` | `float` | Post-trigger temperature sensor values at 4 locations. |
| `AaFilterRateHz` | `float` | Anti-aliasing filter rate in Hz. |
| `NominalExcitationVoltage` | `Test.Module.Channel.Sensor.ExcitationVoltageOption` | Nominal excitation voltage (default: `Volt5`). |
| `RecordingMode` | `Test.Module.RecordingMode` | Recording mode (default: `CircularBuffer`). |
#### Methods
| Signature | Description |
|-----------|-------------|
| `void SetPropertyValuesFrom(DASLib.Service.DASModule that)` | Copies trigger sample numbers, number of samples, and fault flags from a `DASModule` object. |
| `override bool Equals(object obj)` | Memberwise equality comparison of all major properties and child collections. |
| `override int GetHashCode()` | Returns base hash code. |
| `bool IsSlice6DBModule()` | Returns `true` if `Description` equals `"slice6db module"`. |
| `Serialization.Test.Module ToDtsSerializationTestModule(Serialization.Test parentTest)` | Converts this object to a `Serialization.Test.Module`. Only includes channels where `IsConfigured` is `true`. |
| `void FromDtsSerializationTestModule(Serialization.Test.Module that, Serialization.Test.ReportErrors reportErrors)` | Populates this object from a `Serialization.Test.Module`. Creates channels via `Channel.CreateChannel()`. |
---
### Event.Module.ReviewableAttribute Class
**Inheritance:** `Slice.Control.ReviewableAttribute` (abstract)
#### Constructors
| Signature | Description |
|-----------|-------------|
| `public ReviewableAttribute(Event.Module channel)` | **Throws `NotImplementedException`** wrapped in `Module.ReviewableAttribute.Exception`. Documented as "concrete class should implement this constructor." |
| `protected ReviewableAttribute(string name, DetermineValueString calculateValue)` | Protected constructor that passes name and value delegate to base class. |
---
### Event.Module.ReviewableDasSerialNumberAttribute Class
**Inheritance:** `Event.Module.ReviewableAttribute`
| Constructor | Description |
|-------------|-------------|
| `public ReviewableDasSerialNumberAttribute(Event.Module module)` | Initializes with name `"DAS Serial Number"` and a delegate returning `module.DasSerialNumber`. |
---
### Event.Module.ReviewableSampleRateAttribute Class
**Inheritance:** `Event.Module.ReviewableAttribute`
| Constructor | Description |
|-------------|-------------|
| `public ReviewableSampleRateAttribute(Event.Module module)` | Initializes with name `"Sample Rate"` and a delegate returning `module.SampleRateHz.ToString("N")`. |
---
### Event.Module.ReviewableTestDescriptionAttribute Class
**Inheritance:** `Event.Module.ReviewableAttribute`
| Constructor | Description |
|-------------|-------------|
| `public ReviewableTestDescriptionAttribute(Event.Module module)` | Initializes with name `"Test Description"` and a delegate returning `module.ParentEvent.Description`. |
---
### Event.Module.ReviewableHardwareFrequencyAttribute Class
**Inheritance:** `Event.Module.ReviewableAttribute`
| Constructor | Description |
|-------------|-------------|
| `public ReviewableHardwareFrequencyAttribute(Event.Module module)` | Initializes with name `"HW AAF"` and a delegate returning `module.AaFilterRateHz.ToString("N2")`. |
---
## 3. Invariants
1. **Parent-Child Relationship**: A `Module` must have a valid `ParentEvent` reference for operations that access parent properties (e.g., `ReviewableTestDescriptionAttribute` accesses `module.ParentEvent.Description`).
2. **Channel Filtering in Serialization**: `ToDtsSerializationTestModule()` only serializes channels where `IsConfigured` is `true`.
3. **Channel Numbering**: When populating from a serialization module, channels are assigned sequential absolute channel numbers starting from `ParentEvent.LastAbsoluteChannelNumberInEvent + 1`.
4. **Equality Semantics**: `Equals()` performs memberwise comparison including all properties and child collections (`Channels`, `TriggerSampleNumbers`, `UnsubsampledTriggerSampleNumbers`).
5. **ReviewableAttribute Constructor Contract**: The public constructor taking `Event.Module` is explicitly designed to throw; subclasses must use the protected constructor with name and delegate.
---
## 4. Dependencies
### This Module Depends On:
- `DTS.Common.DAS.Concepts`
- `DTS.Serialization.StringResources`
- `DTS.Common.Utilities`
- `DTS.Common.Utilities.DotNetProgrammingConstructs`
- `DTS.Common.Utilities.Logging` (for `APILogger`)
- `DTS.Utilities` (referenced in `ReviewableDasSerialNumberAttribute.cs` and `ReviewableSampleRateAttribute.cs`)
- `System`, `System.Collections.Generic`, `System.Linq`, `System.Diagnostics`
- `DASLib.Service.DASModule` (external service type used in `SetPropertyValuesFrom`)
- `Slice.Control.ReviewableAttribute` (base class for `Event.Module.ReviewableAttribute`)
- `Slice.Control.Event` (parent container class)
- `Serialization.Test.Module` and related serialization types
### What Depends On This Module:
- Not explicitly shown in source, but `Channel` class is referenced extensively, implying `Event.Module.Channel` is a dependent nested class.
---
## 5. Gotchas
1. **ReviewableAttribute Constructor Throws by Design**: The public constructor `ReviewableAttribute(Event.Module channel)` always throws a `NotImplementedException`. This appears to be intentional guard code, but the pattern is unusual—subclasses should call the protected constructor directly.
2. **Inappropriate Exception Handling**: The `FromDtsSerializationTestModule()` method uses try/catch blocks around individual property assignments (e.g., `StartRecordTimestampSec`, `TriggerTimestampSec`, tilt sensor values, temperature values) with logging but no re-throw. This silently swallows errors and continues execution. Source contains TODO comments: `"//TODO: inappropriate using try/catch!!!"`.
3. **Incorrect Log Message**: In `FromDtsSerializationTestModule()`, the catch block for `TriggerTimestampNanoSec` logs `"failed to get TriggerTimestampSec"` instead of `"failed to get TriggerTimestampNanoSec"`.
4. **Wrong Property Assignment**: In `FromDtsSerializationTestModule()`, the line `TriggerTimestampNanoSec = that.StartRecordTimestampNanoSec` appears to copy from the wrong source property (should likely be `that.TriggerTimestampNanoSec`).
5. **Commented-Out Initialization**: In the default `Module()` constructor, the call to `InitializeReviewableAttributes` is commented out. It is unclear if this is intentional or dead code.
6. **Exception Swallowing in SetPropertyValuesFrom**: The method catches exceptions when reading `ParentEvent.FaultFlags` and silently ignores them with an empty catch block (`catch (System.Exception) { }`).
7. **Format String Inconsistency**: `ReviewableSampleRateAttribute` uses `"N"` format while `ReviewableHardwareFrequencyAttribute` uses `"N2"` format for numeric display.

66
docs/ai/Common/DTS.Common.Serialization/Control/Event/Module/AnalogInputChannel.md Normal file
View File

@@ -0,0 +1,66 @@
---
source_files:
- Common/DTS.Common.Serialization/Control/Event/Module/AnalogInputChannel/ReviewableShuntDeflectionAttribute.cs
- Common/DTS.Common.Serialization/Control/Event/Module/AnalogInputChannel/ReviewableFilterFrequencyAttribute.cs
- Common/DTS.Common.Serialization/Control/Event/Module/AnalogInputChannel/ReviewableIsoCodeAttribute.cs
- Common/DTS.Common.Serialization/Control/Event/Module/AnalogInputChannel/ReviewableDescriptionAttribute.cs
- Common/DTS.Common.Serialization/Control/Event/Module/AnalogInputChannel/ReviewableSerialNumberAttribute.cs
- Common/DTS.Common.Serialization/Control/Event/Module/AnalogInputChannel/ReviewableUnitsAttribute.cs
- Common/DTS.Common.Serialization/Control/Event/Module/AnalogInputChannel/ReviewableMinMaxEuAttribute.cs
- Common/DTS.Common.Serialization/Control/Event/Module/AnalogInputChannel/ReviewableCfcAttribute.cs
- Common/DTS.Common.Serialization/Control/Event/Module/AnalogInputChannel/ReviewableTargetShuntDeflectionAttribute.cs
- Common/DTS.Common.Serialization/Control/Event/Module/AnalogInputChannel/ReviewableMeasuredShuntDeflectionAttribute.cs
- Common/DTS.Common.Serialization/Control/Event/Module/AnalogInputChannel/ReviewableShuntDeflectionPercentageAttribute.cs
generated_at: "2026-04-17T15:31:14.276531+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "42e54499338ddc45"
---
# Documentation: DTS.Slice.Control.Event.Module.AnalogInputChannel Reviewable Attributes
## 1. Purpose
This module provides a collection of reviewable attribute classes for analog input channels within the DTS Slice Control event system. Each class encapsulates a specific channel property (e.g., shunt deflection, filter frequency, serial number, calibration values) that can be displayed or reviewed in a standardized format. These attributes follow a consistent pattern where each inherits from `Slice.Control.Event.Module.Channel.ReviewableAttribute` and uses a delegate-based deferred evaluation to retrieve formatted string values from channel data at runtime.
---
## 2. Public Interface
All classes are nested within `DTS.Slice.Control.Event.Module.AnalogInputChannel` and inherit from `Slice.Control.Event.Module.Channel.ReviewableAttribute`.
### ReviewableShuntDeflectionAttribute
```csharp
public ReviewableShuntDeflectionAttribute(Event.Module.Channel channel)
```
Captures the measured shunt deflection in millivolts. The delegate casts `channel` to `DTS.DAS.Concepts.DAS.Channel.IShuntAware` and returns `MeasuredShuntDeflectionMv` formatted as `"F1"`. Label: `"Shunt Deflection (mV)"`.
---
### ReviewableFilterFrequencyAttribute
```csharp
public ReviewableFilterFrequencyAttribute(Event.Module.Channel channel)
```
Captures the filter cutoff frequency. The delegate casts `channel.CurrentFilter` to `SaeJ211Filter` and returns `CutoffFrequencyHz` as an integer formatted with `"N"`. Label: `"Filter Frequency"`.
---
### ReviewableIsoCodeAttribute
```csharp
public ReviewableIsoCodeAttribute(Event.Module.Channel channel)
```
Captures the ISO code. The delegate casts `channel` to `AnalogInputChannel` and returns `IsoCode.ToString()`. Label: `"ISO Code"`.
---
### ReviewableDescriptionAttribute
```csharp
public ReviewableDescriptionAttribute(Event.Module.Channel channel)
```
Captures the channel description. The delegate returns `channel.ChannelDescriptionString`. Label: `"Description"`.
---
### ReviewableSerialNumberAttribute
```csharp
public ReviewableSerialNumberAttribute(Event

220
docs/ai/Common/DTS.Common.Serialization/Control/Event/Module/Channel.md Normal file
View File

@@ -0,0 +1,220 @@
---
source_files:
- Common/DTS.Common.Serialization/Control/Event/Module/Channel/DataValues.cs
- Common/DTS.Common.Serialization/Control/Event/Module/Channel/ReviewableAttribute.NotApplicableException.cs
- Common/DTS.Common.Serialization/Control/Event/Module/Channel/Filter.cs
- Common/DTS.Common.Serialization/Control/Event/Module/Channel/ChannelDefaultSaeJ211Filter.cs
- Common/DTS.Common.Serialization/Control/Event/Module/Channel/CalculatedChannel.cs
- Common/DTS.Common.Serialization/Control/Event/Module/Channel/SaeJ211Filter.cs
generated_at: "2026-04-17T15:34:47.007360+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "ba30fc370955c9dd"
---
# DTS.Slice.Control.Event.Module.Channel Documentation
## 1. Purpose
This module provides the channel-level data structures and filtering mechanisms for the DTS Slice Control Event system. It defines classes for storing channel data values (with optional memory-mapped file support for large datasets), implements SAE J211-compliant digital filters for signal processing, and provides a hierarchy of calculated channel types for derived data operations such as integration, differentiation, FFT analysis, and vector mathematics. The module exists to support data acquisition and analysis workflows within the larger DTS Slice framework.
---
## 2. Public Interface
### `Event.Module.Channel.DataValues`
A class representing a channel's data, inheriting from `Exceptional`.
**Constructors:**
- `DataValues()` — Initializes with memory-mapped file support enabled by default.
- `DataValues(bool useMemoryMappedFile)` — Initializes with explicit control over memory-mapped file usage.
**Properties:**
- `bool UseMemoryMappedFile { get; set; }` — Controls whether the class uses memory-mapped files instead of in-memory lists for data storage.
---
### `Event.Module.Channel.ReviewableAttribute.NotApplicableException`
An exception class for attempts to use a channel attribute that is not applicable to the associated channel. Inherits from `ApplicationException`.
**Constructors:**
- `NotApplicableException()`
- `NotApplicableException(string msg)`
- `NotApplicableException(string msg, System.Exception innerEx)`
---
### `Event.Module.Channel.Filter` (Abstract)
Abstract base class for channel filters. Implements `Exceptional` and `IFilter`.
**Abstract Properties:**
- `string Name { get; }` — Descriptive designation for the filter.
- `bool IsCfc { get; }` — Indicates whether the filter corresponds to a CFC (Channel Filter Class) value.
- `ChannelFilter Type { get; }` — The `ChannelFilter` designation for this filter.
- `double CutoffFrequencyHz { get; }` — The cutoff frequency in Hz.
**Abstract Methods:**
- `double[] Apply(Channel input, DataDisplayUnits displayUnits, bool bUseLegacyTDCSoftwareFilterAdjustment)` — Applies the filter to a channel.
- `double[] Apply(double[] data, double sampleRate, bool bUseLegacyTDCSoftwareFilterAdjustment)` — Applies the filter to raw data.
- `string ToBaseString()` — Returns the base name without decoration (contrast with `ToString()`).
---
### `Event.Module.Channel.SaeJ211Filter`
Concrete implementation of SAE J211-based filters. Inherits from `Filter`.
**Constructors:**
- `SaeJ211Filter(SaeJ211Filter originalFilter)` — Copy constructor.
- `SaeJ211Filter(ChannelFilter originalType)` — Initializes from a `ChannelFilter` enum value. Throws `Exception` if `ChannelFilter.AdHoc` is passed.
- `SaeJ211Filter(double cutoffFrequencyHz)` — Initializes an ad hoc filter with a specific cutoff frequency.
**Properties:**
- `override bool IsCfc { get; }` — Returns `true` if the filter is CFC-compliant (not `Unfiltered` and not `AdHoc`).
- `override ChannelFilter Type { get; }` — Returns the best-fitting `ChannelFilter` value.
- `char IsoDescription { get; }` — Returns the ISO description character.
- `override double CutoffFrequencyHz { get; }` — The cutoff frequency.
- `ChannelFilter OriginalType { get; }` — The original filter type specified at construction.
- `override string Name { get; }` — The filter name (e.g., "1000Hz" for ad hoc, or the CFC description).
**Methods:**
- `override double[] Apply(Channel channel, DataDisplayUnits displayUnits, bool bUseLegacyTDCSoftwareFilterAdjustment)` — Applies the filter to channel data.
- `override double[] Apply(double[] data, double sampleRate, bool bUseLegacyTDCSoftwareFilterAdjustment)` — Applies the filter to raw data.
- `override string ToString()` — Returns `Name`.
- `override string ToBaseString()` — Returns `Name`.
- `override bool Equals(object obj)` — Compares filters by name (case-insensitive).
- `override int GetHashCode()` — Returns hash based on lowercase name.
- `static Filter Parse(string serialization)` — Creates a filter from a string representation.
---
### `Event.Module.Channel.DefaultSaeJ211Filter`
A default wrapper for SAE J211 filters. Inherits from `SaeJ211Filter`.
**Constructors:**
- `DefaultSaeJ211Filter(SaeJ211Filter filter)` — Wraps an existing filter.
- `DefaultSaeJ211Filter(ChannelFilter filterType)` — Creates a filter from a `ChannelFilter` type.
- `DefaultSaeJ211Filter(double adHocFrequency)` — Creates an ad hoc filter with specified frequency.
**Properties:**
- `override string Name { get; }` — Returns `"Default (" + base.Name + ")"`.
**Methods:**
- `override string ToBaseString()` — Returns `base.Name`.
- `override string ToString()` — Returns `Name`.
---
### `Event.Module.Channel.CalculatedChannel` (Abstract)
Abstract base class for calculated/derived channels. Inherits from `Channel` and implements `IEngineeringUnitAware`.
**Nested Enum:**
- `Operation` — Values: `Integral`, `Derivative`, `HeadInjuryCriteria`, `FFT`, `ImportedCSV`, `Resultant`, `TSR`, `Scale`, `Offset`, `Sine`, `Cosine`.
**Nested Enum:**
- `XUnits` — Values: `msec`, `sec`, `Hz`, `samples`.
**Properties:**
- `Operation CalculationType { get; }` — The calculation type.
- `double[] X { get; }` — X-axis values.
- `double[] Y { get; }` — Y-axis values.
- `XUnits XAxis { get; }` — X-axis unit type.
- `string XUnitsString { get; }` — String representation of X units.
- `string EngineeringUnits { get; set; }` — Y-axis engineering units.
- `override bool SupportsADC { get; }` — Returns `false`.
- `override bool SupportsEU { get; }` — Returns `true`.
- `override bool SupportsmV { get; }` — Returns `false`.
- `override double ActualMaxRangeEu { get; }` — Returns `Y.Max()`.
- `override double ActualMinRangeEu { get; }` — Returns `Y.Min()`.
- `override double DataHalfRangeValueEu { get; }`, `DataMaxEu { get; }`, `DataMinEu { get; }`, `DataRangeEu { get; }` — Statistical properties of Y data.
- `override bool IsConfigured { get; set; }` — Always `true`; setter throws `NotSupportedException`.
**Constructor:**
- `CalculatedChannel(string name, XUnits xAxis, string yAxis, double[] xValues, double[] yValues, Operation calcType, int number, Module parentModule)`
**Methods that throw `NotSupportedException` or `NotImplementedException`:**
- `override void FromDtsSerializationTestModuleChannel(Serialization.Test.Module.Channel that)`
- `override void SetPropertyValuesFrom(DASLib.Service.DASChannel dasChannel)`
- `override void SetPropertyValuesFrom(DASLib.Service.DiagnosticsResult diagResults)`
- `override Serialization.Test.Module.Channel ToDtsSerializationTestModuleChannel(Serialization.Test.Module parentModule)`
- `override double ActualMaxRangeMv { get; }`
- `override double ActualMinRangeMv { get; }`
- `override double SensorCapacityEU { get; }`
- `override double DesiredRangeEU { get; }`
- `override List<double> GetUnfilteredDataMV()`
**Methods:**
- `override List<double> GetUnfilteredDataEu()` — Returns a copy of Y values.
- `override string ToString()` — Returns `ChannelDescriptionString` or `"N/A"`.
---
### Concrete Calculated Channel Types
All inherit from `CalculatedChannel` and have identical constructor signatures:
- `FFTCalculatedChannel` — Additional property: `double PeakFrequency { get; }`. Constructor includes extra `double peakFrequency` parameter.
- `IntegralCalculatedChannel`
- `DerivativeCalculatedChannel`
- `ScaleCalculatedChannel`
- `OffsetCalculatedChannel`
- `ResultantCalculatedChannel`
- `AdditiveVectorCalculatedChannel`
- `SineCalculatedChannel`
- `CosineCalculatedChannel`
---
## 3. Invariants
1. **Filter Type Consistency**: `SaeJ211Filter.Type` will never return `ChannelFilter.AdHoc` if the cutoff frequency exactly matches a CFC value; it will return the matching CFC type instead.
2. **CFC Compliance**: `SaeJ211Filter.IsCfc` returns `true` only when `Type` is neither `Unfiltered` nor `AdHoc`.
3. **Filter Equality**: Two `SaeJ211Filter` instances are considered equal if their `Name` properties match case-insensitively. Consequently, `GetHashCode()` is based on the lowercase name.
4. **Calculated Channel Data Immutability**: X and Y data arrays in `CalculatedChannel` are stored in `readonly List<double>` fields and exposed as copies via `ToArray()`.
5. **Calculated Channel Capabilities**: All `CalculatedChannel` derivatives have `SupportsADC = false`, `SupportsEU = true`, and `SupportsmV = false`.
6. **Parse Round-Trip**: `SaeJ211Filter.Parse()` can parse filter names produced by `ToString()`; unrecognized strings return an `Unfiltered` filter.
---
## 4. Dependencies
### This module depends on:
- `DTS.Common.Utilities` — Provides `Exceptional` base class, `Exception`, `Property<T>`, `APILogger`.
- `DTS.Common.Utilities.DotNetProgrammingConstructs` — Provides `Property<T>`.
- `DTS.Common.Utilities.SaeJ211` — Provides `FilterUtility`, `CfcValueAttributeCoder`, `DescriptionAttributeCoder<T>`, `IsoDescriptionAttributeCoder`.
- `DTS.Common.Utilities.Logging` — Provides `APILogger`.
- `DTS.Common.DAS.Concepts.DAS.Channel` — Provides `ChannelFilter`, `IFilter`, `IEngineeringUnitAware`.
- `DTS.Slice.Control.DAS.Channel` — Referenced in `Filter.cs`.
- `DASLib.Service` — Provides `DASChannel`, `DiagnosticsResult` (used in `CalculatedChannel`).
- `System` namespaces — Standard .NET types.
### What depends on this module:
- Cannot be fully determined from source alone, but the partial class structure (`Event.Module.Channel`) indicates this is part of a larger `DTS.Slice.Control` namespace hierarchy.
---
## 5. Gotchas
1. **Empty Memory-Mapped File Implementation**: In `DataValues.DataValues(bool useMemoryMappedFile)`, the `if (UseMemoryMappedFile)` block is empty. The feature appears to be a stub or incomplete implementation.
2. **Legacy TDC Filter Adjustment**: The `Apply` methods on filters accept a `bool bUseLegacyTDCSoftwareFilterAdjustment` parameter (referenced as "8747" in comments) that adjusts filtered data by one sample to match legacy TDC behavior. This may produce unexpected results if not understood.
3. **NotSupportedException on CalculatedChannel**: Many methods on `CalculatedChannel` throw `NotSupportedException` or `NotImplementedException`. These include serialization methods, mV-related properties, and some range properties. Callers must handle these exceptions.
4. **AdHoc Filter Construction Restriction**: `SaeJ211Filter(ChannelFilter originalType)` throws an `Exception` if passed `ChannelFilter.AdHoc`. Use the `SaeJ211Filter(double cutoffFrequencyHz)` constructor instead.
5. **Large Data Handling in Filter.Apply**: When filtering ADC data, the method checks for `ILargeDataAware.IsDataArraySized` and throws `DataTooBigForArrayException` if data is too large. This is a runtime consideration for large datasets.
6. **Commented-Out Code**: Significant blocks of code are commented out in `CalculatedChannel.cs`, including the entire `HICCalculatedChannel` class and `InitializeReviewableAttributes` implementations. This suggests incomplete features or tech debt.
7. **Filter Name Ambiguity**: `DefaultSaeJ211Filter.Name` returns `"Default (" + base.Name + ")"`, while `ToBaseString()` returns just `base.Name`. The `ToString()` returns the decorated name. Use `ToBaseString()` when the undecorated name is needed.

326
docs/ai/Common/DTS.Common.Serialization/DDAS (Chrysler).md Normal file
View File

@@ -0,0 +1,326 @@
---
source_files:
- Common/DTS.Common.Serialization/DDAS (Chrysler)/ChannelDefinition.h
- Common/DTS.Common.Serialization/DDAS (Chrysler)/DDASTestDefinition.h
- Common/DTS.Common.Serialization/DDAS (Chrysler)/DataFloat.h
- Common/DTS.Common.Serialization/DDAS (Chrysler)/DDAS.File.cs
- Common/DTS.Common.Serialization/DDAS (Chrysler)/DDASTest.cs
- Common/DTS.Common.Serialization/DDAS (Chrysler)/DDAS.File.Writer.cs
- Common/DTS.Common.Serialization/DDAS (Chrysler)/TSVSettingsWindow.cs
- Common/DTS.Common.Serialization/DDAS (Chrysler)/TSVSettingsWindow.Designer.cs
- Common/DTS.Common.Serialization/DDAS (Chrysler)/DDASChannel.cs
generated_at: "2026-04-17T15:32:53.691261+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "403f99d261310d3b"
---
# DDAS Serialization Module Documentation
## 1. Purpose
This module provides serialization and deserialization support for the DDAS (DaimlerChrysler Data Acquisition System) file format, a proprietary binary format used for storing crash test data. It bridges legacy C++ structures (originally from DDAS testplan.h) with a modern C# serialization framework, enabling export of test data including channel configurations, transducer metadata, and floating-point sample data. The module handles multiple data types (Raw/ADC, Processed/Filtered, and Converted/Engineering Units) and produces `.ddas` or `.fpd` files compatible with downstream analysis tools.
---
## 2. Public Interface
### C# Classes
#### `DTS.Serialization.DDAS.File`
A partial class representing the DDAS file format, extending `Serialization.File` and implementing `IWritable<Test>`.
```csharp
public File() // Constructor, initializes with "DDAS" format identifier
public static string Extension // Returns ".ddas"
public IWriter<Test> Exporter // Lazy-initialized property returning a Writer instance
```
#### `DTS.Serialization.DDAS.File.Writer`
Nested class for serializing `Test` objects to DDAS format.
```csharp
internal Writer(File fileType, int encoding) // Constructor
public void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength) // Throws NotImplementedException
public void Write(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested, double minStartTime, int dataCollectionLength) // Main write method
public void Initialize(...) // Empty initialization method
public string ExtensionPrefix { get; set; } // Defaults to empty string
public DDASTest MyTVTTest { get; set; } // Reference to DDASTest being written
private int DataSamplesPerTick // Returns 1000
private uint GetChannelTicks(Test.Module.Channel channel) // Calculates progress ticks
```
#### `DTS.Serialization.DDAS.DDASTest`
Represents a complete DDAS test with metadata and channel collection.
```csharp
public enum Fields { LabName, POCName, POCPhoneAndEmail, TestDate, TestTime, TestNumber, TestType, TestObject, DataType, SensorMakeModelSerial, SensorLocation, SensorAxis, SensorMountType, EngineeringUnits, ChannelErrors, SamplingRate, AAFilterCutoffDescription, BitResolution, DigitalFilterType, Notes }
public string GetValue(Fields field) // Returns "#NOVALUE" if not set
public void SetValue(Fields field, string value) // Sets value and propagates to all channels
public DDASChannel[] Channels { get; set; } // Array of channel objects
public Test Test { get; } // Reference to underlying Test object
public FilteredData[] DataUnfilteredEU { get; } // Unfiltered engineering unit data
public FilteredData[] DataADC { get; } // ADC/raw data
public double[] ActualRangesEUFiltered { get; } // Filtered EU ranges
public double[] ActualRangesEUUnfiltered { get; } // Unfiltered EU ranges
public double[] ActualRangesADC { get; } // ADC ranges
public bool FlatFolders { get; } // Folder structure option
public DDASTest(Test test, FilteredData[] adc, FilteredData[] euUnfiltered, string path, double[] actualRangesEUFiltered, double[] actualRangesEUUnfiltered, double[] actualRAngesADC, bool flatFolders) // Constructor
```
#### `DTS.Serialization.DDAS.DDASChannel`
Handles serialization of individual channel data to binary DDAS format.
```csharp
public string GetValue(DDASTest.Fields field) // Returns "#NOVALUE" if not set
public void SetValue(DDASTest.Fields field, string value) // Sets value; handles DataType side effects
public string FileName { get; set; } // Output file path
public int ChannelNumber { get; } // Returns 1 + _channelIndex
public void Serialize(TickEventHandler tickHandler) // Writes binary DDAS file
public DDASChannel(DDASTest parentTest, int channelIndex, string path) // Constructor
```
#### `DTS.Serialization.TSV.TSVSettingsWindow`
Windows Forms dialog for configuring TSV export settings.
```csharp
public TSVSettingsWindow(TSVTest test) // Constructor, populates grids from test data
```
### C++ Structures
#### `CHANNEL` (ChannelDefinition.h)
```c
typedef struct tagCHANNEL {
short Size; // Size of this object
short Flags; // Channel Flags
char Name[64]; // Channel Name
char Sign[8]; // Sign +, -, or blank
char Axis[8]; // X,Y,Z,FX,MX,AX,...
float FilterFreq; // Channel Filter Class (in Hz)
float SetGain; // Gain setting (1 - n)
float ActGain; // Actual (measured?) gain setting
float Rcal; // Shunt cal resistance
float Excitation; // Excitation Voltage (when programable)
byte byteSpares[4]; // Spare bytes (was Cal Date)
TRANSDUCER Transducer; // "Snapshot" of transducer values
} CHANNEL;
typedef CHANNEL *PCHANNEL;
typedef CHANNEL *PCHAN;
```
#### `FILEINFOBLOCK` (DDASTestDefinition.h)
```c
typedef struct tagFILEINFOBLOCK {
UINT Size; // Block Size (including nSize)
char FileTypeName[12]; // Software Type Name
char FileTypeVers[12]; // File Version Name
UINT FileTypeFlags; // Hardware Type in upper 16 bits, File Type in lower 16 bits
char CreatedByName[16]; // Created by T-number
char UpdatedByName[16]; // Updated by T-number
} FILEINFOBLOCK;
```
#### `TESTINFO` (DataFloat.h)
```c
typedef struct tagTESTINFO {
unsigned long Size; // Block Size (including Size)
unsigned long DeviceID; // DAQ device ID
long ChannelNo; // Channel number (1-32)
long SampleRate; // Samples per second
long TotalSamples; // Total samples in data record
long PreEventSamples; // Samples before event
short ChanNumInSys; // Channel Number (1-128) in system
short NumPreCalPts; // Number of preCal points
short NumPostCalPts; // Number of postCal points
char TestCreation[128]; // Test path and date
char TimeAxisTitle[32]; // Time axis title
byte SpareBytes[2]; // 2 bytes of spare (for 4 byte alignment)
} TESTINFO;
```
#### `ACQUISITIONBLOCK` (DDASTestDefinition.h)
```c
typedef struct tagACQUISITIONBLOCK {
long nSize; // Block Size (including nSize)
long nRecordMode; // Enumerated constant data mode
long SampleRate; // Samples per second
long TotalSamples; // Total samples in record
long PreEventSamples; // Pre-Event samples (Rec Mode only!)
long TapeModeChannels; // No of Channels (Tape Mode only!)
long nTrigBlock; // Number of trigger entries (can be 0)
} ACQUISITIONBLOCK;
```
#### `TRIGCHANDEF` and `TRIGCHANBLOCK` (DDASTestDefinition.h)
```c
typedef struct tagTRIGCHANDEF {
BYTE ChanNo; // Channel number to use as trigger
BYTE LevelPct; // Trig level in % full scale (0=off)
} TRIGCHANDEF;
#define MAXTRIGCHANS 4
#define TRIGCHANDSBL 0x80
typedef struct tagTRIGCHANBLOCK {
unsigned short SizeBlock;
unsigned short NumTrigs;
TRIGCHANDEF TrigChan[MAXTRIGCHANS];
} TRIGCHANBLOCK;
```
### C++ Class: `CDataFloat` (DataFloat.h)
```c
CDataFloat(unsigned int nSize);
CDataFloat();
virtual ~CDataFloat();
int GetChannelNumberInBox();
bool VerifyAndCoerceAxis(bool bNegativeSign, const char* szAxis, BOOL bVerbose);
void SetEngrgUnits(char *szNewEngrgUnits);
void SetChannelName(char* szNewChannelName);
int CalcSampIn3mSecInt();
int ConvertTimeToIndex(float fTime);
float ConvertIndexToTime(int nIndex);
const CString GetFileName();
int AppendArrayFloat(CArray<float, float&>* srcArray);
CArray<float, float&>* GetDataArray();
bool GetTimeAtValue(float fValue, float *pTvalue);
bool GetDataPeaks(int nPkType, int nVerbose, float* pTStart, float* pTEnd, float* pTMin, float* pDMin, float* pTMax, float* pDMax);
bool GetDataPeaks(int nPkType, int nVerbose, float* pTMin, float* pDMin, float* pTMax, float* pDMax);
bool GetDataPeaks(int nPkType, int nVerbose, int *pXMin, float *pTMin, float *pDMin, int *pXMax, float *pTMax, float *pDMax);
int GetChannelNumber();
float GetStartTime(bool bmSec);
float GetStartTimeData(bool bmSec);
float GetStopTime(bool bmSec);
float GetStopTimeData(bool bmSec);
const char* GetFileExt();
const char* GetFileTitle();
long GetSampleRate();
const char* GetFilePathAndName();
int SetFilePathAndName(char* szNewFileSpec);
int ClearAll(long NewNumberElements);
TESTINFO* GetTestInfo();
FILEINFOBLOCK* GetFileInfo();
CHANNEL* GetChannel();
float GetFilterClass();
int GetEventOffset();
CString GetDataSetName(CString &csName);
FILEHEADER* GetFileHeader();
bool WriteToFile(const char *lpFilename, bool bPrint);
bool ReadFromFile(const char *lpFilename);
float* GetDataBuffer();
bool SetSize(long lNumberElements);
long GetSize();
bool GetDataNext(float* fData);
bool StoreDataNext(float fData);
bool SetIndexToStart();
void operator=(const CDataFloat &src);
```
### Macros and Constants
```c
// Channel state macros (ChannelDefinition.h)
#define ISCHANACTIVE(pChan) (pChan->Flags&(1<<CHANFLAG_ACTIVE)?1:0)
#define SETCHANACTIVE(pChan) (pChan->Flags|=(1<<CHANFLAG_ACTIVE))
#define CLRCHANACTIVE(pChan) (pChan->Flags&=(~(1<<CHANFLAG_ACTIVE)))
// File type constants (DDASTestDefinition.h)
#define TESTDEFEXT ".tdf"
#define DDASTYPENAME "DDAS V5"
#define DDASFILEVERS "Ver 500"
// Data file constants (DataFloat.h)
#define FLOATDATANAME "DDAS FlPt"
#define FLOATDATARAW "DDAS fpRAW"
#define FLOATDATAVER "Ver 500"
#define RawExt ".raw"
#define FlPtExt ".fpd"
// Trigger constants (DDASTestDefinition.h)
#define MAXTRIGCHANS 4
#define TRIGCHANDSBL 0x80
```
### Enumerations
```c
// ChannelDefinition.h
enum ChannelFlags { CHANFLAG_ACTIVE };
// DDASTestDefinition.h
enum FileTypeFlags { FILETYPE_IMPORTED4X };
enum HardwareType { HWTYPE_UNKNOWN, HWTYPE_DDAS3, HWTYPE_KAYSERTHREDE, HWTYPE_COUNT };
enum AnalogOptionFlags { ANAOPT_CHANTRIGGERS };
enum MemoryOptionFlags { MEMOPT_TAPEMODE, MEMOPT_PREEVENT, MEMOPT_PREEVENTXXX };
enum RecordModes { RECORDMODE_EVENT, RECORDMODE_TAPE };
// DataFloat.h
enum FileTypes { UNKNOWN, FLOATPOINT, PROCESSED };
enum PeakTypes { PEAKS_MINMAX, PEAKS_3MSCONTIN, PEAKS_3MSCUMUL };
enum FPDVerbosity { FPD_SILENT, FPD_ERRORS, FPD_STATUS, FPD_RESULTS, FPD_VERBOSE };
```
---
## 3. Invariants
1. **Channel numbering**: Channels are 1-indexed in DDAS format. `ChannelNumber` returns `1 + _channelIndex`.
2. **Block size fields**: All binary structures include a `Size` field as the first member that must equal the total byte size of the structure (including the size field itself).
3. **Fixed-size string fields**: All character arrays in structures are fixed-width and must be null-padded to their full length when written (e.g., `FileTypeName[12]`, `Name[64]`).
4. **File type/version strings**: DDAS files use `"DDAS FlPt"` as the file type name and `"Ver 500"` as the version string.
5. **Trigger enable condition**: To enable a trigger, `ChanNo` and `LevelPct` must be nonzero, and `TRIGCHANDSBL` (0x80) must not be set in `LevelPct`.
6. **Hardware type encoding**: `FileTypeFlags` stores Hardware Type in upper 16 bits and File Type in lower 16 bits.
7. **Calibration date epoch**: Transducer calibration dates are stored as seconds since January 1, 1971 (not the Unix epoch of 1970).
8. **Data samples per tick**: Progress reporting uses 1000 samples per tick for granularity.
9. **Maximum trigger channels**: The system supports a maximum of 4 analog trigger channels (`MAXTRIGCHANS`).
---
## 4. Dependencies
### This module depends on:
- `TransducerDefinition.h` (C++ header for `TRANSDUCER` structure - referenced but not provided)
- `FilePath.h` (C++ header for `CFilePath` class - referenced but not provided)
- `<Afxtempl.h>` (MFC template collections for `CArray`, `CList`)
- `System.Windows.Forms` (for `TSVSettingsWindow`)
- `C1.Win.C1FlexGrid` (third-party grid control)
- `DTS.Serialization` namespace (base `Serialization.File`, `Test`, `FilteredData`, `IWriter<T>` types - not provided)
### What depends on this module:
- Unclear from source alone; the module appears to be a serialization plugin that would be loaded by a parent serialization framework.
---
## 5. Gotchas
1. **NotImplementedException in Write overload**: The `Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)` method throws `NotImplementedException`. Callers must use the full overload with all parameters.
2. **Historical CalDate field removal**: The `CHANNEL` structure's `CalDate` field was removed and replaced with `byteSpares[4]` per revision dated 11/08/04. The calibration date is now stored in the `TRANSDUCER` substructure instead.
3. **Non-standard epoch for calibration dates**: The `DDASChannel.Serialize` method uses `new DateTime(1971, 1, 1, 0, 0, 0)` as the epoch, not the standard Unix epoch (1970). This differs from the C++ header comment which mentions "seconds since 1970."
4. **SLICE-specific channel numbering logic**: In `DDASChannel` constructor, there is a comment indicating SLICE-specific logic for determining `numberOfChannelsPerModule` using the formula `(channel.ParentModule.NumberOfChannels + 2) / 3 * 3`, which assumes 3 channels per bridge module.
5. **Typo in constructor parameter**: `DDASTest` constructor has a parameter named `actualRAngesADC` (typo: "RAnges" instead of "Ranges").
6. **Unused Write method in TSVSettingsWindow**: The `c1GridGlobal_CellChanged` and `gridChannels_CellChanged` methods are empty event handlers.
7. **Hardcoded manufacturer**: In `DDASChannel.Serialize`, the manufacturer is hardcoded as `"CHRYSLER"` and sensor type as `"UNKNOWN"`.
8. **Commented-out code in DDASChannel.Serialize**: There is commented-out code for CFC frequency calculation that was apparently replaced with direct use of `channel.ParentModule.AaFilterRateHz`.
9. **File extension inconsistency**: The `File` class defines `Extension` as `".ddas"`, but `DDASChannel` generates `.fpd` files (floating point data) in its default path construction.

89
docs/ai/Common/DTS.Common.Serialization/DDAS (Chrysler)/FromChrysler.md Normal file
View File

@@ -0,0 +1,89 @@
---
source_files:
- Common/DTS.Common.Serialization/DDAS (Chrysler)/FromChrysler/ChannelDefinition.h
- Common/DTS.Common.Serialization/DDAS (Chrysler)/FromChrysler/FilePath.h
- Common/DTS.Common.Serialization/DDAS (Chrysler)/FromChrysler/DDASTestDefinition.h
- Common/DTS.Common.Serialization/DDAS (Chrysler)/FromChrysler/DataFloat.h
generated_at: "2026-04-17T15:36:51.829395+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "39b9f7039a4c0cc0"
---
# DDAS (Chrysler) Serialization Module Documentation
## 1. Purpose
This module provides data structures and utilities for the DaimlerChrysler DDAS (Dynamic Data Acquisition System) file format. It defines the binary layout for test definitions, channel configurations, transducer data, and floating-point data files used in crash test data acquisition. The module handles serialization of test configurations, channel definitions, and acquired data, serving as the bridge between proprietary DDAS hardware and software analysis tools.
---
## 2. Public Interface
### ChannelDefinition.h
**Structures:**
- `CHANNEL` / `PCHANNEL` / `PCHAN` — A 64-bit aligned structure representing a data acquisition channel.
- `short Size` — Size of the object
- `short Flags` — Channel flags (bitfield)
- `char Name[64]` — Channel name
- `char Sign[8]` — Sign indicator (+, -, or blank)
- `char Axis[8]` — Axis identifier (X, Y, Z, FX, MX, AX, etc.)
- `float FilterFreq` — Filter frequency in Hz
- `float SetGain` — Configured gain setting
- `float ActGain` — Actual/measured gain
- `float Rcal` — Shunt calibration resistance
- `float Excitation` — Excitation voltage
- `byte byteSpares[4]` — Spare bytes (formerly `CalDate`)
- `TRANSDUCER Transducer` — Embedded transducer snapshot
**Enumerations:**
- `ChannelFlags` — Contains `CHANFLAG_ACTIVE`
**Macros:**
- `ISCHANACTIVE(pChan)` — Returns 1 if channel active flag is set
- `SETCHANACTIVE(pChan)` — Sets channel active flag
- `CLRCHANACTIVE(pChan)` — Clears channel active flag
---
### FilePath.h
**Class: `CFilePath`**
File path manipulation utility with the following public methods:
| Method | Signature | Description |
|--------|-----------|-------------|
| `CFilePath` | `()` | Constructor |
| `~CFilePath` | `() virtual` | Virtual destructor |
| `operator=` | `(const CFilePath &src)` | Assignment operator |
| `Clear` | `void ()` | Clears all path components |
| `SetDrive` | `int (int nDriveAis1)` | Sets drive by number (A=1) |
| `SetDriveOrResource` | `int (char *szNewDrive, int* nNext)` | Sets drive or network resource |
| `SetDir` | `int (char *szNewDir, int* nNext)` | Sets directory component |
| `SetFile` | `int (char *szNewFile, int *nNext)` | Sets filename component |
| `SetExtension` | `int (char *szNewExt)` | Sets file extension |
| `SetFullFilePathAndName` | `int (char* szPathAndName)` | Parses and sets complete path |
| `ParseFilePathAndName` | `int (char *szPathAndName)` | Parses path into components |
| `GetFullFilePathAndName` | `const char* ()` | Returns complete path string |
| `GetFileName` | `const char* ()` | Returns filename without extension |
| `GetFileNameExt` | `const CString ()` | Returns filename with extension |
| `GetFileExtension` | `const char* ()` | Returns file extension |
| `FileExists` | `BOOL ()` | Checks if file exists on disk |
| `IsFileType` | `bool (char *szFileTypeExt)` | Validates file extension matches |
| `IsPathComplete` | `bool (int *pFlgValid)` | Checks if path is fully specified |
| `IsFileValid` | `bool (const char* szFileSpec, const char *szFileTypeExt, CString* pcsError)` | Validates file specification |
| `IsAllValidChars` | `bool (char* szInString, int* pnPosBad)` | Validates characters in string |
**Enumerations:**
- `FileSpecOK` — Bitmask flags for path validation:
- `FSPEC_EXTOK = 0x1` — Extension valid
- `FSPEC_NAMEOK = 0x2` — Filename valid
- `FSPEC_PATHOK = 0x4` — Path valid
- `FSPEC_ROOTOK = 0x8` — Drive/computer valid
- `FSPEC_REL

106
docs/ai/Common/DTS.Common.Serialization/FIAT_ASC.md Normal file
View File

@@ -0,0 +1,106 @@
---
source_files:
- Common/DTS.Common.Serialization/FIAT_ASC/FIAT_Asc.File.cs
- Common/DTS.Common.Serialization/FIAT_ASC/FIAT_Asc.File.Writer.cs
generated_at: "2026-04-17T15:42:04.516508+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "89485aa6a1ed05a2"
---
# Documentation: DTS.Serialization.FIAT_ASC
## 1. Purpose
This module provides serialization support for exporting `DTS.Serialization.Test` objects to FIAT `.asc` file format. It creates one `.asc` file per channel, writing time-series data with headers containing start time, sample interval, and data collection length. The module handles data scaling (ADC to Engineering Units), optional subsampling, filtering, and provides progress reporting events for long-running export operations.
---
## 2. Public Interface
### `DTS.Serialization.FIAT_ASC.File` (partial class)
**Inheritance:** `Serialization.File`, implements `IWritable<Test>`
| Member | Signature | Description |
|--------|-----------|-------------|
| `Extension` | `public static string Extension => ".asc"` | Static property returning the file extension for this format. |
| `UseFlatExportFolders` | `public bool UseFlatExportFolders { get; set; }` | Controls whether exports use flat folder structure. Defaults to `false`. |
| `File()` | `public File()` | Constructor initializing the file type with identifier "ASC". |
| `Exporter` | `public IWriter<Test> Exporter { get; }` | Lazily initializes and returns a `Writer` instance for exporting tests. Creates the writer with `DefaultEncoding` and propagates `UseFlatExportFolders`. |
---
### `DTS.Serialization.FIAT_ASC.File.Writer` (nested partial class)
**Inheritance:** `Writer<File>`, implements `IWriter<Test>`
| Member | Signature | Description |
|--------|-----------|-------------|
| `OnBegin` | `public event BeginEventHandler OnBegin` | Event raised when writing starts. |
| `OnEnd` | `public event EndEventHandler OnEnd` | Event raised when writing completes. |
| `OnTick` | `public event TickEventHandler OnTick` | Event raised for progress updates (every 1000 data samples). |
| `OnCancel` | `public event CancelEventHandler OnCancel` | Event raised if the write is cancelled. |
| `OnError` | `public event ErrorEventHandler OnError` | Event raised if a fatal error occurs during writing. |
| `FilteredChannelData` | `public Dictionary<string, FilteredData> FilteredChannelData { get; set; }` | Dictionary mapping channel IDs to filtered data. Used when `Filtered` is `true`. |
| `UseFlatExportFolder` | `public bool UseFlatExportFolder { get; set; }` | Controls flat folder export behavior. Defaults to `false`. |
| `Start` | `public double Start { get; set; }` | Start time for export range. Defaults to `0D`. |
| `Stop` | `public double Stop { get; set; }` | Stop time for export range. Defaults to `0D`. |
| `SubSampleInterval` | `public ushort SubSampleInterval { get; set; }` | Interval for subsampling data. Defaults to `1` (no subsampling). |
| `Filtered` | `public bool Filtered { get; set; }` | Whether to use filtered channel data. Defaults to `true`. |
| `Write` (overload 1) | `public void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)` | Simplified write method delegating to the full overload with null parameters. |
| `Write` (overload 2) | `public void Write(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested, double minStartTime, int dataCollectionLength)` | Full write method that exports all channels to individual `.asc` files. Creates one file per channel named after the channel. |
| `Initialize` | `public void Initialize(...)` | Empty implementation (no-op). |
---
## 3. Invariants
1. **One file per channel:** The `Write` method creates a separate `.asc` file for each channel in `test.Channels`, named using the channel name (sanitized for filesystem compatibility).
2. **Progress tick granularity:** Progress events are dispatched every `DataSamplesPerTick` (1000) samples written.
3. **File format structure:** Each `.asc` file contains:
- Line 1: `{minStartTime} {1/sampleRate}` (both formatted as `F8`)
- Line 2: `{dataCollectionLength}` (integer)
- Subsequent lines: Data values, one per sample
4. **Channel name resolution:** For `AnalogInputChannel`, the channel name is taken from `Description` property; otherwise `ChannelName2` is used.
5. **Encoding fallback:** If `GetEncoding(DefaultEncoding)` fails, the writer falls back to `Encoding.Default`.
6. **Subsampling only applies when `SubSampleInterval > 1`:** When this condition is met, data is subsampled using `NHTSASubSample<T>`.
---
## 4. Dependencies
### This module depends on:
- `DTS.Common.DAS.Concepts` - For channel types and DAS concepts
- `DTS.Common.Enums.Sensors` - For `SensorConstants.BridgeType`, `ZeroMethodType`, `IsoViewMode`
- `DTS.Common.Utilities` - For `DiskUtility`, `DataScaler`
- `DTS.Common.Utilities.DotNetProgrammingConstructs` - For `Property<T>` wrapper
- `DTS.Common.Utilities.Logging` - For `APILogger`
- `DTS.Serialization.Test` - The `Test` object model being serialized
- `System.Windows.Forms` - For `Application.DoEvents()` during progress reporting
### What depends on this module:
- Not determinable from source alone; consumers would reference `DTS.Serialization.FIAT_ASC` namespace and use `File.Exporter.Write(...)`.
---
## 5. Gotchas
1. **`Initialize` is a no-op:** The `Initialize` method has an empty body despite accepting many parameters. It is unclear if this is intentional or incomplete.
2. **UI thread coupling:** The `WriteChannelInfo` method calls `System.Windows.Forms.Application.DoEvents()` during the write loop, creating a dependency on Windows Forms and potentially causing reentrancy issues.
3. **Unused parameters in `Write` overload 2:** Several parameters (`dataFolder`, `fd`, `tmChannel`, `channelNumber`) are passed to the full `Write` method but never used in the implementation.
4. **Channel name fallback logic:** The `OriginalChannelName` fallback for `AnalogInputChannel` depends on `ISOViewMode`, but the source of `WriterParent.ISOViewMode` is not defined in these files (likely defined in another partial file).
5. **Exception swallowed in `SetWindowAverageADC`:** The `WriteChannelInfo` method catches and silently ignores any exception from `scaler.SetWindowAverageADC(channel.WindowAverageADC)`.
6. **Hardcoded number format:** All numeric output uses `"F8"` format (8 decimal places), defined as a private constant `NUMBER_FORMAT`.
7. **Disk space check may silently fail:** If `GetDiskFreeSpaceEx` returns a non-zero error code, the method logs the error but proceeds with the write without validating available space.

154
docs/ai/Common/DTS.Common.Serialization/FtssCsv.md Normal file
View File

@@ -0,0 +1,154 @@
---
source_files:
- Common/DTS.Common.Serialization/FtssCsv/FtssCsv.File.cs
- Common/DTS.Common.Serialization/FtssCsv/FtssTsv.File.cs
- Common/DTS.Common.Serialization/FtssCsv/FtssTsv.File.Writer.cs
generated_at: "2026-04-17T15:38:52.319168+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "75b02305d1c7a319"
---
# Documentation: DTS.Serialization.FtssCsv / FtssTsv
## 1. Purpose
This module provides file serialization support for FTSS (presumably "Flight Test Data System" or similar) CSV and TSV (Tab-Separated Values) export formats. It enables writing `Test` objects to delimited text files with extensive metadata headers and channel data. The module implements a writer pattern with progress reporting events and supports features like data filtering, subsampling, and disk space verification before export.
---
## 2. Public Interface
### FtssCsv.File Class
**Namespace:** `DTS.Serialization.FtssCsv`
**Inheritance:** `Serialization.File`, `IWritable<Test>`
| Member | Signature | Description |
|--------|-----------|-------------|
| `File()` | `public File()` | Constructor initializing the file with "CSV" format type. |
| `Extension` | `public static string Extension` | Static property returning `".csv"`. |
| `Exporter` | `public IWriter<Test> Exporter` | Lazily instantiates and returns a `Writer<Test>` for exporting test data. Uses `DefaultEncoding`. |
### FtssTsv.File Class
**Namespace:** `DTS.Serialization.FtssTsv`
**Inheritance:** `Serialization.File`, `IWritable<Test>`
| Member | Signature | Description |
|--------|-----------|-------------|
| `File()` | `public File()` | Constructor initializing the file with "TSV" format type. |
| `Extension` | `public static string Extension` | Static property returning `".tsv"`. |
| `Exporter` | `public IWriter<Test> Exporter` | Lazily instantiates and returns a `Writer<Test>` for exporting test data. Uses `DefaultEncoding`. |
### FtssTsv.File.Writer Class
**Namespace:** `DTS.Serialization.FtssTsv`
**Inheritance:** `Writer<File>`, `IWriter<Test>`
#### Constructor
| Signature | Description |
|-----------|-------------|
| `internal Writer(File fileType, int encoding)` | Internal constructor; requires associated `File` instance and encoding integer. |
#### Enum: ExportMode
```csharp
public enum ExportMode
{
FtssExcel,
Ttc,
Standard,
}
```
#### Events
| Event | Type | Description |
|-------|------|-------------|
| `OnBegin` | `BeginEventHandler` | Notifies subscribers that write is starting. |
| `OnEnd` | `EndEventHandler` | Notifies subscribers that write is finished. |
| `OnTick` | `TickEventHandler` | Notifies subscribers of progress (one tick per 1000 data samples). |
| `OnCancel` | `CancelEventHandler` | Notifies subscribers that write was cancelled. |
| `OnError` | `ErrorEventHandler` | Notifies subscribers of fatal errors. |
#### Properties
| Property | Type | Description |
|----------|------|-------------|
| `CurrentExportMode` | `ExportMode` | Gets/sets the current export format. Defaults to `ExportMode.FtssExcel`. |
| `FilteredChannelData` | `List<FilteredData>` | Filtered channel data to use instead of raw data. |
| `DataChannelFilename` | `string` | Filename identifying the data channel to export. |
| `LaboratoryName` | `string` | Laboratory metadata for header. |
| `LaboratoryContactName` | `string` | Contact name for header. |
| `LaboratoryContactPhone` | `string` | Contact phone for header. |
| `LaboratoryContactEmail` | `string` | Contact email for header. |
| `TestEngineerName` | `string` | Engineer name for header. |
| `TestEngineerPhone` | `string` | Engineer phone for header. |
| `TestEngineerEmail` | `string` | Engineer email for header. |
| `NumChannelsWritten` | `int` | Counter for channels written. |
| `UseISOCodeFilterMapping` | `bool` | Whether to adjust ISO codes based on filter class. |
| `UseZeroForUnfiltered` | `bool` | Whether to use zero for unfiltered data in ISO code mapping. |
| `Start` | `double` | Export start time (default: 0D). |
| `Stop` | `double` | Export stop time (default: 0D). |
| `SubSampleInterval` | `ushort` | Subsampling interval for data export. |
| `Filtered` | `bool` | Whether filtered data is being exported. |
#### Methods
| Method | Signature | Description |
|--------|-----------|-------------|
| `Write` | `public void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)` | Simplified write method delegating to the full overload. |
| `Write` | `public void Write(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested, double minStartTime, int dataCollectionLength)` | Full write method with all parameters. Creates directory if needed, deletes existing file, writes header and data. Only `ExportMode.FtssExcel` is currently supported. |
| `Initialize` | `public void Initialize(...)` | Empty implementation (no-op). |
| `WriteChannelInfo` | `protected void WriteChannelInfo(StreamWriter fileWriter, string id, Test test, List<FilteredData> filteredData, string targetPath, TickEventHandler tickEventHandler, uint totalWriteTicksNeeded, ref uint totalWriteTicksDispatched, CancelRequested cancelRequested, int channelNumber, double minStartTime, int dataCollectionLength)` | Writes header lines and channel data to the stream. Handles subsampling, scaling, and filtering. |
#### Enum: FtssHeaderLine (Private)
Defines 31 header line types including: `Headers`, `TestDate`, `TestTime`, `TestId`, `TestDescription`, `LaboratoryName`, `SampleRate`, `HardwareAntiAliasFilter`, `DataChannelName`, `IsoCode`, `ChannelDescription`, `ChannelLocation`, `SensorSerialNumber`, `SoftwareFilter`, `SoftwareFilterDb`, `EngineeringUnits`, `UserComment`, `PreZero`, `PostZero`, `DataZero`, `ScaleEu`, `ScaleMv`, `DataStart`, `Labels`.
---
## 3. Invariants
1. **Exporter Lazy Initialization**: The `_Exporter` field is lazily initialized; once created, it is reused for subsequent accesses.
2. **Only FtssExcel ExportMode Supported**: The `Write` method throws `NotSupportedException` for any `CurrentExportMode` other than `ExportMode.FtssExcel`.
3. **Tab Separator**: The TSV format uses `"\t"` (TAB) as the list separator constant.
4. **Number Format**: All numeric data values are formatted using `"F8"` (8 decimal places).
5. **Progress Granularity**: Progress ticks are dispatched every 1000 data samples (`DataSamplesPerTick`).
6. **Single Channel Export**: The `WriteChannelInfo` method exports only the channel whose filename matches `DataChannelFilename`; it breaks after finding the first match.
7. **Directory Creation**: If the target directory does not exist, it will be created automatically during `Write`.
8. **File Overwrite**: If the target file exists, it will be deleted (or moved if deletion fails) before writing.
---
## 4. Dependencies
### This Module Depends On:
- `System` (Collections.Generic, ComponentModel, Linq, IO, Text)
- `DTS.Common.DAS.Concepts` (including `DTS.Common.DAS.Concepts.DAS.Channel`)
- `DTS.Common.Utilities`
- `DTS.Common.Utilities.DotNetProgrammingConstructs`
- `DTS.Common.Utilities.Logging`
- `DTS.Common`
- `DTS.Common.Enums.Sensors`
- `DTS.Common.Utils`
- `System.Windows.Forms.Application` (for `DoEvents()` during progress reporting)
- Base class `Serialization.File` (inferred from inheritance)
- Interface `IWritable<Test>` (inferred from implementation)
- Types: `Test`, `Test.Module.Channel`, `Test.Module.AnalogInputChannel`, `FilteredData`, `DataScaler`, `NHTSASubSample<T>`, `Property<T>`, `DescriptionAttributeCoder<T>`, `DiskUtility`, `FileUtils`, `APILogger`, `UserException`, `Exception` (custom DTS type)
### What Depends On This Module:
- Not determinable from the provided source alone.
---
## 5. Gotchas
1. **UI Thread Coupling**: The `WriteChannelInfo` method calls `System.Windows.Forms.Application.DoEvents()` during the write loop, creating a dependency on Windows Forms and implying the write may be intended to run on a UI thread.
2. **Empty Initialize Method**: The `Initialize` method has an empty body despite accepting numerous parameters. It is unclear if this is intentional or incomplete.
3. **Unused ExportMode Values**: `ExportMode.Ttc` and `ExportMode.Standard` are defined but throw `NotSupportedException` if used.
4. **Exception Wrapping**: All exceptions are caught and re-thrown wrapped in a custom `Exception` type with descriptive messages, potentially obscuring original stack traces.
5. **Hardcoded Channel Selection**: The `WriteChannelInfo` method filters channels by comparing `Path.GetFileName(((Test.Module.AnalogInputChannel)ch).FileName)` to `DataChannelFilename`. If no channel matches, the export proceeds with empty channel data.
6. **Subsampling Side Effect**: When `SubSampleInterval > 1`, the method modifies `FilteredChannelData[iChannel].Data` and `ChannelList[iChannel].PersistentChannelInfo.Data` in-place, mutating the input test data.
7. **PreZero/PostZero Calculation Edge Cases**: The code clamps `preTriggerSamples` to be non-negative, not exceed `NumberOfSamples`, and not exceed `Start * sampleRate`, but the logic may produce unexpected results if `Start` is not properly set.
8. **Missing CSV Writer Implementation**: The `FtssCsv.File` class references a `Writer` class, but no `FtssCsv.File.Writer.cs` is provided. It is unclear whether this shares the TSV writer or has a separate implementation.

172
docs/ai/Common/DTS.Common.Serialization/HDF.md Normal file
View File

@@ -0,0 +1,172 @@
---
source_files:
- Common/DTS.Common.Serialization/HDF/HDF.File.cs
- Common/DTS.Common.Serialization/HDF/HDF.File.Writer.cs
generated_at: "2026-04-17T15:42:12.245646+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "ac9e3ba44d6e91d0"
---
# Documentation: DTS.Serialization.HDF.File
## 1. Purpose
This module provides HDF5 (Hierarchical Data Format) file export functionality for test data. It implements the `Serialization.File` abstraction for HDF5 format, enabling the serialization of `Test` objects—including channel data (ADC, mV, EU), metadata, and auxiliary files (logs, reports, setup files)—into `.h5` files. The module serves as the export layer for DTS data acquisition systems, supporting both standard and WIAMan-compliant output formats.
---
## 2. Public Interface
### Class: `DTS.Serialization.HDF.File`
**Inheritance:** `Serialization.File`, `IWritable<Test>`
#### Constructor
```csharp
public File()
```
Initializes a new HDF file instance, passing `"HDF"` to the base class.
#### Property: `Exporter`
```csharp
public IWriter<Test> Exporter { get; }
```
Lazy-initialized property that returns the `IWriter<Test>` implementation. Creates and caches a new `Writer` instance on first access. Throws `Exception` wrapping any underlying failure.
#### Set-Only Properties (delegate to internal `Writer`)
| Property | Type | Description |
|----------|------|-------------|
| `ExportADC` | `bool` | Controls whether ADC (raw) data is exported |
| `ExportEU` | `bool` | Controls whether Engineering Units data is exported |
| `ExportMV` | `bool` | Controls whether millivolt data is exported |
| `ExportLogs` | `bool` | Controls whether log files are included |
| `ExportReports` | `bool` | Controls whether report files are included |
| `ExportSetup` | `bool` | Controls whether setup files are included |
| `ExportDTSFile` | `bool` | Controls whether `.dts` files are included |
| `CustomerName` | `string` | Customer metadata for export |
| `TestEngineerName` | `string` | Test engineer metadata for export |
| `LabName` | `string` | Lab name metadata for export |
| `IsWiamanData` | `bool` | Flag for WIAMan-format data |
| `ISOToFineLocation3` | `Dictionary<string, string>` | ISO code to fine location mapping |
| `ISOToPhysicalDimension` | `Dictionary<string, string>` | ISO code to physical dimension mapping |
| `ISOToPosition` | `Dictionary<string, string>` | ISO code to position mapping |
| `ISOToTransducerMainLocation` | `Dictionary<string, string>` | ISO code to transducer location mapping |
---
### Nested Class: `DTS.Serialization.HDF.File.Writer`
**Inheritance:** `Writer<File>`, `IWriter<Test>`
#### Constructor
```csharp
internal Writer(File fileType, int encoding)
```
Internal constructor. Initializes all export flags to `true` by default and stores reference to parent `File`.
#### Method: `Write` (primary overload)
```csharp
public void Write(string pathname,
string id,
string dataFolder,
Test test,
bool bFiltering,
bool includeGroupNameInISOExport,
FilteredData fd,
Test.Module.Channel tmChannel,
int channelNumber,
BeginEventHandler beginEventHandler,
CancelEventHandler cancelEventHandler,
EndEventHandler endEventHandler,
TickEventHandler tickEventHandler,
ErrorEventHandler errorEventHandler,
CancelRequested cancelRequested,
double minStartTime,
int dataCollectionLength)
```
Main export method. Creates an HDF5 file at `{pathname}/{id}_{LabName}_1of1{ExtensionPrefix}.h5`, writes channel data (ADC/MV/EU based on export flags), includes auxiliary files, and invokes progress/event handlers throughout.
#### Method: `Write` (secondary overload)
```csharp
public void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)
```
Empty implementation—does nothing.
#### Method: `Initialize`
```csharp
public void Initialize(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested)
```
Empty implementation—does nothing.
#### Property: `ExtensionPrefix`
```csharp
public string ExtensionPrefix { get; set; } = string.Empty
```
Optional prefix appended before `.h5` extension in output filename.
#### Enum: `ErrorLocation`
```csharp
public enum ErrorLocation { File, Group, SubGroup, DataSpace, DataSet, Write }
```
Identifies where HDF API calls fail for error reporting.
---
## 3. Invariants
1. **Exporter Lazy Initialization**: The `_exporter` field is lazily initialized; once set, the same instance is returned on subsequent accesses.
2. **Default Export Flags**: All export flags (`ExportADC`, `ExportEU`, `ExportMV`, `ExportLogs`, `ExportReports`, `ExportSetup`) default to `true` in the `Writer` constructor.
3. **Attribute Storage Format**: All attributes are stored as HDF5 string attributes when `ATTRIBUTE_STRING_DATATYPE_ONLY` is `true` (which is constant `true`). Integer, ulong, and double values are converted to strings via `ToString()` before storage.
4. **Channel Ordering**: Channels are sorted by `AbsoluteDisplayOrder` before export.
5. **Thread Safety**: The `H5WriteLock` object is used to synchronize HDF5 API calls for string attribute creation. The `_updateProgressLock` object synchronizes progress updates.
6. **HDF Export Version**: All exports include attribute `HDFExportVersion` set to `7.0D`.
7. **Dataset Group Names**:
- EU data: `/Datasets_EU`
- ADC data: `/Datasets`
- MV data: `/Datasets_MV`
---
## 4. Dependencies
### This Module Depends On:
- `System` (core .NET)
- `System.Collections.Generic`
- `System.IO`
- `System.Linq`
- `System.Runtime.InteropServices`
- `System.Threading.Tasks`
- `DTS.Common.Enums.Sensors` - `SensorConstants.BridgeType.IEPE`
- `DTS.Common.Utilities.Logging` - `APILogger.Log()` for error logging
- `HDF.PInvoke` - Low-level HDF5 API (`H5F`, `H5G`, `H5S`, `H5D`, `H5A`, `H5T`, `H5P`)
- `DTS.Common.DAS.Concepts` - `DataScaler`, `Test`, `Test.Module`, `Test.Module.AnalogInputChannel`, `Test.Module.Channel.Sensor`
### Base Class:
- `DTS.Serialization.File` (inferred from inheritance)
- `DTS.Serialization.Writer<File>` (inferred from `Writer` inheritance)
- `DTS.Serialization.IWriter<Test>` (interface implementation)
---
## 5. Gotchas
1. **Set-Only Properties Cast to Concrete Type**: Properties like `ExportADC`, `ExportEU`, etc. on the `File` class cast `Exporter` to `(Writer)` on every set. This will throw if `_exporter` is somehow a different implementation.
2. **Empty Method Implementations**: The `Write` overload with fewer parameters and `Initialize` method are empty stubs. Calling them has no effect.
3. **WIAMan Dictionary Access Without Null Check**: In `CreateDataset()`, the code accesses ISO mapping dictionaries (e.g., `ISOToFineLocation3[aic.IsoCode]`) without null checks. If these dictionaries are not set or lack the key, a `KeyNotFoundException` or `NullReferenceException` will occur.
4. **Hardcoded Directory Traversal**: `AddDirectoryIfExists()` navigates up three parent directories from the binary path to find the root directory. This assumes a specific directory structure depth.
5. **Progress Update Threading**: Progress updates use a lock but the `_curProg` field is read outside the lock in `UpdateProgress()` before the comparison.
6. **Unused Parameters**: Several parameters in `Write()` are unused: `bFiltering`, `includeGroupNameInISOExport`, `fd`, `tmChannel`, `channelNumber`, `cancelEventHandler`, `cancelRequested`, `minStartTime`, `dataCollectionLength`.
7. **File Overwrite**: The HDF5 file is created with `H5F.ACC_TRUNC` which truncates (overwrites) any existing file with the same name.
8. **Channel Type Filtering**: Only `Test.Module.AnalogInputChannel` types are processed; other channel types are silently skipped in the `Parallel.ForEach` loop.

182
docs/ai/Common/DTS.Common.Serialization/IRIGCH10.md Normal file
View File

@@ -0,0 +1,182 @@
---
source_files:
- Common/DTS.Common.Serialization/IRIGCH10/Chapter10.File.cs
- Common/DTS.Common.Serialization/IRIGCH10/WriteTest.cs
- Common/DTS.Common.Serialization/IRIGCH10/CH10AnalogStreamDecode.cs
- Common/DTS.Common.Serialization/IRIGCH10/Chapter10File.cs
- Common/DTS.Common.Serialization/IRIGCH10/Chapter10.File.Writer.cs
generated_at: "2026-04-17T15:37:12.585375+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "1f5b2482ec8c69d4"
---
# Documentation: DTS.Serialization.IRIGCH10
## 1. Purpose
This module provides serialization support for the IRIG 106 Chapter 10 (CH10) data format, enabling both parsing of CH10 binary files and writing new CH10 files from test data. It handles packet-level parsing with CRC validation, real-time UDP multicast stream decoding for live data acquisition, and TMATS (Telemetry Attributes Transfer Standard) document generation. The module supports both PCM and Analog data formats for export operations.
---
## 2. Public Interface
### `File` (partial class) - `Chapter10.File.cs`
A partial class extending `Serialization.File` that provides CH10 file handling capabilities.
```csharp
public File() // Constructor - initializes base with "Chapter10" type
public IWriter<Test> Exporter { get; } // Lazy-initialized writer instance
```
### `CH10AnalogStreamDecode` - `CH10AnalogStreamDecode.cs`
Listens for UDP multicast streams containing CH10 packet data and dispatches parsed packets to registered handlers.
```csharp
// Properties
public string MulticastReceiveAddress { get; set; } // Default: MulticastCommandBase.DEFAULT_RECEIVE_ADDRESS
public int ResponsePort { get; set; } // Default: (int)MulticastCommandBase.Ports.Response
public IPAddress BindToAdapterIPAddress { get; set; } // Default: IPAddress.Any
// Methods
public void StartListening() // Starts UDP listener on background thread
public void StopListening() // Signals listener to stop
// Delegate types
public delegate void TimePacketDelegate(TimePacketFormat2 packet);
public delegate void AnalogDataPacketDelegate(AnalogDataFormat1Packet packet);
public delegate void TMATSPacketDelegate(TMATSPacket packet);
public delegate void BadCRCDelegate(IPacketHeader packet);
// Event handlers (assign to receive callbacks)
public BadCRCDelegate OnBadCRC;
public TimePacketDelegate OnTimePacket;
public AnalogDataPacketDelegate OnAnalogPacket;
public TMATSPacketDelegate OnTMATSPacket;
```
### `Chapter10File` - `Chapter10File.cs`
Parses CH10 binary data and provides access to extracted headers and packets. Also contains static methods for writing CH10 files.
```csharp
// Constructor - parses all packets from byte array
public Chapter10File(byte[] bytes)
// Accessors for parsed data
public ITransportStreamHeader[] GetTransportHeaders()
public IPacketHeader[] GetPacketHeaders()
public ISecondaryTimeFormatHeader[] GetSecondaryTimeHeaders()
public byte[] GetBytesForPacket(IPacketHeader packet)
// Properties
public int GoodPackets { get; } // Count of successfully parsed packets
public int RejectedPackets { get; } // Count of packets failing validation
// Static methods
public static long ReadChapter10PacketHeader(byte[] bytes, long startIndex, out IPacketHeader packetHeader)
public static long GetIndexOfNextPacket(byte[] bytes, long startIndex)
// Static write methods
public static void WriteFilePCM(string tmats, GetNextSampleDelegate getNextSample,
GetChannelLengthDelegate getChannelLength, int totalChannels, int nanoseconds, int seconds,
double sampleRate, bool includeSecondaryHeader, string fileName,
TickEventHandler tickEventHandler, object tickObject)
public static void WriteFileAnalog(string tmats, GetNextSampleDelegate getNextSample,
GetChannelLengthDelegate getChannelLength, int totalChannels, int nanoseconds, int seconds,
double sampleRate, bool includeSecondaryHeader, string fileName,
TickEventHandler tickEventHandler, object tickObject)
// Delegates for write operations
public delegate short GetNextSampleDelegate(int channelIdx);
public delegate long GetChannelLengthDelegate(int channelIndex);
```
### `File.Writer` (nested class) - `Chapter10.File.Writer.cs`
Implements `IWriter<Test>` for exporting test data to CH10 format.
```csharp
// Constructor (internal)
internal Writer(File fileType, int encoding)
// Properties
public bool IncludeSecondaryHeader { get; set; } // Default: true
public bool UseAnalogFormat { get; set; } // Default: true
public bool UsePCMFormat { get; set; } // Default: false
public double Start { get; set; }
public double Stop { get; set; }
public bool Filtered { get; set; }
// Constants
public const long BASE_RTC = 141989612500056L;
// Methods
public void Write(string pathname, string id, string dataFolder, Test test,
bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd,
Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler,
CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler,
TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler,
CancelRequested cancelRequested, double minStartTime, int dataCollectionLength)
public void Initialize(string pathname, string id, string dataFolder, Test test,
bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd,
Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler,
CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler,
TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler,
CancelRequested cancelRequested)
```
---
## 3. Invariants
- **Sync Pattern Validation**: All valid CH10 packets must have `PacketHeader.EXPECTED_SYNC_PATTERN` at their sync pattern field.
- **Checksum Validation**: `packetHeader.CheckSum` must equal `packetHeader.ComputeCheckSum()` for a packet to be considered valid.
- **RTC Frequency**: Relative Time Counter operates at 10MHz (`RTC_PER_SECOND = 10000000`).
- **Time Packet Boundary**: `TimePacketFormat1` packets must always start on a second boundary.
- **Packet Ordering**: Transport headers, packet headers, and secondary time headers are stored in the order they are read.
- **Thread Safety**: `CH10AnalogStreamDecode` uses locks (`MyLock`, `LEFT_OVER_BYTES_LOCK`) for thread-safe operations.
- **Packet Target Size**: Write operations target 100ms of data per packet (sample rate divided by 10).
---
## 4. Dependencies
### This module depends on:
- `DTS.Common.Utilities.Logging` - `APILogger` for logging
- `DTS.Common.Utils` - `FileUtils`, `NetworkUtils`, `PTP1588Timestamps`
- `DTS.Common` - `Constants.NANOS_PER_SECOND`
- `DTS.DASLib.Command.SLICE.MulticastCommands` - `MulticastCommandBase` for default multicast settings
- `DTS.Serialization.IRIGCH10.Packets` - Packet types (`TMATSPacket`, `AnalogDataFormat1Packet`, `TimePacketFormat1`, `TimePacketFormat2`, `PCMDataPacket`, etc.)
- `DTS.Common.DAS.Concepts` - `Channel`, `AnalogInputChannel`
- `DTS.Common.Enums` - `IsoViewMode`
- `IRIGCh10` - External library for CH10 types
- `SliceRaw.File.Reader` - `GetDataScaler` method for channel data scaling
- File system templates at `TMTTemplates\` directory
### What depends on this module:
- Cannot be determined from source alone; no downstream consumers are visible in these files.
---
## 5. Gotchas
1. **NotImplementedException**: The `Write(string pathname, string id, Test test, ...)` overload in `File.Writer` throws `NotImplementedException`. Use the full overload with all parameters instead.
2. **Arbitrary RTC Base**: `BASE_RTC` (141989612500056L) is documented as "made up" and arbitrary. The comment states: "we don't really have an RTC, so we make up one with an arbitrary value."
3. **File Template Dependency**: TMATS generation depends on external template files:
- `TMTTemplates\S6ATMTTemplate_PCM_ExportBase.tmt`
- `TMTTemplates\S6ATMTTemplate_PCM_ExportChannel.tmt`
- `TMTTemplates\S6ATMTTemplate_ANALOG_ExportBase.tmt`
- `TMTTemplates\S6ATMTTemplate_ANALOG_ExportChannel.tmt`
These must exist at runtime or TMATS generation will fail.
4. **Channel Naming Side Effect**: `GetChannelName()` depends on `IsoViewModeStatic.ViewMode`, a static/global state that affects channel naming behavior.
5. **BinaryReader Cleanup**: The `Write` method opens `BinaryReader` instances per channel. If an exception occurs before `CloseAndDisposeReaders` is called, readers may leak. The method does attempt cleanup in a finally block via `endEventHandler` invocation, but explicit reader disposal is not guaranteed on all error paths.
6. **Leftover Bytes Handling**: `CH10AnalogStreamDecode.QueueBytes()` has a bug - it copies data into `newBytes` but then assigns `bytes` (the input parameter) to `_leftOvertBytes` instead of `newBytes`. This may cause data loss in stream parsing.
7. **WriteTest.cs is Commented Out**: The entire `WriteTest` class is commented out, suggesting it may be obsolete or under development.

55
docs/ai/Common/DTS.Common.Serialization/IRIGCH10/Attributes.md Normal file
View File

@@ -0,0 +1,55 @@
---
source_files:
- Common/DTS.Common.Serialization/IRIGCH10/Attributes/DescriptionDecoder.cs
- Common/DTS.Common.Serialization/IRIGCH10/Attributes/PacketHeaderValueAttribute.cs
- Common/DTS.Common.Serialization/IRIGCH10/Attributes/DataTypeVersionValueAttribute.cs
generated_at: "2026-04-17T15:40:03.278067+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "62884204c246cc16"
---
# Documentation: IRIG Chapter 10 Attribute Utilities
## 1. Purpose
This module provides attribute-based metadata extraction utilities for IRIG 106 Chapter 10 data serialization. It enables annotating enum values with descriptive strings, max lengths, packet header values, and data type version numbers—metadata used when generating TMATS (Telemetry Attributes Transfer Standard) files and processing Chapter 10 packet structures. The module serves as a bridge between .NET enum definitions and their corresponding binary protocol representations as defined in the IRIG 106 Chapter 10 specification.
---
## 2. Public Interface
### `DescriptionDecoder` (static class)
**Namespace:** `IRIGCh10`
| Method | Signature | Description |
|--------|-----------|-------------|
| `GetDescription` | `public static string GetDescription(Enum value)` | Retrieves the `DescriptionAttribute` value from an enum member. Returns the description string if the attribute is present; otherwise returns `value.ToString()`. |
### `MaxLengthDecoder` (static class)
**Namespace:** `IRIGCh10`
| Method | Signature | Description |
|--------|-----------|-------------|
| `GetMaxLength` | `public static int GetMaxLength(Enum value)` | Retrieves the `MaxLengthAttribute` length value from an enum member. Returns the length if the attribute is present; otherwise returns `0`. |
### `PacketHeaderValueAttribute`
**Namespace:** `DTS.Serialization.IRIGCh10.Attributes`
| Member | Signature | Description |
|--------|-----------|-------------|
| `Default` (static field) | `public static readonly PacketHeaderValueAttribute Default` | Default instance initialized with `0x00`. |
| `PacketHeader` (property) | `public virtual byte PacketHeader { get; }` | Gets the packet header byte value. |
| `GetPacketHeaderValue` (static method) | `public static byte GetPacketHeaderValue(Enum value)` | Retrieves the `PacketHeaderValueAttribute` byte from an enum member. Returns the attribute value if present; otherwise returns `Default.PacketHeaderValue` (`0x00`). |
**Constructors:**
- `public PacketHeaderValueAttribute()` — Initializes with `0x00`.
- `public PacketHeaderValueAttribute(byte packetHeader)` — Initializes with the specified byte value.
### `DataTypeVersionValueAttribute`
**Namespace:** `DTS.Serialization.IRIGCh10.Attributes`
| Member | Signature | Description |
|--------|-----------|-------------|
| `Default` (static field) | `public static readonly DataTypeVersionValueAttribute Default` | Default instance initialized with `0x00`. |
| `DataTypeVersion` (

87
docs/ai/Common/DTS.Common.Serialization/IRIGCH10/Enums.md Normal file
View File

@@ -0,0 +1,87 @@
---
source_files:
- Common/DTS.Common.Serialization/IRIGCH10/Enums/Enums.cs
generated_at: "2026-04-17T15:43:02.181959+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "c232b0142638d2a2"
---
# Documentation: DTS.Serialization.IRIGCH10.Enums
## 1. Purpose
This module defines enumeration types for the IRIG 106 Chapter 10 data serialization system. It provides strongly-typed mappings between logical data type identifiers and their binary packet header representations used in flight data recording formats. The enums cover data file types, time sources, time formats, data type versions, secondary header time formats, and checksum types, all annotated with `PacketHeaderValue` attributes that specify the exact binary encoding for each value per the IRIG 106 standard.
---
## 2. Public Interface
### `DataFileDataTypes` (enum)
Defines all supported data type formats for IRIG 106 Chapter 10 packets. Each value is decorated with `[PacketHeaderValue(byte)]` and `[DataTypeVersionValue(byte)]` attributes.
**Notable defined values:**
| Value Name | Packet Header | Description |
|------------|---------------|-------------|
| `ComputerGeneratedDataFormat0` | 0x00 | User-Defined |
| `ComputerGeneratedDataFormat1` | 0x01 | Setup Record |
| `ComputerGeneratedDataFormat2` | 0x02 | Recording Events |
| `ComputerGeneratedDataFormat3` | 0x03 | Recording Index |
| `PCMDataFormat1` | 0x09 | Chapter 4 or 8 |
| `TimeDataFormat1` | 0x11 | RCC/Global Positioning System [GPS]/RTC |
| `MILSTD1553DataFormat1` | 0x19 | MIL-STD-1553B Data |
| `MILSTD1553DataFormat2` | 0x1A | 16PP194 Bus |
| `AnalogDataFormat1` | 0x21 | Analog Data |
| `DiscreteDataFormat1` | 0x29 | Discrete Data |
| `MessageDataFormat0` | 0x30 | Generic Message Data |
| `ARINC429DataFormat0` | 0x38 | ARINC-429 Data |
| `VideoDataFormat0` | 0x40 | MPEG-2/H.264 Video |
| `VideoDataFormat1` | 0x41 | ISO 13818-1 MPEG-2 |
| `VideoDataFormat2` | 0x42 | ISO 14496 MPEG-4 Part10 110 AVC/H.264 |
| `VideoDataFormat3` | 0x43 | MJPEG |
| `VideoDataFormat4` | 0x44 | MJPEG 2000 |
| `ImageDataFormat0` | 0x48 | Image Data |
| `ImageDataFormat1` | 0x49 | Still Imagery |
| `ImageDataFormat2` | 0x4A | Dynamic Imagery |
| `UARTDataFormat0` | 0x50 | UART Data |
| `IEEE1394DataFormat0` | 0x58 | IEEE 1394 Transaction |
| `IEEE1394DataFormat1` | 0x59 | IEEE 1394 Physical Layer |
| `ParallelDataFormat0` | 0x60 | Parallel Data |
| `EthernetDataFormat0` | 0x68 | Ethernet Data |
| `EthernetDataFormat1` | 0x69 | Ethernet UDP Payload |
| `TSPI_CTSDataFormat0` | 0x70 | GPS NMEA-RTCM |
| `TSPI_CTSDataFormat1` | 0x71 | EAG ACMI |
| `TSPI_CTSDataFormat2` | 0x72 | ACTTS |
| `ControllerAreaNetworkBus` | 0x78 | CAN Bus |
| `FibreChannelDataFormat0` | 0x79 | Fibre Channel Data |
Many additional values (Format0, Format2-Format7 variants for each category) are marked as "Reserved for future use."
---
### `TimeSource` (enum)
Defines the origin of time information in recordings.
| Value Name | Packet Header | Description |
|------------|---------------|-------------|
| `Internal` | 0x00 | Time derived from a clock in the recorder |
| `External` | 0x01 | Time derived from a clock not in the recorder |
| `InternalFromRMM` | 0x02 | Internal from RMM (Time derived from the clock in the RMM) |
| `None` | 0x0F | None |
---
### `TimeFormats` (enum)
Defines supported time encoding formats.
| Value Name | Packet Header | Description |
|------------|---------------|-------------|
| `IRIGB` | 0x00 | IRIG-B |
| `IRIGA` | 0x01 | IRIG-A |
| `IRIGG` | 0x02 | IRIG-G |
| `RTC` | 0x03 | Real-Time Clock |
| `UTC` | 0x04

256
docs/ai/Common/DTS.Common.Serialization/IRIGCH10/Packets.md Normal file
View File

@@ -0,0 +1,256 @@
---
source_files:
- Common/DTS.Common.Serialization/IRIGCH10/Packets/ITransportStreamHeader.cs
- Common/DTS.Common.Serialization/IRIGCH10/Packets/ISecondaryTimeFormatHeader.cs
- Common/DTS.Common.Serialization/IRIGCH10/Packets/TransportStreamHeader.cs
- Common/DTS.Common.Serialization/IRIGCH10/Packets/SecondaryTimeFormatHeader.cs
- Common/DTS.Common.Serialization/IRIGCH10/Packets/TimeDataPacket.cs
- Common/DTS.Common.Serialization/IRIGCH10/Packets/TMATSPacket.cs
- Common/DTS.Common.Serialization/IRIGCH10/Packets/RootRecorderIndexPacket.cs
- Common/DTS.Common.Serialization/IRIGCH10/Packets/RecorderIndexPacket.cs
- Common/DTS.Common.Serialization/IRIGCH10/Packets/TimePacketFormat2.cs
- Common/DTS.Common.Serialization/IRIGCH10/Packets/IDataPacket.cs
- Common/DTS.Common.Serialization/IRIGCH10/Packets/TimePacketFormat1.cs
- Common/DTS.Common.Serialization/IRIGCH10/Packets/AnalogDataFormat1Packet.cs
generated_at: "2026-04-17T15:30:22.882503+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "ea68d7597278f2c1"
---
# IRIG Chapter 10 Packet Serialization Module Documentation
## 1. Purpose
This module provides serialization and deserialization support for IRIG 106 Chapter 10 data packets. It implements the packet structures defined in the Chapter 10 standard for recording and playback of telemetry data, including time data packets (Format 1 and Format 2), TMATS configuration packets, analog data packets, and recorder index packets. The module serves as the foundational layer for reading and writing Chapter 10 format files, handling binary encoding, checksums, and time format conversions.
---
## 2. Public Interface
### Interfaces
#### `ITransportStreamHeader`
```csharp
public interface ITransportStreamHeader
{
int MessageFormat { get; }
int MessageType { get; }
int SequenceNumber { get; }
}
```
Defines read-only access to transport stream header fields.
#### `ISecondaryTimeFormatHeader`
```csharp
public interface ISecondaryTimeFormatHeader
{
int NanoSeconds { get; }
int Seconds { get; }
ushort Reserved { get; }
ushort CheckSum { get; }
DateTime LocalTime { get; }
}
```
Defines read-only access to secondary time format header fields.
#### `IDataPacket`
```csharp
public interface IDataPacket
{
IPacketHeader PacketHeader { get; }
uint ComputeCheckSum();
byte[] GetBytes();
void SetRTC(long rtc);
void SetDataVersion(DataTypeVersion version);
void SetChannelID(ushort channelID);
void SetSequenceNumber(ushort seq);
}
```
Defines the contract for all Chapter 10 data packets.
---
### Abstract Base Class
#### `AbstractDataPacket`
Base class for all packet types. Provides common functionality:
| Member | Signature | Description |
|--------|-----------|-------------|
| `ChannelSpecificDataWord` | `uint` property | Gets/sets the Channel Specific Data Word (CSDW). |
| `PacketHeader` | `IPacketHeader` property | Gets the packet header. |
| `ComputeCheckSum` | `uint ComputeCheckSum()` | Computes 32-bit checksum of packet data. |
| `GetRTC` | `long GetRTC()` | Returns the 10MHz Realtime Counter value. |
| `SetRTC` | `void SetRTC(long rtc)` | Sets the RTC value in both the packet and header. |
| `SetSequenceNumber` | `void SetSequenceNumber(ushort seq)` | Sets the packet sequence number. |
| `SetDataVersion` | `void SetDataVersion(DataTypeVersion version)` | Sets the data version in the header. |
| `SetChannelID` | `void SetChannelID(ushort channelID)` | Sets the channel ID in the header. |
| `GetBytes` | `virtual byte[] GetBytes()` | Serializes the packet to a byte array. |
| `BASE_RTC` | `const long = 141989612500056L` | Base RTC value constant. |
---
### Concrete Packet Classes
#### `TransportStreamHeader`
```csharp
public TransportStreamHeader(byte[] input)
public const int TRANSPORT_HEADER_LENGTH = 4;
```
Parses a 4-byte transport stream header. Extracts `MessageFormat` (bits 0-3), `MessageType` (bits 4-7), and `SequenceNumber` (bits 8-31) from the input bytes.
#### `SecondaryTimeFormatHeader`
```csharp
public SecondaryTimeFormatHeader(byte[] input)
public static byte[] GetBytes(int nanoseconds, int seconds)
public const int SECONDARY_TIME_HEADER_LENGTH = 12;
```
Parses or constructs a 12-byte secondary time header. `LocalTime` is computed as Unix epoch (1970-01-01) plus `Seconds` and `NanoSeconds` converted to ticks, then converted to local time. Constructor validates checksum and writes to `Trace` on mismatch.
#### `TimeDataPacket`
```csharp
public TimeDataPacket()
public DateTime GetDateTime()
public void SetTime(DateTime dt)
public void SetTimeSource(byte b)
public void SetTimeSource(TimeSource src)
public void SetTimeFormat(TimeFormats fmt)
```
Implements Time Data Format 1 packet. `SetTime` encodes a `DateTime` into BCD format in a 12-byte payload at positions 4-11.
#### `TimePacketFormat1`
```csharp
public TimePacketFormat1(byte sequenceNumber, DateTime packetTime, long rtc, int nanoseconds, int seconds)
```
Implements Time Data Format 1 with full IRIG time encoding. Properties include:
- `ITS` (`IRIGTimeSource` enum) - IRIG time source (bits 15-12, not serialized per comment)
- `TimeFormat` (`TimeFormats` enum) - bits 7-4
- `TimeSource` (`TimeSources` enum) - bits 3-0
- `DateFormat` (`DateFormats` enum) - bit 9
- `IsLeapYear` (`bool`) - bit 8
- `TimePacketTime` (`DateTime`) - the time represented by this packet
#### `TimePacketFormat2`
```csharp
public TimePacketFormat2(byte sequenceNumber, bool rtcSyncError, int nanoseconds, int seconds, long rtc, bool includeSecondaryHeader)
public TimePacketFormat2(byte[] bytes)
```
Implements Time Data Format 2 for network time protocols. Properties include:
- `LocalTimeOfFirstSample` (`DateTime`)
- `NetworkTimeFormat` (`NetworkTimeFormats` enum) - bits 7-4
- `TimeStatus` (`TimeStatuses` enum) - bits 3-0
- `UnsignedSeconds` (`uint`)
- `UnsignedNanoSeconds` (`uint`)
- `PTPTime` (`string`) - formatted PTP timestamp
#### `TMATSPacket`
```csharp
public TMATSPacket(int nanoseconds, int seconds, string tmatsDoc, bool secondaryHeaderPresent)
public TMATSPacket(byte[] bytes)
public string TMATSDocument { get; }
public bool XMLFormat { get; }
public bool SetupRecordConfigurationChange { get; }
public RCCChapter10Versions Chapter10Version { get; }
```
Implements TMATS (Telemetry Attributes Transfer Standard) packet. `TMATSDocument` returns ASCII-decoded content. `RCCChapter10Versions` enum maps values 0x07-0x0B to versions RCC_106_07 through RCC_106_15.
#### `AnalogDataFormat1Packet`
```csharp
public AnalogDataFormat1Packet(int nanoseconds, int seconds, Chapter10File.GetNextSampleDelegate getNextSample, int totalChannels, long channelLength, long rtc, long numSamples, long currentSample, byte sequenceNumber, ushort channelId, bool includeSecondaryHeader)
public AnalogDataFormat1Packet(byte[] bytes)
public SampleData[] Samples { get; }
```
Implements Analog Data Format 1 packet. CSDW properties:
- `Same` (bit 28)
- `Factor` (bits 27-24)
- `TotChan` (bits 23-16)
- `Subchan` (bits 15-8)
- `Length` (bits 7-2)
- `Mode` (`Modes` enum, bits 1-0)
`SampleData` inner class holds `ChannelData` as `short[]`.
#### `RecorderIndexPacket`
```csharp
public RecorderIndexPacket()
public void SetRootPacketAddress(long address)
public void AddRecordingIndex(RecordingIndex index)
public int NumberOfEntries { get; }
public DateTime GetDateTime()
public override byte[] GetBytes()
```
Implements recorder index packet. Uses hardcoded `ChannelSpecificDataWord = {0x8D, 0x02, 0x00, 0xE0}`.
#### `RootRecorderIndexPacket`
```csharp
public RootRecorderIndexPacket(DateTime dt)
public void SetRootPacketAddress(long address)
public void AddRecordingIndex(RecordingIndexIndex index)
public override byte[] GetBytes()
```
Implements root recorder index packet (last packet in file). Uses hardcoded `ChannelSpecificDataWord = {0x8D, 0x00, 0x00, 0x60}`.
#### `RecordingIndex`
```csharp
public RecordingIndex(long rtc, long offset, DateTime dt)
public const int SIZE = 28;
public byte[] GetBytes()
public DateTime GetDateTime()
```
Helper structure for recorder index entries. Fixed size of 28 bytes.
#### `RecordingIndexIndex`
```csharp
public RecordingIndexIndex(long rtc, long offset, DateTime dt)
public const int SIZE = 24;
public byte[] GetBytes()
```
Helper structure for root index entries. Fixed size of 24 bytes.
---
## 3. Invariants
- **TransportStreamHeader**: Input must be exactly `TRANSPORT_HEADER_LENGTH` (4) bytes; null input throws `NullReferenceException`.
- **SecondaryTimeFormatHeader**: Input must be exactly `SECONDARY_TIME_HEADER_LENGTH` (12) bytes.
- **Packet alignment**: `PacketHeader.PacketLength` is always padded to a multiple of 4 bytes.
- **RTC consistency**: Setting RTC via `SetRTC(long)` updates both the internal `_rtc` field and `PacketHeader`.
- **Sequence numbers**: Should be monotonically increasing and wrap to 0 after maximum value (caller responsibility).
- **TimeDataPacket**: `_dataBytes` is initialized to 12 bytes; time data is written at positions 4-11.
- **TMATSDocument encoding**: Always decoded as ASCII.
- **AnalogDataFormat1Packet sample data**: Samples are byte-swapped and offset by 0x8000 for signed/unsigned conversion.
---
## 4. Dependencies
### This module depends on:
- `DTS.Serialization.IRIGCH10.Enums` - Data type enumerations (`DataFileDataTypes`, `DataTypeVersion`)
- `DTS.Serialization.IRIGCh10.Attributes` - `PacketHeaderValueAttribute`
- `DTS.Serialization.IRIGCH10.Packets` - `PacketHeader`, `IPacketHeader`
- `DTS.Common.Utilities` - `PTP1588Timestamps` (referenced in `TimePacketFormat2`)
- `Utils.Utils` (external utility class) - Static methods: `BitArrayToInt32`, `SetBits`, `GetCheckSum8`, `GetCheckSum32`, `GetBCDBytes`
- `System.IO` - `MemoryStream`, `BinaryWriter`
- `System.Collections` - `BitArray`
### What depends on this module:
- `Chapter10File` (referenced in `AnalogDataFormat1Packet` constructor delegate type `GetNextSampleDelegate`)
---
## 5. Gotchas
1. **SecondaryTimeFormatHeader checksum validation is non-blocking**: When checksum mismatch occurs, the constructor only writes to `System.Diagnostics.Trace.WriteLine` rather than throwing an exception. Callers must not assume valid checksums.
2. **TimePacketFormat1 ITS field not serialized**: The `ITS` property (IRIGTimeSource) is explicitly not serialized to the CSDW due to EMC validation tool compatibility issues (comment dated 2023-10-27).
3. **Hardcoded ChannelSpecificDataWord values**: `RecorderIndexPacket` and `RootRecorderIndexPacket` use hardcoded byte arrays for `ChannelSpecificDataWord` with comments indicating uncertainty about individual field breakdown.
4. **AnalogDataFormat1Packet data version selection**: Uses `DATA_VERSION_DASSAULT` (0x06) when secondary header is present, otherwise `DATA_VERSION_V105` (0x01). Comment indicates EMC validation tool only supports CH10 106v5.
5. **TimeDataPacket SetTimeSource overloads behave differently**: The `byte` overload sets bits 0-3 directly, while the `TimeSource` enum overload reverses bit order (bit 0←3, bit 1←2, etc.) per Chapter 10 reference 10-47.
6. **LocalTime calculation in SecondaryTimeFormatHeader**: Uses `AddTicks(NanoSeconds / 100)` which truncates nanoseconds to 100-nanosecond tick precision.
7. **RecordingIndexIndex added automatically in RootRecorderIndexPacket.GetBytes()**: The last index entry pointing back to the current packet is appended internally during `GetBytes()` call, modifying `_indices` list state.

166
docs/ai/Common/DTS.Common.Serialization/IRIGCH10/TMATS.md Normal file
View File

@@ -0,0 +1,166 @@
---
source_files:
- Common/DTS.Common.Serialization/IRIGCH10/TMATS/DescriptionDecoder.cs
- Common/DTS.Common.Serialization/IRIGCH10/TMATS/TMATSectionNumbered.cs
- Common/DTS.Common.Serialization/IRIGCH10/TMATS/TMATSSection.cs
- Common/DTS.Common.Serialization/IRIGCH10/TMATS/TMATS.cs
- Common/DTS.Common.Serialization/IRIGCH10/TMATS/GeneralInformation.cs
- Common/DTS.Common.Serialization/IRIGCH10/TMATS/PCM.cs
generated_at: "2026-04-17T15:35:03.196850+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "d1584336ff58226c"
---
# TMATS Serialization Module Documentation
## 1. Purpose
This module provides a C# implementation for generating TMATS (Telemetry Attributes Transfer Standard) documents compliant with the IRIG 106 standard. It offers a strongly-typed, object-oriented API for constructing telemetry configuration metadata, including PCM format attributes, storage source definitions, and general information sections. The module serializes configured objects into the TMATS text format using reflection-based attribute decoding to map enum values to their standard TMATS field identifiers.
---
## 2. Public Interface
### DescriptionDecoder (static class)
**Signature:** `public static string GetDescription(Enum value)`
Returns the `DescriptionAttribute` value from the enum field, or the enum's string representation if no attribute is present. Used to map enum values to TMATS field codes.
### MaxLengthDecoder (static class)
**Signature:** `public static int GetMaxLength(Enum value)`
Returns the `MaxLengthAttribute.Length` value from the enum field, or `0` if no attribute is present. Intended for field length validation.
### TMATSSection\<T\> (abstract class)
Generic base class for TMATS sections where `T : Enum`.
| Member | Signature | Description |
|--------|-----------|-------------|
| `SetValue` | `public void SetValue(T tag, string value)` | Stores a value for the given tag key. |
| `GetValue` | `public string GetValue(T tag)` | Retrieves value for tag, or `null` if unset. |
| `SetDate` | `public void SetDate(T tag, DateTime? value)` | Sets a date in `MM-DD-YYYY` format, or empty string if `null`. |
| `GetDate` | `public DateTime? GetDate(T tag)` | Parses date from `MM-DD-YYYY` format, or `null` if invalid/empty. |
| `GetIntOrNull` | `public int? GetIntOrNull(T tag)` | Parses integer value, or `null` if unset/unparseable. |
| `SetIntOrNull` | `public void SetIntOrNull(T tag, int? val)` | Sets integer as string, or empty string if `null`. |
| `SetValueWithLength` | `public void SetValueWithLength(T tag, string value)` | Sets value (length validation currently disabled). |
| `Serialize` | `public virtual string Serialize()` | Serializes all tag/value pairs to TMATS format. |
| Constructor | `public TMATSSection()` | Default constructor for unnumbered sections. |
| Constructor | `public TMATSSection(AttributeIdentifiers attribute, int number)` | Constructor for numbered sections (e.g., channel-specific). |
### TMATSectionNumbered\<T\> (class)
Represents a section with numbered sub-items where `T : Enum`.
| Member | Signature | Description |
|--------|-----------|-------------|
| `Identifier` | `public AttributeIdentifiers Identifier { get; set; }` | Section identifier (default: `GeneralInformation`). |
| `Number` | `public int Number { get; set; }` | Section number (default: `-1`). |
| `SetValue` | `public void SetValue(T tag, string value)` | Sets value for tag in internal dictionary. |
| `GetValue` | `public string GetValue(T tag)` | Gets value for tag, or `null`. |
| `Serialize` | `public string Serialize(int number)` | Serializes all tags with the given number. |
| `SetValueWithLength` | `public void SetValueWithLength(T tag, string value)` | Sets value with length retrieval (validation disabled). |
### TMATSectionNumberedArray\<T\> (class)
Manages an array of `TMATSectionNumbered<T>` items where `T : Enum`.
| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `public TMATSectionNumberedArray(string numberedTag)` | Initializes with tag name for count field. |
| Constructor | `public TMATSectionNumberedArray(string numberedTag, int maxNumber)` | Initializes with tag name and maximum count. |
| Constructor | `public TMATSectionNumberedArray(AttributeIdentifiers identifier, int number, string numberedTag, int maxNumber)` | Full constructor with all parameters. |
| `SetValue` | `public virtual void SetValue(int number, T tag, string value)` | Sets value at 1-based index, expanding array if needed. |
| `GetValue` | `public string GetValue(int number, T tag)` | Gets value at 1-based index, or `null` if out of range. |
| `Serialize` | `public string Serialize()` | Serializes array with count header and all items. |
| `GetCount` | `public int GetCount()` | Returns current item count. |
| `SetCount` | `public void SetCount(int count)` | Resizes array, enforcing `maxNumber` if set. |
### AttributeIdentifiers (enum)
TMATS top-level section identifiers with `Description` attributes:
- `GeneralInformation` ("G")
- `TransmitionAttributes` ("T")
- `StorageSourceAttributes` ("R")
- `MultiplexingAttributes` ("M")
- `PCMFormatAttributes` ("P")
- `PCMMeasurementDescription` ("D")
- `BusDataAttributes` ("B")
- `PacketFormatAttributes` ("S")
- `PAMAttributes` ("A")
- `DataConversionAttributes` ("C")
- `AirborneHardwareAttributes` ("H")
- `VendorSpecificAttributes` ("V")
### GeneralInformationGroup (class)
Extends `TMATSSection<GeneralTags>`. Key properties include:
- `ProgramName`, `TestItem` (string)
- `IRIG106RevisionLevel`, `RevisionNumber`, `UpdateNumber`, `TestNumber` (string)
- `OriginationDate`, `RevisionDate`, `UpdateDate` (DateTime?)
- `NumberOfDataSources`, `NumberOfPointsOfContact` (int)
- `PreTestRequirement`, `PostTestRequirement` (bool)
- `SecurityClassification` (enum)
- `Comments` (string)
Methods:
- `SetDataSourceField(int number, Information.DataSourceIdentificationTags tag, string value)`
- `SetDataSourceType(int number, Information.DataSourceTypes sourceType)`
- `Serialize()` override
### PCM (class)
Extends `TMATSSection<PCMAttributes>`. Constructor: `public PCM(int number)`.
Properties: `DataLinkName`, `PCMCode`, `BitsPerSecond`, `DataRandomized`, `Polarity`, `DataDirection`, `TypeFormat`, `NumberOfBitsInCommonWordLength`, `WordTransferOrder`, `PCMWordParity`.
### MinorFrameSection (class)
Extends `TMATSSection<MinorFrameTags>`. Constructor: `public MinorFrameSection(int number = 1)`.
Properties: `NumberOfMinorFramesInAMajorFrame`, `NumberOfWordsInMinorFrame`, `NumberOfBitsInMinorFrame`, `SyncLength`, `SynchronizationPattern`.
### TMATSCreationTest (class)
**Signature:** `public static string CreateTMATS()`
Demonstration method that constructs a complete TMATS document with storage, PCM, and message data configurations.
---
## 3. Invariants
- **1-based indexing**: `TMATSectionNumberedArray<T>.SetValue` and `GetValue` use 1-based indexing internally (`_items[number - 1]`).
- **Enum attribute requirements**: All enum values used as TMATS tags must have `[Description("...")]` attributes for proper serialization.
- **Date format**: Dates are serialized/parsed in `MM-DD-YYYY` format only.
- **TMATS output format**: Serialized lines follow pattern `{identifier}-{number}\{attribute}{subnumber}:{value};` or `{identifier}\{attribute}:{value};` for unnumbered sections.
- **Default number value**: Sections with `Number < 0` serialize without the `-{number}` suffix.
- **Null handling**: `GetValue` methods return `null` for unset keys, not empty strings or exceptions.
---
## 4. Dependencies
**This module depends on:**
- `System` (core types, `DateTime`, `Enum`)
- `System.ComponentModel` (`DescriptionAttribute`)
- `System.ComponentModel.DataAnnotations` (`MaxLengthAttribute`)
- `System.Collections.Generic` (`Dictionary<T,K>`, `List<T>`)
- `System.Linq` (`Cast<T>()`, `Any()`, `First()`, etc.)
- `System.Text` (`StringBuilder`)
- `System.Globalization` (used in `GetDate` for parsing)
**Consumers (inferred):**
- Any module requiring IRIG 106 TMATS document generation for telemetry recording configuration.
---
## 5. Gotchas
1. **MaxLength validation is disabled**: Both `TMATSSection<T>.SetValueWithLength` and `TMATSectionNumbered<T>.SetValueWithLength` contain commented-out validation logic. The code comments state "maxlength is just a suggestion in the spec." Values exceeding `MaxLengthAttribute` will be stored without error.
2. **DataSource ID uniqueness check bug**: In `GeneralInformationGroup.Information.SetDataSourceField`, the loop iterates with `i` but compares using `number`:
```csharp
if (_datasources.GetValue(number, tag) == value) // Should likely be GetValue(i, tag)
```
This compares the value against itself rather than checking other indices.
3. **Typo in enum**: `AttributeIdentifiers.TransmitionAttributes` is misspelled (should be "Transmission").
4. **Double semicolon**: In `TMATSectionNumberedArray<T>.SetCount`, there is a syntax quirk: `newItem.Number = _number;;`.
5. **Incomplete enum definitions**: `SubFrameSynchronizationTags` and `SubFrameDefinitionTags` lack `[Description]` attributes, meaning they cannot be properly serialized using `DescriptionDecoder.GetDescription`.
6. **Date format inconsistency**: The format string `"MM-DD-YYYY"` uses non-standard year formatting. Standard C# would be `"MM-dd-yyyy"`. The behavior with `DateTime.TryParseExact` using `"YYYY"` (uppercase) may not parse correctly on all systems.
7. **Empty vs null ambiguity**: `SetIntOrNull` and `SetDate` set empty strings for `null` values, but `GetValue` returns `null` for missing keys. This creates an inconsistency where explicitly-set nulls become empty strings while never-set values remain null.

81
docs/ai/Common/DTS.Common.Serialization/IRIGCH10/TMATS/DataConversion.md Normal file
View File

@@ -0,0 +1,81 @@
---
source_files:
- Common/DTS.Common.Serialization/IRIGCH10/TMATS/DataConversion/DataConversionSection.cs
- Common/DTS.Common.Serialization/IRIGCH10/TMATS/DataConversion/TelemetrySection.cs
- Common/DTS.Common.Serialization/IRIGCH10/TMATS/DataConversion/CoefficientSection.cs
- Common/DTS.Common.Serialization/IRIGCH10/TMATS/DataConversion/Measurand.cs
- Common/DTS.Common.Serialization/IRIGCH10/TMATS/DataConversion/OtherInformationSection.cs
- Common/DTS.Common.Serialization/IRIGCH10/TMATS/DataConversion/TransducerInformation.cs
generated_at: "2026-04-17T15:35:23.451592+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "f25d8d008b57c725"
---
# TMATS Data Conversion Module Documentation
## 1. Purpose
This module implements the Data Conversion section of TMATS (Telemetry Attributes Transfer Standard) packets for IRIG Ch10 data serialization. It provides strongly-typed classes and enumerations for defining measurement metadata including conversion types, telemetry formats, calibration coefficients, measurand descriptions, alert/warning limits, and transducer information. Each section class maps enum-backed attributes to their TMATS-compliant string representations via `Description` attributes.
---
## 2. Public Interface
### `DataConversionSection` (class)
**Namespace:** `DTS.Serialization.IRIGCH10.Attributes`
**Inherits:** `TMATSSection<DataConversionAttributes>`
| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `DataConversionSection(int number)` | Initializes with `AttributeIdentifiers.DataConversionAttributes` and section number |
| `SetConversionType` | `void SetConversionType(ConversionTypes type)` | Sets the DCT attribute using the `Description` value of the provided `ConversionTypes` enum |
**Related Enums:**
- `DataConversionAttributes`: Contains `ConversionType` (Description: "DCT")
- `ConversionTypes`: `None`, `PairSets`, `Coefficients`, `CoefficientsNegative`, `Derived`, `Discrete`, `PCMTime`, `Time1553`, `DigitalVoice`, `DigitalVideo`, `SpecializedProcessing`, `Other`
---
### `TelemetrySection` (class)
**Namespace:** `DTS.Serialization.IRIGCH10.TMATS.DataConversion`
**Inherits:** `TMATSSection<TelemetryAttributes>`
| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `TelemetrySection(int number)` | Initializes with `AttributeIdentifiers.DataConversionAttributes` and section number |
| `SetBinaryFormat` | `void SetBinaryFormat(BinaryFormats format)` | Sets the BFM attribute using the `Description` value of the provided `BinaryFormats` enum |
**Related Enums:**
- `TelemetryAttributes`: Contains `BinaryFormat` (Description: "BFM", MaxLength: 3)
- `BinaryFormats`: `Integer`, `UnsignedBinary`, `SignAndMagnitudeSig`, `SignAndMagnitudeSim`, `OnesCompliment`, `TwosCompliment`, `OffsetBinary`, `FloatingPoint`, `BinaryCodedDecimal`, `BitWeight`, `Other`
---
### `CoefficientSection` (class)
**Namespace:** `DTS.Serialization.IRIGCH10.TMATS.DataConversion`
**Inherits:** `TMATSSection<CoefficientsAttributes>`
| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `CoefficientSection(int number)` | Initializes with `AttributeIdentifiers.DataConversionAttributes` and section number |
| `OrderOfCurveFit` | `int?` (property) | Gets/sets the polynomial curve fit order (attribute "CO\\N") |
| `Coefficient0` | `string` (property) | Gets/sets the zero-order term/offset (attribute "CO") |
| `Coefficient1` | `string` (property) | Gets/sets the first-order coefficient (attribute "CO-1") |
**Related Enum:**
- `CoefficientsAttributes`: `OrderOfCurveFit` ("CO\\N"), `DerivedFromPairSet` ("CO1"), `Coefficient0` ("CO"), `Coefficient1` through `Coefficient7` ("CO-1" through "CO-7")
---
### `MeasurandSection` (class)
**Namespace:** `DTS.Serialization.IRIGCH10.TMATS.DataConversion`
**Inherits:** `TMATSSection<MeasurandAttributes>`
| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `MeasurandSection(int number)` | Initializes with `AttributeIdentifiers.DataConversionAttributes` and section number |
| `Description` | `string` (property) | Gets/sets parameter description (attribute "MN1", MaxLength: 64) |
| `MeasurementAlias` | `string` (property) | Gets/sets alternate measurand name (attribute "MNA", MaxLength: 32) |
| `ExcitationVoltage` | `string` (property) | Gets/sets sensor reference voltage in volts (attribute "MN2", MaxLength: 10) |
| `EngineeringUnits` | `string` (property) | Gets/sets engineering units (attribute

38
docs/ai/Common/DTS.Common.Serialization/IRIGCH10/Utils.md Normal file
View File

@@ -0,0 +1,38 @@
---
source_files:
- Common/DTS.Common.Serialization/IRIGCH10/Utils/Utils.cs
generated_at: "2026-04-17T16:43:36.818421+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "2999f5bcc681631b"
---
# Documentation: DTS.Serialization.IRIGCH10.Utils.Utils
## 1. Purpose
This module provides low-level utility functions for IRIG Chapter 10 data serialization, including Binary Coded Decimal (BCD) encoding for date/time values, checksum computation (8-bit, 16-bit, and 32-bit variants per the CH10 specification), and bit-level manipulation of `BitArray` structures. It serves as a foundational helper class for encoding and validating binary packet data in the IRIG Chapter 10 format.
---
## 2. Public Interface
### `public static byte[] GetBCDBytes(int value)`
Converts an integer value to a 2-byte Binary Coded Decimal representation.
- **Parameter:** `value` — must be in range [0, 9999]
- **Returns:** 2-byte array containing the BCD-encoded value
- **Throws:** `ArgumentOutOfRangeException` if `value` is outside the valid range
### `public static ushort GetCheckSum8(byte[] bytes)`
Computes an 8-bit checksum by summing all byte values.
- **Parameter:** `bytes` — input byte array
- **Returns:** `ushort` representing the sum of all bytes (wrapping at 8 bits via implicit truncation)
### `public static ushort GetCheckSum16(byte[] bytes)`
Computes a 16-bit checksum per the Chapter 10 specification by treating the byte array as an array of 16-bit unsigned integers and summing them.
- **Parameter:** `bytes` — input byte array (must have even length)
- **Returns:** `ushort` checksum value
- **Asserts:** `bytes.Length % 2 == 0` via `System.Diagnostics.Trace.Assert`
### `public static uint GetCheckSum32(byte[] bytes)`
Computes a 32-bit checksum per the Chapter 10 specification by treating the byte array as an array of

170
docs/ai/Common/DTS.Common.Serialization/Iso.md Normal file
View File

@@ -0,0 +1,170 @@
---
source_files:
- Common/DTS.Common.Serialization/Iso/Iso.File.Test.ExtraProperty.cs
- Common/DTS.Common.Serialization/Iso/Iso.File.cs
- Common/DTS.Common.Serialization/Iso/Iso.File.Test.Object.cs
- Common/DTS.Common.Serialization/Iso/Iso.File.Test.cs
generated_at: "2026-04-17T15:35:58.814665+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "e65ccfacaca06b40"
---
# Documentation: DTS.Serialization.Iso
## 1. Purpose
This module provides ISO-standard file serialization for test data, generating `.mme` (test) and `.chn` (channel) files. It serves as the export layer that transforms internal test data structures into the ISO MME format, handling metadata such as laboratory information, customer details, test objects, and measurement channels. The module bridges the domain model (`Common.ISO.TestPlan`, `Serialization.Test`) with the ISO file format specification.
---
## 2. Public Interface
### `File` (partial class)
**Namespace:** `DTS.Serialization.Iso`
**Inheritance:** `Serialization.File`, `IWritable<Test>`
| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `File(Common.ISO.TestPlan testplan)` | Initializes an ISO file instance with the given test plan. |
| `GetTestPlan()` | `Common.ISO.TestPlan GetTestPlan()` | Returns the test plan associated with this file. |
| `AddChannel` | `void AddChannel(string dasserial, int moduleNumber, int number, string description, FilteredData data)` | Delegates channel addition to the internal `Writer`. |
| `ApplyTestPlan` | `void ApplyTestPlan(Serialization.Test test)` | Populates `TestInstance` fields from the test plan using `Common.ISO.TestPlan.IsoFields` enum. Falls back to `test.InceptionDate` if date parsing fails. |
| `Exporter` | `IWriter<Serialization.Test>` (property) | Lazy-initialized writer; propagates `UseZeroForUnfiltered`, `UseIsoCodeFilterMapping`, `FilteredExport`, `ExportISOChannelName`, and `ExportSummaryReport` settings. |
| `TestInstance` | `Test` (property) | Returns the `Test` instance associated with this file. |
| `TestFileExtension` | `static string` (property) | File extension for test files; default `".mme"`. |
| `ChannelFileExtension` | `static string` (property) | File extension for channel files; default `".chn"`. |
| `ExportSummaryReport` | `bool` (property) | Whether to export a summary report; default `false`. |
| `UseZeroForUnfiltered` | `bool` (property) | Default `false`. |
| `UseIsoCodeFilterMapping` | `bool` (property) | Forces ISO code filter determination by software filter; default `false`. |
| `FilteredExport` | `bool` (property) | Default `false`. |
| `ExportISOChannelName` | `bool` (property) | Default `false`. |
---
### `File.Test` (partial class)
**Inheritance:** `Exceptional`
| Member | Type | Description |
|--------|------|-------------|
| `DataFormatEditionNumber` | `string` | Default `"1.6"`. |
| `LaboratoryName` | `string` | Laboratory name. |
| `LaboratoryContactName` | `string` | Contact name. |
| `LaboratoryContactPhone` | `string` | Contact phone. |
| `LaboratoryContactFax` | `string` | Contact fax. |
| `LaboratoryContactEmail` | `string` | Contact email. |
| `LaboratoryTestReferenceNumber` | `string` | Test reference number. |
| `LaboratoryProjectReferenceNumber` | `string` | Project reference number (non-standard field; label prefixed with `.`). |
| `CustomerName` | `string` | Customer name. |
| `CustomerTestReferenceNumber` | `string` | Customer test reference. |
| `CustomerProjectReferenceNumber` | `string` | Customer project reference. |
| `CustomerOrderNumber` | `string` | Customer order number. |
| `CustomerCostUnit` | `string` | Customer cost unit. |
| `TestEngineerName` | `string` | Test engineer name. |
| `TestEngineerPhone` | `string` | Test engineer phone. |
| `TestEngineerFax` | `string` | Test engineer fax. |
| `TestEngineerEmail` | `string` | Test engineer email. |
| `Title` | `string` | Test title. |
| `NumberOfMedia` | `string` | Default `"1/1"`. |
| `Timestamp` | `string` | Default `DateTime.Now` formatted as `"yyyy-MM-dd HH:mm:ss"`. |
| `TestComment` | `string` | Test comments. |
| `Type` | `string` | Test type. |
| `Date` | `DateTime` | Test date; defaults to `DateTime.Now`. |
| `Subtype` | `string` | Test subtype. |
| `Regulation` | `string` | Regulation. |
| `ReferenceTemperature` | `string` | Reference temperature. |
| `RelativeAirHumidity` | `string` | Relative air humidity. |
| `NumberOfTestObjects` | `int` (read-only) | Returns `Objects.Count`. |
| `Objects` | `List<Object>` | List of test objects. |
| `Channels` | `List<Channel>` | List of channels. |
| `ExtraProperties` | `List<ExtraProperty>` | Custom properties. |
| `ToString()` | `override string` | Generates ISO-formatted string representation. |
---
### `File.Test.Object` (class)
**Inheritance:** `Exceptional`
| Member | Type | Description |
|--------|------|-------------|
| `Comments` | `string[]` | Array of comments. |
| `Name` | `string` | Test object name. |
| `Type` | `string` | Test object type (e.g., `"B"` for barrier). |
| `Number` | `string` | Reference number. |
| `MmeNumber` | `int` | MME sequence number; default `-1`. |
| `Velocity` | `string` | Velocity; default `"0.0"`. |
| `Mass` | `string` | Mass. |
| `TestObject` | `string` | Test object identifier. |
| `Position` | `string` | Driver position code; default `"?"`. |
| `TestObjectImpactSide` | `string` | Impact side. |
| `Class` | `string` | Object class. |
| `Code` | `string` | Object code. |
| `Offset` | `string` | Offset. |
| `BarrierWidth` | `string` | Barrier width (for type `"B"`). |
| `BarrierHeight` | `string` | Barrier height (for type `"B"`). |
| `YawAngle` | `string` | Yaw angle (for type `"B"`). |
| `ReferenceSystem` | `string` | Reference system (for type `"B"`). |
| `OriginX`, `OriginY`, `OriginZ` | `string` | Origin coordinates (for type `"B"`). |
| `NumberOfLoadcells` | `string` | Load cell count (for type `"B"`). |
| `ExtraProperties` | `List<ExtraProperty>` | Custom properties. |
| `ToString()` | `override string` | Generates ISO-formatted string; includes barrier-specific fields when `Type == "B"`. |
---
### `File.Test.ExtraProperty` (class)
**Inheritance:** `Exceptional`
| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `ExtraProperty(string key, string value)` | Initializes with key and value. |
| `Key` | `string` (property) | Property key; returns `null` if not initialized. |
| `Value` | `string` (property) | Property value; returns `null` if not initialized. |
---
## 3. Invariants
- **File Extensions:** `TestFileExtension` is always `".mme"`; `ChannelFileExtension` is always `".chn"` unless explicitly modified.
- **Format Constants:** `SeparatorOffset` is fixed at `28`; `Separator` is `":"`; `NoValue` constant is `"NOVALUE"`.
- **Default Values:** `DataFormatEditionNumber` defaults to `"1.6"`; `NumberOfMedia` defaults to `"1/1"`.
- **Timestamp Behavior:** `Timestamp` is set to `DateTime.Now` at `Test` construction time in format `"yyyy-MM-dd HH:mm:ss"`.
- **Null Safety:** `ExtraProperty.Key` and `ExtraProperty.Value` return `null` when `_Key.IsValueInitialized` or `_Value.IsValueInitialized` is `false`.
- **Field String Extraction:** `GetFieldString()` always returns either the extracted value or `"NOVALUE"`—never throws for field access failures.
- **Barrier Type Condition:** `Object.ToString()` only emits barrier-specific fields (`BarrierWidth`, `BarrierHeight`, `YawAngle`, `ReferenceSystem`, `OriginX/Y/Z`, `NumberOfLoadcells`) when `Type == "B"`.
---
## 4. Dependencies
### This module depends on:
- `DTS.Common.Utilities` — provides utility functions (specific members unclear from source).
- `DTS.Common.Utilities.DotNetProgrammingConstructs` — provides `Property<T>` and `Exceptional` base class.
- `DTS.Serialization.Iso.Report` — referenced in comments; usage unclear from source.
- `Common.ISO.TestPlan` — provides test plan data and `IsoFields` enum.
- `Serialization.File` — base class for `File`.
- `Serialization.Test` — used in `ApplyTestPlan` parameter.
- `IWriter<Serialization.Test>`, `IWritable<Test>` — writer interfaces.
- `Writer` — internal writer class (not shown in source).
- `FilteredData` — data type for `AddChannel` (not shown in source).
- `Channel` — referenced in `Test.Channels` (not shown in source).
### What depends on this module:
- Cannot be determined from source alone; the module exposes public types that could be consumed by any ISO export functionality.
---
## 5. Gotchas
1. **Empty Case Handlers in `ApplyTestPlan`:** The switch statement has empty cases for `CustName`, `TEName`, `LabName`, and `NumberOfTestObjects`—these fields are read from the test plan but never assigned to `TestInstance`.
2. **Position/ImpactSide Parsing:** `Object.ToString()` parses `Position` and `TestObjectImpactSide` by extracting text before the first hyphen (`IndexOf('-') - 1`). This will throw if the string does not contain a hyphen and is not `"NOVALUE"`.
3. **Title Fallback:** `ApplyTestPlan` sets `Title` to `test.Id` when the test plan value equals `"NOVALUE"`.
4. **Non-Standard Field Labels:** `LaboratoryProjectReferenceNumberLabel` is prefixed with `.` (`.Laboratory project ref. num`), indicating it's an extension to the standard ISO format.
5. **Exporter Exception Wrapping:** The `Exporter` property catches all exceptions and re-throws with a generic message `"encountered problem getting exporter"`, potentially obscuring the root cause.
6. **Date Fallback Logic:** In `ApplyTestPlan`, if `DateTime.TryParse` fails for the date field, it falls back to `test.InceptionDate` without logging or indicating the parse failure.
7. **Property Wrapper Pattern:** All field access uses `Property<T>` wrapper objects with `IsValueInitialized` checks—direct field access via `_Key.Value` without checking initialization state may behave unexpectedly.

26
docs/ai/Common/DTS.Common.Serialization/Iso/Report.md Normal file
View File

@@ -0,0 +1,26 @@
---
source_files:
- Common/DTS.Common.Serialization/Iso/Report/SummaryReport.cs
- Common/DTS.Common.Serialization/Iso/Report/ChannelData.cs
generated_at: "2026-04-17T16:26:51.854079+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "73f0d595156f65dc"
---
# Report
### Purpose
This module provides functionality for generating ISO-compliant test summary reports. It transforms test data (channels, ISO codes, filter classes, electronic IDs, data flags) into a formatted text file output suitable for documentation and compliance purposes. The report lists all channels with their associated metadata in a structured format.
### Public Interface
**`SummaryReport`** (public class)
- `string GetLines()` — Returns the complete formatted report as a single string, including a header line with channel count followed by one line per channel.
- `static SummaryReport CreateSummaryReport(Test test)` — Factory method that creates a `SummaryReport` from a `Test` object, extracting and sorting all channel data.
- `static void OutputToPath(string path, SummaryReport summary)` — Writes the summary report to a file named `"TestNo_FilterList.txt"` in the specified directory. Can throw I/O exceptions.
**`ChannelData`** (internal class)
- `int ChannelNumber { get; set; }` — The display order number of the channel; default is 1.
- `string ISOCode { get; set; }` — The ISO code for the channel; default is `string.Empty`.
- `string ChannelName { get; set; }` — The

55
docs/ai/Common/DTS.Common.Serialization/Properties.md Normal file
View File

@@ -0,0 +1,55 @@
---
source_files:
- Common/DTS.Common.Serialization/Properties/AssemblyInfo.cs
- Common/DTS.Common.Serialization/Properties/Settings1.Designer.cs
generated_at: "2026-04-17T16:26:51.852900+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "82b6939ea361a0a4"
---
# Properties
### Purpose
This module provides assembly-level metadata and persistent application/user settings for the `DTS.Common.Serialization` assembly. It contains standard .NET assembly information and a settings class that stores user preferences for data import/export operations, including default folder paths, time ranges, and UI color themes.
### Public Interface
**Assembly-level attributes** (in `AssemblyInfo.cs`)
- `AssemblyTitle`: "Serialization"
- `AssemblyCompany`: "DTS"
- `AssemblyVersion`: "1.06.0081"
- `AssemblyFileVersion`: "1.06.0081"
- `ComVisible`: false
- `Guid`: "af5fae89-f630-4b35-b51f-9acf65c996ba"
**`Settings1`** (internal sealed class, auto-generated, inherits `ApplicationSettingsBase`)
- `static Settings1 Default { get; }` — Returns the default synchronized instance.
- `string TDMFolder { get; set; }` — User-scoped setting; default value: `".\Data\TDM CFC1000"`.
- `double DefaultStart { get; set; }` — User-scoped setting; default value: `-500`.
- `double DefaultStop { get; set; }` — User-scoped setting; default value: `500`.
- `string TSVPOCNameLastUsed { get; set; }` — User-scoped setting; default value: `"#NOVALUE"`.
- `string TSVPOCPhoneAndEmailLastUsed { get; set; }` — User-scoped setting; default value: `"#NOVALUE"`.
- `string TSVDataTypeLastUsed { get; set; }` — User-scoped setting; default value: `"Converted"`.
- `string TSVLabNameLastUsed { get; set; }` — User-scoped setting; default value: `"#NOVALUE"`.
- `string TSVTestObjectLastUsed { get; set; }` — User-scoped setting; default value: `"#NOVALUE"`.
- `string TSVTestTypeLastUsed { get; set; }` — User-scoped setting; default value: `"#NOVALUE"`.
- `System.Drawing.Color TableHeader { get; }` — Application-scoped setting (read-only); default value: RGB(215, 225, 255).
- `System.Drawing.Color AlternatingRow { get; set; }` — User-scoped setting; default value: RGB(238, 242, 255).
### Invariants
- `TableHeader` is application-scoped and read-only at runtime.
- All TSV-related settings use `"#NOVALUE"` as a sentinel for "not yet set".
- The class is in namespace `DTS.Serialization.Properties`, which differs from the assembly name pattern `DTS.Common.Serialization`.
- `Settings1` is a singleton accessed via `Settings1.Default`.
### Dependencies
- **Depends on**: `System.Reflection`, `System.Runtime.InteropServices`, `System.Configuration`, `System.Drawing`.
- **Depended on by**: Unclear from source alone—likely consumed by serialization/import/export logic within the assembly.
### Gotchas
- The class name `Settings1` (not `Settings`) suggests there may be another settings file in the project or a naming conflict was resolved by appending a number.
- The sentinel value `"#NOVALUE"` is used for unset string settings; consumers must explicitly check for this value rather than relying on `null` or `string.Empty`.
- The `TDMFolder` default path is relative (`".\Data\TDM CFC1000"`), which depends on the current working directory at runtime.
---

158
docs/ai/Common/DTS.Common.Serialization/RDF.md Normal file
View File

@@ -0,0 +1,158 @@
---
source_files:
- Common/DTS.Common.Serialization/RDF/RDF.File.cs
- Common/DTS.Common.Serialization/RDF/RDF.File.Writer.cs
generated_at: "2026-04-17T15:42:21.831959+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "0c02ee86055c6c96"
---
# RDF File Serialization Module Documentation
## 1. Purpose
This module provides serialization of test data to RDF (Representation Data Format) files, a binary format designed for Toyota CSV file compatibility. It handles the export of `Test` objects containing channel data, converting ADC values, scaling factors, and metadata into a structured binary format with fixed-width fields. The module supports various sensor types including analog inputs, digital inputs, IEPE sensors, and squib channels, with special handling for linearized and non-linear data.
---
## 2. Public Interface
### `DTS.Serialization.RDF.File` (Partial Class)
**Inherits:** `Serialization.File`, `IWritable<Test>`
#### Constructor
```csharp
public File(Common.ISO.TestPlan plan)
```
Initializes an RDF file instance with the specified test plan.
#### Constants
```csharp
public const string SUFFIX_RUNTEST = " RunTest";
public const string SUFFIX_CHECKOUT = " Checkout";
public const int MAX_TEST_NAME_LENGTH = 8;
```
#### Properties
```csharp
public static string Extension => ".001";
public bool UseZeroForUnfiltered { get; set; }
public bool FilteredExport { get; set; }
public IWriter<Test> Exporter { get; }
```
- `Extension` returns the hardcoded file extension ".001"
- `Exporter` lazily instantiates a `Writer` instance, configuring it with `TestPlan`, `UseZeroForUnfiltered`, and `FilteredExport` values
#### Methods
```csharp
public override void SetEUData(string channelID, FilteredData fd);
public override FilteredData GetEUData(string channelID);
```
Manages EU (Engineering Units) data storage in an internal dictionary `_EUUnfilteredDataForLinearizedChannels`.
---
### `DTS.Serialization.RDF.File.Writer` (Nested Class)
**Inherits:** `Writer<File>`, `IWriter<Test>`
#### Constructor
```csharp
internal Writer(File fileType, int encoding)
```
Internal constructor; instances are obtained via `File.Exporter`.
#### Properties
```csharp
public File WriterParent { get; set; }
public TestPlan TestPlan { get; set; }
public string ExtensionPrefix { get; set; }
public bool UseIsoCodeForDiadem200 { get; set; }
public bool UseZeroForUnfiltered { get; set; }
public bool FilteredExport { get; set; }
```
#### Methods
```csharp
public void Write(string pathname, string id, Test test, bool bFiltering,
bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)
```
Simplified overload that delegates to the full `Write` method with null parameters.
```csharp
public void Write(string pathname, string id, string dataFolder, Test test,
bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd,
Test.Module.Channel tmChannel, int channelNumber,
BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler,
EndEventHandler endEventHandler, TickEventHandler tickEventHandler,
ErrorEventHandler errorEventHandler, CancelRequested cancelRequested,
double minStartTime, int dataCollectionLength)
```
Writes the test to disk as an RDF file. Creates the directory if needed, normalizes the test ID by removing `SUFFIX_RUNTEST` or `SUFFIX_CHECKOUT` suffixes, and writes test info and channel info via `BinaryWriter`.
```csharp
public void Initialize(string pathname, string id, string dataFolder, Test test,
bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd,
Test.Module.Channel tmChannel, int channelNumber,
BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler,
EndEventHandler endEventHandler, TickEventHandler tickEventHandler,
ErrorEventHandler errorEventHandler, CancelRequested cancelRequested)
```
Empty implementation (no-op).
```csharp
public string GetTestObjectNumber(string isocode, TestPlan plan)
```
Returns the 1-based index of the test object matching the ISO code's test object character.
---
## 3. Invariants
- **Test ID Length:** Test IDs are truncated or padded to exactly `MAX_TEST_NAME_LENGTH` (8 characters) in the output file.
- **File Extension:** Output files always use the `.001` extension.
- **Channel Ordering:** Channels are sorted by `AbsoluteDisplayOrder` before writing.
- **ADC Centering:** ADC values are centered at `DTS.Common.Constants.ADC_MIDPOINT` (32767) in the binary output.
- **Sample Alignment:** All channels are homogenized to share the same time range (max start time to min end time across all channels).
- **Suffix Removal:** `SUFFIX_RUNTEST` and `SUFFIX_CHECKOUT` are stripped from test IDs before file naming.
- **File Number:** The file number field is always written as "1".
---
## 4. Dependencies
### This Module Depends On:
- `System`, `System.Globalization`, `System.IO`, `System.Linq`, `System.Text` (BCL)
- `DTS.Common.DAS.Concepts` (for `DataScaler`, `NonLinearStyles`)
- `DTS.Common.Utilities.Logging` (for `APILogger`)
- `DTS.Common.ISO` (for `TestPlan`, `IsoCode`)
- `DTS.Common.Enums.Sensors` (for `SensorConstants.BridgeType`)
- `DTS.Serialization` (base classes `Serialization.File`, `Writer<T>`, `IWriter<T>`, `Test`, `FilteredData`)
- `Common.ISO.TestPlan` (constructor parameter type)
- `Common.Constants.ADC_MIDPOINT` (constant reference)
### What Depends On This Module:
- Not determinable from source alone.
---
## 5. Gotchas
1. **Sample Count Discrepancy:** Two samples are removed from the end of each channel's data during export. Comments indicate this is to match TDC RDF export behavior, noting "TDC appears to be miscounting by 1 sample" and "DataPRO download appears to download 1 extra sample."
2. **Trigger Sample Hack:** There is an acknowledged "hack" in the time range calculation when `TotalSamplesRecorded` is less than `TriggerSampleNumber`. The comment states this case was worked around specifically for RDF export without modifying core data structures.
3. **Empty Initialize Method:** The `Initialize` method has no implementation, which may indicate incomplete interface compliance or deprecated functionality.
4. **Slice System Channel Numbering:** Channels from Slice systems (identified by serial prefixes "SPS", "SPT", "SPD", "BA", "SLT", "SLS", "SLD") have their channel numbers offset by `ParentModule.Number * 3` to convert to DAS order (1-18).
5. **Naturally Inverted Scale Factors:** Channels from modules with serial number prefixes "SPS" or "SLS" that are analog and non-linearized have their scale factors and data inverted.
6. **Squib Channel Naming:** Squib channels use a decorator suffix ("I" for indication, "C" for current) appended to the channel number in the DAS Channel field.
7. **Digital Input Threshold:** Digital input on/off detection uses a simple threshold comparison (`eu != 0`), with a comment noting this may need refinement based on `DigitalMode` (CCNO/CCNC/LowToHigh/HighToLow).
8. **Debug Output Files:** Methods `CreateLinearizedData`, `CreateLinearizedDataCSV`, and `CreateDigitizedData` create auxiliary files (`.lin`, `.csv`, `.dig`) alongside the main RDF output for debugging non-linear channels.

240
docs/ai/Common/DTS.Common.Serialization/SliceRaw.md Normal file
View File

@@ -0,0 +1,240 @@
---
source_files:
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.IDasTimestampHeader.cs
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.Reader.BadCrcException.cs
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.Reader.MissingFileException.cs
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.Reader.TooManyFilesException.cs
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.PersistentChannel.NotInitializedException.cs
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.PersistentChannel.IsInitializingException.cs
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.PersistentChannel.DataTooBigForArrayException.cs
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.PersistentChannel.AlreadyInitializedException.cs
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.PersistentChannel.DependencyNotInitializedException.cs
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.BinaryDasTimestampHeader.cs
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.PersistentEuChannel.cs
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.IChannelHeader.cs
- Common/DTS.Common.Serialization/SliceRaw/ModifyChannel.cs
- Common/DTS.Common.Serialization/SliceRaw/SliceRaw.File.BinaryChannelHeader.cs
generated_at: "2026-04-17T15:27:55.460417+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "433e54278b633cd4"
---
# DTS.Serialization.SliceRaw Module Documentation
## 1. Purpose
This module provides serialization support for the SliceRaw binary file format used by Diversified Technical Systems' data acquisition systems. It defines header structures, exception types, and data access patterns for reading and writing binary channel data files (`.chn` files). The module handles timestamp headers, channel headers with calibration metadata, and provides a persistent channel abstraction for accessing large sample datasets without loading them entirely into memory.
---
## 2. Public Interface
### Interfaces
#### `IDasTimestampHeader`
Defines the contract for timestamp header data in binary files.
| Property | Type | Access | Description |
|----------|------|--------|-------------|
| `MagicKey` | `uint` | get/set | Relatively-unique identifier for the binary file type |
| `HeaderVersionNumber` | `uint` | get/set | Version number of the header format |
| `OffsetOfSampleDataStart` | `ulong` | get/set | Byte offset where sample data begins |
| `NumberOfSamples` | `ulong` | get/set | Total count of samples in the file |
| `NumberOfBitsPerSample` | `uint` | get/set | Bit depth per sample |
| `Crc32` | `uint` | get | CRC value for current header state |
#### `IChannelHeader`
Defines the contract for channel header data with extensive calibration and diagnostic metadata.
| Property | Type | Access | Description |
|----------|------|--------|-------------|
| `MagicKey` | `uint` | get/set | File type identifier |
| `HeaderVersionNumber` | `uint` | get/set | Header format version |
| `OffsetOfSampleDataStart` | `ulong` | get/set | Byte offset to sample data |
| `NumberOfSamples` | `ulong` | get/set | Sample count |
| `NumberOfBitsPerSample` | `uint` | get/set | Bits per sample |
| `AreSamplesSigned` | `uint` | get/set | Signed sample indicator |
| `SampleRate` | `double` | get/set | Sample rate in Hz |
| `NumberOfTriggers` | `ushort` | get/set | Trigger count |
| `TriggerSampleNumbers` | `ulong[]` | get/set | Array of trigger sample indices |
| `PreTestZeroLevelCounts` | `int` | get/set | Pre-test zero level ADC counts |
| `RemovedADC` | `int` | get/set | ADC offset removed during hardware zeroing |
| `Excitation` | `double` | get/set | Excitation voltage |
| `ZeroMvInADC` | `int` | get/set | ADC value for 0mV injected signal |
| `WindowAverageADC` | `int` | get/set | Average ADC over zero window |
| `OriginalOffsetADC` | `int` | get/set | Initial offset in ADC |
| `TriggerAdjustmentSamples` | `int` | get/set | Samples for trigger qualification |
| `PreTestDiagnosticsLevelCounts` | `int` | get/set | Pre-test diagnostic level |
| `PreTestNoisePercentageOfFullScale` | `double` | get/set | Pre-test noise percentage |
| `PostTestZeroLevelCounts` | `int` | get/set | Post-test zero level counts |
| `PostTestDiagnosticsLevelCounts` | `int` | get/set | Post-test diagnostic level |
| `DataZeroLevelCounts` | `int` | get/set | Data zero level counts |
| `ScaleFactorMv` | `double` | get/set | Millivolt scale factor |
| `MvPerEu` | `double` | get/set | Sensitivity in mV/EU |
| `EuFieldLengthWithTerminator` | `ushort` | get/set | EU field length including terminator |
| `EngineeringUnit` | `char[]` | get/set | Engineering unit string |
| `IsoCode` | `char[]` | get/set | ISO code string |
| `Crc32` | `uint` | get | CRC for current header state |
---
### Classes
#### `File.BinaryDasTimestampHeader`
Implementation of `IDasTimestampHeader`.
**Static Properties:**
- `RequiredMagicKey` → `0xF15363C2`
- `CurrentVersionNumber` → `0x01`
- `KnownHeaderVersionNumbers` → `List<uint>` containing `{ 0x01 }`
**CRC Calculation:** Uses CRC16 algorithm via `Utils.Math_DoCRC16Step()`.
---
#### `File.BinaryChannelHeader`
Implementation of `IChannelHeader`.
**Static Properties:**
- `RequiredMagicKey` → `0x2C36351F`
- `CurrentVersionNumber` → `0x04`
- `KnownHeaderVersionNumbers` → `List<uint>` containing `{ 0x01, 0x02, 0x03, 0x04 }`
**CRC Properties:**
- `Crc32` - Standard CRC with EU padding preserved
- `UnpaddedEuCrc32` - CRC with EU string padding stripped
- `UnpaddedEuStringPaddedEuLengthCrc32` - CRC with unpadded EU string but padded EU length
**Version-Conditional Fields:**
- `RemovedADC` included for `HeaderVersionNumber >= 2`
- `Excitation`, `TriggerAdjustmentSamples`, `ZeroMvInADC`, `OriginalOffsetADC` included for `HeaderVersionNumber >= 3`
- `WindowAverageADC` included for `HeaderVersionNumber >= 4`
---
#### `File.PersistentEuChannel`
Wrapper class that converts ADC values to Engineering Units on-demand. Inherits from `ExceptionalList<double>`.
**Constructor:**
```csharp
public PersistentEuChannel(PersistentChannel persistentChannel, DataScaler scaler)
```
**Properties:**
| Property | Type | Description |
|----------|------|-------------|
| `BasePersistentChannel` | `PersistentChannel` | The wrapped channel providing raw ADC data |
| `EuDataScaler` | `DataScaler` | Conversion scaler from ADC to EU |
| `Length` | `long` | Length of the channel data |
**Indexer:**
```csharp
public double this[ulong i] { get; } // Read-only, applies EU conversion
```
**Methods:**
- `void Dispose()` - Disposes the base persistent channel
---
#### `ModifyChannel`
Windows Forms dialog for editing channel header metadata.
**Properties:**
```csharp
public File.PersistentChannel ChannelToModify { set; }
```
**Key UI Event Handlers:**
- `btnBrowse_Click` - Opens file dialog to select `.chn` file
- `btnWrite_Click` - Applies edits and calls `StampCrc()` on the channel
- `c1Button2_Click` - Cancels and closes dialog
---
### Exception Classes
All exception classes follow standard .NET exception patterns with three constructors:
1. Default constructor
2. Message constructor
3. Message + inner exception constructor
#### `File.Reader.BadCrcException`
Thrown when CRC validation fails during file reading. Inherits from `Exception`.
#### `File.Reader.MissingFileException`
Thrown when a required file is not found. Inherits from `Exception`.
#### `File.Reader.TooManyFilesException`
Thrown when file count exceeds expected limits. Inherits from `Exception`.
#### `File.PersistentChannel.NotInitializedException`
Thrown when accessing a property before initialization. Inherits from `ApplicationException`.
#### `File.PersistentChannel.IsInitializingException`
Thrown when accessing a property while the channel is still being initialized. Inherits from `ApplicationException`.
#### `File.PersistentChannel.DataTooBigForArrayException`
Thrown when attempting to convert a dataset too large for a .NET array. Inherits from `ApplicationException`.
#### `File.PersistentChannel.AlreadyInitializedException`
Thrown when attempting to set a property that has set-once behavior after initialization. Inherits from `ApplicationException`.
#### `File.PersistentChannel.DependencyNotInitializedException`
Thrown when accessing a property whose dependency has not been initialized. Inherits from `ApplicationException`.
---
## 3. Invariants
1. **Magic Key Validation:** `BinaryDasTimestampHeader` requires `MagicKey == 0xF15363C2`. `BinaryChannelHeader` requires `MagicKey == 0x2C36351F`.
2. **Version Compatibility:** `BinaryChannelHeader` only supports header versions 1-4. Unknown versions may cause undefined behavior during CRC calculation.
3. **CRC Algorithm:** All CRC calculations use CRC16 (not CRC32 as property names suggest), initialized with `0xFFFF` and processed 16 bits at a time.
4. **Word Alignment:** CRC data is padded to even byte count for DIAdem `.dat` file compatibility.
5. **Set-Once Behavior:** `PersistentChannel` properties exhibit set-once behavior; re-initialization throws `AlreadyInitializedException`.
6. **Read-Only EU Indexer:** `PersistentEuChannel[ulong i]` setter throws `NotSupportedException`.
7. **EU String Padding:** Engineering Unit strings are padded to even length for CRC calculation when `stripEuPadding` is false.
---
## 4. Dependencies
### External Dependencies (from imports):
- `System` - Core .NET types
- `System.Collections.Generic` - `List<T>` for data collection
- `System.Text` - `Encoding.UTF8` for EU string encoding
- `System.Windows.Forms` - UI components for `ModifyChannel`
- `DTS.Common.Utilities` - `Exceptional` base class, utility functions
- `DTS.Common.Utilities.Logging` - `APILogger` for logging
- `DTS.Common.Utils` - `Utils.Math_DoCRC16Step()` for CRC calculation
- `DTS.Common.DAS.Concepts` - `DataScaler` for EU conversion
- `DTS.Common.Utilities.DotNetProgrammingConstructs` - `Property<T>` wrapper class
### Internal Dependencies:
- `File.PersistentChannel` is referenced by `PersistentEuChannel` and `ModifyChannel` but its full implementation is not provided in the source files.
- `File.Reader` is referenced by exception classes but its implementation is not provided.
---
## 5. Gotchas
1. **Misleading CRC Property Name:** Properties named `Crc32` actually compute a **CRC16** value (initialized to `0xFFFF`, processed 16 bits at a time). The method name and comments reference "CRC 32" but the implementation is CRC16.
2. **EU Field Length Bug Handling:** `BinaryChannelHeader.CalculateCrc32()` contains special handling for a historical bug where `EuFieldLengthWithTerminator` was set to `length + 1` incorrectly. The `plusOneFieldLengthBugErrorPresent` flag accommodates this.
3. **Duplicate Data in CRC Calculation:** In `BinaryChannelHeader.CalculateCrc32()`, `NumberOfSamples` is added to the CRC data twice (lines appear to be duplicated).
4. **Partial Class Structure:** Many classes are defined across multiple files using `partial class`. The complete implementation requires files not provided here (e.g., `SliceRaw.File.cs`, `SliceRaw.File.PersistentChannel.cs`, `SliceRaw.File.Reader.cs`).
5. **Version-Dependent Header Fields:** When reading older format files, fields like `RemovedADC`, `Excitation`, `TriggerAdjustmentSamples`, `ZeroMvInADC`, `OriginalOffsetADC`, and `WindowAverageADC` may not be present depending on `HeaderVersionNumber`.
6. **ModifyChannel Creates Backup:** The `btnBrowse_Click` method automatically creates a `.BAK` file when opening a channel, but silently deletes any existing backup without warning.
7. **Hardcoded Data Directory:** `ModifyChannel` defaults to a `DATA` subdirectory relative to `Environment.CurrentDirectory`.

63
docs/ai/Common/DTS.Common.Serialization/SoMat.md Normal file
View File

@@ -0,0 +1,63 @@
---
source_files:
- Common/DTS.Common.Serialization/SoMat/SoMat.File.cs
- Common/DTS.Common.Serialization/SoMat/SoMatTestHeader.cs
- Common/DTS.Common.Serialization/SoMat/SoMatChannel.cs
- Common/DTS.Common.Serialization/SoMat/SoMat.File.Writer.cs
generated_at: "2026-04-17T15:38:19.942361+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "950813b64d2e6206"
---
# SoMat Serialization Module Documentation
## 1. Purpose
This module provides serialization support for exporting `DTS.Serialization.Test` objects to the SoMat file format (a text-based format compatible with DIAdem). It implements the `IWritable<Test>` interface to write test data, channel metadata, and filtered data samples to `.txt` files with a specific key-value structure. The module transforms internal test/channel structures into the SoMat schema, including header information, channel definitions, and tab-separated data columns.
---
## 2. Public Interface
### `DTS.Serialization.SoMat.File`
A partial class representing the SoMat file format handler.
| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `File()` | Initializes a new instance, passing `"SoMat"` to the base `Serialization.File` constructor. |
| `Extension` | `static string Extension => ".txt"` | Static property returning the file extension for this format. |
| `Exporter` | `IWriter<Test> Exporter { get; }` | Lazily initializes and returns a `Writer` instance using `DefaultEncoding`. Wraps exceptions in a custom `Exception` with message "encountered problem getting exporter". |
---
### `DTS.Serialization.SoMat.SoMatTestHeader`
Represents the header section of a SoMat file.
| Member | Signature | Description |
|--------|-----------|-------------|
| `TestTitle` | `string TestTitle { get; set; }` | Defaults to empty string. |
| `Operator` | `string Operator { get; set; }` | Defaults to empty string. |
| `RunDateTime` | `string RunDateTime { get; set; }` | Defaults to empty string. |
| `NumLogChannels` | `int NumLogChannels => _channels.Count` | Read-only count of channels. |
| `Channels` | `SoMatChannel[] Channels => _channels.ToArray()` | Returns a copy of the internal channel list as an array. |
| `NumDataModes` | `int NumDataModes { get; set; }` | Defaults to `1`. |
| `Serialize` | `void Serialize(System.IO.StreamWriter sw)` | Writes header key-value pairs to the stream (DM_TestTitle, DM_Operator, RUNDATETIME, DM_NumLogChans, DM_NumDataModes). |
| Constructor | `SoMatTestHeader(Test test, FilteredData[] filteredData)` | Populates header from test data; attempts to set Operator from `WindowsIdentity.GetCurrent().Name` (silently catches exceptions). Creates `SoMatChannel` instances for each channel up to `filteredData.Length`. |
---
### `DTS.Serialization.SoMat.SoMatChannel`
Represents a single channel's metadata in the SoMat format.
| Member | Signature | Description |
|--------|-----------|-------------|
| `LogicalChannel` | `int LogicalChannel { get; set; }` | Logical channel number. |
| `ChanType` | `string ChanType { get; set; }` | Defaults to `"SEQUENTIAL"`. |
| `ChanName` | `string ChanName { get; set; }` | Defaults to empty string. |
| `NumDataPoints` | `ulong NumDataPoints { get; set; }` | Defaults to `0`. |
| `NumDims` | `int NumDims { get; set; }` | Defaults to `2`. |
| `DataMode` | `int DataMode { get; set; }` | Defaults to `1`. |
| `DataModeType` | `string DataModeType { get; set; }` | Defaults to `"TIMHIS"`. |
| `AxisLabelDim1` | `string AxisLabelDim1 { get; set; }` | Defaults to `"Time"`. |
| `AxisUnitsDim1

28
docs/ai/Common/DTS.Common.Serialization/StringResources.md Normal file
View File

@@ -0,0 +1,28 @@
---
source_files:
- Common/DTS.Common.Serialization/StringResources/Strings.Designer.cs
generated_at: "2026-04-17T16:10:52.944180+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "36ac7204bb194b1d"
---
# StringResources
### Purpose
This module provides strongly-typed access to localized string resources for the `DTS.Serialization` namespace. It is an auto-generated designer class (from a `.resx` file) that exposes error messages and string constants used in serialization operations, particularly related to "Slice Control" event validation and comparison failures.
### Public Interface
The `Strings` class is marked `internal`, so it is only accessible within the `DTS.Serialization.StringResources` namespace/assembly:
- `internal static ResourceManager ResourceManager { get; }` — Returns the cached `ResourceManager` instance for the "DTS.Serialization.StringResources.Strings" resource bundle. Lazily initialized.
- `internal static CultureInfo Culture { get; set; }` — Gets or sets the current thread's UI culture for resource lookups.
- `internal static string DTS_Slice_Control_Equals_ComparisonFailedString { get; }` — Localized string for comparison failure messages.
- `internal static string DTS_Slice_Control_Event_ConstructionFailedString { get; }` — Localized string for event construction failure.
- `internal static string DTS_Slice_Control_Event_Event_DASTestIdMismatchString { get; }` — Localized string for DAS test ID mismatch errors.
- `internal static string DTS_Slice_Control_Event_Event_EmptyDasListString { get; }` — Localized string for empty DAS list errors.
- `internal static string DTS_Slice_Control_Event_Event_FailedToDetermineIdOrDescriptionFromConfigurationString { get; }` — Localized string for configuration parsing failures.
- `internal static string DTS_Slice_Control_Event_Event_NullDasListString { get; }` — Localized string for null DAS list errors.
- `internal static string DTS_Slice_Control_Event_Module_Channel_DataEquals_ComparisonFailedString { get; }` — Localized string for channel data comparison failures.
- `internal static string DTS_Slice_Control_Event_Module_ChannelsEquals_ComparisonFailedString { get; }` — Localized string for channels equality comparison failures.
- `internal static string DTS_Slice

226
docs/ai/Common/DTS.Common.Serialization/TDAS.md Normal file
View File

@@ -0,0 +1,226 @@
---
source_files:
- Common/DTS.Common.Serialization/TDAS/TDAS.File.Reader.BadCrcException.cs
- Common/DTS.Common.Serialization/TDAS/TDAS.File.Reader.MissingFileException.cs
- Common/DTS.Common.Serialization/TDAS/TDAS.File.Reader.TooManyFilesException.cs
- Common/DTS.Common.Serialization/TDAS/TDAS.File.IChannelHeader.cs
- Common/DTS.Common.Serialization/TDAS/TDAS.File.PersistentChannel.NotInitializedException.cs
- Common/DTS.Common.Serialization/TDAS/TDAS.File.PersistentChannel.DataTooBigForArrayException.cs
- Common/DTS.Common.Serialization/TDAS/TDAS.File.cs
- Common/DTS.Common.Serialization/TDAS/TDAS.File.BinaryChannelHeader.cs
- Common/DTS.Common.Serialization/TDAS/TDAS.File.Writer.cs
- Common/DTS.Common.Serialization/TDAS/TLFBin.cs
generated_at: "2026-04-17T15:31:04.374981+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "6096e17ba8eed1d1"
---
# TDAS File Serialization Module Documentation
## 1. Purpose
This module provides TDAS (Test Data Acquisition System) file serialization and deserialization capabilities for the DTS framework. It handles reading and writing TDAS-specific file formats including `.tlf` test files, `.BIN` binary channel data files, and `.cchn` calculated channel files. The module implements binary channel header structures with CRC validation, supports multiple sensor types including digital input modes, and provides comprehensive exception handling for file I/O operations specific to the TDAS data acquisition workflow.
---
## 2. Public Interface
### `DTS.Serialization.TDAS.File` (partial class)
**Constructor:**
- `File()` — Initializes a new instance with format identifier "TDAS".
**Static Properties:**
- `string Extension` — Returns `".tlf"`, the file format extension.
- `string TestFileExtension` — Gets/sets the test file extension (default: `".tlf"`).
- `string ChannelFileExtension` — Gets/sets the channel file extension (default: `".BIN"`).
- `string CalculatedChannelFileExtension` — Gets/sets the calculated channel extension (default: `".cchn"`).
**Instance Properties:**
- `IWriter<Test> Exporter` — Gets the file writer instance (lazy-initialized).
- `IReader<Test> Importer` — Gets the file reader instance (lazy-initialized).
**Methods:**
- `int GetChannelNumberFromChannelFileName(string channelFileName)` — Extracts the 3-digit channel number from a channel filename by parsing before the extension.
---
### `DTS.Serialization.TDAS.File.Reader` (nested partial class)
**Nested Exception Types:**
#### `BadCrcException : Exception`
Represents a bad CRC file event.
| Constructor | Description |
|-------------|-------------|
| `BadCrcException()` | Default constructor. |
| `BadCrcException(string msg)` | Initializes with message. |
| `BadCrcException(string msg, System.Exception innerEx)` | Initializes with message and inner exception. |
#### `MissingFileException : Exception`
Represents a missing-file event.
| Constructor | Description |
|-------------|-------------|
| `MissingFileException()` | Default constructor. |
| `MissingFileException(string msg)` | Initializes with message. |
| `MissingFileException(string msg, System.Exception innerEx)` | Initializes with message and inner exception. |
#### `TooManyFilesException : Exception`
Represents a too-many-files event.
| Constructor | Description |
|-------------|-------------|
| `TooManyFilesException()` | Default constructor. |
| `TooManyFilesException(string msg)` | Initializes with message. |
| `TooManyFilesException(string msg, System.Exception innerEx)` | Initializes with message and inner exception. |
---
### `DTS.Serialization.TDAS.File.PersistentChannel` (nested partial class)
**Nested Exception Types:**
#### `NotInitializedException : ApplicationException`
Thrown when attempting to access a property that has not been initialized.
| Constructor | Description |
|-------------|-------------|
| `NotInitializedException()` | Default constructor. |
| `NotInitializedException(string msg)` | Initializes with message. |
| `NotInitializedException(string msg, System.Exception innerEx)` | Initializes with message and inner exception. |
#### `DataTooBigForArrayException : ApplicationException`
Thrown when attempting to convert a large dataset to an array that exceeds safe handling limits.
| Constructor | Description |
|-------------|-------------|
| `DataTooBigForArrayException()` | Default constructor. |
| `DataTooBigForArrayException(string msg)` | Initializes with message. |
| `DataTooBigForArrayException(string msg, System.Exception innerEx)` | Initializes with message and inner exception. |
---
### `DTS.Serialization.TDAS.IChannelHeader` (interface)
Defines the contract for channel header data.
| Property | Type | Description |
|----------|------|-------------|
| `AcquisitionRate` | `Double` | Get/set acquisition rate value. |
| `NumberOfPreT0DataPoints` | `int` | Get/set number of pre-T0 data points. |
| `NumberOfPostT0DataPoints` | `int` | Get/set number of post-T0 data points. |
| `PreZeroLevelInCnts` | `int` | Get/set pre-zero level in counts. |
| `PreCalLevelInCnts` | `int` | Get/set pre-calibration level in counts. |
| `SignalToNoiseRatioInDb` | `Double` | Get/set signal-to-noise ratio in dB. |
| `PostZeroLevelInCnts` | `int` | Get/set post-zero level in counts. |
| `PostCalLevelInCnts` | `int` | Get/set post-calibration level in counts. |
| `DataZeroLevelInCnts` | `int` | Get/set data zero level in counts. |
| `ScaleFactorMVPerCnt` | `Double` | Get/set scale factor (mV per count). |
| `ScaleFactorEUPerCnt` | `Double` | Get/set scale factor (EU per count). |
---
### `DTS.Serialization.TDAS.File.TDASBinaryChannelHeader` (nested class)
Implements `IChannelHeader` and `Exceptional`. Represents binary channel header information.
**Properties (in addition to `IChannelHeader`):**
- `UInt32 Crc32` — Gets the CRC for the current header state.
- `UInt32 UnpaddedEuCrc32` — Gets the CRC with EU padding automatically stripped.
- `UInt32 UnpaddedEuStringPaddedEuLengthCrc32` — Gets the CRC with unpadded EU string but padded EU length.
**Private Methods:**
- `UInt32 CalculateCrc32(bool stripEuPadding, bool bKeepEuLength)` — Calculates CRC16 for the binary channel header.
---
### `DTS.Serialization.TDAS.File.Writer` (nested class)
Implements `IWriter<Test>`. Serializes `Test` objects to TDAS format.
**Constructor:**
- `Writer(File fileType, int encoding)` — Internal constructor.
**Methods:**
- `void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)` — **Throws `NotSupportedException`**.
- `void Write(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested, double minStartTime, int dataCollectionLength)` — Writes the test to TDAS format files.
- `void Initialize(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested)` — Empty implementation.
---
### `DTS.Serialization.TDAS.TLFBin`
Helper class for binary channel file serialization.
**Constructor:**
- `TLFBin(Test.Module.Channel channel, double superSampleRate)` — Initializes header values from channel data.
**Properties:**
| Property | Type |
|----------|------|
| `AcquisitionRate` | `double` |
| `PreTriggerDataPoints` | `int` |
| `PostTriggerDataPoints` | `int` |
| `PreZeroLevel` | `int` |
| `PreCalLevel` | `int` |
| `SignalToNoiseRatio` | `double` |
| `PostZeroLevel` | `int` |
| `PostCalLevel` | `int` |
| `SuperSampleRate` | `double` |
**Methods:**
- `void Serialize(System.IO.BinaryWriter bw, Test.Module.Channel channel)` — Serializes channel data to binary format, handling digital inputs and linearization formulas.
---
## 3. Invariants
1. **Channel Number Format**: Channel numbers are extracted from filenames using a fixed 3-character format (e.g., `"001"`, `"901"`).
2. **Squib Channel Numbering**: Squib channels always start numbering at `901` and increment; regular channels start at `LastChannelNumber + 1`.
3. **CRC Algorithm**: Binary channel headers use CRC16 with initial value `0xFFFF`, processing data in 2-byte steps.
4. **Exception Pattern**: All custom exceptions provide three standard constructors: parameterless, message-only, and message-with-inner-exception.
5. **File Extension Consistency**: The `ChannelFileExtension` lookup is case-insensitive (checks both `".BIN"` and `".bin"`).
6. **Binary Data Alignment**: CRC calculation pads data to even byte count (`if (data.Count % 2 > 0) data.Add(0x0)`).
---
## 4. Dependencies
### This Module Depends On:
- `DTS.Common.Utilities.DotNetProgrammingConstructs` — `Property<T>` class
- `DTS.Common.Utilities` — `Exceptional` interface
- `DTS.Common.Utils` — `Math_DoCRC16Step` for CRC calculation
- `DTS.Common.Utilities.Logging` — `APILogger` for error logging
- `DTS.Common.Constant` — `SensorConstants.BridgeType`
- `DTS.Common.Enums` — `DigitalInputModes` enum
- `DTS.Common.Enums.Sensors` — Sensor-related constants
- `DTS.Serialization.Test` — `Test`, `Test.Module.Channel`, `Test.Module.AnalogInputChannel`
- `SliceRaw.File.Reader` — `GetDataScaler()` method
- `System.IO` — `BinaryWriter`, `StreamWriter`, `FileStream`
- `System.Linq` — Channel queries
### External References (Inferred):
- `Serialization.File` — Base class for `File`
- `IWritable<Test>`, `IWriter<Test>`, `IReader<Test>` — Serialization interfaces
- `FilteredData`, `BeginEventHandler`, `CancelEventHandler`, `EndEventHandler`, `TickEventHandler`, `ErrorEventHandler`, `CancelRequested` — Event/delegate types
- `TLF` — TLF file format handler
---
## 5. Gotchas
1. **Unsupported Write Overload**: The `Write(pathname, id, test, bFiltering, ...)` overload with fewer parameters throws `NotSupportedException`. Use the full parameter version instead.
2. **Hardcoded Post-Test Values**: In `TLFBin`, `PostZeroLevel` and `PostCalLevel` are hardcoded to `0` with a `@TODO` comment indicating this information is not currently available.
3. **PreCalLevel Derivation**: `PreCalLevel` is set to `70%` of `short.MaxValue` (`0.7D * short.MaxValue`) rather than being read from actual calibration data.
4.

152
docs/ai/Common/DTS.Common.Serialization/TDM.md Normal file
View File

@@ -0,0 +1,152 @@
---
source_files:
- Common/DTS.Common.Serialization/TDM/File.cs
- Common/DTS.Common.Serialization/TDM/TDMParameterDlg.cs
- Common/DTS.Common.Serialization/TDM/Writer.cs
- Common/DTS.Common.Serialization/TDM/TestHeader.cs
- Common/DTS.Common.Serialization/TDM/TDMParameterDlg.Designer.cs
- Common/DTS.Common.Serialization/TDM/ChannelHeader.cs
generated_at: "2026-04-17T15:34:32.846343+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "0fe61a89fffa2819"
---
# TDM Serialization Module Documentation
## 1. Purpose
This module provides TDM (Test Data Management) CSV export functionality for test data objects. It serializes `Test` objects into a legacy CSV format compatible with TDM, THF, and TEMA analysis systems. The module handles the complete export pipeline including test headers, channel headers, and channel data, with support for time range selection, subsampling, and optional data filtering. A Windows Forms dialog (`TDMParameterDlg`) provides user configuration for export parameters.
---
## 2. Public Interface
### `DTS.Serialization.TDM.File`
A file type definition for TDM exports, inheriting from `Serialization.File` and implementing `IWritable<Test>`.
| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `File()` | Initializes with format name "TDM CFC1000" |
| `Exporter` | `IWriter<Test>` (get) | Lazy-initializes and returns a `Writer` instance, configuring it with `Start` and `Stop` values |
| `Start` | `double` (get/set) | Export start time in seconds |
| `Stop` | `double` (get/set) | Export stop time in seconds |
### `DTS.Serialization.TDM.TDMParameterDlg`
A Windows Forms dialog for collecting TDM export parameters from the user.
| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `TDMParameterDlg(string testName, double testStart, double testEnd)` | Initializes dialog with test name and valid time bounds; sets default file path and populates start/stop fields from settings or test bounds |
| `FileName` | `string` (get) | Returns the user-selected output file path |
| `Start` | `double` (get) | Returns start time in seconds (divides textbox value by 1000) |
| `Stop` | `double` (get) | Returns stop time in seconds (divides textbox value by 1000) |
### `DTS.Serialization.TDM.Writer`
Handles the actual serialization of `Test` objects to TDM CSV format.
| Member | Signature | Description |
|--------|-----------|-------------|
| `AllowTTSExportFiltering` | `bool` (get/set) | Enables/disables filtered data export; default `false` |
| `Start` | `double` (get/set) | Export start time |
| `Stop` | `double` (get/set) | Export stop time |
| `FilteredData` | `List<FilteredData>` (get/set) | Filtered channel data for export |
| `Test` | `Test` (get/set) | The test object being exported |
| `IncrementLevel` | `ulong` (get) | Calculated tick increment for progress reporting |
| `SubSampleInterval` | `ushort` (get/set) | Subsampling interval; default behavior uses 1 |
| `ExtensionPrefix` | `string` (get/set) | Optional prefix for output filename |
| `Write` | `void Write(string pathname, string id, Test target, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)` | **Throws `NotSupportedException`** |
| `Write` | `void Write(string pathname, string id, string dataFolder, Test target, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler onBeginEvent, CancelEventHandler onCancelEvent, EndEventHandler onEndEvent, TickEventHandler onTickEvent, ErrorEventHandler onErrorEvent, CancelRequested cancelRequested, double minStartTime, int dataCollectionLength)` | Main export method; rounds `Start`/`Stop` to 3 decimal places, calculates progress increments, invokes begin event, and calls `DoExport` |
| `Initialize` | `void Initialize(...)` | Empty implementation (no-op) |
| `IncrementDone` | `void IncrementDone(double amount)` | Invokes the tick event handler with progress amount |
### `DTS.Serialization.TDM.TestHeader`
Writes the test header section of the TDM CSV file.
| Member | Signature | Description |
|--------|-----------|-------------|
| `WriteTestHeader` | `void WriteTestHeader(Writer writer, System.IO.TextWriter tw, bool bFiltered, ushort subSampleInterval, ulong numSamples, int preTriggerSamples)` | Writes test metadata including ID, impact data, timestamps, device sections, sample counts, and channel count |
**Constants:**
- `MAX_TESTDEVICES = 1000`
- `MAX_DUMMY_DISPLAY = 16`
- `MAX_BARRIER_DISPLAY = 3`
- `MAX_GROUP_DISPLAY = 20`
- `MAX_DEVICE_DISPLAY = 40` (sum of above + 1)
- `DEV_TYPE_DUMMY = 'D'`, `DEV_TYPE_BARRIER = 'B'`, `DEV_TYPE_GROUP = 'G'`, `DEV_TYPE_UNDEFINED = 'U'`
- `MAX_DEVICE_LINES = 23`
- `MAX_OLD_GROUP_LINES = 4`
### `DTS.Serialization.TDM.ChannelHeader`
Writes the channel header section of the TDM CSV file.
| Member | Signature | Description |
|--------|-----------|-------------|
| `WriteChannelHeaderToString` | `void WriteChannelHeaderToString(Writer writer, System.IO.TextWriter tw, bool bFiltered, double start, double end)` | Writes 15 header lines per channel including DAS name, capacity, units, serial number, sensitivity, excitation, min/max values, Toyota calc fields, filter frequency, data flags, and channel codes |
**Constants (line indices):**
- `DAS_LINE = 0`, `CAPACITY_LINE = 1`, `EU_LINE = 2`, `SENSOR_SN_LINE = 3`
- `SENSITIVITY_LINE = 4`, `EXCITATION_LINE = 5`, `MIN_LINE = 6`, `MAX_LINE = 7`
- `TOYOTA_CALC1_LINE = 8`, `TOYOTA_CALC2_LINE = 9`, `TOYOTA_CALC3_LINE = 10`
- `KNEE_POINT_LINE = 11`, `STRANGE_DATA_FLAG_LINE = 12`
- `CHANNEL_CODE_LINE = 13`, `CHANNEL_JCODE_LINE = 14`
---
## 3. Invariants
1. **Time ordering**: `Start` must be less than `Stop` (validated in `TDMParameterDlg.btnOK_Click`)
2. **Time bounds**: User-selected start/stop must fall within the test's actual data range (`_min` to `_max`)
3. **Pre-trigger samples**: Must be between `0` and `numSamples` (clamped in `WriteTestHeader`)
4. **Time precision**: `Start` and `Stop` are rounded to 3 decimal places (milliseconds) in `Writer.Write` to handle floating-point precision issues
5. **Channel exclusion**: Squib voltage channels (detected via `IsSquibVoltage()`) are excluded from the channel count in the test header
6. **Modules without channels**: Modules with zero channels are skipped during test header processing (e.g., Slice6DB modules for temperature storage)
---
## 4. Dependencies
### This module depends on:
- `System.Windows.Forms` - For `TDMParameterDlg` UI components
- `DTS.Common.DAS.Concepts` - For `Test`, `Test.Module.Channel`, `Test.Module.AnalogInputChannel`, `DataScaler`
- `DTS.Common.Utilities.Logging` - For `APILogger.Log`
- `DTS.Common.Enums.Sensors` - For `ChannelFilter` enum and `SensorConstants`
- `DTS.Common.Utilities` - For `DescriptionAttributeCoder<T>`
- `DTS.Serialization` (inferred) - For base class `Serialization.File`, `Serialization.File.Writer<File>`, interfaces `IWriter<Test>`, event handlers (`BeginEventHandler`, `EndEventHandler`, `TickEventHandler`, `CancelEventHandler`, `ErrorEventHandler`, `CancelRequested`)
- `Properties.Settings1` - For user settings (TDMFolder, DefaultStart, DefaultStop)
### What depends on this module:
- Unclear from source alone; the module exposes `IWriter<Test>` suggesting consumers use the interface to trigger exports
---
## 5. Gotchas
1. **Unsupported Write overload**: The 7-parameter `Write` method throws `NotSupportedException` with message "TDM::Writer Write(pathname, id, test, bFiltering) not supported". Callers must use the 16-parameter overload.
2. **Floating-point precision workaround**: `Start` and `Stop` are rounded to 3 decimal places in `Writer.Write`. The source comments indicate this is a "hack" to reconcile differences between TDAS and SLICE download models regarding trigger sample handling.
3. **Unit conversion in dialog**: `TDMParameterDlg` displays and accepts times in milliseconds (multiplies by 1000 on display, divides by 1000 on retrieval), but the `File` and `Writer` classes work in seconds.
4. **Progress tick limitations**: The progress reporting logic in `Writer.Write` notes that the dataform expects a uint and can only handle single tick progress updates. `IncrementLevel` is calculated to work around this for large sample counts.
5. **Incomplete device section implementation**: `TestHeader.WriteDeviceSection` has a comment noting that barriers and groups are written with blank lines, and the implementation is "not completely implemented equivalent to TDM" for these device types.
6. **Hardcoded values**:
- Squib channel capacity is hardcoded to `10`
- Squib excitation voltage is hardcoded to `5D`
- Digital excitation is hardcoded to `1D`
- Toyota Calc 1 (cable multiplier) is hardcoded to `1`
- Toyota Calc 2 and 3 are hardcoded to `0`
7. **Empty Initialize method**: `Writer.Initialize` is implemented but does nothing, which may indicate incomplete refactoring or an unused interface requirement.

143
docs/ai/Common/DTS.Common.Serialization/TDMS.md Normal file
View File

@@ -0,0 +1,143 @@
---
source_files:
- Common/DTS.Common.Serialization/TDMS/TDMS.File.cs
- Common/DTS.Common.Serialization/TDMS/TDMS.File.Writer.cs
generated_at: "2026-04-17T15:42:11.798940+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "a50ccb16d11e1148"
---
# TDMS Serialization Module Documentation
## 1. Purpose
This module provides TDMS (Technical Data Management Streaming) file format serialization for test data. It implements a writer that serializes `DTS.Serialization.Test` objects to disk in the NI TDMS format, capturing channel metadata, test properties, and raw measurement data. The module serves as an export mechanism for test results within the DTS serialization framework.
## 2. Public Interface
### `DTS.Serialization.TDMS.File` (partial class)
**Inheritance:** `Serialization.File`, `IWritable<Test>`
```csharp
public File(Common.ISO.TestPlan plan)
```
Constructor that initializes a TDMS file instance with the specified test plan. Sets the file format to "TDMS".
```csharp
public static string Extension => ".tdms"
```
Static property returning the file extension for TDMS files.
```csharp
public bool UseZeroForUnfiltered { get; set; }
public bool FilteredExport { get; set; }
```
Configuration properties for export behavior (default `false`).
```csharp
public override void SetEUData(string channelId, FilteredData fd)
public override FilteredData GetEUData(string channelId)
```
Methods for storing and retrieving engineering unit data for linearized channels via an internal dictionary.
```csharp
public IWriter<Test> Exporter { get; }
```
Property that lazily initializes and returns a `Writer` instance. Sets `WriterParent` on each access.
---
### `DTS.Serialization.TDMS.File.Writer` (nested class)
**Inheritance:** `Writer<File>`, `IWriter<Test>`
```csharp
internal Writer(File fileType, int encoding)
```
Internal constructor accepting the parent `File` object and encoding value.
```csharp
public File WriterParent { get; set; }
public Common.ISO.TestPlan TestPlan { get; set; }
public string ExtensionPrefix { get; set; }
```
Public properties for writer configuration.
```csharp
public void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)
```
Simplified write method that delegates to the full overload with null parameters for unused event handlers.
```csharp
public void Write(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested, double minStartTime, int dataCollectionLength)
```
Full write method that creates the output directory, writes the TDMS file with lead-in, metadata, and raw data. Invokes progress event handlers.
```csharp
public void Initialize(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested)
```
**Note:** Empty implementation in source.
---
### Private Enums and Constants
```csharp
private enum ToCMaskFields { TocMetaData, TocNewObjList, TocRawData, TocInterleavedData, TocBigEndian, TocDAQmxRawData }
private enum DataTypes { Void, I8, I16, I32, I64, U8, U16, U32, U64, SingleFloat, DoubleFloat, ExtendedFloat, SingleFloatWithUnit = 0x19, DoubleFloatWithUnit, ExtendedFloatWithUnit, String = 0x20, Boolean = 0x21, TimeStamp = 0x44, FixedPoint = 0x4F, ComplexSingleFloat = 0x08000c, ComplexDoubleFloat = 0x10000d }
private enum GroupProperties { TestId, Description, TestDate, TestTime }
private enum ChannelProperties { SensorSerialNo, ChannelDescriptionString, ChannelName, ModuleSerialNumber, SampleRate, NumberOfSamples, AAFilterRateHz, BridgeType, BridgeResistanceOhms, DesiredRange, Sensitivity, SensitivityUnits, ScaleFactorMV, ScaleFactorEU, LinearizationFormula, ZeroMethod, ZeroAverageWindowBegin, ZeroAverageWindowEnd, EU, InitialEU, InitialOffset, MeasuredShuntDeflectionMV, FactoryExcitationVoltage, MeasuredExcitationVoltage, SensorCalibrationDate, wf_xName, wf_xunit_string, wf_start_offset, wf_increment, wf_samples }
```
Key constants:
- `TDSmTag = "TDSm"`
- `ToCMask = 14` (TocMetaData | TocNewObjList | TocRawData)
- `Version = 4713`
- `NoRawDataAssigned = 0xFFFFFFFF`
- `ChannelObjectDataType = DataTypes.I16`
## 3. Invariants
- **File Format Version:** Always `4713` per TDMS specification.
- **Table of Contents Mask:** Fixed at `14` (combining `TocMetaData`, `TocNewObjList`, `TocRawData`).
- **Channel Data Type:** All channel data written as `I16` (16-bit signed integer).
- **File Object Structure:** TDMS files contain exactly 1 file object, 1 group object, plus N channel objects (where N = `test.Channels.Count`).
- **Raw Data Index:** File and Group objects always have `NoRawDataAssigned` (0xFFFFFFFF); channels have data index information.
- **Channel Path Format:** `/{groupId}/'{channelName}:{channelDescription}'`
- **Group Path Format:** `'/{testId}'` (test.Id is used as the group identifier).
## 4. Dependencies
### This module depends on:
- `System`, `System.IO`, `System.Linq`, `System.Collections.Generic` (BCL)
- `DTS.Common.Utilities.Logging.APILogger` for error logging
- `Serialization.File` (base class)
- `IWritable<Test>`, `IWriter<Test>` interfaces
- `Common.ISO.TestPlan`
- `DTS.Serialization.Test` and nested types:
- `Test.Module.Channel`
- `Test.Module.AnalogInputChannel`
- `Test.Channels`
- `FilteredData` type
- Delegate types: `BeginEventHandler`, `CancelEventHandler`, `EndEventHandler`, `TickEventHandler`, `ErrorEventHandler`, `CancelRequested`
### Consumers:
- Unclear from source alone; this module appears to be a plugin format within a larger serialization framework.
## 5. Gotchas
1. **Empty `Initialize` method:** The `Initialize` method has a signature matching `Write` but contains no implementation. It is unclear if this is intentional or incomplete.
2. **Unused parameters in `Write` overload:** The full `Write` method accepts parameters `dataFolder`, `fd`, `tmChannel`, `channelNumber`, `cancelEventHandler`, and `cancelRequested` that are not referenced in the method body.
3. **`Exporter` property side effect:** Every access to `Exporter` sets `WriterParent` on the cached writer instance, potentially overwriting previous values.
4. **Channel casting assumption:** All channels are cast to `Test.Module.AnalogInputChannel` without type checking. If `test.Channels` contains non-`AnalogInputChannel` types, this will throw at runtime.
5. **Superscript byte handling:** `GetSuperScriptBytes` calculates extra bytes for Unicode superscript characters in linearization formulas, which affects property length calculations.
6. **`ScaleFactorEU` calculation complexity:** The scale factor calculation branches on `ProportionalToExcitation` and `IsInverted` flags, and applies a `Multiplier`—logic that may not be obvious from the property name alone.
7. **Conditional excitation/shunt values:** `MeasuredShuntDeflectionMv` and excitation voltage properties are written as `0D` if their respective `Valid` flags are false, rather than omitting the property.

126
docs/ai/Common/DTS.Common.Serialization/TSV.md Normal file
View File

@@ -0,0 +1,126 @@
---
source_files:
- Common/DTS.Common.Serialization/TSV/TSV.File.cs
- Common/DTS.Common.Serialization/TSV/TSVTest.cs
- Common/DTS.Common.Serialization/TSV/TSVSettingsWindow.cs
- Common/DTS.Common.Serialization/TSV/TSV.File.Writer.cs
- Common/DTS.Common.Serialization/TSV/TSVChannel.cs
- Common/DTS.Common.Serialization/TSV/TSVSettingsWindow.Designer.cs
generated_at: "2026-04-17T15:35:48.983406+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "a3b01c62359ae1fc"
---
# TSV Serialization Module Documentation
## 1. Purpose
This module provides Tab-Separated Values (TSV) serialization for `Test` objects within the DTS serialization framework. It enables exporting test data and metadata to human-readable TSV files, supporting multiple data types (Raw ADC, Converted, and Processed/Filtered). The module includes a Windows Forms UI (`TSVSettingsWindow`) for configuring export parameters at both global and per-channel levels, and persists user preferences via application settings.
---
## 2. Public Interface
### `DTS.Serialization.TSV.File` (partial class)
**Inherits:** `Serialization.File`
**Implements:** `IWritable<Test>`
| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `File()` | Initializes a new instance with format name "TSV". |
| `Extension` | `static string Extension => ".tsv"` | Returns the file extension for this format. |
| `Exporter` | `IWriter<Test> Exporter { get; }` | Lazily initializes and returns a `Writer` instance for exporting tests. Throws `Exception` on failure. |
---
### `DTS.Serialization.TSV.TSVTest`
| Member | Signature | Description |
|--------|-----------|-------------|
| `Fields` | `public enum Fields` | Enumeration of metadata fields: `LabName`, `POCName`, `POCPhoneAndEmail`, `TestDate`, `TestTime`, `TestNumber`, `TestType`, `TestObject`, `DataType`, `SensorMakeModelSerial`, `SensorLocation`, `SensorAxis`, `SensorMountType`, `EngineeringUnits`, `ChannelErrors`, `SamplingRate`, `AAFilterCutoffDescription`, `BitResolution`, `DigitalFilterType`, `Notes`. |
| `GetValue` | `string GetValue(Fields field)` | Returns the value for the specified field. Adds `"#NOVALUE"` to the dictionary if the field is not present. |
| `SetValue` | `void SetValue(Fields field, string value)` | Sets a field value, propagates it to all channels in `_channels`, and persists specific fields (`POCName`, `POCPhoneAndEmail`, `DataType`, `LabName`, `TestObject`, `TestType`) to `Properties.Settings1.Default`. |
| `Channels` | `TSVChannel[] Channels { get; set; }` | Gets or sets the array of channels. Setting clears and repopulates the internal list. |
| `Test` | `Test Test { get; }` | The source test object. |
| `DataFilteredEU` | `FilteredData[] DataFilteredEU { get; }` | Filtered engineering unit data. |
| `DataUnfilteredEU` | `FilteredData[] DataUnfilteredEU { get; }` | Unfiltered engineering unit data. |
| `DataADC` | `FilteredData[] DataADC { get; }` | Raw ADC data. |
| `ActualRangesEUFiltered` | `double[] ActualRangesEUFiltered { get; }` | Actual ranges for filtered EU data. |
| `ActualRangesEUUnfiltered` | `double[] ActualRangesEUUnfiltered { get; }` | Actual ranges for unfiltered EU data. |
| `ActualRangesADC` | `double[] ActualRangesADC { get; }` | Actual ranges for ADC data. |
| Constructor | `TSVTest(Test test, FilteredData[] euFiltered, FilteredData[] adc, FilteredData[] euUnfiltered, string path, double[] actualRangesEUFiltered, double[] actualRangesEUUnfiltered, double[] actualRAngesADC)` | Initializes the test, data arrays, creates `TSVChannel` instances, and populates fields from test data and persisted settings. |
---
### `DTS.Serialization.TSV.TSVChannel`
| Member | Signature | Description |
|--------|-----------|-------------|
| `GetValue` | `string GetValue(TSVTest.Fields field)` | Returns the value for the specified field. Adds `"#NOVALUE"` if not present. |
| `SetValue` | `void SetValue(TSVTest.Fields field, string value)` | Sets a field value. Special handling for `DataType`: `"Raw"`, `"Processed"`, or `"Converted"` triggers recalculation of `EngineeringUnits`, `DigitalFilterType`, `BitResolution`, and `FileName`. |
| `FileName` | `string FileName { get; set; }` | The output file path for this channel. |
| `Serialize` | `void Serialize(TickEventHandler tickHandler)` | Creates the output directory if needed, writes metadata header lines, then writes time-value data pairs. Reports progress via `tickHandler`. |
| `ChannelNumber` | `int ChannelNumber => 1 + _channelIndex` | 1-based channel number. |
| Constructor | `TSVChannel(TSVTest parentTest, int channelIndex, string path)` | Initializes from parent test and channel index. Sets initial values for `EngineeringUnits`, `SensorMakeModelSerial`, `SensorLocation`, `DigitalFilterType`, `BitResolution`, and default `FileName`. |
---
### `DTS.Serialization.TSV.File.Writer` (nested class)
**Inherits:** `Writer<File>`
**Implements:** `IWriter<Test>`
| Member | Signature | Description |
|--------|-----------|-------------|
| `ExportMode` | `public enum ExportMode` | Values: `FtssExcel`, `Ttc`, `Standard`. |
| `CurrentExportMode` | `ExportMode CurrentExportMode { get; set; }` | Gets/sets the current export mode. Defaults to `ExportMode.FtssExcel`. Persisted via `Property<ExportMode>`. |
| `FilteredChannelData` | `List<FilteredData> FilteredChannelData { get; set; }` | Optional filtered channel data list. |
| `MyTSVTest` | `TSVTest MyTSVTest { get; set; }` | The `TSVTest` instance to write. |
| `Start` | `double Start { get; set; }` | Default: `0D`. |
| `Stop` | `double Stop { get; set; }` | Default: `0D`. |
| `SubSampleInterval` | `ushort SubSampleInterval { get; set; }` | Subsample interval. |
| `Filtered` | `bool Filtered { get; set; }` | Filtered flag. |
| Constructor | `internal Writer(File fileType, int encoding)` | Internal constructor. |
| `Write` (overload 1) | `void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)` | **Throws `NotSupportedException`.** |
| `Write` (overload 2) | `void Write(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested, double minStartTime, int dataCollectionLength)` | Invokes `beginEventHandler`, serializes each channel via `channel.Serialize(tickEventHandler)`, handles exceptions, and invokes `endEventHandler`/`errorEventHandler` as appropriate. |
| `Initialize` | `void Initialize(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested)` | Empty implementation. |
---
### `DTS.Serialization.TSV.TSVSettingsWindow`
**Inherits:** `Form`
| Member | Signature | Description |
|--------|-----------|-------------|
| Constructor | `TSVSettingsWindow(TSVTest test)` | Initializes the form, populates `c1GridGlobal` with non-excluded fields, populates `c1GridChannels` with channel data. Excluded fields: `AAFilterCutoffDescription`, `BitResolution`, `ChannelErrors`, `DataType`, `DigitalFilterType`, `EngineeringUnits`, `SensorAxis`, `SensorLocation`, `SensorMakeModelSerial`, `SensorMountType`. |
| `button1_Click` | `void button1_Click(object sender, EventArgs e)` | Sets `DialogResult.OK` and closes the form. |
| `c1GridGlobal_AfterEdit` | `void c1GridGlobal_AfterEdit(object sender, RowColEventArgs e)` | Updates `_test.SetValue()` and refreshes corresponding column in `c1GridChannels`. |
| `c1GridChannels_AfterEdit` | `void c1GridChannels_AfterEdit(object sender, RowColEventArgs e)` | Updates the `TSVChannel.SetValue()` for the edited cell. |
---
## 3. Invariants
1. **Channel Index Bounds:** `_channelIndex` in `TSVChannel` must be a valid index into `_parentTest.Test.Channels`, `_parentTest.DataADC`, `_parentTest.DataFilteredEU`, `_parentTest.DataUnfilteredEU`, and corresponding `ActualRanges*` arrays.
2. **DataType Values:** When setting `Fields.DataType` on a `TSVChannel`, the value must be one of: `"Raw"`, `"Processed"`, or `"Converted"`. Other values will not trigger file path or metadata recalculation.
3. **File Extension:** `File.Extension` always returns `".tsv"`.
4. **Default Value:** `GetValue` on both `TSVTest` and `TSVChannel` returns `"#NOVALUE"` for any field not explicitly set.
5. **Channel Number:** `TSVChannel.ChannelNumber` is always 1-based (`1 + _channelIndex`).
6. **Writer Export Mode:** `Writer.CurrentExportMode` defaults to `ExportMode.FtssExcel` and is persisted across sessions via the `Property<ExportMode>` mechanism.
---
## 4. Dependencies
### This module depends on:
- `DTS.Serialization` — Base `Serialization.File`, `Test` model, `FilteredData`, `IWriter<T>`, `IWritable<T>`, delegate types (`BeginEventHandler`, `CancelEventHandler`, `EndEventHandler`, `TickEventHandler`, `ErrorEventHandler`, `CancelRequested`)
- `DTS.Common.Utilities.DotNetProgrammingConstructs` — `Property<T>` class
- `DTS.Common.Utilities.Logging` — `APILogger`
- `C1.Win.C1FlexGrid` — Third-party grid control used in `TSVSettingsWindow`
- `System.Windows.Forms` — Windows Forms infrastructure
- `Properties.Settings1` — Application settings for persisting last-used values (`

173
docs/ai/Common/DTS.Common.Serialization/Test.md Normal file
View File

@@ -0,0 +1,173 @@
---
source_files:
- Common/DTS.Common.Serialization/Test/IConvertable.cs
- Common/DTS.Common.Serialization/Test/IntervalSec.cs
- Common/DTS.Common.Serialization/Test/DasTimestamp.cs
- Common/DTS.Common.Serialization/Test/Test.cs
generated_at: "2026-04-17T15:38:58.339536+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "c3111610a62a3486"
---
# DTS.Serialization.Test Module Documentation
## 1. Purpose
This module provides the core serialization framework for test data within the DTS (Diversified Technical Systems) system. The primary `Test` class serves as a serializable container for test metadata, data acquisition modules, channel configurations, and DAS timestamp information. It implements `IXmlSerializable` for custom XML serialization/deserialization and defines nested types for time intervals (`IntervalSec`) and DAS timestamps (`DasTimestamp`), as well as an `IConvertable` interface for bi-directional conversion between domain objects and `Test` instances.
---
## 2. Public Interface
### Test Class
**Namespace:** `DTS.Serialization`
**Constructors:**
- `Test()` — Parameterless constructor; initializes channel order lookup.
- `Test(string dtsfile)` — Constructor accepting a DTS file path (implementation body is empty in source).
- `Test(string id, string description)` — Initializes with ID and description; delegates to `Test(string, string, int)` with eventNumber=0.
- `Test(string id, string description, int eventNumber)` — Full constructor initializing Id, Description, and EventNumber.
**Properties:**
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `Software` | `string` | `"DataPRO"` | Software name associated with this test. |
| `SoftwareVersion` | `string` | `""` | Software version string. |
| `Id` | `string` | `""` | Test identifier. |
| `Description` | `string` | `""` | Test description. |
| `EventNumber` | `int` | `0` | Event number for this test. |
| `Guid` | `Guid` | Empty GUID | Globally unique identifier. |
| `FaultFlags` | `ushort` | `0` | Fault flags bitmask. |
| `ExtendedFaultFlags1` | `uint` | `0` | Extended fault flags (bank 1). |
| `ExtendedFaultFlags2` | `uint` | `0` | Extended fault flags (bank 2). |
| `ExtendedFaultFlags3` | `uint` | `0` | Extended fault flags (bank 3). |
| `ExtendedFaultFlags4` | `uint` | `0` | Extended fault flags (bank 4). |
| `InlineSerializedData` | `bool` | `false` | Controls inline serialization; propagates to all modules when set. |
| `Modules` | `List<Module>` | Empty list | Collection of modules in this test. |
| `DasTimestamps` | `List<DasTimestamp>` | Empty list | Collection of DAS timestamps. |
| `Channels` | `List<Module.Channel>` | Computed | Aggregated, sorted list of all channels from all modules. |
| `InceptionDate` | `DateTime` | `DateTime.Now` | Creation timestamp of serialization. |
**Methods:**
- `void ClearExtendedFaultFlags()` — Sets all four extended fault flag properties to 0.
- `void TryGetChannelOrder()` — Reads `ChannelOrder.txt` from current directory to establish custom channel ordering.
- `void WriteXml(XmlWriter writer)` — Serializes this object to XML.
- `void ReadXml(XmlReader reader)` — Deserializes this object from XML.
- `XmlSchema GetSchema()` — Returns `null` (required by `IXmlSerializable`).
- `override bool Equals(object obj)` — Compares Id, Description, and Modules for equality.
- `override int GetHashCode()` — Returns `base.GetHashCode()`.
- `void SaveTest(string directory, string testId, int defaultEncoding, bool includeGroupNameInISOExport)` — Saves test to .dts file with backup handling.
**Nested Types:**
- `ChannelOrderComparor : IComparer<Module.Channel>` — Comparer for channel ordering based on external file.
---
### Test.IConvertable Interface
**Namespace:** `DTS.Serialization`
```csharp
public delegate void ReportErrors(List<string> errors);
public interface IConvertable
{
Test ToDtsSerializationTest();
void FromDtsSerializationTest(Test test, ReportErrors reportErrors);
}
```
- `Test ToDtsSerializationTest()` — Converts implementing object to a `Test` instance.
- `void FromDtsSerializationTest(Test test, ReportErrors reportErrors)` — Initializes implementing object from a `Test` instance; errors reported via callback.
---
### Test.IntervalSec Class
**Namespace:** `DTS.Serialization`
**Base Class:** `Exceptional`
**Constructors:**
- `IntervalSec()` — Parameterless; Begin and End remain at default (0).
- `IntervalSec(double begin, double end)` — Initializes with specified begin and end times.
**Properties:**
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `Begin` | `double` | `0` | Interval begin time in seconds. |
| `End` | `double` | `0` | Interval end time in seconds. |
| `DoRoundOffValues` | `bool` | `false` | Controls automatic rounding of Begin/End on get. |
| `NumberRoundingDecimalPlaces` | `int` | `6` | Decimal places for rounding when enabled. |
**Methods:**
- `override bool Equals(object obj)` — Compares Begin and End values.
- `override int GetHashCode()` — Returns `base.GetHashCode()`.
---
### Test.DasTimestamp Class
**Namespace:** `DTS.Serialization`
**Base Class:** `Exceptional`
**Attribute:** `[XmlSerializationTag("DasTimestamp")]`
**Constructor:**
- `DasTimestamp(Test parentTest)` — Requires parent `Test` reference.
**Properties:**
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `ParentTest` | `Test` | `null` | Reference to containing Test object. |
| `BaseSerialNumber` | `string` | `""` | DAS base serial number. |
| `NumberOfSamples` | `UInt64` | `0` | Sample count. |
| `NumberOfBitsPerSample` | `UInt32` | `0` | Bits per sample timestamp. |
| `FileName` | `string` | `""` | Name of corresponding .bin file. |
**Methods:**
- `void WriteXml(XmlWriter writer)` — Writes XML; only serializes `BaseSerialNumber` and `NumberOfSamples`.
- `void ReadXml(XmlReader reader)` — Reads XML; sets `NumberOfBitsPerSample` to `8 * sizeof(ulong)` (64) if not present.
- `XmlSchema GetSchema()` — Returns `null`.
- `override bool Equals(object obj)` — Compares FileName, NumberOfSamples, NumberOfBitsPerSample, and BaseSerialNumber.
- `override int GetHashCode()` — Returns `base.GetHashCode()`.
---
## 3. Invariants
- **IntervalSec**: When `DoRoundOffValues` is `true`, the getter returns rounded values but the underlying stored value is unrounded.
- **DasTimestamp**: `NumberOfBitsPerSample` defaults to 64 (`8 * sizeof(ulong)`) when not present in XML.
- **Test.Guid**: Always initialized; defaults to `00000000-0000-0000-0000-000000000000` if parsing fails.
- **Test.Channels**: Always returns a sorted list; sorting is by `AbsoluteDisplayOrder`, then `ParentModule.Number`, then `Channel.Number`, with optional external ordering from `ChannelOrder.txt`.
- **Test.InlineSerializedData**: Setting this property propagates the value to all modules in `Modules`.
- **XML Serialization**: All properties marked with `[XmlSerializationTag]` are candidates for serialization, but `DasTimestamp.WriteXml` does not serialize all tagged properties.
---
## 4. Dependencies
**This module depends on:**
- `System`, `System.Collections.Generic`, `System.IO`, `System.Text`
- `System.Xml`, `System.Xml.Schema`, `System.Xml.Serialization`
- `DTS.Common.Utilities` — Provides `Exceptional` base class
- `DTS.Common.Utilities.DotNetProgrammingConstructs` — Provides `Property<T>`
- `DTS.Common.Utilities.Logging` — Provides `APILogger`
- `DTS.Common.Utilities.Xml` — Provides `XmlSerializationTagAttribute`, `AttributeExtractor<T>`
**Consumers of this module:**
- Not determinable from the provided source files alone.
---
## 5. Gotchas
1. **Empty Constructor**: `Test(string dtsfile)` has an empty body — it does not load the file despite the parameter name suggesting it should.
2. **Incomplete XML Serialization in DasTimestamp**: `WriteXml` only writes `BaseSerialNumber` and `NumberOfSamples`, but `ReadXml` attempts to read `NumberOfBitsPerSample` and `FileName` is never serialized. The source contains a TODO-style comment acknowledging this should use reflection for automatic property handling.
3. **GetHashCode Implementations**: Both `IntervalSec` and `DasTimestamp` override `Equals` for value-based comparison but `GetHashCode` returns `base.GetHashCode()`, which violates the .NET guideline that equal objects must have equal hash codes.
4. **ChannelOrder.txt Side Effect**: `Test.Channels` getter and constructors call `TryGetChannelOrder()`, which reads a file named `ChannelOrder.txt` from the current working directory. This creates an implicit dependency on the execution environment.
5. **Backup File Handling in SaveTest**: The backup file (`.dts.bak`) is only deleted if it was created during the current save operation; pre-existing backups are preserved.
6. **Fault Flags Not Serialized**: `FaultFlags` and `ExtendedFaultFlags1-4` are written to XML but not all are read back with the same robustness — `ExtendedFaultFlags` use `GetUintSafe` with defaults, while `FaultFlags` uses a try/catch with silent default to 0.
7. **IntervalSec Parameterless Constructor**: The comment states Begin and End are left "uninitialized", but they are actually initialized to 0 via the `Property<double>` default.

67
docs/ai/Common/DTS.Common.Serialization/Test/Module.md Normal file
View File

@@ -0,0 +1,67 @@
---
source_files:
- Common/DTS.Common.Serialization/Test/Module/IConvertable.cs
- Common/DTS.Common.Serialization/Test/Module/CalculatedChannel.cs
generated_at: "2026-04-17T15:38:29.079561+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "a6c5362a20ffc690"
---
# Documentation: DTS.Serialization.Test.Module
## 1. Purpose
This module defines the `CalculatedChannel` class and `IConvertable` interface within the `DTS.Serialization.Test.Module` namespace hierarchy. The `CalculatedChannel` class represents a derived data channel whose values are computed from one or more source channels, supporting XML serialization/deserialization and aggregation of multiple source channels. The `IConvertable` interface provides a contract for objects that can transform themselves to/from `Module` objects. This is part of a larger test serialization framework for capturing test measurement data.
---
## 2. Public Interface
### `DTS.Serialization.Test.Module.IConvertable` (Interface)
**Location:** `IConvertable.cs`
| Method | Signature | Description |
|--------|-----------|-------------|
| `ToDtsSerializationTestModule` | `Module ToDtsSerializationTestModule(Test parentTest)` | Converts the implementing object to a `Module` instance, receiving the containing `ParentTest` as context. |
| `FromDtsSerializationTestModule` | `void FromDtsSerializationTestModule(Module testModule, ReportErrors reportErrors)` | Initializes the implementing object from a `Module` instance, with error reporting via `ReportErrors` delegate/callback. |
---
### `DTS.Serialization.Test.Module.CalculatedChannel` (Class)
**Location:** `CalculatedChannel.cs`
**Inheritance:** Inherits from `AnalogInputChannel`
**XML Tag:** `[XmlSerializationTag("CalculatedChannel")]`
#### Constructor
| Signature | Description |
|-----------|-------------|
| `CalculatedChannel(Module parentModule)` | Constructs a new instance with a reference to its parent `Module`. |
#### Properties
| Property | Type | Default | XML Tag | Description |
|----------|------|---------|---------|-------------|
| `SourceChannelNumber` | `int[]` | `null` | `SourceChannelNumber` | Array of source channel numbers this calculated channel derives from. |
| `SourceModuleNumber` | `int[]` | `null` | `SourceModuleNumber` | Array of source module numbers. |
| `SourceModuleSerialNumber` | `string[]` | `null` | `SourceModuleSerialNumber` | Array of source module serial numbers. |
| `Calculation` | `string` | `"NONE"` | `Calculation` | The calculation expression/formula for this channel. |
| `T1` | `ulong` | `0` | `T1` | Time parameter 1 (HIC-related). Only serialized if `HIC` is initialized. |
| `T2` | `ulong` | `0` | `T2` | Time parameter 2 (HIC-related). Only serialized if `HIC` is initialized. |
| `HIC` | `double` | `0D` | `HIC` | Head Injury Criterion value. Conditionally serialized. |
| `SampleRateHz` | `double` | `0` | `SampleRateHz` | Sample rate in Hertz. |
#### Methods
| Method | Signature | Description |
|--------|-----------|-------------|
| `WriteXml` | `void WriteXml(XmlWriter writer)` | Serializes this object to XML. Writes `HIC`, `T1`, `T2` attributes only if `_HIC.IsValueInitialized` is true. |
| `ReadXml` | `void ReadXml(XmlReader reader)` | Deserializes from XML. Calls `base.ReadXml(reader)` first, then populates derived properties. `HIC`, `T1`, `T2` only read if `HIC` attribute is present and non-whitespace. |
| `Equals` | `override bool Equals(object obj)` | Memberwise equality check comparing: `ChannelId`, `SourceChannelNumber`, `ChannelDescriptionString`, `EngineeringUnits`, `Calculation`, `IsoCode`. |
| `GetHashCode` | `override int GetHashCode()` | Returns `base.GetHashCode()`. |
| `ToString` | `override string ToString()` | Returns `ChannelDescriptionString`. |
| `CreateInstance` (static) | `static CalculatedChannel CreateInstance(Channel[] channels)` | Factory method creating a `CalculatedChannel` from multiple source channels. Validates that the maximum sample rate is a multiple of each source's sample rate. Copies properties from the first channel via reflection. |
| `CreateInstance

160
docs/ai/Common/DTS.Common.Serialization/Test/Module/Channel.md Normal file
View File

@@ -0,0 +1,160 @@
---
source_files:
- Common/DTS.Common.Serialization/Test/Module/Channel/IConvertable.cs
- Common/DTS.Common.Serialization/Test/Module/Channel/ChannelWithMeta.cs
- Common/DTS.Common.Serialization/Test/Module/Channel/DataArray.cs
generated_at: "2026-04-17T15:38:47.836386+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "03e73ca9f12d1506"
---
# Documentation: DTS.Serialization.Test.Module.Channel
## 1. Purpose
This module provides serialization infrastructure for channel data within the DTS serialization framework. It defines a contract for channel conversion (`IConvertable`), a metadata wrapper for serialization operations (`ChannelWithMeta`), and a generic, XML-serializable data container (`DataArray<DataType>`) that handles typed channel data with associated scaling factors and unit conversions. The module is designed to support the serialization of measurement channel data with full fidelity of engineering unit conversions and timing metadata.
---
## 2. Public Interface
### `DTS.Serialization.Test.Module.Channel.IConvertable` (Interface)
**Location:** `IConvertable.cs`
Defines a conversion contract for objects that can transform to/from a `DTS.Serialization.Test.Module.Channel` object.
| Method | Signature | Description |
|--------|-----------|-------------|
| `ToDtsSerializationTestModuleChannel` | `Channel ToDtsSerializationTestModuleChannel()` | Converts the implementing object to a `Channel` instance. |
| `FromDtsSerializationTestModuleChannel` | `void FromDtsSerializationTestModuleChannel(Channel channel)` | Initializes the implementing object from a `Channel` instance. |
---
### `DTS.Serialization.ChannelWithMeta` (Class)
**Location:** `ChannelWithMeta.cs`
A container class bundling a channel with its associated metadata required for serialization.
**Constructor:**
```csharp
public ChannelWithMeta(DTS.Serialization.Test.Module.Channel channel, DataScaler scaler, double samplerate, double starttime)
```
**Properties:**
| Property | Type | Access | Description |
|----------|------|--------|-------------|
| `Channel` | `Test.Module.Channel` | Get only | The channel to be serialized. |
| `Scaler` | `DataScaler` | Get only | Scaling information for the channel. |
| `SampleRate` | `double` | Get only | Sample rate of the associated channel. |
| `StartTime` | `double` | Get only | Start time of the associated channel. |
**Static Methods:**
| Method | Signature | Description |
|--------|-----------|-------------|
| `GetMinStartTime` | `double GetMinStartTime(double start, IList<ChannelWithMeta> channelsWithMeta)` | Returns the maximum of the provided start value and the minimum start time across all channels. Note: Uses `Math.Max` because start times are typically negative. |
| `GetMinStopTime` | `double GetMinStopTime(double stop, IList<ChannelWithMeta> channelsWithMeta)` | Returns the minimum stop time across the provided stop value and all channels. Uses decimal arithmetic internally to avoid floating-point rounding errors. |
---
### `DTS.Serialization.Test.Module.Channel.DataArray<DataType>` (Generic Class)
**Location:** `DataArray.cs`
A generic, XML-serializable container for channel data with scaling and conversion metadata. Inherits from `Exceptional` and implements `IXmlSerializable`.
**Constructors:**
| Constructor | Signature |
|-------------|-----------|
| Default | `public DataArray()` |
| With values | `public DataArray(DataType[] values)` |
**Implicit Conversion Operators:**
| Operator | Signature | Description |
|----------|-----------|-------------|
| From `List<DataType>` | `implicit operator DataArray<DataType>(List<DataType> dataList)` | Converts a `List<DataType>` to a `DataArray<DataType>`. |
| To `List<DataType>` | `implicit operator List<DataType>(DataArray<DataType> dataArray)` | Converts a `DataArray<DataType>` to a `List<DataType>`. |
**Properties:**
| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `Values` | `DataType[]` | Empty array | The data values array. Returns empty array if uninitialized or null. |
| `ScaleFactorMv` | `double` | `0.0` | ADC to millivolt scale factor. |
| `ScaleFactorEU` | `double` | `0.0` | Engineering unit scale factor. |
| `UseEUScaleFactors` | `bool` | `false` | Flag indicating whether to use EU scale factors. |
| `DataZeroLevel` | `short` | `0` | Zero level offset for data. |
| `UnitConversion` | `double` | `1.0` | Unit conversion factor. |
| `Multiplier` | `double` | `1.0` | Multiplier for data. |
| `UserOffsetEU` | `double` | `0.0` | User-defined offset in engineering units. |
| `MvPerEu` | `double` | `0.0` | Millivolts per engineering unit sensitivity. |
**IXmlSerializable Methods:**
| Method | Signature | Description |
|--------|-----------|-------------|
| `WriteXml` | `void WriteXml(XmlWriter writer)` | Writes the data array and metadata to XML. Emits `Data` element with `Length`, `Type`, `ScaleFactorMv`, and `SensitivityMvEu` attributes, followed by individual `Datum` elements. |
| `ReadXml` | `void ReadXml(XmlReader reader)` | Reads and reconstructs the data array from XML. Dynamically instantiates the generic type and invokes its `Parse` method via reflection. |
| `GetSchema` | `XmlSchema GetSchema()` | Returns `null`. Not invoked during serialization. |
**Equality Methods:**
| Method | Signature | Description |
|--------|-----------|-------------|
| `Equals` | `override bool Equals(object obj)` | Memberwise equality comparison including `ScaleFactorMv`, `MvPerEu`, and all values in the `Values` array. |
| `GetHashCode` | `override int GetHashCode()` | Returns base implementation hash code. |
---
## 3. Invariants
1. **`DataArray<DataType>` Generic Constraint:** The `DataType` type parameter must have a `Parse(string)` method; otherwise, `ReadXml` will throw an exception with message "data type does not contain a \"Parse\" method".
2. **`DataArray.Values` Null Safety:** The `Values` property getter will never return `null`. If the internal `_Values` is uninitialized or null, it returns an empty `DataType[0]` array.
3. **`ChannelWithMeta` Immutability:** All properties on `ChannelWithMeta` are get-only; the class is effectively immutable after construction.
4. **`GetMinStopTime` Precision:** The method uses `decimal` arithmetic internally to avoid floating-point rounding errors (e.g., `4.999999999999995` vs `5.0`).
5. **XML Serialization Format:** `DataArray` XML output uses invariant culture (`CultureInfo("")`) for all numeric formatting to ensure locale-independent serialization.
---
## 4. Dependencies
### This Module Depends On:
- `System` (standard library)
- `System.Collections.Generic` (standard library)
- `System.Linq` (standard library)
- `System.Reflection` (standard library)
- `System.Xml` (standard library)
- `System.Xml.Schema` (standard library)
- `System.Xml.Serialization` (standard library)
- `DTS.Common.Utilities` (for `Exceptional` base class)
- `DTS.Common.Utilities.DotNetProgrammingConstructs` (for `Property<T>` wrapper class)
- `DTS.Common.DAS.Concepts` (for `DataScaler` type used in `ChannelWithMeta`)
### What Depends On This Module:
- **Unclear from source alone.** The partial class structure (`Test`, `Test.Module`, `Test.Module.Channel`) suggests other files exist that complete these class definitions, but they are not included in the provided sources.
---
## 5. Gotchas
1. **`IConvertable` Naming:** The interface is named `IConvertable` (with an 'a'), not the standard .NET spelling `IConvertible`. This is intentional but could cause confusion.
2. **`GetMinStartTime` Logic Inversion:** The method uses `Math.Max` to find the "minimum" start time because start times are typically negative values. This counterintuitive logic is documented in the source comment but may trip up developers.
3. **`DataArray.ReadXml` Reflection Dependency:** The XML deserialization relies on reflection to invoke a `Parse` method on the generic type. If `DataType` lacks this method or has an incompatible signature, deserialization will fail at runtime.
4. **`GetHashCode` Implementation:** The `DataArray<DataType>.GetHashCode()` method calls `base.GetHashCode()` rather than computing a hash from the object's values. This could lead to incorrect behavior if the object is used as a dictionary key or in a hash set.
5. **Partial Class Structure:** All three files contribute to nested partial classes (`Test.Module.Channel`). The full class definitions are spread across multiple files not provided here, as indicated by comments like `// *** see Test.cs ***`.
6. **XML End Element Handling:** In `ReadXml`, the call to `ReadEndElement()` is conditional based on whether the element name matches `DataXmlTag`. The comment indicates this handles edge cases with zero-length data, primarily occurring in unit tests.

139
docs/ai/Common/DTS.Common.Serialization/TestSetup.md Normal file
View File

@@ -0,0 +1,139 @@
---
source_files:
- Common/DTS.Common.Serialization/TestSetup/ExtraProperty.cs
- Common/DTS.Common.Serialization/TestSetup/Sensor.cs
- Common/DTS.Common.Serialization/TestSetup/TestSetup.cs
generated_at: "2026-04-17T15:40:22.555743+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "e880b50c9256e817"
---
# Documentation: DTS.Serialization.TestSetup
## 1. Purpose
This module provides a data model for test configuration and metadata in what appears to be a testing/measurement system. The `TestSetup` class serves as the primary container for test-related information including laboratory details, customer information, test engineer contacts, sensor configurations, graph definitions, and export/upload settings. It supports serialization (marked `[Serializable]`) and uses a custom property wrapper pattern (`Property<T>`) for property management. Nested classes `Sensor` and `ExtraProperty` provide structured storage for sensor configurations and custom key-value metadata respectively.
---
## 2. Public Interface
### TestSetup Class
**Namespace:** `DTS.Serialization`
**Inheritance:** `Exceptional`
**Attributes:** `[Serializable]`
#### Constructors
- `TestSetup()` — Default constructor initializing all properties to default values. Sets `Version` to `"2.0.0.0"`, `CalibrationBehavior` to `CalibrationBehaviors.NonLinearIfAvailable`, and initializes collection properties (`Graphs`, `Sensors`, `ExtraProperties`, `TestObjects`) to empty lists.
#### Upload Configuration Properties
| Property | Type | Description |
|----------|------|-------------|
| `Upload` | `bool` | Indicates whether the test setup was configured to upload when run. |
| `UploadFolder` | `string` | The upload folder path; can be overridden by an INI file. |
| `UploadExportsOnly` | `bool` | Controls whether only exports are uploaded. |
#### Test Metadata Properties
| Property | Type | Description |
|----------|------|-------------|
| `Name` | `string` | Name of the test setup. |
| `Description` | `string` | Description of the test. |
| `DateOfTheTest` | `string` | Date when the test was performed. |
| `TypeOfTheTest` | `string` | Type classification of the test. |
| `Subtype` | `string` | Subtype classification. |
| `Timestamp` | `string` | Timestamp of the test. |
| `Version` | `string` | Version string (default `"2.0.0.0"`). Marked `virtual`. |
| `TestComment` | `string` | Free-form comment field. |
| `ISFFile` | `string` | ISF file reference. |
#### Laboratory Information Properties
| Property | Type |
|----------|------|
| `LabName` | `string` |
| `LaboratoryName` | `string` |
| `LaboratoryContactName` | `string` |
| `LaboratoryContactPhone` | `string` |
| `LaboratoryContactFax` | `string` |
| `LaboratoryContactEmail` | `string` |
| `LaboratoryTestReferenceNumber` | `string` |
| `LaboratoryProjectReferenceNumber` | `string` |
#### Customer Information Properties
| Property | Type |
|----------|------|
| `CustName` | `string` |
| `CustomerName` | `string` |
| `CustomerTestReferenceNumber` | `string` |
| `CustomerProjectReferenceNumber` | `string` |
| `CustomerOrderNumber` | `string` |
| `CustomerCostUnit` | `string` |
#### Test Engineer Properties
| Property | Type |
|----------|------|
| `TEName` | `string` |
| `TestEngineerName` | `string` |
| `TestEngineerPhone` | `string` |
| `TestEngineerFax` | `string` |
| `TestEngineerEmail` | `string` |
#### Test Configuration Properties
| Property | Type | Description |
|----------|------|-------------|
| `CalibrationBehavior` | `CalibrationBehaviors` | Defaults to `NonLinearIfAvailable`. |
| `ExportFolder` | `string` | Folder for exports. |
| `ExportTypes` | `Int32` | Export format flags. |
| `ReferenceTemperature` | `string` | Reference temperature for the test. |
| `RelativeAirHumidity` | `string` | Relative air humidity. |
| `Regulation` | `string` | Regulation reference. |
| `NumberOfTestObjects` | `string` | Count of test objects. |
| `NumberOfMedia` | `string` | Count of media. |
#### Collection Properties
| Property | Type |
|----------|------|
| `Graphs` | `List<Graph>` |
| `Sensors` | `List<Sensor>` |
| `ExtraProperties` | `List<ExtraProperty>` |
| `TestObjects` | `List<TestObject>` |
#### XML-Ignored Runtime Properties
| Property | Type | Attribute |
|----------|------|-----------|
| `Channels` | `List<Graph.Channel>` | `[System.Xml.Serialization.XmlIgnore]` |
| `SingleChannelGraphs` | `List<Graph>` | `[System.Xml.Serialization.XmlIgnore]` |
| `SortedGraphs` | `IDictionary<Guid, Graph>` | `[System.Xml.Serialization.XmlIgnore]` |
#### Methods
- `void SortGraphs()` — Populates `SortedGraphs` dictionary. First adds all `Graphs` in their original order, then sorts `SingleChannelGraphs` by `AbsoluteDisplayOrder` and appends them.
---
### TestSetup.Sensor Class (Nested)
**Inheritance:** `Exceptional`
#### Constructors
- `Sensor()` — Default constructor. Sets `Version` to `"1.0.0.0"`, all other properties to `null`.
#### Properties
| Property | Type |
|----------|------|
| `FilterClass` | `string` |
| `Name` | `string` |
| `Polarity` | `string` |
| `Position` | `string` |
| `Range` | `string` |
| `Version` | `string` |
---
### TestSetup.ExtraProperty Class (Nested)
**Inheritance:** `Exceptional`
#### Constructors
- `ExtraProperty()` — Default constructor. Sets `Key` and `Value` to `null`, `Version` to `"1.0.0.0"`.
- `ExtraProperty(string key, string value)` — Initializes with specified key and value.
#### Properties
| Property

57
docs/ai/Common/DTS.Common.Serialization/TestSetup/Graph.md Normal file
View File

@@ -0,0 +1,57 @@
---
source_files:
- Common/DTS.Common.Serialization/TestSetup/Graph/Graph.cs
- Common/DTS.Common.Serialization/TestSetup/Graph/Channel.cs
generated_at: "2026-04-17T16:26:22.110592+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "1596815b04ddd43d"
---
# Graph
### Purpose
This module defines the data structure for a `TestSetup.Graph` and its nested `Channel` objects. It serves as a serialization-compatible model for test configurations, wrapping properties in a custom `Property` construct (likely for change tracking or validation) and exposing metadata about test channels, hardware associations, and versioning. It acts as a bridge between raw test module definitions and serialized storage formats.
### Public Interface
**Class: `TestSetup.Graph`**
* `Graph()` - Constructor. Initializes `Name` to null, `Version` to "1.0.0.0", and generates a new `Identifier`.
* `void UnSet()` - No-op implementation in current source.
* `List<Channel> Channels` - Gets or sets the list of channels associated with this graph.
* `string Name` - Gets or sets the name of the graph.
* `string HardwareChannelName` - Gets or sets the hardware channel name.
* `string DisplayName` - Read-only. Returns `_Name.Value + "_" + _HardwareChannelName.Value`.
* `string Version` - Gets or sets the version string.
* `bool IsSingleChannelGraph` - (XmlIgnore) Returns true if `Channels` is not null and contains exactly one channel.
* `Channel FirstChannel` - (XmlIgnore) Returns the first channel in the `Channels` list.
* `Test.Module.Channel FirstTestChannel` - (XmlIgnore) Returns the `TestChannel` property of the first channel in the list.
* `Guid Identifier` - (XmlIgnore) Gets a unique identifier for this graph instance; set privately by constructor.
**Class: `TestSetup.Graph.Channel`**
* `Channel(Test.Module.Channel channel)` - Constructor. Initializes the channel from a `Test.Module.Channel` object.
* `Channel(string channelId)` - Constructor. Initializes with a specific string ID; sets `ParentTestModule` and `TestChannel` to null.
* `Channel(long groupChannelId)` - Constructor. Initializes with a long ID converted to string; sets `ParentTestModule` and `TestChannel` to null.
* `string ChannelId` - Gets or sets the unique ID for the logical channel.
* `string ChannelGroupName` - Gets or sets the group name.
* `string Name` - Read-only. Returns `TestChannel.ChannelDescriptionString` or "Not Set".
* `string SensorName` - (XmlIgnore) Returns `TestChannel.ChannelDescriptionString` or "Not Set".
* `string AxisUnit` - (XmlIgnore) Returns engineering units if `TestChannel` is an `AnalogInputChannel`, otherwise "EU".
* `string SerialNumber` - (XmlIgnore) Returns `ParentTestModule.SerialNumber` or "Not Set".
* `Test.Module ParentTestModule` - (XmlIgnore) Field holding a reference to the parent test module.
* `Test.Module.Channel TestChannel` - (XmlIgnore) Field holding a reference to the underlying test channel.
### Invariants
* `Graph.Identifier` is immutable after construction (private setter).
* `Graph.Version` defaults to "1.0.0.0" upon instantiation.
* `Channel` has a private parameterless constructor, enforcing that instances must be created via one of the public constructors providing data.
* `Channel.Name`, `SensorName`, `AxisUnit`, and `SerialNumber` all return "Not Set" (or "EU" for units) if `TestChannel` is null.
### Dependencies
* **Depends on**: `System`, `System.Collections.Generic`, `DTS.Common.Utilities`, `DTS.Common.Utilities.DotNetProgrammingConstructs`, `Test.Module` (referenced in `Channel` constructors and properties).
* **Dependents**: Unknown from source alone, but likely serialization logic or test setup management components.
### Gotchas
* **Indexing Risks**: The properties `FirstChannel` and `FirstTestChannel` access `Channels[0]` directly without bounds checking. If `Channels` is null or empty, this will throw an exception.
* **DisplayName Format**: `DisplayName` concatenates values with an underscore. If `_Name.Value` is null (the default), the result will start with an underscore (e.g., `_HardwareName`).
* **Internal Property Wrappers**: Public properties are backed by `Property` objects. The behavior of these wrappers (e.g., validation logic) is defined in `DTS.Common.Utilities.DotNetProgrammingConstructs` and is not visible here.

84
docs/ai/Common/DTS.Common.Serialization/TestSetup/TestObject.md Normal file
View File

@@ -0,0 +1,84 @@
---
source_files:
- Common/DTS.Common.Serialization/TestSetup/TestObject/Channel.cs
- Common/DTS.Common.Serialization/TestSetup/TestObject/DASHardware.cs
- Common/DTS.Common.Serialization/TestSetup/TestObject/DASHardware.DASChannel.cs
- Common/DTS.Common.Serialization/TestSetup/TestObject/TestObject.cs
generated_at: "2026-04-17T15:38:31.613238+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "91ab4a5415c6a0dd"
---
# Documentation: DTS.Serialization TestObject Module
## 1. Purpose
This module defines a hierarchical data model for test setup configuration within the DTS (presumably Data Test System) serialization framework. It models physical test objects and their associated Data Acquisition System (DAS) hardware configurations, including channels, sensors, and measurement parameters. The classes are designed as nested partial classes under the `TestSetup` root, all inheriting from `Exceptional`, and use a custom `Property<T>` wrapper for property storage—likely to support serialization tracking, change notification, or validation.
---
## 2. Public Interface
### `TestSetup.TestObject` (partial class)
**Constructor:**
- `TestObject()` — Initializes all string properties to `null`, list properties to empty lists, and `Version` to `"1.0.0.0"`.
**Properties:**
| Property | Type | Description |
|----------|------|-------------|
| `BarrierHeight` | `string` | Barrier height value. |
| `BarrierWidth` | `string` | Barrier width value. |
| `Channels` | `List<TOChannel>` | Collection of channel configurations. Initialized to empty list. |
| `ClassOfTestObject` | `string` | Classification of the test object. |
| `CodeOfTestObject` | `string` | Code identifier for the test object. |
| `Comment1`, `Comment2`, `Comment3` | `string` | Free-form comment fields. |
| `DASHardwares` | `List<DASHardware>` | Collection of DAS hardware configurations. Initialized to empty list. |
| `DriverPositionObject` | `string` | Driver position identifier. |
| `ExcitationWarmupMS` | `string` | Excitation warmup time in milliseconds. |
| `ExtraProperties` | `List<ExtraProperty>` | Collection of additional properties. Initialized to empty list. |
| `ImpactSideTestObject` | `string` | Impact side designation. |
| `Location` | `string` | Location identifier. |
| `MassOfTestObject` | `string` | Mass of the test object. |
| `NameOfTestObject` | `string` | Name of the test object. |
| `NumberOfLoadCells` | `string` | Number of load cells. |
| `Offset` | `string` | Offset value. |
| `OriginX`, `OriginY`, `OriginZ` | `string` | 3D origin coordinates. |
| `ReferenceSystem` | `string` | Reference system identifier. |
| `RefNumberOfTestObject` | `string` | Reference number for the test object. |
| `SerialNumber` | `string` | Serial number. |
| `TargetSampleRate` | `string` | Target sample rate. |
| `Velocity` | `string` | Velocity value. |
| `VelocityMeasurementUnit` | `string` | Unit for velocity measurement. |
| `Version` | `string` | Version string, defaults to `"1.0.0.0"`. |
| `YawAngle` | `string` | Yaw angle value. |
**Note:** `TypeOfTestObject` is commented out in the source and is not available.
---
### `TestSetup.TestObject.TOChannel` (partial class)
**Constructor:**
- `TOChannel()` — Initializes `Name` and `SensorName` to `null`, `Version` to `"1.0.0.0"`.
**Properties:**
| Property | Type | Description |
|----------|------|-------------|
| `Name` | `string` | Channel name. |
| `SensorName` | `string` | Associated sensor name. |
| `Version` | `string` | Version string, defaults to `"1.0.0.0"`. |
---
### `TestSetup.TestObject.DASHardware` (partial class)
**Constructor:**
- `DASHardware()` — Initializes `SampleRate` and `SerialNumber` to `null`, `Version` to `"1.0.0.0"`. `DASChannels` initialized to empty list.
**Properties:**
|

150
docs/ai/Common/DTS.Common.Serialization/XLSX.md Normal file
View File

@@ -0,0 +1,150 @@
---
source_files:
- Common/DTS.Common.Serialization/XLSX/Excel.File.cs
- Common/DTS.Common.Serialization/XLSX/Excel.File.Writer.cs
generated_at: "2026-04-17T15:42:08.979045+00:00"
model: "zai-org/GLM-5-FP8"
schema_version: 1
sha256: "ab2a2a0d3558d3b8"
---
# Documentation: DTS.Serialization.XLSX
## 1. Purpose
This module provides XLSX (Excel) export functionality for test data within the DTS serialization framework. It implements the `Serialization.File` abstract base class and `IWriter<Test>` interface to export `Test` objects—specifically analog input channel data—to Excel spreadsheets. The module supports exporting data in multiple representations (ADC, EU, mV) and can apply SAE J211 filtering to channel data during export.
## 2. Public Interface
### `File` Class (partial)
**Namespace:** `DTS.Serialization.XLSX`
**Inheritance:** `Serialization.File`, `IWritable<Test>`
#### Constructor
```csharp
public File()
```
Constructs a new XLSX file instance, passing `"XLSX"` to the base class.
#### Properties
```csharp
public IWriter<Test> Exporter { get; }
```
Returns the writer instance for this file type. Lazily instantiates a `Writer` on first access. Throws `Exception` with message "encountered problem getting exporter" on failure.
```csharp
public bool ExportADC { set; }
public bool ExportEU { set; }
public bool ExportMV { set; }
```
Set-only properties that control which data representation to export. Each delegates to the corresponding property on the underlying `Writer` instance (accessed via `Exporter`).
---
### `File.Writer` Class (nested)
**Inheritance:** `Writer<File>`, `IWriter<Test>`
#### Properties
```csharp
internal File WriterParent { get; private set; }
```
The owning `File` instance that created this writer.
```csharp
public bool ExportADC { get; set; }
public bool ExportEU { get; set; }
public bool ExportMv { get; set; }
```
Control which data representation to include in the export. Default values: `ExportADC = false`, `ExportEU = true`, `ExportMv = false`.
```csharp
public double Start { get; set; }
public double Stop { get; set; }
```
Time bounds for the export (in seconds).
```csharp
public bool Filtered { get; set; }
```
Controls whether channel data should be filtered using SAE J211 filtering during export.
#### Methods
```csharp
public void Write(string pathname, string id, Test test, bool bFiltering, bool includeGroupNameInISOExport, double minStartTime, int dataCollectionLength)
```
**Empty implementation** - does nothing.
```csharp
public void Write(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested, double minStartTime, int dataCollectionLength)
```
Primary export method. Writes test data to an XLSX file at `pathname`. Uses a template file `XLSXExportTemplate.xlsx` from `ReportTemplates` directory. Writes metadata (inception date, test ID, description), channel configuration, and sample data. Supports progress reporting via `tickEventHandler` and error handling via `errorEventHandler`.
```csharp
public void Initialize(string pathname, string id, string dataFolder, Test test, bool bFiltering, bool includeGroupNameInISOExport, FilteredData fd, Test.Module.Channel tmChannel, int channelNumber, BeginEventHandler beginEventHandler, CancelEventHandler cancelEventHandler, EndEventHandler endEventHandler, TickEventHandler tickEventHandler, ErrorEventHandler errorEventHandler, CancelRequested cancelRequested)
```
**Empty implementation** - does nothing.
#### Protected/Internal Methods
```csharp
protected Cell GetCell(Worksheet worksheet, string xColumn, UInt32 rowIndex, bool bLookForCell = true)
```
Retrieves or creates a cell at the specified column and row.
```csharp
protected WorksheetPart GetWorksheetPartByName(SpreadsheetDocument document, string sheetName)
```
Retrieves a worksheet part by name. Returns `null` if not found.
```csharp
protected int InsertSharedStringItem(string text, SharedStringTablePart shareStringPart)
```
Inserts text into the shared string table and returns its index. Handles `null` text by converting to empty string.
## 3. Invariants
- The `Exporter` property always returns the same `Writer` instance after first access (lazy singleton pattern).
- The `Writer` constructor sets default export flags: `ExportEU = true`, `ExportADC = false`, `ExportMv = false`.
- The template file `XLSXExportTemplate.xlsx` must exist in `ReportTemplates` subdirectory of the application base directory.
- The `Data` worksheet must exist in the template file.
- Row indices for sample data start at row 24 (hardcoded as `24 + sampleIndex`).
- Column indexing starts at column B (index 0 maps to column B via `GetColumn`).
- Progress updates occur every `UPDATE_INTERVAL` (1000) samples.
## 4. Dependencies
### External Dependencies (from imports)
- **DocumentFormat.OpenXml** - Open XML SDK for Excel file manipulation
- **DocumentFormat.OpenXml.Packaging** - Spreadsheet document handling
- **DocumentFormat.OpenXml.Spreadsheet** - Spreadsheet-specific elements
- **DTS.Common.Utilities.Logging** - `APILogger` for error logging
- **DTS.Slice.Control** - Event delegates (`BeginEventHandler`, `CancelEventHandler`, `EndEventHandler`, `TickEventHandler`, `ErrorEventHandler`, `CancelRequested`)
### Internal Dependencies (inferred)
- **DTS.Serialization** - Base class `Serialization.File` and `Writer<T>` base class
- **Common.DAS.Concepts** - `Test`, `Test.Module.AnalogInputChannel`, `Test.Module.Channel`, `DataScaler`, `FilteredData`
- **Event.Module.Channel.SaeJ211Filter** - Filter parsing and application
### Depended On By
- Unknown from source alone (consumers would use `File` class for XLSX exports)
## 5. Gotchas
1. **Empty Method Implementations**: The `Write` overload with fewer parameters and the `Initialize` method are both empty implementations. This may indicate incomplete refactoring or dead code.
2. **Type Casting in Property Setters**: `ExportADC`, `ExportEU`, and `ExportMV` properties on `File` cast `Exporter` to `Writer`. This will fail if `_exporter` is mocked or substituted with a different `IWriter<Test>` implementation.
3. **Template File Dependency**: The export will fail at runtime if `XLSXExportTemplate.xlsx` does not exist in the expected location. This is not validated at construction.
4. **Hardcoded Worksheet Name**: The code expects a worksheet named `"Data"` - this is not configurable.
5. **GC Manipulation**: The `Write` method explicitly forces garbage collection with `GC.Collect()` and modifies `GCLatencyMode` and `LargeObjectHeapCompactionMode`. This is unusual and may have performance implications for the calling application.
6. **UseLegacyTDCSoftwareFiltering**: Referenced in the filtering logic but not defined in the visible source - unclear where this value comes from.
7. **Commented-Out Code**: The `FilteredChannelData` property is commented out, suggesting this functionality was removed or never completed.
8. **Exception Swallowing**: The `GetDataScaler` method catches and logs exceptions internally but continues execution, potentially returning a partially-configured `DataScaler`.