DP44/enriched-qwen3-coder-next/DataPRO/IService/Classes.md

---
source_files:
  - DataPRO/IService/Classes/ConfigurationConstants.cs
  - DataPRO/IService/Classes/StaticInformation.cs
  - DataPRO/IService/Classes/NewData.cs
  - DataPRO/IService/Classes/SampleData.cs
  - DataPRO/IService/Classes/ModuleDiagnosticResult.cs
  - DataPRO/IService/Classes/FlashEraseStatus.cs
  - DataPRO/IService/Classes/TriggerCheckResult.cs
  - DataPRO/IService/Classes/TOMModule.cs
  - DataPRO/IService/Classes/Exceptions.cs
  - DataPRO/IService/Classes/EID.cs
  - DataPRO/IService/Classes/ServiceCallbackData.cs
  - DataPRO/IService/Classes/EID.Reader.cs
  - DataPRO/IService/Classes/XMLHelper.cs
  - DataPRO/IService/Classes/ConfigurationData.cs
  - DataPRO/IService/Classes/InfoResult.cs
generated_at: "2026-04-16T03:56:14.475389+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "a79ee819003fd838"
---

# DAS Service Layer Documentation

## 1. Purpose

This module provides core data structures and helper utilities for the DAS (Data Acquisition System) service layer within the `DTS.DASLib.Service` namespace. It defines the foundational data models used to represent hardware state, configuration, diagnostics, and data payloads exchanged between the service layer and higher-level components. These classes serve as the contract for data flow during DAS operations such as configuration, data acquisition, diagnostics, and flash programming, enabling consistent representation of hardware metadata and runtime state across the system.

## 2. Public Interface

### Classes

#### `ConfigurationConstants`
- **Nested Enum**: `VerifyConfig_Errors`
  - `DefaultHardwareFilterRateOutOfRange`: Represents a configuration validation error where the hardware filter rate is outside acceptable bounds.

#### `StaticInformation`
- **Constructor**: `StaticInformation(double[] _NominalRanges)`
  - Stores a reference to the provided array of nominal ranges (e.g., expected sensor voltage ranges).
- **Property**: `NominalRanges` (`double[]`)
  - Read-only array of nominal range values.

#### `NewDataData`
- **Constructor**: `NewDataData(short[][][] data, ulong[] sns, ulong[] timeStamps, ulong[] sequenceNumbers)`
  - Initializes all properties with provided values.
- **Properties**:
  - `datas` (`short[][][]`): Three-dimensional array of acquired data samples.
  - `SampleNumbers` (`ulong[]`): Per-sample sequence identifiers.
  - `TimeStamps` (`ulong[]`): Timestamps for each sample.
  - `SequenceNumbers` (`ulong[]`): Sequence numbers for ordering samples.

#### `SampleData`
- **Constructor**: `SampleData(short[][] data, ulong sampleNumber, ulong timeStamp, ulong sequenceNumber)`
  - Initializes all properties with provided values.
- **Properties**:
  - `Data` (`short[][]`): Two-dimensional array of channel data for one sample (channels × values).
  - `SampleNumber` (`ulong`): Hardware sample counter value.
  - `TimeStamp` (`ulong`): Timestamp associated with this sample.
  - `SequenceNumber` (`ulong`): Sequence number for ordering samples.

#### `ModuleDiagnosticsResult`
- **Properties** (all `float`):
  - `TemperatureLocation1Pre` through `TemperatureLocation4Pre`: Pre-flash-erase temperatures at four locations.
  - `TemperatureLocation1Post` through `TemperatureLocation4Post`: Post-flash-erase temperatures at four locations.

#### `FlashEraseStatus`
- **Properties**:
  - `LastError` (`DFConstantsAndEnums.CommandStatus`): Last error encountered during flash erase; `StatusNoError` indicates success.
  - `PercentComplete` (`float`): Progress percentage (0.0–100.0) of the current flash erase operation.

#### `TriggerCheckResult`
- **Properties** (all `bool`):
  - `IsStatusGood`: Overall diagnostic status of the DAS.
  - `IsStartRecordActive`: Whether the start record line is currently active.
  - `HasStartRecordBeenActive`: Whether the start record line has been active since arming.
  - `IsTriggered`: Whether the trigger line is currently active.
  - `HasTriggered`: Whether the trigger line has been active since arming.

#### `TOMModule`
- **Nested Enum**: `TomTriggerType`
  - `NONE`: Trigger type unknown.
  - `BUS_ONLY`: Triggered only by rack bus.
  - `PANEL_ONLY`: Triggered only by panel trigger.
  - `BUS_PANEL`: Triggered only when both rack bus and panel triggers are active.
- **Properties**:
  - `TriggerType` (`TomTriggerType`): Gets/sets the trigger type.
