DP44/docs/ai/DataPRO/IService/Classes.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-17T15:28:43.247435+00:00	zai-org/GLM-5-FP8	1	f5d708ac0e3a8539

Documentation: DTS.DASLib.Service

1. Purpose

This module serves as the data contract and utility layer for the DTS Data Acquisition System (DAS) service infrastructure. It defines the fundamental data structures used to represent hardware configuration (ConfigurationData), device information (InfoResult), sensor identification (EID), and acquired sample data (SampleData, NewDataData). Additionally, it provides utilities for XML serialization (XMLHelper), hardware interaction callbacks (ServiceCallbackData), and custom error handling via specific exception types. It acts as the bridge between the hardware communication layer and the higher-level application logic.

2. Public Interface

Classes

ConfigurationData

Implements IConfigurationData, IXmlSerializable. Represents the configuration of a DAS device.

• IDASModule[] Modules: Array of modules in the DAS.
• IEID[] IDs: EIDs for the DAS (ignored in XML serialization).
• string TestID, string InstanceID, string Description: Test metadata.
• int NumberOfConfiguredChannels(): Returns the count of channels where IsConfigured is true.
• static void Serialize(string file, ConfigurationData config): Serializes config to an XML file.
• static string Serialize(ConfigurationData config): Serializes config to an XML string.
• static byte[] SerializeBin(ConfigurationData config): Serializes config to a binary blob (uses BinaryFormatter).
• static ConfigurationData Deserialize(string file): Deserializes XML file to object.
• static ConfigurationData DeserializeFromString(string SerializedText): Deserializes XML string to object.
• void WriteXml(XmlWriter writer): Custom XML write logic.
• void ReadXml(XmlReader reader): Custom XML read logic.

InfoResult

Implements IInfoResult. Contains hardware information about a discovered DAS device.

• IInfoResultModule[] Modules: Array of module descriptors.
• string MACAddress: The MAC address of the device.
• IEID BatteryID: Electronic ID of the battery.
• bool HasBattery: Calculated property checking if a valid battery ID is present.
• byte MapDASChannelNumber2ModuleArrayIndex(int channelNumber): Converts global channel number to module index.
• byte MapDASChannelNumber2ModuleChannelNumber(int channelNumber): Converts global channel number to local module channel number.
• byte MapModuleArrayIndexAndChannelNum2DASChannel(int moduleArrayIdx, int channelNumber): Converts local module/channel indices to global DAS channel number.
• static void SetDASInfo(IDASCommunication das, IInfoResult dasInfo, bool bSetInDb = true): Updates DAS info, optionally persisting to the database.

EID (Electronic ID)

Implements IEID, IComparable<EID>, IComparable<string>. Represents a sensor Electronic ID.

• string ID: The ID string.
• byte[] Blob: Raw binary data.
• bool IsValid(): Validates the ID (checks length=16, hex format, non-blank, and CRC8).
• int CompareTo(EID eid): Case-insensitive comparison.

EIDReader

Static helper class for reading EIDs from hardware.

• static bool SupportsQueryOneWireID(ICommunication comm): Returns false for EthernetTsrAir and WinUSBTsrAir; true otherwise.
• static IEID[] RetriveEIDs(ICommunication comm, byte DASChannelNumber, int idType): Retrieves EIDs with retry logic (3 attempts). Returns null on failure or if unsupported.
• static EID[] RetriveEIDs(ICommunication comm, int moduleIndex): Retrieves EIDs for a specific module index.
• static EID[][] RetrieveEIDsG5(ICommunication comm): Retrieves EIDs for G5 hardware racks.
• static bool IsBlankID(string id): Checks if ID equals BLANK_ID ("0000000000000000").

ServiceCallbackData

Base class for internal service callbacks.

• CallbackStatus Status: Enum (ProgressReport, NewData, Timeout, Success, Failure, Canceled, InvalidParameters).
• SampleData[] DataSamples: Array of sample data segments.
• void AddSampleData(short[][] data, ulong sampleNumber, ulong timeStamp, ulong sequenceNumber): Adds a sample segment to the internal list.
• void SetNewDiagnosticData(DiagnosticNewData data), SetNewTiltData(TiltNewData data), etc.: Setters for specific data payload types.

XMLHelper

Static helper for type-safe XML parsing/writing using InvariantCulture.

• GetString(XmlReader reader): Reads element text content.
• GetDouble(XmlReader reader), GetInt(XmlReader reader), etc.: Parses text to specific types.
• TryGetString(...), TryGetDouble(...), etc.: Safe versions returning default values on failure.
• PutString(XmlWriter writer, string tag, string value), PutDouble(...), etc.: Writes elements with specified tags.

