init
This commit is contained in:
166
docs/ai/Common/DTS.Common.Serialization/IRIGCH10/TMATS.md
Normal file
166
docs/ai/Common/DTS.Common.Serialization/IRIGCH10/TMATS.md
Normal 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.
|
||||
Reference in New Issue
Block a user