- **Constructors**:
  - `TOMModule()`: Default constructor.
  - `TOMModule(int moduleArrayIdx, IDASCommunication _OwningDAS)`: Initializes with module index and owning DAS communication interface.

#### Exception Classes
- **`BusyException`**: Thrown when a service call is made while the service is already processing another request.
- **`TriggerShortedException`**: Thrown when a trigger line short condition is detected.
- **`StartShortedException`**: Thrown when a start record line short condition is detected.
- **`NoDiagnosticsAvailable`**: Thrown when diagnostic data is requested but none exists for the channel (e.g., diagnostics not yet run).
- **`TooManyDiagnosticsAvailable`**: Thrown when multiple diagnostic results are returned for a single channel (unexpected).

#### `EID`
- **Properties**:
  - `ID` (`string`): 16-character hexadecimal string representing the sensor Electronic ID.
  - `Blob` (`byte[]`): Optional raw binary blob associated with the ID.
- **Constructors**:
  - `EID()`: Initializes with empty ID and null blob.
  - `EID(string _id)`: Initializes with ID string.
  - `EID(string _id, byte[] _blob)`: Initializes with ID and blob.
- **Methods**:
  - `IsValid()`: Returns `true` if ID is non-empty, 16 characters, not blank (`0000000000000000`), in hex format, and CRC8 check passes.
  - `CompareTo(EID eid)` / `CompareTo(string eidStr)`: Case-insensitive lexicographic comparison of IDs.

#### `EIDReader`
- **Constants**:
  - `BLANK_ID`: `"0000000000000000"` (blank EID value).
- **Static Methods**:
  - `SupportsQueryOneWireID(ICommunication comm)`: Returns `false` for `EthernetTsrAir`/`WinUSBTsrAir`; `true` otherwise.
  - `IsBlankID(string id)`: Returns `true` if `id` equals `BLANK_ID`.
  - `RetriveEIDs(ICommunication comm, byte DASChannelNumber, int idType)`: Retrieves EIDs for a channel with retry logic; returns `null` if none found or invalid.
  - `RetriveEIDs(ICommunication comm, int moduleIndex)`: Retrieves EIDs for a module index with retry logic; returns `null` if none found or invalid.
  - `RetrieveEIDsG5(ICommunication comm)`: Retrieves EIDs for all G5 modules; returns `EID[][]`.

#### `ServiceCallbackData`
- **Nested Classes**:
  - `DiagnosticNewData`: Contains channel number, action type (`Actions` enum), and result object for diagnostic callbacks.
    - `Actions` enum: `MeasureBridgeMv`, `MeasureShunt`, `ScaleFactorMv`, `FactoryExcitation`, `MeasureExcitation`, `MeasureOffset`, `CalSignalCheck`, `FinalOffset`, `MeasureNoise`, `RemoveOffset`, `ShuntCheck`, `QueryModules`, `MeasureVoltages`, `TestChannelRun`, `TestChannelRead`, `MeasureInternalOffset`, `MeasureFinalInternalOffset`.
  - `TiltNewData`: Contains `TiltData` (`double[]`) and `AccelData` (`double[]`).
  - `TemperatureData`: Contains `Channel1`, `Channel2` (`int`), `Timestamps` (`DateTime[]`), `Sensor1`, `Sensor2` (`double[]`).
  - `UARTNewData`: Contains `DataOffset` (`ulong`) and `UARTData` (`byte[]`).
- **Properties**:
  - `Status` (`CallbackStatus`): One of `ProgressReport`, `NewData`, `Timeout`, `Success`, `Failure`, `Canceled`, `InvalidParameters`.
  - `ErrorMessage` (`string`): Error message if `Status == Failure`.
  - `ErrorException` (`Exception`): Exception object if `Status == Failure`, else `null`.
  - `ProgressValue` (`int`): Progress percentage (0–100) if `Status == ProgressReport`.
  - `UserData` (`object`): User-provided state object.
  - `DataSamples` (`SampleData[]`): Collection of non-contiguous sample blocks.
  - `NewDiagnosticData`, `NewTiltData`, `NewUARTData`, `NewTemperatureData`: Accessors for respective data types.
  - `ByteData` (`byte[]`): Raw byte data payload.
- **Methods**:
  - `AddSampleData(short[][] data, ulong sampleNumber, ulong timeStamp, ulong sequenceNumber)`: Appends a new `SampleData` to internal list.
  - `GetSampleData(int index)`: Returns `SampleData` at given index.
  - `GetNumberOfSamples()`: Returns count of stored sample blocks.

#### `XMLHelper`
- **Fields**:
  - `InvariantCulture`: `CultureInfo` for culture-independent parsing.