SampleData

Represents a single poll of hardware data.

• short[][] Data: Jagged array of channel data.
• ulong SampleNumber, TimeStamp, SequenceNumber: Metadata for the sample.

NewDataData

Container for bulk data acquisition results.

• short[][][] datas: 3D array of data.
• ulong[] SampleNumbers, TimeStamps, SequenceNumbers: Arrays of metadata.

TOMModule

Inherits from DASModule. Represents a digital output channel.

• TomTriggerType TriggerType: Enum defining trigger source (NONE, BUS_ONLY, PANEL_ONLY, BUS_PANEL).

ModuleDiagnosticsResult

Implements IModuleDiagnosticsResult. Holds temperature readings from diagnostics.

• float TemperatureLocation1Pre ... TemperatureLocation4Post: Temperature properties.

FlashEraseStatus

Tracks flash erase progress.

• CommandStatus LastError: Status of the operation.
• float PercentComplete: Progress percentage.

TriggerCheckResult

Implements ITriggerCheckResult. Holds trigger line states.

• bool IsStatusGood, IsTriggered, HasTriggered, IsStartRecordActive, HasStartRecordBeenActive.

Exceptions

• BusyException: Thrown when a service is called while already busy.
• TriggerShortedException, StartShortedException: Hardware trigger faults.
• NoDiagnosticsAvailable: Diagnostics data requested before diagnostics run.
• TooManyDiagnosticsAvailable: Ambiguous diagnostic results found.

Enums

• ConfigurationConstants.VerifyConfig_Errors: Contains DefaultHardwareFilterRateOutOfRange.

3. Invariants

• EID Validation: A valid EID must be exactly 16 characters, in Hex format, not equal to "0000000000000000", and must match the internal CRC8 checksum calculated via the static CRCTable.
• XML Parsing: XMLHelper methods enforce InvariantCulture for all numeric parsing to ensure locale independence.
• Sample Data: SampleData and NewDataData associate data arrays strictly with corresponding metadata arrays (SampleNumbers, TimeStamps, etc.). The consumer must ensure array lengths match.
• Module Mapping: InfoResult mapping functions assume Modules is ordered by ModuleArrayIndex. MapDASChannelNumber2ModuleArrayIndex defaults to the last module index if the channel number exceeds the calculated total.

4. Dependencies

Internal Dependencies (within DTS.DASLib.Service)

• TOMModule depends on DASModule (base class).
• ServiceCallbackData depends on SampleData.
• ConfigurationData depends on XMLHelper, DASModule, EID.
• InfoResult depends on EID, EIDReader.

External Dependencies

• DTS.Common.Interface.DASFactory: Interfaces IDASCommunication, ICommunication, IEID, IInfoResult, IModuleDiagnosticsResult, ITriggerCheckResult, IDASModule.
• DTS.Common.Enums.DASFactory: Enums CommandStatus, ModuleType, RecordingMode.
• DTS.Common.Utilities: HexEncoding, APILogger.
• DTS.DASLib.Command.SLICE: QueryOneWireID command.
• DTS.DASLib.Command.TDAS: ReadSensorIDs, RackIDX commands.
• DASFactoryDb: Database wrapper for configuration and info storage (Config.SetConfiguration, DbWrapper).

5. Gotchas

• Null vs Empty Array in EIDReader: The method EIDReader.RetriveEIDs explicitly returns null instead of an empty array if no IDs are found or the device is unsupported. The source comments indicate this is to avoid breaking legacy "CalStation" code that indexes the result directly (e.g., result[0]) without checking length.
• Method Name Typo: The method RetriveEIDs in EIDReader is misspelled (missing an 'e').
• BinaryFormatter Obsolescence: ConfigurationData.SerializeBin uses BinaryFormatter, which is deprecated in modern .NET versions due to security risks.
• Silent Failures in Deserialization: ConfigurationData.DeserializeFromString catches exceptions, logs them, and returns null rather than propagating the exception to the caller.
• Hardcoded G5Digital Channel Count: In InfoResult.MapDASChannelNumber2RealtimeChannelNumber, the case for ModuleType.G5Digital returns a hardcoded 32, though the comment notes this case is currently unreachable due to logic flow.
• Redundant Class Name: The class NewDataData has a redundant name.
• Magic Numbers: EID validation relies on a hardcoded 256-byte CRC lookup table. InfoResult defaults NumberOfBridgeChannels to 3.