- **Static Methods** (all take `XmlReader`/`XmlWriter`):
  - `GetString`, `TryGetString`: Reads element text; `TryGetString` returns `defaultValue` on failure.
  - `GetDouble`, `TryGetDouble`: Parses element text as `double`.
  - `GetFloat`: Parses element text as `float`.
  - `GetInt`, `TryGetInt`: Parses element text as `int`.
  - `GetInt64`: Parses element text as `long`.
  - `GetUInt`, `GetUInt64`: Parses element text as `uint`/`UInt64`.
  - `GetOptionalDouble`: Reads element; returns `null` if `xsi:nil="true"`.
  - `GetBool`: Parses element text as `bool`.
  - `PutString`, `PutInt`, `PutInt64`, `PutUInt`, `PutUInt64`, `PutDouble`, `PutOptionalDouble`, `PutBool`: Writes corresponding XML elements.

#### `ConfigurationData`
- **Properties**:
  - `Modules` (`IDASModule[]`): Array of modules in the DAS.
  - `IDs` (`IEID[]`): EIDs for the entire DAS (ignored during XML serialization).
  - `TestID`, `TestSetupUniqueId`, `InstanceID`, `Description`: Test/event metadata.
  - `ClearSetup` (`bool`): Defaults to `false`.
  - `DisplayOrder` (`int[]`): Channel display ordering; defaults to `[-1]`.
  - `DasDisplayOrder` (`int`): DAS display order; defaults to `-1`.
  - `UDPReceiveAddress` (`string`): UDP multicast address; defaults to `"UDP://239.1.2.10:8401"`.
- **Methods**:
  - `NumberOfConfiguredChannels()`: Counts channels where `IsConfigured == true`.
  - `NumberOfChannels()`: Counts all channels (configured or not).
  - `NumberOfDownloadChannels()`: Counts non-UART/non-StreamOut channels.
  - `GetDisplayOrder(uint channelIdx)`: Returns `DisplayOrder[channelIdx]` or `-1` if out of bounds.
  - `Serialize(string file, ConfigurationData config)`: Serializes to XML file.
  - `Serialize(ConfigurationData config)`: Serializes to XML string.
  - `SerializeBin(ConfigurationData config)`: Serializes to binary.
  - `DeserializeFromString(string SerializedText)`: Deserializes XML string to `ConfigurationData`.
  - `Deserialize(string file)`: Deserializes XML file to `ConfigurationData`.
  - `SetConfiguration(IDASCommunication das, string xml, int fileStore)`: Stores XML config in database (`DASFactoryDb.Config.SetConfiguration`).
- **Constants**:
  - `DIAGNOSTIC_FILESTORE = 0`, `EVENT_FILE_STORE = 1`: File store identifiers.

#### `InfoResult`
- **Nested Class**: `Module` (implements `IInfoResultModule`)
  - `SerialNumber`, `FirmwareVersion` (`string`)
  - `OwningInfoResult` (`InfoResult`)
  - `ModuleArrayIndex` (`int`)
  - `NumberOfChannels` (`uint`)
  - `SupportedSampleRates` (`uint[]`)
  - `SampleRate2AAFrequency` (`Dictionary<uint, float>`)
  - `MaxEventStorageSpaceInBytes` (`ulong?`)
  - `NumberOfBytesPerSampleClock` (`uint?`)
  - `MaxRecordingSamples` (`double`)
  - `CalibrationDate` (`DateTime?`)
  - `RackIsUnreadable` (`bool`)
  - `TypeOfModule` (`DFConstantsAndEnums.ModuleType`)
  - `SupportedModes` (`DFConstantsAndEnums.RecordingMode[]`)
  - `IsProgrammable` (`bool`)
- **Properties**:
  - `Modules` (`IInfoResultModule[]`): Array of modules.
  - `ActiveExternalTilts` (`List<ExternalTilt>`): List of active external tilt sensors.
  - `OwningDAS` (`IDASCommunication`): Reference to owning DAS communication interface.
  - `MaxNumberOfModules` (`uint`)
  - `MaxEventStorageSpaceInBytes` (`ulong?`)
  - `NumberOfBytesPerSampleClock` (`uint?`)
  - `DeviceStreamingOnly` (`bool?`)
  - `NumberOfBridgeChannels` (`int`): Hardcoded to `3`.
  - `BatteryID` (`IEID`)
  - `HasBattery` (`bool`): `true` if `BatteryID` is non-null, non-empty, and not blank.
  - `CalibrationDate` (`DateTime?`): Returns earliest module calibration date or `1970-01-01` if invalid.
- **Mapping Methods**:
  - `MapDASChannelNumber2RealtimeChannelNumber(int channelNumber)`: Maps DAS channel to real-time channel (module-type dependent).
  - `MapDASChannelNumber2ModuleArrayIndex(int channelNumber)`: Maps DAS channel to module array index.
  - `MapDASChannelNumber2ModuleDeviceID(int channelNumber)`: Maps DAS channel to module device ID (`channelNumber / 3 + 1`).
  - `MapDASChannelNumber2ModuleChannelNumber(int channelNumber)`: Maps DAS channel to module-local channel number.
  - `MapModuleArrayIndexAndChannelNum2DASChannel(int moduleArrayIdx, int channelNumber)`: Inverse mapping.
- **Static Methods**:
  - `SetDASInfo(IDASCommunication das)`: Stores DAS info in database.
  - `SetDASInfo(IDASCommunication das, IInfoResult dasInfo, bool bSetInDb)`: Updates `das.DASInfo` and optionally stores in DB.
  - `InsertDASInfo(IDASCommunication das, IInfoResult dasInfo)`: Inserts DAS info into database.

## 3. Invariants

- **EID Format**: All `EID.ID` strings must be exactly 16 hexadecimal characters. Validation in `EID.IsValid()` enforces:
  - Non-empty and non-null.
  - Length = 16.
  - Not equal to `EIDReader.BLANK_ID` (`"0000000000000000"`).
  - Hexadecimal format (via `HexEncoding.InHexFormat`).
  - CRC8 check passes (first byte = CRC of remaining 15 bytes using `CRCTable`).
- **SampleData Consistency**: Each `SampleData` instance must have `Data` array with dimensions `[channels][values]`, where `channels` matches the module's channel count, and `SampleNumber`, `TimeStamp`, `SequenceNumber` are monotonically increasing within a contiguous block.
- **ConfigurationData Serialization**:
  - `Modules` must be non-null and contain valid `IDASModule` instances.
  - `IDs` is ignored during XML serialization (`[XmlIgnore]`).
- **FlashEraseStatus Progress**: `PercentComplete` must be in range `[0.0, 100.0]`.
- **TriggerCheckResult Semantics**: `HasStartRecordBeenActive` and `HasTriggered` are cumulative flags set only after arming; they are not reset until re-arming.

## 4. Dependencies

### Dependencies *on* this module:
- **`DTS.Common.Interface.DASFactory`**: Interfaces like `IDASCommunication`, `ICommunication`, `IDASModule`, `IEID`, `IInfoResult`, `IModuleDiagnosticsResult`, `ITriggerCheckResult`.
- **`DTS.Common.Enums.DASFactory`**: `DFConstantsAndEnums` (e.g., `CommandStatus`, `ModuleType`, `RecordingMode`).
- **`DTS.Common.Utilities`**: `HexEncoding`, `APILogger`, `RunTestVariables`.
- **`DASFactoryDb`**: `DbWrapper`, `Config` for database persistence (`SetConfiguration`, `DASInfoInsert`, etc.).
- **`DTS.DASLib.Command.SLICE`**: SLICE commands like `QueryOneWireID`, `ReadSensorIDs`, `RackIDX`.
- **`System.Xml`**: XML serialization (`XmlSerializer`, `XmlReader`, `XmlWriter`).
- **`System`**: Core types (`Exception`, `DateTime`, `CultureInfo`, etc.).

### Dependencies *of* this module:
- **`DTS.DASLib.Service` namespace**: All classes are internal to this namespace; no external consumers are implied by source.
- **`DTS.DASLib.Command.SLICE`**: Used by `EIDReader` for hardware ID queries.

## 5. Gotchas

- **`EIDReader.RetriveEIDs` returns `null` instead of empty array**: Explicitly avoids returning empty arrays to prevent downstream consumers (e.g., calstation) from indexing `ids[0]` on an empty collection. This is a known design trade-off.
- **`EID.IsValid()` CRC computation**: CRC is calculated over bytes 2–15 (skipping first byte), but the first byte is used as the expected CRC. Ensure correct byte ordering.
- **`SampleData.Data` shape**: The `short[][]` structure implies `[channel][value]`, but firmware behavior varies:
  - G8 and older: 1 value per channel per poll.
  - Newer firmware: Multiple values per channel per poll.
- **`InfoResult.NumberOfBridgeChannels` is hardcoded to `3`**: This may break for non-G5 modules with different channel counts per module.
- **`ConfigurationData.DeserializedFromString` returns `null` on failure**: Callers must handle `null` explicitly; no exception is thrown for invalid XML (only logged).
- **`XMLHelper` uses `InvariantCulture`**: Parsing fails if XML contains locale-specific formatting (e.g., commas for decimals).
- **`TOMModule.TriggerType` default is `NONE`**: Uninitialized modules will report `NONE`, which may not reflect actual hardware configuration.
- **`FlashEraseStatus.LastError` type**: Uses `DFConstantsAndEnums.CommandStatus`, but no specific error codes are defined in this source file—consumers must reference that enum.
- **`ServiceCallbackData.DataSamples` is a copy**: `DataSamples` returns a copy (`_Data.ToArray()`); modifications to the returned array do not affect internal state.
-