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

261
enriched-qwen3-coder-next/DataPRO/IService/Classes.md Normal file
View File

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

194
enriched-qwen3-coder-next/DataPRO/IService/Classes/Arm.md Normal file
View File

@@ -0,0 +1,194 @@
---
source_files:
- DataPRO/IService/Classes/Arm/ArmCheckActions.cs
- DataPRO/IService/Classes/Arm/ArmCheckResults.cs
- DataPRO/IService/Classes/Arm/ArmStatus.cs
generated_at: "2026-04-16T03:59:53.800390+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "51c3cf5ed1e74c4d"
---
# Arm
## Documentation: ARM Status and Pre-Arm Checks Module
---
### 1. Purpose
This module provides data structures and utilities for managing the **ARM state** of a Data Acquisition System (DAS) unit and for configuring/collecting **pre-arm diagnostic checks**. It enables the system to track real-time operational status (e.g., armed, triggered, faulted, recording) via `ArmStatus`, and to define and store results of diagnostic checks (e.g., battery voltage, sensor IDs, squib resistance) via `ArmCheckActions` and `ArmCheckResults`. It serves as the core data layer for the `ArmingService`, supporting safe arming workflows and post-test diagnostics.
---
### 2. Public Interface
#### `ArmCheckActions`
- **`bool PerformBatteryVoltageCheck { get; set; }`**
Flag indicating whether to perform a battery voltage diagnostic check.
- **`bool PerformInputVoltageCheck { get; set; }`**
Flag indicating whether to perform an input voltage diagnostic check.
- **`bool PerformSensorIdCheck { get; set; }`**
Flag indicating whether to verify sensor EIDs.
- **`bool PerformEventLineCheck { get; set; }`**
Flag indicating whether to check for shorts on the event line.
- **`bool PerformSquibResistanceCheck { get; set; }`**
Flag indicating whether to measure squib resistance.
- **`bool PerformTiltSensorCheck { get; set; }`**
Flag indicating whether to perform tilt sensor diagnostics.
- **`bool PerformTemperatureCheck { get; set; }`**
Flag indicating whether to perform temperature diagnostics.
- **`bool PerformClockSyncCheck { get; set; }`**
Flag indicating whether to verify clock synchronization status.
- **`ArmCheckActions()`**
Constructor initializes all check flags to `false`.
#### `ArmCheckResults`
- **`Dictionary<int, string[]> SensorIds { get; set; }`**
Maps channel index (int) to an array of sensor EIDs (strings) read from that channel.
- **`Dictionary<int, double> SquibResistances { get; set; }`**
Maps channel index (int) to measured squib resistance (Ω).
- **`double?[] BatteryVoltage { get; set; }`**
Array of optional battery voltage readings (mV), supporting multiple batteries per module (e.g., TDAS Pro rack).
- **`double? InputVoltage { get; set; }`**
Optional input voltage reading (mV).
- **`bool? StartLineShorted { get; set; }`**
Optional result indicating if the start line is shorted.
- **`bool? EventLineShorted { get; set; }`**
Optional result indicating if the event line is shorted.
- **`short[] TiltSensorDataPre { get; set; }`**
Raw pre-check tilt sensor ADC values.
- **`double[] TiltDegrees { get; set; }`**
Tilt angles (degrees) computed from `TiltSensorDataPre`.
- **`Dictionary<byte, short[]> IndexedTiltSensorDataPre { get; set; } = new Dictionary<byte, short[]>();`**
Indexed raw tilt data (key = device/module index).
- **`Dictionary<byte, double[]> IndexedTiltDegrees { get; set; } = new Dictionary<byte, double[]>();`**
Indexed tilt angles (key = device/module index).
- **`float[] TemperaturesPre { get; set; }`**
Raw temperature sensor readings (likely ADC counts or mV).
- **`double[] Gains { get; set; }`**
Channel gains used during diagnostics.
- **`double[] ZeroData { get; set; }`**
Zero-offset calibration data.
- **`IDictionary<InputClockSource, bool> InputClockLocks { get; set; }`**
Maps clock source type (`InputClockSource`) to lock status (`true` = locked).
#### `ArmStatus`
- **`bool ReceivedInvalidModeDuringSetup { get; set; } = false;`**
Indicates if `InvalidMode` error was received during setup; used as a heuristic to detect streaming mode.
- **`void ClearTriggerCheckStatus()`**
Resets trigger-related flags: `IsTriggered`, `IsArmed`, `IsRecording`, `IsTriggerShorted`, `IsStartShorted`.
- **`ArmStatus()`**
Default constructor.
- **`ArmStatus(IArmStatusData status)`**
Copy constructor from `IArmStatusData` interface; copies all properties.
- **`bool IsArmed { get; set; }`**
True if DAS is currently armed.
- **`bool IsTriggered { get; set; }`**
True if DAS has sensed a trigger event.
- **`bool IsTriggerShorted { get; set; }`**
True if trigger line is shorted *during trigger check only*.
- **`bool IsStartShorted { get; set; }`**
True if start line is shorted *during trigger check only*.
- **`bool IsRecording { get; set; }`**
True if DAS is currently recording samples.
- **`bool IsFaulted { get; set; }`**
True if DAS has faulted.
- **`bool IsInRealtime { get; set; }`**
True if DAS is in real-time mode.
- **`bool IsInFlashWrite { get; set; }`**
True if DAS is in flash write mode (G5).
- **`bool IsUndefined { get; set; }`**
True if `ARM STAT READ` returned no data.
- **`bool IsInPostTestDiagnostics { get; set; }`**
True if DAS is running post-test diagnostics.
- **`double TimeRemainingSeconds { get; set; }`**
Estimated seconds remaining in recording.
- **`double PercentComplete { get; set; }`**
Flash write progress percentage.
- **`ulong TotalSamples { get; set; }`**
Total samples to be recorded in the test.
- **`ulong CurrentSample { get; set; }`**
Current sample index being recorded.
- **`uint SampleRate { get; set; }`**
Current sample rate (Hz).
- **`double? InputMilliVolts { get; set; }`**
Input voltage (mV); auto-converts values > 100,000 from µV to mV.
- **`double? BatteryMilliVolts { get; set; }`**
Battery voltage (mV); auto-converts values > 100,000 from µV to mV.
- **`int? EventNumber { get; set; }`**
Current event number being recorded.
- **`ushort? MaxEventsPossible { get; set; }`**
Maximum number of events supported by the device (per issue #26817).
- **`int RecordingMode { get; set; }`**
Numeric recording mode identifier.
- **`string FaultMessage { get; set; }`**
Human-readable fault description (if any).
- **`bool IsRearming { get; set; }`**
True if DAS is in rearming state.
- **`bool HasBeenRecording { get; set; }`**
True if DAS has ever recorded during the current session.
- **`double? TimeLeftInArm { get; set; }`**
Time remaining in armed state (seconds).
- **`static void SetArmStatus(IDASCommunication unit, IArmStatusData status, bool bSetInDb)`**
Assigns `status` to `unit.DASArmStatus`. If `bSetInDb` is true and DB is connected, persists status to `ARM.SetArmStatus` stored procedure; logs exceptions via `APILogger`.
---
### 3. Invariants
- **`InputMilliVolts` and `BatteryMilliVolts`**:
Values > 100,000 are *always* divided by 1,000 to convert from µV to mV. Null values remain null.
- **`TimeLeftInArm`**:
No conversion is applied—values are stored directly as `double`.
- **`ClearTriggerCheckStatus()`**:
Only resets trigger-related flags (`IsTriggered`, `IsArmed`, `IsRecording`, `IsTriggerShorted`, `IsStartShorted`). Does *not* affect `IsFaulted`, `IsRecording`, or other non-trigger flags.
- **`ArmCheckActions`**:
All check flags default to `false`; no validation ensures at least one check is enabled.
- **`ArmCheckResults.SensorIds`**:
Key is channel index (0-based), value is array of EIDs (strings) per channel.
- **`ArmStatus.SetArmStatus(...)`**:
Does *not* throw exceptions; failures in DB persistence are silently logged via `APILogger`.
---
### 4. Dependencies
#### Imports/Usings
- `DTS.Common.Interface.DASFactory.Diagnostics` → Provides `IArmCheckActions`, `IArmCheckResults`, `IArmStatusData`.
- `DTS.Common.Interface.DASFactory` and `DTS.Common.Interface.DASFactory.ARM` → Provides `IDASCommunication`, `IArmStatusData`, `InputClockSource`.
- `DTS.Common` → Provides logging utilities (e.g., `APILogger`).
- `DASFactoryDb.ARM` → Provides `ARM.SetArmStatus(...)` stored procedure.
- `System.Collections.Generic`, `System` → Standard .NET types.
#### Dependencies *on* this module
- `ArmingService.GetArmStatus(...)` (referenced in `ArmStatus` summary) — *not shown in source*, but implied to be the primary consumer of `ArmStatus`.
- Any code performing pre-arm diagnostics — uses `ArmCheckActions` to configure checks and `ArmCheckResults` to store results.
- Database layer — calls `ARM.SetArmStatus(...)` via `ArmStatus.SetArmStatus(...)`.
#### Dependencies *of* this module
- `DASFactoryDb.DbWrapper.Connected` — checked before DB writes.
- `APILogger` — used for exception logging in `SetArmStatus`.
---
### 5. Gotchas
- **`InputMilliVolts`/`BatteryMilliVolts` unit conversion**:
Values > 100,000 are assumed to be in µV and converted to mV. If a value is legitimately > 100,000 mV (e.g., 120,000 mV = 120 V), it will be *incorrectly* divided to 120 mV. This is likely a legacy assumption for µV inputs.
- **`IsTriggerShorted` vs `IsTriggered`**:
`IsTriggerShorted` is *only* set during `TriggerCheck`, while `IsTriggered` is set in many contexts. Confusing the two may lead to incorrect logic (e.g., mistaking a trigger event for a line short).
- **`ReceivedInvalidModeDuringSetup` heuristic**:
Used to detect streaming mode, but this is not a guaranteed or documented protocol behavior—may break if firmware changes.
- **`ArmCheckResults.SensorIds` key type**:
Key is `int` (channel index), but no validation ensures keys are non-negative or contiguous.
- **`IndexedTiltSensorDataPre`/`IndexedTiltDegrees`**:
Key is `byte` (device/module index), but no documentation clarifies how indices are assigned or whether duplicates are possible.
- **`SetArmStatus(...)` silently swallows DB errors**:
Exceptions during DB persistence are logged but do *not* propagate—callers may assume persistence succeeded.
- **`ArmStatus` copy constructor does not guard against null `status`**:
While it returns early on null, it does *not* clear the current instance’s properties—only copies non-null values from `status`.
- **No validation in `ArmCheckActions`**:
It is possible to configure *no* checks (all flags `false`), which may lead to unsafe arming if not handled upstream.
None identified beyond the above.

125
enriched-qwen3-coder-next/DataPRO/IService/Classes/BaseInput.md Normal file
View File

@@ -0,0 +1,125 @@
---
source_files:
- DataPRO/IService/Classes/BaseInput/SLICEBaseInputValues.cs
- DataPRO/IService/Classes/BaseInput/SLICE.Base.Input.Reader.cs
- DataPRO/IService/Classes/BaseInput/BaseInputValues.cs
generated_at: "2026-04-16T03:58:02.897735+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "371fccf4478077de"
---
# Documentation: SLICE Base Input Module
## 1. Purpose
This module provides data acquisition and status reporting for power-related inputs on SLICE-based hardware units. It enables reading raw diagnostic values (e.g., input voltage, battery voltage, temperature, charging status) via the `SLICEBaseInputReader` class and encapsulating them into a standardized data model (`BaseInputValues` and its SLICE-specific subclass `SLICEBaseInputValues`). The `SLICEBaseInputValues` subclass implements domain-specific logic to compute battery voltage status (e.g., `GREEN`, `YELLOW`, `RED`, `NOBATTERY`, `OFF`) based on battery voltage, input voltage, and charge capacity, while also handling device-specific behavior for backup power measurement and enablement.
## 2. Public Interface
### `SLICEBaseInputValues` (inherits `BaseInputValues`)
- **`PossibleVoltageStatus` enum**
Defines voltage status levels: `GREEN`, `YELLOW`, `RED`, `OFF`.
*Note: This enum is declared but not used in the current implementation.*
- **`PossibleBatteryStatus` enum**
Defines battery status levels: `GREEN`, `YELLOW`, `RED`, `NOBATTERY`, `OFF`.
- **`BatteryVoltageStatus` (override property)**
*Read-only computed property.* Returns a string representation of `PossibleBatteryStatus` based on the following logic:
- If `BatteryMilliVoltsValid` is `false`, returns `"NOBATTERY"`.
- Else if `ChargeCapacityValid` is `true`:
- `> 70%` → `"GREEN"`
- `> 40%` → `"YELLOW"`
- else → `"RED"`
- Else if `InputMilliVoltsValid` is `true`, computes status using thresholds on `InputMilliVolts` and `BatteryMilliVolts` (see detailed logic in source).
- Else → `"RED"`.
*Write setter is a no-op; value is always regenerated on read.*
### `SLICEBaseInputReader`
- **Constructor**
`SLICEBaseInputReader(ICommunication comm)`
Initializes the reader with a communication interface (`ICommunication`). Throws no exceptions documented.
- **`InputMilliVolts` (virtual property)**
Returns the input voltage in millivolts by querying the `MeasureBaseDiagnosticChannel` for `BaseDiagnosticChannelList.InputVoltage`. Multiplies raw measurement by `1000.0`.
- **`TemperatureC` (virtual property)**
Returns the temperature in degrees Celsius by querying `MeasureBaseDiagnosticChannel` for `BaseDiagnosticChannelList.TemperatureC`.
- **`BatteryIsCharging` (property)**
Returns `true` if the base unit’s charge status switch (via `QuerySwitchImmediate` for `Switches.BaseSwitches.ChargeStatus`) is set to `1`.
- **`DirectBackupMilliVolts` (virtual property)**
Returns backup voltage in millivolts *without* enabling/disabling backup power. Returns `0D` if `ShouldMeasureBackupPower()` returns `false`.
- **`BackupMilliVolts` (property)**
Returns backup voltage in millivolts *with* power management:
- If `ShouldEnableBackupPower()` returns `true`, enables backup power, waits 1.5 seconds, reads via `DirectBackupMilliVolts`, then disables backup power in a `finally` block.
- If `ShouldEnableBackupPower()` returns `false`, directly returns `DirectBackupMilliVolts`.
- **`ShouldEnableBackupPower()` (private method)**
Returns `false` for SLICE6, SLICE2, and USB variants (`EthernetSlice6`, `EthernetSlice2`, `EthernetSlice6Air`, `EthernetSlice6AirBridge`, `EthernetTsrAir`, `WinUSBSlice6`, `CDCUSBSlice`); `true` otherwise.
- **`ShouldMeasureBackupPower()` (public method)**
Returns `false` for SLICE6 and USB variants (`EthernetSlice6`, `EthernetSlice6Air`, `EthernetSlice6AirBridge`, `WinUSBSlice6`, `CDCUSBSlice`), `true` for `EthernetSlice2` and `EthernetTsrAir`, and defaults to `true` for other types.
- **`EnableBackupPower()` (private method)**
Sends `SetSwitchImmediate` command to set `Switches.BaseSwitches.BackupPower` to `1`, but only if `ShouldEnableBackupPower()` returns `true`.
- **`DisableBackupPower()` (private method)**
Sends `SetSwitchImmediate` command to set `Switches.BaseSwitches.BackupPower` to `0`, but only if `ShouldEnableBackupPower()` returns `true`.
### `BaseInputValues` (base class)
- **Properties**
- `InputMilliVolts`, `InputVoltage` (both `double`)
- `InputMilliVoltsValid` (virtual `bool`) — `true` if `InputMilliVolts` is within `(MinimumValidInputVoltage, MaximumValidInputVoltage)` (default: 6–16 V).
- `MinimumValidInputVoltage`, `MaximumValidInputVoltage` (both `double`, default 6 and 16).
- `BatteryMilliVolts`, `BatteryVoltage` (both `double`)
- `BatteryMilliVoltsValid` (virtual `bool`) — `true` if `BatteryMilliVolts` is within `(MinimumValidBatteryVoltage, MaximumValidBatteryVoltage)` (default: 6–16 V).
- `BatterySoC` (`double?`) — battery state of charge (percentage), `null` if not queried.
- `MinimumValidBatteryVoltage`, `MaximumValidBatteryVoltage` (both `double`, default 6 and 16).
- `BatteryIsCharging` (`bool`)
- `TemperatureC` (`double`)
- `BatteryVoltageStatus`, `InputVoltageStatus`, `StatusDisplayBattery`, `StatusDisplayInput` (all `string`, default `null`)
- `BatteryVoltageStatusColor`, `InputVoltageStatusColor` (both `DFConstantsAndEnums.VoltageStatusColor`, default `null`)
- `ChargeCapacity` (`double`, default `double.NaN`)
- `ChargeCapacityValid` (`bool`) — `true` if `ChargeCapacity` is not `NaN`, and `0 < ChargeCapacity < 100`.
- **Constructors**
- Default constructor.
- Copy constructor: `BaseInputValues(IBaseInputValues copy)` — copies all properties from another `IBaseInputValues` instance.
## 3. Invariants
- `BatteryVoltageStatus` in `SLICEBaseInputValues` is *always* computed on read and never settable; the setter is a no-op.
- `InputMilliVoltsValid` and `BatteryMilliVoltsValid` depend on configurable min/max thresholds (default 6–16 V), but are validated against raw millivolt values.
- `ChargeCapacityValid` requires `ChargeCapacity` to be in `(0, 100)` and not `NaN`.
- `BackupMilliVolts` always disables backup power after measurement, regardless of success or failure, via `finally` block.
- `ShouldEnableBackupPower()` and `ShouldMeasureBackupPower()` may differ in behavior (e.g., `EthernetTsrAir` returns `true` for `ShouldMeasureBackupPower()` but `false` for `ShouldEnableBackupPower()`).
- Backup power is *not* enabled for SLICE6 or USB variants (`EthernetSlice6`, `EthernetSlice6Air`, `EthernetSlice6AirBridge`, `WinUSBSlice6`, `CDCUSBSlice`), per `ShouldEnableBackupPower()`.
## 4. Dependencies
### Imports/Usings
- `System.Threading` → used for `Thread.Sleep(1500)` in `BackupMilliVolts`.
- `DTS.Common.Interface.DASFactory` → provides `ICommunication`, `MeasureBaseDiagnosticChannel`, `QuerySwitchImmediate`, `SetSwitchImmediate`, `Switches`, `MeasureBaseDiagnosticChannel.BaseDiagnosticChannelList`.
- `DTS.DASLib.Command.SLICE` → provides SLICE-specific command types (`MeasureBaseDiagnosticChannel`, `QuerySwitchImmediate`, `SetSwitchImmediate`, `Switches`).
- `DTS.Common.Enums.DASFactory` → provides `DFConstantsAndEnums.VoltageStatusColor`.
- `DTS.Common.Interface.DASFactory.Diagnostics` → used via `IBaseInputValues`.
### Inferred Usage
- `SLICEBaseInputReader` is used by higher-level services (e.g., `DiagnosticsService.Diagnose`) to populate `BaseInputValues` instances.
- `SLICEBaseInputValues` is likely instantiated or assigned where SLICE-specific battery status logic is required.
## 5. Gotchas
- **`BatteryVoltageStatus` logic is complex and voltage-threshold-dependent**: The fallback logic for battery status when `ChargeCapacityValid` is `false` but `InputMilliVoltsValid` is `true` uses multiple nested `if` conditions with overlapping voltage ranges (e.g., `InputMilliVolts > 11000`, `> 9000`, `< 9`). This may be error-prone and could lead to unexpected status if input voltage is exactly at boundary values (e.g., `9000`, `11000`, `9000` mV).
- **`BackupMilliVolts` has side effects**: It enables/disables backup power *even if the device does not support it* (guarded by `ShouldEnableBackupPower()`), but the 1.5-second delay (`Thread.Sleep`) may block the calling thread. This is not async-friendly.
- **`ShouldEnableBackupPower()` vs `ShouldMeasureBackupPower()` divergence**: `EthernetTsrAir` is explicitly excluded from enabling backup power but *should* measure it — a subtle distinction that could cause confusion if not understood.
- **`ChargeCapacityValid` excludes `0`**: A valid battery at 0% charge would be considered invalid (`ChargeCapacityValid = false`), potentially forcing fallback to voltage-based status even when charge data is present.
- **No validation on `BatteryMilliVolts` vs `InputMilliVolts`**: The logic assumes `BatteryMilliVolts` is always ≤ `InputMilliVolts` when input is present, but no explicit checks exist.
- **`InputMilliVoltsValid` uses `1000D * MinimumValidInputVoltage`**: This is redundant since `InputMilliVolts` is already in millivolts; could be simplified to `InputMilliVolts > MinimumValidInputVoltage * 1000`.

155
enriched-qwen3-coder-next/DataPRO/IService/Classes/CAN.md Normal file
View File

@@ -0,0 +1,155 @@
---
source_files:
- DataPRO/IService/Classes/CAN/CANConfig.cs
- DataPRO/IService/Classes/CAN/CANModuleConfig.cs
generated_at: "2026-04-16T03:56:57.762497+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "49767c75e3daaeaa"
---
# CAN
## Documentation: CAN Configuration Module (`DTS.DASLib.Service`)
---
### 1. Purpose
This module provides XML-based serialization and deserialization for CAN (Controller Area Network) hardware configuration data in the DAS (Data Acquisition System) service layer. It enables persistent storage and retrieval of system-wide CAN module configurations (`CANConfig`) and per-module settings (`CANModuleConfig`), including channel definitions, recording parameters, and firmware metadata. The classes implement `IXmlSerializable` to support custom XML formatting, allowing configuration files to be stored in a human-readable and version-tolerant manner under the `DASConfigs` subdirectory relative to the executing assembly.
---
### 2. Public Interface
#### `CANConfig` class
- **`public Dictionary<string, CANModuleConfig> Modules { get; }`**
Read-only dictionary mapping module serial numbers (string keys) to `CANModuleConfig` instances. Represents all configured CAN modules.
- **`public string FileName { get; }`**
Full path to the XML file from which this `CANConfig` instance was loaded (or to which it will be written). Set only during construction.
- **`public CANConfig()`**
Default constructor. Initializes an empty configuration with no modules or file association.
- **`public CANConfig(string fileName, bool deleteIfPresent)`**
Constructor that attempts to load configuration from `fileName` (relative to `DASConfigs/` subdirectory). If `deleteIfPresent` is `true`, the file is deleted before loading (resulting in an empty config). If `false`, the file is read via `ReadXml`. Exceptions during file I/O or XML parsing are logged via `APILogger`.
- **`public void SetModule(CANModuleConfig module)`**
Inserts or updates a module in the `_modules` dictionary using `module.SerialNumber` as the key. No validation beyond key existence.
- **`public CANModuleConfig GetModule(CANModuleConfig module)`**
Returns the module stored under `module.SerialNumber`. If not present, inserts the provided `module` instance into the dictionary and returns it. *Note: This mutates the config even when the module is not yet known.*
- **`public XmlSchema GetSchema()`**
Returns `null`. Required by `IXmlSerializable` but unused.
- **`public void ReadXml(XmlReader reader)`**
Deserializes XML starting at `<CANConfig>` root. Reads a `<Modules>` section containing multiple `<CANModule>` elements. Each `<CANModule>` is deserialized into a `CANModuleConfig` and added via `SetModule`.
- **`public void WriteXml(XmlWriter writer)`**
Serializes the configuration as `<CANConfig><Modules>...</Modules></CANConfig>`. Each `CANModuleConfig` is written via its own `WriteXml` method, with `writer.Flush()` called after writing the `<Modules>` start tag and after each module.
#### `CANModuleConfig` class
- **`public string SerialNumber { get; set; }`**
Unique identifier for the CAN module (used as dictionary key in `CANConfig.Modules`).
- **`public string TestId { get; set; }`**
Identifier for the test associated with this module.
- **`public string TestDescription { get; set; }`**
Human-readable description of the test.
- **`public DFConstantsAndEnums.RecordingMode RecordingMode { get; set; }`**
Recording mode enum (e.g., continuous, event-triggered). Defaults to `InvalidArmMode`.
- **`public float AAFilterRateHz { get; set; }`**
Anti-aliasing filter rate in Hz. Default `0`.
- **`public double PreTriggerSeconds { get; set; }`**
Duration (seconds) of data to capture *before* a trigger event. Default `0`.
- **`public double PostTriggerSeconds { get; set; }`**
Duration (seconds) of data to capture *after* a trigger event. Default `0`.
- **`public string FirmwareVersion { get; set; }`**
Firmware version string reported by the module.
- **`public UInt64? MaxEventStorageSpaceInBytes { get; set; }`**
Optional maximum storage space (in bytes) for event-triggered recordings. Nullable; defaults to `0`.
- **`public int ModuleArrayIndex { get; set; }`**
Index of the module in a logical array (e.g., for ordering). Default `0`.
- **`public string FileName { get; }`**
Full path to the XML file from which this module config was loaded. Set only during construction.
- **`public CANModuleConfig()`**
Default constructor. Initializes all properties to defaults.
- **`public CANModuleConfig(string fileName)`**
Constructor that loads configuration from `fileName` (relative to `DASConfigs/`). Logs errors on failure.
- **`public void SetChannel(CANInputDASChannel channel)`**
Inserts or updates a channel in the internal `_channels` dictionary using `channel.ModuleChannelNumber` as the key.
- **`public CANInputDASChannel GetChannel(CANInputDASChannel channel)`**
Returns the channel stored under `channel.ModuleChannelNumber`. If not present, inserts the provided `channel` and returns it. *Note: Mutates config on miss.*
- **`public XmlSchema GetSchema()`**
Returns `null`. Required by `IXmlSerializable` but unused.
- **`public void ReadXml(XmlReader reader)`**
Deserializes XML starting at `<CANModule>`. Reads scalar properties (`SerialNumber`, `TestId`, etc.) and the `<Channels>` section. For `RecordingMode`, `AAFilterRateHz`, `PreTriggerSeconds`, `PostTriggerSeconds`, and `MaxEventStorageSpaceInBytes`, parsing errors are logged and defaults retained. `ModuleArrayIndex` is read via `ReadModuleArray`, which silently ignores errors (for backward compatibility with older config files).
- **`public void WriteXml(XmlWriter writer)`**
Serializes the module as `<CANModule>...</CANModule>`. Writes all scalar properties and the `<Channels>` section. For each channel, calls `WriteElementStart`, `WriteXml`, and `WriteElementEnd` on the channel object.
- **`public virtual void WriteElementStart(XmlWriter writer)`**
Writes `<CANModule xsi:type="...">` where `...` is the runtime type name (e.g., `CANInputDASChannel`). Allows polymorphic deserialization.
- **`public virtual void WriteElementEnd(XmlWriter writer)`**
Writes `</CANModule>`.
---
### 3. Invariants
- **`SerialNumber` uniqueness**: Within a `CANConfig.Modules` dictionary, keys are `SerialNumber` strings. Duplicate keys are overwritten (not rejected).
- **`ModuleChannelNumber` uniqueness**: Within a `CANModuleConfig._channels` dictionary, keys are `ModuleChannelNumber` integers. Duplicate keys are overwritten.
- **XML structure**: `CANConfig` XML root is `<CANConfig>`, containing `<Modules>` with nested `<CANModule>` elements. `CANModuleConfig` XML root is `<CANModule>`.
- **Backward compatibility**: `ReadModuleArray` silently ignores missing or malformed `ModuleArrayIndex` elements, assuming older config files may lack them.
- **Default values**: All numeric/string properties have non-null defaults (e.g., `""` for strings, `0` for numerics, `InvalidArmMode` for `RecordingMode`). `MaxEventStorageSpaceInBytes` defaults to `0` (not `null`).
- **File paths**: All file paths are constructed relative to the executing assembly’s directory, under `DASConfigs/<fileName>`.
---
### 4. Dependencies
- **Internal dependencies**:
- `DTS.Common.Utilities.Logging.APILogger` for error logging (used in constructors, `ReadXml`, `WriteXml`, and `ReadModuleArray`).
- `DTS.Common.Enums.DASFactory.DFConstantsAndEnums.RecordingMode` enum (used in `RecordingMode` property).
- `DASChannel` (base class) and `CANInputDASChannel` (concrete channel type) for channel storage and serialization. *Note: `DASChannel` is referenced but not defined in the provided sources.*
- **External dependencies**:
- `System.Xml`, `System.Xml.Serialization`, `System.IO`, `System.Reflection` (standard .NET libraries).
- File system access (for reading/writing XML files in `DASConfigs/`).
- **Depended upon by**:
Unknown from source alone. Likely consumed by higher-level DAS service components (e.g., configuration managers, CAN interface drivers) that initialize or update CAN module settings.
---
### 5. Gotchas
- **`GetModule`/`GetChannel` mutate on miss**: Both methods add the provided module/channel to the internal dictionary if not found, which may be unintended (e.g., during read-only queries). Consider renaming or clarifying intent.
- **No validation on `SerialNumber`/`ModuleChannelNumber`**: Duplicates are silently overwritten. No uniqueness enforcement beyond dictionary semantics.
- **`ReadModuleArray` swallows errors**: The `catch` block in `ReadModuleArray` ignores all exceptions, potentially masking real issues (e.g., malformed XML). This is intentional for backward compatibility but may complicate debugging.
- **`MaxEventStorageSpaceInBytes` range check is incomplete**: The condition `d >= 0 && d < ulong.MaxValue` allows `d == ulong.MaxValue`, but `Convert.ToUInt64(d)` will throw for `d == ulong.MaxValue` (since `double` may not represent it exactly). Should use `d <= ulong.MaxValue - 1` or similar.
- **No `WriteXml` override for base `DASChannel`**: The `WriteXml` method iterates over `_channels.Values` as `DASChannel`, but only `CANInputDASChannel` is instantiated in `ReadXml`. If other `DASChannel` subclasses exist, `WriteElementStart`/`WriteElementEnd` must be overridden appropriately.
- **Hardcoded path construction**: `Path.Combine(Path.GetDirectoryName(...), "DASConfigs", fileName)` assumes `DASConfigs` is a subdirectory of the assembly directory. May fail in non-standard deployment scenarios (e.g., single-file publish).
- **No XML validation schema**: `GetSchema()` returns `null`, so no schema validation occurs during deserialization. Malformed XML may cause runtime errors or silent data loss.
None identified beyond the above.

189
enriched-qwen3-coder-next/DataPRO/IService/Classes/Channels.md Normal file
View File

@@ -0,0 +1,189 @@
---
source_files:
- DataPRO/IService/Classes/Channels/OutputDASChannel.cs
- DataPRO/IService/Classes/Channels/AnalogOutputDASChannel.cs
- DataPRO/IService/Classes/Channels/DigitalOutputDASChannel.cs
- DataPRO/IService/Classes/Channels/InputDASChannel.cs
- DataPRO/IService/Classes/Channels/AnalogInputDASChannelComparer.cs
- DataPRO/IService/Classes/Channels/TimestampDASChannel.cs
- DataPRO/IService/Classes/Channels/StreamInputDASChannel.cs
- DataPRO/IService/Classes/Channels/OutputTOMDigitalChannel.cs
- DataPRO/IService/Classes/Channels/CANInputDASChannel.cs
- DataPRO/IService/Classes/Channels/UARTInputDASChannel.cs
- DataPRO/IService/Classes/Channels/StreamOutputDASChannel.cs
- DataPRO/IService/Classes/Channels/DASChannel.cs
- DataPRO/IService/Classes/Channels/OutputSquibChannel.cs
generated_at: "2026-04-16T04:00:36.696222+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "3f93d07c4af5eba3"
---
# DAS Channel Classes Documentation
## 1. Purpose
This module defines the class hierarchy for Data Acquisition System (DAS) channels, providing base and specialized classes for input and output channels used in the DTS DASLib.Service namespace. The classes model physical and logical channels in a DAS, supporting analog, digital, timestamp, CAN, UART, and streaming configurations. The hierarchy enables consistent channel management, serialization, and configuration across the system, with `DASChannel` as the root base class, `InputDASChannel` and `OutputDASChannel` as primary abstractions for directionality, and further derived classes for specific channel types (e.g., `AnalogInputDASChannel`, `CANInputDASChannel`, `OutputSquibChannel`). The module supports XML serialization for persistence and configuration, and includes validation logic via `IsConfigured()` overrides.
## 2. Public Interface
### Base Classes
- **`DASChannel`**
Abstract base class for all DAS channels. Implements `IXmlSerializable`.
- `DASChannel(DASModule owner, int channelNumber)` – Constructor with owner module and channel number.
- `DASChannel()` – Parameterless constructor.
- `virtual bool IsConfigured()` – Returns `false` by default; overridden in derived classes to indicate configuration state.
- `virtual void WriteXml(XmlWriter writer)` / `ReadXml(XmlReader reader)` – XML serialization/deserialization.
- `virtual void WriteXmlCRC32(XmlWriter writer)` – CRC32-specific serialization (subset of `WriteXml`).
- `virtual void HandleElement(XmlReader reader)` – Handles XML element parsing; can be overridden.
- `bool CanReProgram()` – Returns `true` if the channel’s module supports reprogramming (IEPE/analog switching).
- `int Number { get; }` – Stack channel number (0-based) relative to the DAS, computed via `OwningModule.OwningDAS.DASInfo.MapModuleArrayIndexAndChannelNum2DASChannel(...)`.
- Key properties: `ModuleChannelNumber`, `AbsoluteDisplayOrder`, `OwningModule`, `UnitConverision`, `ConfigurationMode`, `DiagnosticsMode`, `IsoChannelName`, `UserCode`, `UserChannelName`, `SetupEID`, `DataCollectionEID`, `SensitivityUnits`, `AtCapacity`, `CapacityOutputIsBasedOn`, `QualificationSamples`, `LevelTriggerT0AdjustmentSamples`, `UserValue1/2/3`, `IdType`.
- **`InputDASChannel : DASChannel`**
Base class for all input channels.
- `InputDASChannel(DASModule owner, int channelNumber)` – Constructor.
- `InputDASChannel()` – Parameterless constructor.
- **`OutputDASChannel : DASChannel`**
Base class for all output channels.
- `OutputDASChannel(DASModule owner, int channelNumber)` – Constructor.
- `OutputDASChannel()` – Parameterless constructor.
### Derived Input Channel Classes
- **`AnalogInputDASChannel`** *(not shown in source)*
Not present in provided files; assumed to exist as base for analog inputs (e.g., used by `AnalogInputDASChannelComparer`).
- **`AnalogInputDASChannelComparer : IEqualityComparer<AnalogInputDASChannel>`**
Custom equality comparer for `AnalogInputDASChannel` instances.
- `bool Equals(AnalogInputDASChannel x, AnalogInputDASChannel y)` – Returns `true` if channels match on:
`ModuleChannelNumber`, `OwningModule.ModuleArrayIndex`, `OwningModule.OwningDAS.SerialNumber`, `AbsoluteDisplayOrder`, and `UnitConverision`.
Includes null checks for objects, `OwningModule`, and `OwningDAS`; also validates `SerialNumber` is non-null/non-empty.
- `int GetHashCode(AnalogInputDASChannel analog)` – Hash code computed from same fields as `Equals`, with fallback to `0` if `SerialNumber` is null/empty.
- **`TimestampDASChannel : InputDASChannel`**
Channel for sample timestamps (RTC).
- `TimestampDASChannel(DASModule owner, int channelNumber)` – Constructor.
- `TimestampDASChannel()` – Parameterless constructor.
- `override bool IsConfigured()` – Always returns `true`.
- `override string ToString()` – Returns fixed string based on `ModuleType()` and `ModuleChannelNumber`:
- `"MARKER"`, `"SECONDS_HIGH"`, `"SECONDS_LOW"` for `EmbeddedClockSecondsAndMarker`
- `"NANOSECONDS_HIGH"`, `"NANOSECONDS_LOW"`, `"RESERVED"` for `EmbeddedClockNanosAndPad`
- Otherwise: `ModuleChannelNumber.ToString()`.
- Constants: `MARKER`, `SEC_H`, `SEC_L`, `NANOS_H`, `NANOS_L`, `RSVD`.
- **`StreamInputDASChannel : InputDASChannel`**
Channel for streaming input settings.
- `StreamInputDASChannel(DASModule owner, int channelNumber)` – Constructor.
- `StreamInputDASChannel()` – Parameterless constructor.
- `override bool IsConfigured()` – Returns `true` if `SerialNumber` is non-null/non-empty.
- `override string ToString()` – Returns `"Stream{ModuleChannelNumber}"`.
- `override void WriteXml(XmlWriter writer)` / `override void HandleElement(XmlReader reader)` – XML I/O for: `SerialNumber`, `HardwareChannelName`, `UDPAddress`.
- Properties: `SerialNumber`, `HardwareChannelName`, `UDPAddress`.
- **`CANInputDASChannel : InputDASChannel`**
Channel for CAN interface configuration.
- `CANInputDASChannel(DASModule owner, int channelNumber)` – Constructor; initializes `SerialNumber` from `owner.SerialNumber()`.
- `CANInputDASChannel()` – Parameterless constructor.
- `override bool IsConfigured()` – Returns `true` if `SerialNumber` is non-null/non-empty.
- `override string ToString()` – Returns `"CAN{ModuleChannelNumber}"`.
- `override void WriteXml(XmlWriter writer)` / `override void HandleElement(XmlReader reader)` – XML I/O for: `SerialNumber`, `HardwareChannelName`, `IsFD`, `ArbBaseBitrate`, `ArbBaseSJW`, `DataBitrate`, `DataSJW`, `FileType`.
- Properties: `SerialNumber`, `HardwareChannelName`, `IsFD`, `ArbBaseBitrate`, `ArbBaseSJW`, `DataBitrate`, `DataSJW`, `FileType`.
- **`UARTInputDASChannel : InputDASChannel`**
Channel for UART interface configuration.
- `UARTInputDASChannel(DASModule owner, int channelNumber)` – Constructor.
- `UARTInputDASChannel()` – Parameterless constructor.
- `override bool IsConfigured()` – Returns `true` if `SerialNumber` is non-null/non-empty.
- `override string ToString()` – Returns `"UART{ModuleChannelNumber}"`.
- `override void WriteXml(XmlWriter writer)` / `override void HandleElement(XmlReader reader)` – XML I/O for: `SerialNumber`, `HardwareChannelName`, `BaudRate`, `DataBits`, `StopBits`, `Parity`, `FlowControl`, `DataFormat`.
Includes `try/catch` blocks for enum parsing with logging via `APILogger.Log`.
- Properties: `SerialNumber`, `HardwareChannelName`, `BaudRate`, `DataBits`, `StopBits`, `Parity`, `FlowControl`, `DataFormat`.
### Derived Output Channel Classes
- **`AnalogOutputDASChannel : OutputDASChannel`**
Base class for analog output channels.
- `AnalogOutputDASChannel(DASModule owner, int channelNumber)` – Constructor.
- `AnalogOutputDASChannel()` – Parameterless constructor.
- **`DigitalOutputDASChannel : OutputDASChannel`**
Base class for digital output channels.
- `DigitalOutputDASChannel(DASModule owner, int channelNumber)` – Constructor.
- `DigitalOutputDASChannel()` – Parameterless constructor.
- **`StreamOutputDASChannel : OutputDASChannel`**
Channel for streaming output settings.
- `StreamOutputDASChannel(DASModule owner, int channelNumber)` – Constructor.
- `StreamOutputDASChannel()` – Parameterless constructor.
- `override bool IsConfigured()` – Returns `true` if `SerialNumber` is non-null/non-empty.
- `override string ToString()` – Returns `"Stream{ModuleChannelNumber}"`.
- `override void WriteXml(XmlWriter writer)` / `override void HandleElement(XmlReader reader)` – XML I/O for: `SerialNumber`, `HardwareChannelName`, `UDPProfileName`, `UDPTimeChannelId`, `UDPDataChannelId`, `IRIGTimeDataPacketIntervalMs`, `TMATSIntervalMs`, `UDPAddress`, `UDPTmNSConfig`.
- Properties: `SerialNumber`, `HardwareChannelName`, `UDPProfileName`, `UDPTimeChannelId`, `UDPDataChannelId`, `IRIGTimeDataPacketIntervalMs`, `TMATSIntervalMs`, `UDPAddress`, `UDPTmNSConfig`.
- **`OutputTOMDigitalChannel : DigitalOutputDASChannel`**
Base class for TOM (Test Output Module) digital channels (e.g., SQUIB-related).
- `OutputTOMDigitalChannel(DASModule owner, int channelNumber)` – Constructor.
- `OutputTOMDigitalChannel()` – Parameterless constructor.
- `OutputTOMDigitalChannel(XmlReader reader)` – Constructor for deserialization.
- `override bool IsConfigured()` – Returns `true` if `OutputMode != DigitalOutputModes.NONE` and `DigitalChannelDescription` is non-empty.
- `override void WriteXml(XmlWriter writer)` / `override void WriteXmlCRC32(XmlWriter writer)` / `override void HandleElement(XmlReader reader)` – XML I/O for: `DelayMS`, `DurationMS`, `OutputMode`, `LimitDuration`, `DigitalChannelDescription`.
- Properties: `OutputMode`, `DelayMS`, `LimitDuration`, `DurationMS`, `DigitalChannelDescription`, `LastModifiedBy`, `LastModified`, `LocalOnly`, `HardwareChannelName`, `Version`, `Date`.
- **`OutputSquibChannel : AnalogOutputDASChannel`**
Channel for SQUIB (squib fire) output configuration. Implements `IComparable`.
- `OutputSquibChannel(DASModule owner, int channelNumber)` – Constructor.
- `OutputSquibChannel()` – Parameterless constructor.
- `OutputSquibChannel(XmlReader reader)` – Constructor for deserialization.
- `override bool IsConfigured()` – Returns `true` if `FireMode != SquibFireMode.NONE` and `SquibDescription` is non-empty.
- `override string ToString()` – Returns `SquibDescription.Trim()` if non-empty; otherwise `base.ToString()`.
- `int IComparable.CompareTo(object o)` – Compares by `SquibDescription`.
- `override void WriteXml(XmlWriter writer)` / `override void WriteXmlCRC32(XmlWriter writer)` / `override void HandleElement(XmlReader reader)` – XML I/O for:
`BypassCurrentFilter`, `BypassVoltageFilter`, `DelayMS`, `DurationMS`, `FireMode`, `ISOCode`, `MeasurementType`, `SquibDescription`, `ChannelId`, `ChannelName2`, `ChannelGroupName`, `HardwareChannelName`, `SquibFiredPassed`, `SquibFiredValid`, `SquibMeasuredOhms`, `SquibOutputCurrent`, `SquibToleranceHigh`, `SquibToleranceLow`, `LimitDuration`, `ScaleFactorMv`, `PreTestDataZeroLevelADC`, `SupportedSquibFireModes`, `SoftwareFilterFrequency`, `Sensor`, `SerialNumber`.
- Properties: `SupportedSquibFireModes`, `Diagnostics`, `FireMode`, `MeasurementType`, `BypassCurrentFilter`, `BypassVoltageFilter`, `SquibToleranceLow`, `SquibToleranceHigh`, `SquibOutputCurrent`, `SquibMeasuredOhms`, `SquibFiredValid`, `SquibFiredPassed`, `DelayMS`, `DurationMS`, `SquibDescription`, `ISOCode`, `ChannelId`, `ChannelName2`, `HardwareChannelName`, `LimitDuration`, `ScaleFactorMv`, `PreTestDataZeroLevelADC`, `LocalOnly`, `LastModifiedBy`, `Sensor`, `SerialNumber`, `SoftwareFilterFrequency`.
- Constants: `DEFAULT_MIN_FIRE_DURATION_MS`, `DEFAULT_MIN_FIRE_DELAY_MS`, `DEFAULT_DEFINEINTEST_FIRE_DELAY_FLAG`, `DEFAULT_MAX_FIRE_DURATION_MS`, `DEFAULT_MAX_FIRE_DELAY_MS`.
## 3. Invariants
- **Channel Ownership**: Every channel instance has an `OwningModule` (set via constructor or deserialization). `DASChannel.Number` depends on `OwningModule.OwningDAS` being non-null and `DASInfo`/`Modules` being initialized.
- **Serialization Consistency**: `WriteXml` and `ReadXml` must be symmetric; `HandleElement` implementations must handle all XML tags written by `WriteXml`.
- **Configuration State**: `IsConfigured()` must be deterministic and based on concrete configuration data (e.g., presence of `SerialNumber`, non-`NONE` `FireMode`, etc.). Default implementation returns `false`.
- **Equality Semantics**: `AnalogInputDASChannelComparer` enforces that equality is based on a composite key: channel number, module index, DAS serial number, display order, and unit conversion. `GetHashCode` must match `Equals`.
- **Timestamp Channels**: `TimestampDASChannel.IsConfigured()` always returns `true`, indicating it is always considered configured.
- **String Constants**: Tag names used in XML I/O (e.g., `SERIALNUMBER_TAG`, `DELAYMS_TAG`) are `private const string` and must match exactly between `WriteXml` and `HandleElement`.
- **Enum Parsing Safety**: `UARTInputDASChannel` and `OutputSquibChannel` wrap enum parsing in `try/catch` blocks with logging to prevent deserialization failure.
## 4. Dependencies
### Dependencies *of* this module:
- **`DTS.DASLib.Service` namespace**:
- `DASModule` (used in constructors and `OwningModule` property).
- `DASInfo` (used in `DASChannel.Number` and `CanReProgram()`).
- **External Libraries**:
- `System`, `System.Xml`, `System.Collections.Generic`, `System.IO.Ports`, `System.Linq` (via LINQ in `AnalogInputDASChannelComparer`).
- `DTS.Common.Enums.DASFactory` (`DFConstantsAndEnums`, `ModuleType`).
- `DTS.Common.Enums` (`DigitalOutputModes`, `SquibFireMode`, `SquibMeasurementType`, `UartDataFormat`, `StopBits`, `Parity`, `Handshake`).
- `DTS.Common.Interface.DASFactory.Config` (`IDASChannel`, `IEID`).
- `DTS.Common.Interface.DASFactory.Diagnostics` (`IDiagnosticResult`).
- `DTS.Common.Utilities.Logging` (`APILogger`).
- `DTS.Common.Utilities` (`ArrayToString`).
- `DTS.Common.Classes.Sensors` (`UDPStreamProfile`, `SensorConstants`).
### Dependencies *on* this module:
- Any class that manages DAS channels (e.g., `DASModule`, `DAS`, `IDASCommunication`) depends on these channel types.
- `AnalogInputDASChannelComparer` is explicitly noted as being used by `IDASCommunication` (per comment in source).
## 5. Gotchas
- **Typo in Property Name**: `UnitConverision` (instead of `UnitConversion`) is used consistently in `DASChannel` and XML I/O. This is likely a historical typo.
- **`DASChannel.Number` May Throw**: The `Number` property can throw `ApplicationException` if `OwningModule`, `OwningDAS`, or `DASInfo` are null or improperly initialized.
- **`CanReProgram()` Null Safety**: `CanReProgram()` performs multiple null checks; returns `false` if any link in the chain (`OwningModule`, `OwningDAS`, `DASInfo`, `Modules`) is null.
- **`AnalogInputDASChannelComparer` Null Sensitivity**: `Equals` returns `false` if `OwningModule.OwningDAS.SerialNumber` is null/empty—even if other fields match. This may cause unexpected inequality for partially initialized channels.
- **`OutputSquibChannel` Serialization of `ArticleId`**: In `WriteXmlCRC32` and `WriteXml`, `ArticleId` is written but ignored in `HandleElement` (commented as “why aren’t we using this id?”). This may indicate legacy or incomplete implementation.
- **`TimestampDASChannel.ToString()` Relies on `ModuleType()`**: The `ToString()` override calls `OwningModule.ModuleType()`, but `ModuleType()` is not defined in the provided source—its implementation is assumed to be in `DASModule`.
- **`OutputSquibChannel` Default Fire Delay Flag**: `DEFAULT_DEFINEINTEST_FIRE_DELAY_FLAG = -1` is a special sentinel value indicating delay must be defined in test setup; not documented in `IsConfigured()` or XML handling.
- **`StreamOutputDASChannel.TMATSIntervalMs` Default**: Uses `StreamOutputRecord.DEFAULT_TMATS_INTERVAL_MS`, but `StreamOutputRecord` is not defined in the provided source.
- **`AnalogInputDASChannel` Not Defined**: The comparer `AnalogInputDASChannelComparer` references `AnalogInputDASChannel`, but no such class is defined in the provided files—only `AnalogOutputDASChannel` is present. This suggests an omission or that `AnalogInputDASChannel` is defined elsewhere.
- **`OutputTOMDigitalChannel` vs `OutputSquibChannel`**: Both are described as “base class for SQUIB channels” in comments, but `OutputSquibChannel` inherits from `AnalogOutputDASChannel`, while `OutputTOMDigitalChannel` inherits from `DigitalOutputDASChannel`. This may indicate

298
enriched-qwen3-coder-next/DataPRO/IService/Classes/Diagnostics.md Normal file
View File

@@ -0,0 +1,298 @@
---
source_files:
- DataPRO/IService/Classes/Diagnostics/OptimizationValues.cs
- DataPRO/IService/Classes/Diagnostics/DiagnosticActions.cs
- DataPRO/IService/Classes/Diagnostics/DiagnosticsResultActions.cs
- DataPRO/IService/Classes/Diagnostics/DiagnosticsResult.cs
generated_at: "2026-04-16T03:59:21.765469+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "3fe2b63623721951"
---
# Documentation: Diagnostics Module
## 1. Purpose
This module provides the data structures and utility methods required to configure, execute, and store diagnostic tests for DAS (Data Acquisition System) channels. It defines how diagnostic actions are specified (`DiagnosticsActions`), what results are collected from those actions (`DiagnosticsResult`), and how to persist or clear diagnostics data in memory and the database (`DiagnosticsResultActions`). Its role is to enable pre-recording validation of sensor and channel configuration by comparing measured diagnostic values (e.g., excitation voltage, offset, noise, shunt deflection) against expected hardware specifications, thereby supporting system integrity checks before data acquisition begins.
## 2. Public Interface
### `DiagnosticsActions` class (`IDiagnosticActions` implementation)
- **`int DASChannelNumber { get; set; }`**
Identifies the DAS channel (0-indexed globally across the DAS unit) for which these diagnostic instructions apply.
- **`bool MeasureExcitation { get; set; }`**
If `true`, measure the excitation voltage applied to the sensor.
- **`bool MeasureOffset { get; set; }`**
If `true`, measure the sensor’s offset from 0 (in mV); can be validated against `AnalogInputDASChannel` offset limits.
- **`bool CheckDigitalState { get; set; }`**
If `true`, check the open/closed/high/low state of a digital input channel.
- **`bool MeasureInternalOffset { get; set; }`**
If `true`, measure internal offset (likely ADC or front-end offset).
- **`bool RemoveOffset { get; set; }`**
If `true`, instruct firmware to compensate for and remove the measured offset.
- **`bool MeasureNoise { get; set; }`**
If `true`, measure noise floor as a percentage of full-scale reading.
- **`bool PerformShuntCheck { get; set; }`**
If `true`, perform an emulated shunt-check test.
- **`bool SquibFireCheck { get; set; } = false`**
If `true`, run a squib fire check on the channel.
- **`bool PerformVoltageInsertCheck { get; set; }`**
If `true`, perform a voltage insertion gain check (SLICE Pro-specific).
- **`bool PerformCalSignalCheck { get; set; }`**
If `true`, perform a calibration signal-check test.
- **`bool MeasureBridgeResistance { get; set; }`**
If `true`, measure the bridge resistance of the sensor.
- **`DiagnosticsActions()`**
Default constructor initializes all action flags to `false` and `DASChannelNumber` to `0`.
- **`bool AllActionsDisabled()`**
Returns `true` if *none* of the diagnostic action flags are enabled.
- **`static void SetChannelDiagnosticActions(IDASCommunication unit, IDiagnosticActions[] actions, bool setInDb)`**
Assigns the diagnostic action array to `unit.ChannelDiagnostics`. If `setInDb` is `true` and the database is connected, clears existing diagnostic actions for the record and inserts the new ones via `Diagnostics.InsertDiagnosticAction`.
### `DiagnosticsResult` class (`IDiagnosticResult` implementation)
- **`int DASChannelNumber { get; set; }`**
The DAS channel number for which this result applies.
- **`int EventNumber { get; set; }`**
The event number associated with this diagnostic result.
- **`double ScalefactorMilliVoltsPerADC { get; set; } = 1`**
Mandatory scale factor to convert raw ADC counts to millivolts. Required for post-download data scaling.
- **`double ScalefactorEngineeringUnitsPerADC { get; set; } = 1`**
Scale factor to convert ADC counts to engineering units.
- **`double ExpectedExcitationMilliVolts { get; set; }`**
Factory-set expected excitation voltage (mandatory).
- **`short GetExpectedDataZeroLevelADC(ZeroMethodType zeroMethod)`**
Returns the expected zero-level ADC value based on the zeroing method:
- `ZeroMethodType.None`: returns `ZeroMVInADC`
- Otherwise: uses `FinalOffsetADC` if non-null, else converts `MeasuredOffsetMilliVolts` to ADC using `ScalefactorMilliVoltsPerADC`, else returns `0`.
- **`double? MeasuredExcitationMilliVolts { get; set; }`**
Measured excitation voltage (may be `null` if not measured; `0.0` in serialized data may indicate `null`).
- **`bool NegativeExcitation { get; set; }`**
Flag indicating whether `MeasuredExcitationMilliVolts` was negative (legacy support for broken-sensor warnings).
- **`double? MeasuredOffsetMilliVolts { get; set; }`**
Measured offset in mV (may be `null`).
- **`double? MeasuredInternalOffsetMilliVolts { get; set; }`**
Measured internal offset in mV.
- **`double? MeasuredOffsetEngineeringUnits { get; set; }`**
Measured offset in engineering units.
- **`double? AutoZeroPercentDeviation { get; set; }`**
Deviation from zero after auto-zeroing (absolute value enforced on set). Reflects deviation in ADC counts (±5% check).
- **`short? FinalOffsetADC { get; set; }`**
Offset remaining after firmware offset removal (if `RemoveOffset` was enabled).
- **`int? RemovedOffsetADC { get; set; }`**
Amount of offset removed (in ADC counts).
- **`int? RemovedInternalOffsetADC { get; set; }`**
Amount of internal offset removed.
- **`double? NoisePercentFullScale { get; set; }`**
Noise floor as % of full-scale reading.
- **`bool ShuntDeflectionFailed { get; set; }`**
`true` if shunt-check failed.
- **`bool CalSignalCheckFailed { get; set; }`**
`true` if calibration signal check failed.
- **`double? MeasuredShuntDeflectionMv { get; set; }`**
Measured shunt deflection in mV (if `PerformShuntCheck` was enabled).
- **`double? MeasuredCalSignalMv { get; set; }`**
Measured calibration signal in mV.
- **`double? TargetCalSignalMv { get; set; }`**
Expected calibration signal in mV.
- **`double? MeasuredDurationMS { get; set; }`**
Measured squib fire duration (ms).
- **`double? MeasuredDelayMS { get; set; }`**
Measured squib fire delay (ms).
- **`bool? SquibFirePassed { get; set; }`**
`true` if squib fire test passed.
- **`bool? SquibDurationPassed { get; set; }`**
`true` if squib duration passed.
- **`bool? SquibDelayPassed { get; set; }`**
`true` if squib delay passed.
- **`double[] SquibFireCurrentData { get; set; }`**
Raw current data from squib fire test.
- **`double[] SquibFireVoltageData { get; set; }`**
Raw voltage data from squib fire test.
- **`double[] SquibFireTimeAxis { get; set; }`**
Time axis (ms) for squib fire test.
- **`double SquibThreshold { get; set; }`**
Squib fire threshold (likely current or voltage).
- **`double SquibVoltageScaler { get; set; }`**
Voltage scaler used in squib test.
- **`double SquibCurrentScaler { get; set; }`**
Current scaler used in squib test.
- **`double? TargetGain { get; set; }`**
Expected gain (e.g., for voltage insertion check).
- **`double? MeasuredGain { get; set; }`**
Measured gain.
- **`double? QueriedGain { get; set; }`**
Gain value queried from firmware/config.
- **`double? TargetShuntDeflectionMv { get; set; }`**
Expected shunt deflection in mV.
- **`double? BridgeResistance { get; set; }`**
Measured bridge resistance in ohms (if `MeasureBridgeResistance` enabled).
- **`short ZeroMVInADC { get; set; } = 0`**
ADC value corresponding to 0 mV input.
- **`short WindowAverageADC { get; set; } = short.MinValue`**
Average ADC over the configured window. `short.MinValue` indicates uninitialized/invalid.
- **`bool DigitalInputActiveState { get; set; }`**
Current active state of digital input (`true` = active/high, `false` = inactive/low).
### `DiagnosticsResultActions` static class
- **`static void ClearChannelDiagnosticsResults(IDASCommunication unit, bool bClearDb = true)`**
Clears `unit.ChannelDiagnosticsResults` and `unit.ChannelDiagnostics` arrays. If `bClearDb` is `true` and DB is connected, clears diagnostics from the database.
- **`static void SetChannelDiagnosticsResults(IDASCommunication unit, IDiagnosticResult[] results, bool setInDb)`**
Assigns `results` to `unit.ChannelDiagnosticsResults`. If `setInDb` is `true`, writes each result to the DB using type-specific methods:
- `InsertDigitalDiagnosticResult` for digital channels
- `InsertAnalogDiagnosticResult` for analog channels
- `InsertSquibDiagnosticResult` for squib channels
Channel type is determined via `unit.DASInfo.MapDASChannelNumber2ModuleArrayIndex` and `MapDASChannelNumber2ModuleChannelNumber`.
- **`private static void InsertDiagnosticsResultDigital(...)`**
Writes digital diagnostic result to DB.
- **`private static void InsertDiagnosticsResultAnalog(...)`**
Writes analog diagnostic result to DB (18 parameters).
- **`private static void InsertDiagnosticsResultsSquib(...)`**
Writes squib diagnostic result to DB (14 parameters). Exceptions are silently swallowed.
### `OptimizationValues` class
- **`float TransferSpeed { get; set; }`**
Holds a single float value representing transfer speed (likely for optimization tuning). No further behavior or usage context provided.
## 3. Invariants
- **`DiagnosticsActions.AllActionsDisabled()`** returns `true` only when *all* action flags are `false`.
- Includes: `MeasureExcitation`, `MeasureOffset`, `RemoveOffset`, `MeasureNoise`, `PerformShuntCheck`, `MeasureBridgeResistance`, `PerformCalSignalCheck`, `PerformVoltageInsertCheck`, `MeasureInternalOffset`, `SquibFireCheck`, `CheckDigitalState`.
- **`DiagnosticsResult.ScalefactorMilliVoltsPerADC`** is mandatory for scaling raw ADC data to real-world voltages; no fallback is provided if missing.
- **`DiagnosticsResult.ZeroMVInADC`** defaults to `0`, and `WindowAverageADC` defaults to `short.MinValue` to indicate uninitialized/invalid state.
- **`DiagnosticsResult.AutoZeroPercentDeviation`** enforces non-negativity: setter applies `Math.Abs()`.
- **`DiagnosticsResult.GetExpectedDataZeroLevelADC()`** uses a priority order:
`ZeroMethodType.None` → `ZeroMVInADC`;
otherwise → `FinalOffsetADC` (if non-null) → `MeasuredOffsetMilliVolts` (converted) → `0`.
- **`DiagnosticsResultActions.SetChannelDiagnosticsResults()`** determines channel type via mapping and type-checks against `AnalogInputDASChannel` or `OutputSquibChannel`. If the channel is neither, no DB insertion occurs (no exception thrown, but no logging either).
- **Database writes** in `SetChannelDiagnosticActions` and `DiagnosticsResultActions` are guarded by `DASFactoryDb.DbWrapper.Connected` and `setInDb`/`bClearDb` flags. Exceptions during DB operations are logged via `APILogger.Log(ex)` (except squib result insertion, which silently swallows exceptions).
## 4. Dependencies
### Imports / External Types Used
- **`DTS.Common.Interface.DASFactory`**
Provides `IDASCommunication`, `IDiagnosticActions`, `IDiagnosticResult`, `AnalogInputDASChannel`, `OutputSquibChannel`.
- **`DTS.Common.Interface.DASFactory.Diagnostics`**
Defines `IOptimizationValues`, `IDiagnosticActions`, `IDiagnosticResult`.
- **`DTS.Common.Enums.Sensors`**
Provides `ZeroMethodType` enum used in `GetExpectedDataZeroLevelADC`.
- **`DTS.Common.Utilities.Logging`**
Provides `APILogger` for exception logging.
- **`DASFactoryDb.Diagnostics`**
Provides `Diagnostics` class with methods:
- `ClearDiagnosticActionsAllChannels`
- `InsertDiagnosticAction`
- `ClearExistingDiagnosticsAllChannels`
- `InsertDigitalDiagnosticResult`
- `InsertAnalogDiagnosticResult`
- `InsertSquibDiagnosticResult`
- **`DASFactoryDb.DbWrapper`**
Provides `Connected` property to check DB connectivity.
### Inferred Usage
- **Consumers**: Likely `DiagnosticsService` (referenced in `DiagnosticsResult` XML comments) and `ConfigureService` (for populating `AnalogInputDASChannel` specs).
- **Dependencies on other modules**:
- `DiagnosticsService` (for calibration/diagnostics execution)
- `ConfigureService` (to populate sensor specs like offset limits in `AnalogInputDASChannel`)
- `DASFactoryDb` (for persistence)
- `APILogger` (for error logging)
## 5. Gotchas
- **`MeasuredExcitationMilliVolts`, `MeasuredOffsetMilliVolts`, and other nullable fields**: A value of `0.0` read from event attributes may actually mean `null` (i.e., not measured). Callers must treat `0.0` as ambiguous and not assume it indicates a valid zero reading.
- **`WindowAverageADC` default value**: `short.MinValue` is used as a sentinel for uninitialized/invalid values. Code must check for this explicitly rather than assuming `0` is valid.
- **`AutoZeroPercentDeviation` setter**: Automatically applies `Math.Abs()`. Setting a negative value will silently flip the sign.
- **`DiagnosticsResultActions.SetChannelDiagnosticsResults()`**: If a channel is neither `AnalogInputDASChannel` nor `OutputSquibChannel`, no DB insertion occurs and no error is logged. This may silently skip unsupported channel types.
- **Squib result insertion**: Exceptions during `InsertSquibDiagnosticResult` are silently swallowed (no logging). This is explicitly noted in source comments as temporary.
- **`DiagnosticsActions.SetChannelDiagnosticActions()`**: Clears *all* existing diagnostic actions for the record *before* inserting new ones. If called with `actions == null`, it clears the DB but inserts nothing.
- **Channel mapping**: Relies on `unit.DASInfo.MapDASChannelNumber2ModuleArrayIndex` and `MapDASChannelNumber2ModuleChannelNumber`. Incorrect mapping could lead to DB writes to wrong channels or index-out-of-range errors.
- **`OptimizationValues`**: Only contains `TransferSpeed`. No usage context or integration points are visible in the provided source. Its purpose and consumers are unclear.
- **No validation in constructors**: `DiagnosticsActions` and `DiagnosticsResult` do not validate property values (e.g., negative `DASChannelNumber`, out-of-range `EventNumber`). Validation is deferred to downstream logic.
- **No thread-safety guarantees**: All methods are non-atomic and share mutable state (e.g., `unit.ChannelDiagnostics`, `unit.ChannelDiagnosticsResults`). Concurrent access may cause race conditions.
- **Legacy flag `NegativeExcitation`**: Introduced to preserve legacy TDC/TDAS behavior for broken-sensor warnings. Its presence suggests historical quirks in excitation reading that may affect interpretation of `MeasuredExcitationMilliVolts`.
None identified from source alone.

144
enriched-qwen3-coder-next/DataPRO/IService/Classes/Download.md Normal file
View File

@@ -0,0 +1,144 @@
---
source_files:
- DataPRO/IService/Classes/Download/UARTDownloadRequest.cs
- DataPRO/IService/Classes/Download/DownloadRequest.cs
- DataPRO/IService/Classes/Download/DownloadReport.cs
generated_at: "2026-04-16T03:58:36.838770+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "6a51104a1281b13a"
---
# Documentation: Download Request and Report Classes
## 1. Purpose
This module provides data structures and static utility methods to configure and persist download requests and event metadata for a DAS (Data Acquisition System). It defines concrete implementations (`UARTDownloadRequest`, `DownloadRequest`, `DownloadReport`) of their corresponding interfaces (`IUARTDownloadRequest`, `IDownloadRequest`, `IDownloadReport`) used to specify *what* data to download from the DAS device and *which events* are present/already downloaded. The `SetWhatToDownload` and `SetEvent*` static methods in these classes synchronize request/report state with both the DAS communication layer (`IDASCommunication`) and a backing database via `DASFactoryDb.Download` functions.
## 2. Public Interface
### `UARTDownloadRequest` class
- **`EventNumber`** (`ushort`): Gets or sets the event number from which to download UART data.
- **`TotalByteCount`** (`ulong`): Gets or sets the total number of bytes in the UART stream.
- **`TriggerByteCount`** (`ulong`): Gets or sets the byte offset within the stream where the trigger occurred.
- **`FaultByteCount`** (`ulong`): Gets or sets the byte offset within the stream where a fault occurred.
- **`StartTimestamp`** (`ulong`): Gets or sets the start timestamp of the UART stream.
- **`EndTimestamp`** (`ulong`): Gets or sets the end timestamp of the UART stream.
- **`BaudRate`** (`int`): Gets or sets the baud rate used during UART recording.
- **`SetWhatToDownload(IDASCommunication das, IUARTDownloadRequest request, bool bSetInDb)`** (`static void`):
Assigns the provided `request` to `das.WhatUARTToDownload` (if `das` implements `IUARTDownload`). If `bSetInDb` is `true` and the database is connected, clears existing UART download requests for `das.RecordId`, then inserts the new request (or does nothing if `request` is `null`). Exceptions during DB insertion are logged via `APILogger.Log`.
### `DownloadRequest` class
- **`ALL_CHANNELS`** (`const byte`): Value `0xFF`; indicates all channels should be downloaded. *Currently the only supported value*.
- **`EventNumber`** (`ushort`): Gets or sets the event number to download.
- **`DASChannelNumber`** (`byte`): Gets or sets the channel number; must be `ALL_CHANNELS` (`0xFF`) per current implementation.
- **`StartSample`** (`ulong`, `virtual`): Gets or sets the first sample index to download.
- **`EndSample`** (`ulong`, `virtual`): Gets or sets the last sample index to download.
- **`SamplesToSkip`** (`ulong`): Gets or sets subsampling factor. `0` or `1` means no subsampling; `n > 1` means every *n*th sample. *Invariant*: `(EndSample - StartSample + 1)` must be divisible by `SamplesToSkip`.
- **`StartRecordTimestampSec`** (`double`): Gets or sets the integer seconds portion of the record start timestamp.
- **`TriggerTimestampSec`** (`double`): Gets or sets the integer seconds portion of the trigger timestamp.
- **`StartRecordTimestampNanoSec`** (`double`): Gets or sets the nanoseconds portion of the record start timestamp.
- **`TriggerTimestampNanoSec`** (`double`): Gets or sets the nanoseconds portion of the trigger timestamp.
- **`PTPMasterSync`** (`bool`): Gets or sets whether PTP master synchronization was used.
- **`SetWhatToDownload(IDASCommunication das, IDownloadRequest request, bool bSetInDb)`** (`static void`):
Assigns `request` to `das.WhatToDownload`. Logs the request details if non-null. If `bSetInDb` is `true` and the database is connected, clears existing download requests for `das.RecordId`, then inserts the new request (or does nothing if `request` is `null`). Exceptions during DB insertion are logged via `APILogger.Log`.
### `DownloadReport` class
#### Nested Types
- **`EventInfo`** (`class`, implements `IEventInfo`):
Represents metadata for a single event/test.
- `Modules` (`IDASModule[]`): Array of modules involved in the event, indexed by `ModuleArrayIndex`.
- `EventNumber` (`int`): Event number.
- `TestGUID` (`Guid`): Event GUID.
- `FaultFlags` (`ushort`): Fault flags.
- `FaultFlagsEx` (`ushort`): Extended fault flags.
- `ArmAttempts` (`byte`): Number of arm attempts.
- `TestTime` (`DateTime`): Timestamp of the event.
- `TestID` (`string`): Event ID string.
- `Description` (`string`): Event description.
- `HasBeenDownloaded` (`bool`): Whether the event has been downloaded.
- `WasTriggered` (`bool`): Whether the event received a trigger.
- `ClearFaults()` (`void`): Resets `FaultFlags` and `FaultFlagsEx` to `0`.
- `EventInfo(EventInfo copy)` (`constructor`): Copies all fields from another `EventInfo`.
- **`UARTEventInfo`** (`class`, implements `IUARTEventInfo`):
Represents metadata for a single UART event.
- `EventNumber` (`ushort`): Event number.
- `DataPresent` (`bool`): Whether UART data exists for this event.
- `DataDownloaded` (`bool`): Whether UART data has been downloaded.
- `TotalByteCount` (`ulong`): Total bytes of UART data.
- `TriggerByteCount` (`ulong`): Byte offset of trigger.
- `FaultByteCount` (`ulong`): Byte offset of fault.
- `StartTimestamp` (`ulong`): UART stream start timestamp.
- `EndTimestamp` (`ulong`): UART stream end timestamp.
- `BaudRate` (`uint`): Baud rate during recording.
#### Instance Properties
- **`Events`** (`IEventInfo[]`): Array of all events on the DAS.
- **`UARTEvents`** (`IUARTEventInfo[]`): Array of all UART events on the DAS.
#### Static Methods
- **`SetEventDownloadStatus(IDASCommunication das, bool[] status, bool bStoreInDb)`** (`static void`):
Sets `das.EventDownloadedStatus` to `status`. If `bStoreInDb` and DB connected, clears and re-inserts status entries for `das.RecordId`. Logs exceptions.
- **`SetEventArmAttempts(IDASCommunication das, byte[] armAttempts, bool storeInDb)`** (`static void`):
Sets `das.ArmAttempts` to `armAttempts`. Persists to DB if applicable.
- **`SetEventFaultFlags(IDASCommunication das, ushort[] faultFlags, bool storeInDb)`** (`static void`):
Sets `das.FaultFlags` to `faultFlags`. Persists to DB if applicable.
- **`SetEventInfo(IDASCommunication das, IDownloadReport eventInfo, bool storeInDB)`** (`static void`):
Sets `das.EventInfo` to `eventInfo`. Persists each `IEventInfo` in `eventInfo.Events` to DB by serializing `Modules` to XML and calling `Download.InsertEventInfo`. Logs exceptions.
- **`SetEventGuids(IDASCommunication das, Guid[] guids, bool storeInDb)`** (`static void`):
Sets `das.EventGuids` to `guids`. Persists to DB if applicable.
## 3. Invariants
- **`DownloadRequest.DASChannelNumber`** must be `ALL_CHANNELS` (`0xFF`). Other values are unsupported per the class documentation.
- **`DownloadRequest.SamplesToSkip`** must divide `(EndSample - StartSample + 1)` exactly. The code does not enforce this at runtime; violation would likely cause downstream errors.
- **`DownloadRequest.SetWhatToDownload`** and **`UARTDownloadRequest.SetWhatToDownload`**:
- If `bSetInDb` is `false` or `DASFactoryDb.DbWrapper.Connected` is `false`, no DB operations occur.
- DB operations always clear *all* existing requests for `das.RecordId` before inserting the new one (or none if `request` is `null`).
- **`DownloadReport.SetEventInfo`** serializes `eventInfo.Modules` to XML using `XmlWriter` with `ConformanceLevel.Document`. If any `IDASModule.WriteXml` implementation fails, the entire operation fails and is logged.
- **`DownloadReport.EventInfo.ClearFaults()`** unconditionally sets both `FaultFlags` and `FaultFlagsEx` to `0`.
## 4. Dependencies
### Internal Dependencies (from source)
- **`DASFactoryDb.Download`**: Provides DB functions:
- `ClearExistingUARTDownloadRequests`, `UARTDownloadRequestInsert`
- `ClearExistingDownloadRequests`, `DownloadRequestInsert`
- `ClearExistingEventDownloadStatus`, `InsertEventDownloadStatus`
- `ClearExistingEventArmAttempts`, `InsertEventArmAttempts`
- `ClearExistingFaultFlags`, `InsertEventFaultFlags`
- `ClearExistingDownloadReports`, `InsertEventInfo`
- `ClearExistingEventGuids`, `EventGuidInsert`
- **`DASFactoryDb.DbWrapper`**: Provides `Connected` property and is used to gate DB operations.
- **`DTS.Common.Interface.DASFactory`**: Defines `IDASCommunication`, `IDownloadRequest`, `IUARTDownloadRequest`, `IDownloadReport`, `IEventInfo`, `IUARTEventInfo`.
- **`DTS.Common.Interface.DASFactory.Download`**: Defines `IUARTDownload` (used in `UARTDownloadRequest.SetWhatToDownload` to cast `das`).
- **`DTS.Common.Interface.DownloadEvent`**: Defines `IEventInfo` (used in `DownloadReport.EventInfo`).
- **`DTS.Common.Utilities.Logging`**: Provides `APILogger` for exception logging.
### External Dependencies (inferred)
- **Database**: SQL Server (via `System.Data.SqlClient` and `SqlTypes` imports in `DownloadReport.cs`).
- **XML serialization**: Uses `System.Xml` for `IDASModule.WriteXml` serialization.
## 5. Gotchas
- **`DownloadRequest.SamplesToSkip` validation is not enforced**: The code comments state `(EndSample - StartSample + 1)` must be a multiple of `SamplesToSkip`, but no runtime check exists. Invalid values may cause errors downstream.
- **`UARTDownloadRequest.SetWhatToDownload` silently ignores non-`IUARTDownload` instances**: If `das` does not implement `IUARTDownload`, the method returns early without setting `WhatUARTToDownload` or logging.
- **`DownloadReport.EventInfo` copy constructor performs shallow copy**: `Modules = copy.Modules` copies the array reference, not the elements. Modifying the array or its contents via one instance affects the other.
- **`DownloadReport.SetEventInfo` serializes `Modules` to XML**: If any `IDASModule.WriteXml` implementation is buggy or writes invalid XML, the entire operation fails and is logged. No partial persistence occurs.
- **`DownloadRequest.SetWhatToDownload` logs only when `request` is non-null**: If `request` is `null`, no log entry is made, even though `das.WhatToDownload` is set to `null`.
- **`DownloadReport.UARTEventInfo.BaudRate` is `uint`, but `UARTDownloadRequest.BaudRate` is `int`**: Mismatched types may require conversion when copying data between them.
- **DB operations are all-or-nothing per call**: Each `SetEvent*` method clears *all* existing DB records for its respective field before inserting new ones. This is not incremental and may cause data loss if called with incomplete arrays.
- **`DownloadReport.SetEventDownloadStatus`, `SetEventArmAttempts`, `SetEventFaultFlags`, `SetEventGuids` do not validate array length**: Passing an array of incorrect length (e.g., mismatched with number of events) may cause DB inconsistencies or downstream errors.

83
enriched-qwen3-coder-next/DataPRO/IService/Classes/InputRangeAttributes.md Normal file
View File

@@ -0,0 +1,83 @@
---
source_files:
- DataPRO/IService/Classes/InputRangeAttributes/GainDisabledAttribute.cs
- DataPRO/IService/Classes/InputRangeAttributes/MaxInputRangeAttribute.cs
- DataPRO/IService/Classes/InputRangeAttributes/GainAvailableUnmodifiedAttribute.cs
- DataPRO/IService/Classes/InputRangeAttributes/MinInputRangeAttribute.cs
- DataPRO/IService/Classes/InputRangeAttributes/FirmwareInputRangeAttribute.cs
generated_at: "2026-04-16T03:57:34.431495+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "9e76f2c3f64de0c9"
---
# InputRangeAttributes
## Documentation: Input Range Attribute Classes
### 1. Purpose
This module defines a set of custom attribute classes used to annotate gain enumerations (likely in an input range configuration system) with metadata that controls gain behavior, availability, and interface constraints. Specifically, it enables fine-grained control over gain disablement, maximum/minimum input ranges (in mV), firmware-specific input ranges, and availability for unmodified hardware variants (e.g., Gen 3 SPS). These attributes are applied at compile-time via reflection and queried at runtime to enforce system-level constraints without hardcoding logic, supporting flexibility for calibration, hardware variants, and future tuning.
### 2. Public Interface
All classes reside in the `DTS.DASLib.Service` namespace and derive from `System.Attribute`. Each provides a static method to query the attribute value from an enum field (passed as `object`), and a constructor to set the attribute’s value.
- **`GainDisabledAttribute`**
- `GainDisabledAttribute(bool disabled)`
Constructor. Sets `_bDisabled` to the provided value.
- `static bool IsGainDisabled(object o)`
Returns `true` if `o` is non-null, represents a valid enum field, and that field has a `GainDisabledAttribute` with `_bDisabled == true`. Returns `false` otherwise (including for `null`, missing members, or missing attribute).
- **`MaxInputRangeAttribute`**
- `MaxInputRangeAttribute(double maxInputRangemV)`
Constructor. Sets `_maximumInputRangemV` to the provided value (in mV).
- `static double GetMaxInputRangemV(object o)`
Returns `_maximumInputRangemV` if `o` is non-null, represents a valid enum field, and that field has a `MaxInputRangeAttribute`. Returns `0D` otherwise.
- **`GainAvailableUnmodifiedAttribute`**
- `GainAvailableUnmodifiedAttribute(bool available)`
Constructor. Sets `_bAvailable` to the provided value.
- `static bool IsGainAvailableToUnmodified(object o)`
Returns `false` only if `o` is non-null, represents a valid enum field, and that field has a `GainAvailableUnmodifiedAttribute` with `_bAvailable == false`. Returns `true` otherwise (including for `null`, missing members, or missing attribute).
- **`MinInputRangeAttribute`**
- `MinInputRangeAttribute(double minInputRangemV)`
Constructor. Sets `_minimumInputRangemV` to the provided value (in mV).
- `static double GetMinInputRangemV(object o)`
Returns `_minimumInputRangemV` if `o` is non-null, represents a valid enum field, and that field has a `MinInputRangeAttribute`. Returns `0D` otherwise.
- **`FirmwareInputRangeAttribute`**
- `FirmwareInputRangeAttribute(double firmwareInputRangemV)`
Constructor. Sets `_firmwareInputRangeAttribute` to the provided value (in mV).
- `static double GetFirmwareInputRangemV(object o)`
Returns `_firmwareInputRangeAttribute` if `o` is non-null, represents a valid enum field, and that field has a `FirmwareInputRangeAttribute`. Returns `0D` otherwise.
### 3. Invariants
- All attributes are **optional** by design: if an enum field lacks a given attribute, default values apply (e.g., `IsGainDisabled` → `false`, `IsGainAvailableToUnmodified` → `true`, range getters → `0D`).
- The static query methods assume the input `o` is an **enum value** (or `null`). They use `o.ToString()` to look up the corresponding `MemberInfo` via reflection (`GetMember(o.ToString())`).
- Attribute values are **immutable** after construction (`_bDisabled`, `_maximumInputRangemV`, etc. are `readonly`).
- Range values are interpreted as **millivolts (mV)**.
- The `FirmwareInputRangeAttribute` is intended to represent a *firmware-selectable* range, possibly derived from neighboring gain steps (e.g., midpoint between adjacent gains), to avoid unintended gain-step changes during operation.
### 4. Dependencies
- **Dependencies**:
- `System` (for `Attribute`, `Type`, reflection APIs).
- Implicit dependency on the *enum type(s)* that these attributes annotate (e.g., `InputRangeGain` or similar). These attributes are meaningless without such enums.
- **Depended upon by**:
- Unknown from source alone. Likely used by input configuration, calibration, or firmware interface modules that inspect gain enums at runtime via reflection (e.g., to determine valid ranges or skip disabled gains).
- All attributes reference the same FogBugz ticket (`10080`), suggesting a shared context (likely gain/range configuration for a specific hardware platform).
### 5. Gotchas
- **Reflection-based lookup is fragile**:
- `GetMember(o.ToString())` assumes the enum field name matches `ToString()`. If the enum uses `Display` attributes or custom `ToString()` overrides, this may fail or return incorrect members.
- If `o.ToString()` returns a non-field name (e.g., due to `Flags` enum formatting like `"A, B"`), `GetMember` may return an empty array → default values.
- **`FirmwareInputRangeAttribute` field name typo**:
- The private field is named `_firmwareInputRangeAttribute` (note: *Attribute* suffix), while the property/constructor parameter uses `firmwareInputRangemV`. This is likely a typo but is preserved as-is in the source.
- **No validation of range values**:
- No checks ensure `MinInputRangeAttribute` ≤ `MaxInputRangeAttribute`, or that `FirmwareInputRangeAttribute` lies between them. Consumers must enforce this.
- **`0D` as sentinel value**:
- A return value of `0D` from range getters could mean either: (a) the attribute is absent, or (b) the attribute was explicitly set to `0`. Ambiguity may cause misinterpretation.
- **No documentation of enum usage**:
- The source files do not show *how* these attributes are applied (e.g., `public enum Gain { [GainDisabled(true)] High = 3 }`). Without concrete examples, it is unclear if attributes are applied to fields, values, or types.
- **No thread-safety guarantees**:
- Reflection calls (`GetMember`, `GetCustomAttribute`) are not inherently thread-safe in older .NET versions, though modern runtimes typically handle this robustly. Not explicitly documented.
- **None identified from source alone.**

73
enriched-qwen3-coder-next/DataPRO/IService/Classes/PowerProInput.md Normal file
View File

@@ -0,0 +1,73 @@
---
source_files:
- DataPRO/IService/Classes/PowerProInput/SLICE.PowerPro.Input.Reader.cs
generated_at: "2026-04-16T03:57:12.321531+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "155f476d57ed5515"
---
# PowerProInput
## 1. Purpose
This module provides a concrete implementation of `SLICEBaseInputReader` for reading diagnostic inputs from a PowerPro device via the SLICE DAS (Data Acquisition System) infrastructure. It enables retrieval of key power-related diagnostic metrics—specifically input voltage, device temperature, and direct backup (battery) voltage—by executing synchronous measurements using the `MeasurePowerProDiagnosticChannel` command class. Its role is to abstract low-level communication details and expose standardized, type-safe properties for downstream system components (e.g., monitoring, diagnostics, or control logic) to consume real-time PowerPro hardware state.
---
## 2. Public Interface
### `SLICEPowerProInputReader(ICommunication comm)`
- **Type**: Constructor
- **Behavior**: Initializes a new instance with the specified `ICommunication` interface (`_comm`) used for hardware interaction. Delegates to the base class constructor with the same `comm` instance.
### `override double InputMilliVolts { get; }`
- **Type**: Read-only property
- **Behavior**: Returns the PowerPro input voltage in millivolts. Internally creates a `MeasurePowerProDiagnosticChannel` instance, configures it to read `InputVoltage_A` on device group `0`, device ID `0`, executes a synchronous measurement, and returns `Measurement * 1000.0`.
### `override double TemperatureC { get; }`
- **Type**: Read-only property
- **Behavior**: Returns the PowerPro internal temperature in degrees Celsius. Internally creates a `MeasurePowerProDiagnosticChannel`, sets `Channel` to `TemperatureC`, configures device group and ID to `0`, executes a synchronous measurement, and returns `Measurement` directly.
### `override double DirectBackupMilliVolts { get; }`
- **Type**: Read-only property
- **Behavior**: Returns the direct backup (battery) voltage in millivolts. Internally creates a `MeasurePowerProDiagnosticChannel`, sets `Channel` to `BatteryVoltage`, configures device group and ID to `0`, executes a synchronous measurement, and returns `Measurement * 1000.0`.
> **Note**: All three properties override abstract members defined in the base class `SLICEBaseInputReader`. Each property performs a *synchronous* hardware read on every access.
---
## 3. Invariants
- **Device targeting**: All measurements are hard-coded to `DeviceGroup = 0` and `DeviceID = 0`. No support for multi-device or configurable addressing is present.
- **Unit consistency**:
- `InputMilliVolts` and `DirectBackupMilliVolts` are returned in **millivolts** (i.e., `Measurement * 1000.0`).
- `TemperatureC` is returned in **degrees Celsius** (i.e., raw `Measurement` value).
- **Synchronous execution**: Every property getter performs a blocking `SyncExecute()` call; no async or buffered reads are used.
- **Channel mapping**: Only three specific diagnostic channels are supported: `InputVoltage_A`, `TemperatureC`, and `BatteryVoltage`. Other channels in `PowerProDiagnosticChannelList` are not exposed via this class.
---
## 4. Dependencies
### Dependencies *on* this module:
- `SLICEBaseInputReader` (base class) — defines the abstract properties (`InputMilliVolts`, `TemperatureC`, `DirectBackupMilliVolts`) implemented here.
- `ICommunication` — injected dependency for low-level hardware communication.
- `MeasurePowerProDiagnosticChannel` — concrete command class from `DTS.DASLib.Command.SLICE` used to perform synchronous measurements.
### Dependencies *of* this module:
- **External libraries**:
- `DTS.Common.Interface.DASFactory` (for `ICommunication`)
- `DTS.DASLib.Command.SLICE` (for `MeasurePowerProDiagnosticChannel`)
- **Inferred callers**: Likely consumed by higher-level services (e.g., monitoring daemons, status reporters) that inherit from or use `SLICEBaseInputReader` polymorphically.
---
## 5. Gotchas
- **Repeated hardware calls per property access**: Each property read triggers a *new* `MeasurePowerProDiagnosticChannel` instance and a full `SyncExecute()` round-trip to the device. This may cause performance issues if properties are accessed frequently (e.g., in tight loops or high-frequency telemetry). Caching is not implemented.
- **Hard-coded device addressing**: All reads target `DeviceGroup = 0`, `DeviceID = 0`. If the PowerPro system supports multiple devices, this class cannot be used without modification.
- **No error handling visible**: The source does not show explicit exception handling (e.g., for communication failures, invalid measurements). Failures in `SyncExecute()` or invalid `measure.Measurement` values may propagate unhandled exceptions.
- **Unit ambiguity in base `Measurement`**: The raw `measure.Measurement` value’s unit (e.g., volts, °C) is assumed by context but not enforced by this class. Incorrect assumptions about the underlying `MeasurePowerProDiagnosticChannel`’s output units could lead to incorrect scaling.
- **No thread-safety guarantees**: Since each property creates a new `MeasurePowerProDiagnosticChannel` and calls `SyncExecute()` on `_comm`, concurrent access to multiple properties *may* be safe *if* `_comm` is thread-safe, but this is not documented or verified in the source.
> **None identified from source alone.** *(Note: The above gotchas are inferred from observed patterns in the code, not explicit warnings.)*

216
enriched-qwen3-coder-next/DataPRO/IService/Classes/SLICE.md Normal file
View File

@@ -0,0 +1,216 @@
---
source_files:
- DataPRO/IService/Classes/SLICE/DASConfigurationEventArg.cs
- DataPRO/IService/Classes/SLICE/SLICE6DB3.cs
- DataPRO/IService/Classes/SLICE/S6DBConnectedDevice.cs
- DataPRO/IService/Classes/SLICE/SLICEPRODB.cs
- DataPRO/IService/Classes/SLICE/SLICE6AIRBR.cs
- DataPRO/IService/Classes/SLICE/SLICE6AIRTC.cs
generated_at: "2026-04-16T03:58:03.811712+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "4572c24a2832d452"
---
# SLICE
**Documentation Page: SLICE DAS Device Implementations and Configuration Events**
---
### 1. Purpose
This module provides concrete implementations of DAS (Data Acquisition System) device types for the SLICE family (SLICE6DB3, SLICEPRODB, SLICE6AIRBR, SLICE6AIRTC), each tailored to specific hardware capabilities and protocol support levels. It also defines `DASConfigurationArg`, a data carrier for the `DASConfigurationEvent`, enabling consumers to react to configuration read outcomes (e.g., blank configs, validation failures). These classes implement core DAS functionality—configuration, diagnostics, clock synchronization, and real-time streaming—while accounting for hardware-specific limitations and protocol versioning. The module serves as the runtime bridge between high-level service logic and low-level device communication, ensuring correct behavior per device variant.
---
### 2. Public Interface
#### `DASConfigurationArg`
- **Namespace**: `DTS.DASLib.Service`
- **Implements**: `IDASConfigurationArg`
- **Purpose**: Encapsulates state passed during a `DASConfigurationEvent`.
| Member | Type | Description |
|--------|------|-------------|
| `DAS` | `IDASCommunication` | The DAS instance whose configuration event occurred. Read-only. |
| `BlankConfigurationRead` | `bool` | `true` if the configuration loaded from disk was blank (e.g., empty filestore). Read-only. |
| `ConfigurationFailedValidation` | `bool` | `true` if the loaded configuration failed validation. Read-only. |
| **Constructor** | `DASConfigurationArg(IDASCommunication das, bool blankRead, bool failedValidation)` | Initializes the event args with the given state. |
#### `SLICE6DB3<T>`
- **Namespace**: `DTS.DASLib.Service`
- **Inherits**: `SLICE6DB<T>`
- **Constraints**: `T : IConnection, new()`
- **Purpose**: A limited SLICE6DB variant without PTP/IEEE 1588 support.
| Member | Type | Description |
|--------|------|-------------|
| `SetClockSyncConfig(ServiceCallback callback, object userData, ClockSyncProfile profile)` | `override void` | No-op; returns success immediately. Clock sync not supported. |
| `GetClockSyncStatus(ServiceCallback callback, object userData)` | `override void` | No-op; returns success immediately. |
| `SetPTPDomainID(ServiceCallback callback, object userData, byte domainID)` | `override void` | No-op; returns success immediately. PTP not supported. |
| `GetPTPDomainID(ServiceCallback callback, object userData)` | `override void` | No-op; returns success immediately. |
#### `S6DBConnectedDevice`
- **Namespace**: `DTS.DASLib.Service.Classes.SLICE`
- **Implements**: `IDASConnectedDevice`
- **Purpose**: Represents a device discovered on a SLICE6DB via `QAUTIL_QUERY_MAC_IP_TABLE`.
| Member | Type | Description |
|--------|------|-------------|
| `DeviceType` | `HardwareTypes` | Default `HardwareTypes.SLICE6_Base`; set to `HardwareTypes.SLICE6_AIR` if `SerialNumber` starts with `"S6A"`. Read-only. |
| `Port` | `int` | 0-based port index. Valid only if ≥ 0. Default `-1`. |
| `SpotOnPort` | `int` | 0-based position on the port/chain. Valid only if ≥ 0. Default `-1`. |
| `PhysicalAddress` | `PhysicalAddress` | MAC address of the device. |
| `IPAddress` | `string` | IP address reported by device. Default `""`. |
| `SerialNumber` | `string` | Device serial number. Default `""`. |
| `Location` | `string` | Device location string. Default `""`. |
| `Version` | `string` | Device firmware version. Default `""`. |
| **Constructor** | `S6DBConnectedDevice(int port, int spotOnPort, PhysicalAddress physicalAddress, string ipAddress, string serialNumber, string location, string version)` | Initializes all fields; updates `DeviceType` if `SerialNumber` starts with `"S6A"`. |
#### `SLICEPRODB<T>`
- **Namespace**: `DTS.DASLib.Service`
- **Inherits**: `SLICE6DB<T>`, implements `IDownloadActions`
- **Constraints**: `T : IConnection, new()`
- **Purpose**: SLICEPRO DB variant with limited protocol support (e.g., no MAC table query, no PTP).
| Member | Type | Description |
|--------|------|-------------|
| `QueryConnectedDevices()` | `override void` | No-op; sets `ConnectedDevices` to an empty array. |
| `IsSlice6Distributor()` | `override bool` | Returns `false`. |
| `IsBattery()` | `override bool` | Returns `true` (comment: “um maybe?”). |
| `SupportsTimeSynchronization` | `override bool` | Returns `false`. |
| `SupportsTemperatureCheck` | `protected override bool` | Returns `true`. |
| `SupportsTiltCheck` | `protected override bool` | Returns `true`. |
| `SupportsClockSyncCheck` | `protected override bool` | Returns `true`. |
| `InitMinProto()` | `override void` | Populates `MinimumProtocols` dictionary with protocol version requirements. Key commands with `byte.MaxValue` are unsupported (e.g., `PTPSyncStatus`, `SetClockSyncConfig`, `QueryEthernetMacTable`). |
| `MinimumProtocols` | `Dictionary<ProtocolLimitedCommands, byte>` | Inherited from base; set in `InitMinProto()`. |
#### `SLICE6AIRBR<T>`
- **Namespace**: `DTS.DASLib.Service`
- **Inherits**: `SLICE6_Base<T>`, implements `IAlignUDPToPPSAware`
- **Constraints**: `T : IConnection, new()`
- **Purpose**: SLICE6 AIR BR variant with PTP, UDP alignment, and full feature set.
| Member | Type | Description |
|--------|------|-------------|
| `AlignUDPToPPS` | `bool` | Property to configure UDP alignment to PPS. |
| `SupportsRemoveLeapSeconds` | `override bool` | Returns `true`. |
| `SupportsADCSamplesPerPacket` | `override bool` | Returns `true`. |
| `RequiresNon0QualificationSamples` | `protected override bool` | Returns `true`. |
| `GetRTChannelIndices(RealTimeAsyncPacket packet)` | `override byte[]` | Returns channel indices `[0x00..0x05]` (6 channels). |
| `SetIsStreamingSupported(bool)` | `override void` | Sets `IsStreamingSupported = true`. |
| `DASIndex` | `int` | Device order among multiple DAS units. Default `-1`. |
| `InitMinProto()` | `override void` | Populates `SLICE6AIR_BR_MinimumProtocols` dictionary. Includes protocol versions for `UDPAlignOnPPS` (`UDPALIGNONPPS_PROTOCOL`) and `ADCSamplesPerPacket` (`ADC_SAMPLES_PER_PACKET_VER`). |
| `MaxSampleRateHz` | `protected override uint` | Queries `MaximumSampleRate` system attribute; returns `50000` on error. |
| `MakeConfigModuleFromInfoModule(InfoResult.Module)` | `override DASModule` | Creates `DASModule` with `AnalogInputDASChannel` (full/half bridge support) or `StreamOutputDASChannel`. |
| `AsyncConfigure(object)` | `override void` | Full configuration flow: sets UDP/PPS, leap seconds, ADC samples/packet, resets event list, configures modules, stores attributes, and calls `RemainingConfigWork`. |
| `GetIsStreaming()` | `override bool` | Returns `true` if `DASArmStatus.ReceivedInvalidModeDuringSetup` or `DASArmStatus.IsInRealtime`. |
#### `SLICE6AIRTC<T>`
- **Namespace**: `DTS.DASLib.Service`
- **Inherits**: `SLICE6_Base<T>`, implements `IAlignUDPToPPSAware`, `IDASReconfigure`, `ITCDiagnosticResults`, `IUARTDownloadActions`, `IUARTDownload`
- **Constraints**: `T : IConnection, new()`
- **Purpose**: SLICE6 AIR TC variant with thermocouple diagnostics, UART support, and PTP.
| Member | Type | Description |
|--------|------|-------------|
| `WhatUARTToDownload` | `IUARTDownloadRequest` | Request object for UART event download. |
| `SetWhatUARTToDownload(IUARTDownloadRequest, bool)` | `void` | Delegates to `UARTDownloadRequest.SetWhatToDownload`. |
| `BaudRate`, `DataBits`, `StopBits`, `Parity`, `FlowControl` | `uint` / `StopBits` / `Parity` / `Handshake` | UART settings. Populated by `AsyncGetUARTSettings`. |
| `UARTDownload(ServiceCallback, object)` | `void` | Returns `"Not supported"` error. |
| `QueryUARTDownload(ServiceCallback, object, int, TDASServiceSetupInfo)` | `void` | Launches `AsyncQueryUARTDownload`. |
| `AsyncQueryUARTDownload(object)` | `protected virtual void` | Checks `IsCommandSupported(ProtocolLimitedCommands.QueryUARTDownload)`; errors if unsupported. |
| `GetUARTSettings(ServiceCallback, object)` | `void` | Launches `AsyncGetUARTSettings`. |
| `AsyncGetUARTSettings(object)` | `protected virtual void` | Queries `S6A_GpsCanUARTSettings` system attribute; populates UART fields. Handles retries (`PERMITTED_FAILURES`). |
| `SetUARTSettings(ServiceCallback, object, uint, uint, uint, uint, uint)` | `void` | Launches `AsyncSetUARTSettings`. |
| `AsyncSetUARTSettings(object)` | `protected virtual void` | Sets `S6A_GpsCanUARTSettings` system attribute. |
| `TCDiagnosticResults` | `ITCDiagnosticResult[]` | Array of thermocouple diagnostic results. |
| `ClearTCDiagnosticResults()` | `void` | Resets `TCDiagnosticResults` to empty array. |
| `SetTCDiagnosticResults(ITCDiagnosticResult[])` | `void` | Sets `TCDiagnosticResults`. |
| `InitializeTCDiagnostics()` | `private void` | Allocates 24 `TCDiagnosticResult` entries, one per channel. |
| `AsyncDiagnosAndGetResults(object)` | `override void` | Initializes diagnostics, then calls `MeasureOffsets` and `MeasureShunts`. |
| `MeasureShunts(SliceServiceAsyncInfo)` | `private bool` | Queries `QueryChannelShuntResults`; sets `ConnectionStatus` based on deflection values (`0` → `ModuleNotConnected`, `100` → `Connected`). |
| `MeasureOffsets(SliceServiceAsyncInfo)` | `private bool` | Queries `RetrieveSampleAverage` (4000 samples); sets `CurrentReading` (scaled by `0.1`). |
| `GetChannelName(int)` | `private string` | Returns `UserChannelName` or `IsoChannelName` for given channel index. |
| `IsSlice6AirTc()` | `override bool` | Returns `true`. |
| `GetMaxFileLengthTMATS()` | `override int` | Returns `MAX_TMATS_FILE_LENGTH` (32000). |
| `AlignUDPToPPS` | `bool` | Property to configure UDP alignment to PPS. |
| `SupportsRemoveLeapSeconds` | `override bool` | Returns `true`. |
| `SupportsADCSamplesPerPacket` | `override bool` | Returns `true`. |
| `RequiresNon0QualificationSamples` | `protected override bool` | Returns `true`. |
| `GetRTChannelIndices(RealTimeAsyncPacket)` | `override byte[]` | Returns channel indices based on `_maxModuleCount`: 8, 16, or 24 channels. |
| `GetRealtimeSamplesClass(ICommunication, bool)` | `override IGetRealtimeSamples` | Returns `RealtimeStreamingNextSamples` (signed data) if streaming supported. |
| `SetIsStreamingSupported(bool)` | `override void` | Sets `IsStreamingSupported = true`. |
| `InitMinProto()` | `override void` | Populates `SLICE6AIR_TC_MinimumProtocols` dictionary. Includes `GetUARTSettings`, `SetUARTSettings`, `AutoArmUDPSetting`. |
| `GetConfigAttributes(ICommunication)` | `override ConfigAttributes` | Returns `S6ATCConfigAttributes` (bridge/AC-coupling NOOPs). |
| `MakeConfigModuleFromInfoModule(InfoResult.Module)` | `override DASModule` | Creates `DASModule` with `AnalogInputDASChannel`, `StreamOutputDASChannel`, or `UARTInputDASChannel`. |
| `AsyncConfigure(object)` | `override void` | Similar to `SLICE6AIRBR`, but includes `numUart` in `StoreConfigAttributes`. |
| `GetIsStreaming()` | `override bool` | Same logic as `SLICE6AIRBR`. |
| `GetStackChannelConfigTypes()` | `override int[]` | Queries `StackChannelConfigType` attribute; returns array of channel types or `[0]` on error. |
---
### 3. Invariants
- **`DASConfigurationArg`**:
- `BlankConfigurationRead` and `ConfigurationFailedValidation` are mutually independent; both may be `true` or `false`.
- `DAS` is non-null at construction (enforced by caller).
- **`S6DBConnectedDevice`**:
- `Port` and `SpotOnPort` are valid only when ≥ 0. Negative values indicate uninitialized state.
- `DeviceType` is derived solely from `SerialNumber.StartsWith("S6A")`; no other logic modifies it.
- **`SLICE6DB3<T>`**:
- All clock sync and PTP methods are no-ops; they never query the device or throw exceptions.
- `SupportsTimeSynchronization` is always `false`.
- **`SLICEPRODB<T>`**:
- `QueryConnectedDevices()` always sets `ConnectedDevices` to an empty array.
- `IsSlice6Distributor()` is always `false`.
- `IsBattery()` is hardcoded to `true`.
- Protocol commands with `byte.MaxValue` in `MinimumProtocols` are unsupported and must not be invoked.
- **`SLICE6AIRBR<T>` / `SLICE6AIRTC<T>`**:
- `GetIsStreaming()` relies on `DASArmStatus` flags (`ReceivedInvalidModeDuringSetup`, `IsInRealtime`); returns `false` if `DASArmStatus` is `null`.
- `MaxSampleRateHz` caches the value after first query; errors default to `50000`.
- `GetRTChannelIndices()` returns channel indices based on `_maxModuleCount` (0 → 8, 1 → 16, ≥2 → 24).
- `AsyncConfigure` always calls `ResetEventListPriorToConfigure()` before configuration.
---
### 4. Dependencies
#### Imports/Usings
- **Common Infrastructure**:
- `DTS.Common.Interface.DASFactory` (`IDASCommunication`, `IDASConfigurationArg`, `DASModule`, `DASChannel`, `DASInfo`, etc.)
- `DTS.Common.Interface.Connection` (`IConnection`)
- `DTS.Common.Interface.Communication` (`ICommunication`)
- `DTS.Common.Enums.Hardware` (`HardwareTypes`)
- `DTS.Common.Enums.Sensors` (`SensorConstants.BridgeType`)
- `DTS.Common.Constant.DASSpecific` (e.g., `AttributeTypes`, `DFConstantsAndEnums`)
- `DTS.Common.Utilities.Logging` (`APILogger`)
- `DTS.DASLib.Command.SLICE` (e.g., `QuerySystemAttributeSLICE6`, `SetSystemAttributeSLICE6AIR`, `RetrieveSampleAverage`, `QueryChannelShuntResults`)
#### Inheritance Hierarchy
- `SLICE6DB3<T>`, `SLICEPRODB<T>`, `SLICE6AIRBR<T>`, `SLICE6AIRTC<T>` all inherit from `SLICE6DB<T>` or `SLICE6_Base<T>`.
- `SLICE6_Base<T>` likely inherits from a base `DAS` class implementing `IDASCommunication`.
#### Usage Inferred From Source
- `SLICE6AIRBR<T>` and `SLICE6AIRTC<T>` are used for devices requiring advanced features (PTP, UDP alignment, thermocouple diagnostics).
- `SLICE6DB3<T>` is used for devices without PTP.
- `SLICEPRODB<T>` is used for battery-powered or simplified units.
- `S6DBConnectedDevice` is populated by `QueryConnectedDevices()` in other classes (e.g., `SLICE6DB` base), though `SLICEPRODB` overrides it to do nothing.
---
### 5. Gotchas
- **`SLICEPRODB<T>.IsBattery()`**: Comment `//um maybe?` suggests uncertainty or incomplete validation. Verify behavior with hardware team.
- **`SLICE6DB3<T>` Clock Sync Methods**: All clock sync/PTP methods are no-ops and silently succeed. Calling code must not assume actual configuration occurred.
- **`S6DBConnectedDevice.DeviceType`**: Only updates to `SLICE6_AIR` if `SerialNumber.StartsWith("S6A")`; no other device type detection logic exists.
- **`SLICE6AIRBR<T>.GetRTChannelIndices()`**: Returns only 6 channels (`0x00..0x05`), regardless of `_maxModuleCount`. This may be intentional for BR variant.
- **`SLICE6AIRTC<T>.AsyncConfigure()`**: Includes `numUart` in `StoreConfigAttributes`, but `MakeConfigModuleFromInfoModule` creates `UARTInputDASChannel` only if `ModuleType.UART == configModule.ModuleType()`. Ensure `InfoResult.Module.TypeOfModule` is correctly set.
- **`SLICE6AIRTC<T>.UARTDownload()`**: Explicitly returns `"Not supported"`; callers must check `WhatUARTToDownload` and use `QueryUARTDownload`/`GetUARTSettings` instead.
- **`SLICE6AIRBR<T>`/`SLICE6AIRTC<T>` `MaxSampleRateHz`**: Caching may cause stale values if firmware changes dynamically. Re-query may be needed on reconnection.
- **Protocol Versioning**: Commands with

110
enriched-qwen3-coder-next/DataPRO/IService/Classes/SLICEService.md Normal file
View File

@@ -0,0 +1,110 @@
---
source_files:
- DataPRO/IService/Classes/SLICEService/SLICE Service.TriggerCheck.cs
- DataPRO/IService/Classes/SLICEService/SLICE Service.cs
- DataPRO/IService/Classes/SLICEService/SLICE Service.Public.cs
generated_at: "2026-04-16T03:59:44.857737+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "358379cedd1a8fff"
---
# Documentation: `Slice<T>` Trigger Check Module
## 1. Purpose
This module implements the trigger check functionality for the `Slice<T>` DAS (Data Acquisition System) service class, providing asynchronous and synchronous methods to prepare, execute, and cancel hardware-level trigger and start-record integrity checks. It validates hardware input line states (e.g., short circuits on trigger/start inputs) before arming the system, and supports configurable polarity inversion for trigger and start signals. The module ensures safe pre-arm conditions by querying hardware via `InitializeHardwareLines` and reporting status via `ArmStatus`, while integrating with the broader `Slice<T>` service infrastructure for async callbacks and state management.
## 2. Public Interface
The interface is implemented explicitly via `ITriggerCheckActions`. All methods follow an async pattern using `LaunchAsyncWorker` and `SliceServiceAsyncInfo` for callback reporting.
### `void ITriggerCheckActions.PreStartTriggerCheck(ServiceCallback callback, object userData)`
- **Behavior**: Performs pre-startup configuration before trigger checks. If supported, sets `StartRecordPolarity` and `TriggerPolarity` attributes based on `InvertStart` and `InvertTrigger` properties using `SetSystemAttribute`. Logs exceptions but does not fail the operation on error.
- **Async worker**: `AsyncPreStartTriggerCheck`
### `void ITriggerCheckActions.PostStartTriggerCheck(ServiceCallback callback, object userData)`
- **Behavior**: No-op placeholder; immediately reports success. Presumably reserved for future or subclass use.
### `void ITriggerCheckActions.StartTriggerCheck(ServiceCallback callback, object userData)`
- **Behavior**: Initiates the main trigger check sequence. Executes `AsyncStartTriggerCheck`, which:
- Runs `InitializeHardwareLines` (if supported).
- Checks for `TriggerInputShorted` or `StartRecordShorted` conditions; reports specific errors if detected.
- Handles `CanceledException` and other exceptions via `info.Error`/`info.Cancel`.
- **Async worker**: `AsyncStartTriggerCheck`
### `void ITriggerCheckActions.DoStartCheck(ServiceCallback callback, object userData)`
- **Behavior**: Performs a *start-record-only* check. Executes `AsyncDoStartCheck`, which:
- Queries hardware via `InitializeHardwareLines`.
- Sets `ArmStatus.IsArmed = !ihl.TriggerInputShorted`
- Sets `ArmStatus.IsRecording = ihl.StartRecordShorted`
- Calls `SetDASArmStatus(status, true)` to persist status.
- **Async worker**: `AsyncDoStartCheck`
### `void ITriggerCheckActions.DoTriggerCheck(ServiceCallback callback, object userData)`
- **Behavior**: Performs a *full trigger check*. Executes `AsyncDoTriggerCheck`, which internally calls `DoTriggerCheckSync()`. Reports success/failure/cancel via `SliceServiceAsyncInfo`.
### `void ITriggerCheckActions.DoTriggerCheckSync()`
- **Behavior**: Synchronous variant of `DoTriggerCheck`. Directly queries hardware via `InitializeHardwareLines` (no async wrapper), constructs an `ArmStatus` object with:
- `IsTriggered = ihl.TriggerInputShorted`
- `IsArmed = !ihl.TriggerInputShorted`
- `IsTriggerShorted = ihl.TriggerInputShorted`
- `IsStartShorted = ihl.StartRecordShorted`
- Calls `SetDASArmStatus(status, true)` to update internal and persistent state.
### `void ITriggerCheckActions.CancelTriggerCheck(ServiceCallback callback, object userData)`
- **Behavior**: Cancels any pending trigger check. Currently a no-op; reports success immediately via `AsyncCancelTriggerCheck`.
### Supporting Types (from `Slice<T>` base class)
#### `protected virtual void AsyncPreStartTriggerCheck(object asyncInfo)`
- Actual worker method for `PreStartTriggerCheck`. Validates `asyncInfo` is `SliceServiceAsyncInfo`, configures polarity attributes if supported, logs exceptions, and calls `info.Success()`.
#### `protected virtual void AsyncStartTriggerCheck(object asyncInfo)`
- Actual worker for `StartTriggerCheck`. Executes `InitializeHardwareLines`, checks for shorted inputs, and reports errors (`"TriggerInputShorted"`, `"StartInputShorted"`) or success.
#### `private void AsyncDoTriggerCheck(object asyncInfo)`
- Wraps `DoTriggerCheckSync()` in async callback handling.
#### `private void AsyncDoStartCheck(object asyncInfo)`
- Wraps synchronous start-check logic in async callback handling.
#### `private void AsyncCancelTriggerCheck(object asyncInfo)`
- Wraps no-op cancellation logic.
## 3. Invariants
- **Hardware Query Dependency**: Trigger checks rely on `InitializeHardwareLines` command support. If `IsCommandSupported(DFConstantsAndEnums.ProtocolLimitedCommands.InitHardwareInputLines)` returns `false`, the check is skipped (no error), but shorted-line detection is bypassed.
- **Polarity Configuration**: `InvertStart` and `InvertTrigger` are only applied if `SupportsStartInversion()` and `SupportsTriggerInversion()` return `true`, respectively. Default implementations return `true`.
- **State Consistency**: After `DoTriggerCheckSync` or `DoStartCheck`, `SetDASArmStatus(status, true)` is called, ensuring `DASArmStatus` reflects current hardware state. `IsArmed` is always `!ihl.TriggerInputShorted`.
- **Error Reporting**: Shorted inputs (`TriggerInputShorted`, `StartRecordShorted`) result in immediate `info.Error()` with a literal string message; no exception is thrown.
- **Callback Safety**: All async workers wrap callback invocations in `try/catch` blocks to prevent unhandled exceptions from crashing the worker thread.
## 4. Dependencies
### Dependencies *on*:
- `DTS.DASLib.Command.SLICE.InitializeHardwareLines` — for querying hardware input line states.
- `DTS.DASLib.Command.SLICE.SetSystemAttribute` — for polarity configuration.
- `DTS.Common.Interface.DASFactory.IArmStatusData` and `ArmStatus` — for status reporting.
- `DTS.Common.Interface.Connection.IConnection` (via `Communication<T>`) — for transport.
- `DTS.Common.Enums.DASFactory.DFConstantsAndEnums.ProtocolLimitedCommands` — to check command support.
- `DTS.Common.Interface.DASFactory.IDASCommunication` — base interface.
- `DTS.Common.Utilities.Logging.APILogger` — for error logging.
- `SliceServiceAsyncInfo` — for async callback handling.
### Dependencies *of*:
- This module is used by higher-level arming workflows (e.g., `IArmActions`, `IRealTimeActions`) to ensure safe pre-arm conditions.
- Subclasses (`WinUSBSlice6Air`, `EthernetTsrAir`, etc.) inherit this behavior unless overridden.
## 5. Gotchas
- **`DoTriggerCheckSync` is synchronous but used in async wrappers**: `DoTriggerCheckSync()` performs blocking I/O; its async wrappers (`AsyncDoTriggerCheck`) do not offload the actual hardware query — only the callback dispatch. This may cause UI thread blocking if invoked on the UI thread.
- **No cancellation support in hardware checks**: `AsyncStartTriggerCheck` and `AsyncDoStartCheck` catch `CanceledException`, but there is no mechanism to *cancel* a pending `InitializeHardwareLines.SyncExecute()` call — cancellation only affects post-query callback dispatch.
- **Polarity inversion is hardware-dependent**: `SupportsStartInversion()` and `SupportsTriggerInversion()` are virtual and return `true` by default, but subclasses may override. If overridden to `false`, polarity settings are silently ignored.
- **`PostStartTriggerCheck` is a stub**: Its implementation does nothing; relying on it for post-check cleanup may be unsafe.
- **`DoStartCheck` conflates armed and recording states**: `IsArmed = !ihl.TriggerInputShorted`, but `IsRecording = ihl.StartRecordShorted`. This implies a device can be armed but *not* recording (e.g., trigger armed, start not yet pressed), which may be counterintuitive.
- **`TriggerResult` is public but not populated**: The `ITriggerCheckResult TriggerResult` property is declared but never set by this module — callers must interpret `DASArmStatus` instead.
- **No timeout configuration**: `SliceServiceAsyncInfo` has a `MaxTimeout` property, but it is never used or propagated to the underlying `SyncExecute()` calls — all hardware commands use fixed timeouts.
- **`InvertStart`/`InvertTrigger` defaults to `false`**: If not explicitly set, polarity remains non-inverted. No validation ensures these are set consistently with hardware wiring.
None identified beyond those above.

333
enriched-qwen3-coder-next/DataPRO/IService/Classes/TDAS Service.md Normal file
View File

@@ -0,0 +1,333 @@
---
source_files:
- DataPRO/IService/Classes/TDAS Service/TDAS Service.cs
- DataPRO/IService/Classes/TDAS Service/Public.cs
- DataPRO/IService/Classes/TDAS Service/TriggerCheck.cs
generated_at: "2026-04-16T03:58:51.683058+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "7b8b4e6a57d3d900"
---
# TDAS Service Module Documentation
## 1. Purpose
The `TDAS<T>` class is a core service implementation for the TDAS (Time-Domain Acquisition System) hardware family, providing a unified interface across multiple connection types (Ethernet, Serial) and hardware variants (G5, Rack, SIM, TOM, LabRack). It implements multiple interface contracts (`IDASCommunication`, `IConfigurationActions`, `IDiagnosticsActions`, `ITriggerCheckActions`, `IRealTimeActions`, `IArmActions`, `IDownloadActions`) to manage configuration, diagnostics, arming, triggering, real-time data streaming, and event downloading. The class acts as a bridge between high-level application logic and low-level hardware commands, encapsulating device-specific behavior (e.g., G5 vs. non-G5 modules) and maintaining runtime state (e.g., arming status, recording flags, diagnostic results). It inherits from `Communication<T>` and uses asynchronous workers via `ThreadPool.QueueUserWorkItem` for long-running operations, with callback-based progress and result reporting.
## 2. Public Interface
### Core Properties
- **`bool IsEthernetDistributor()`**
Returns `false`. Indicates this instance is not an Ethernet distributor.
- **`bool IsSlice6Distributor()`**
Returns `false`. Indicates this instance is not a Slice6 distributor.
- **`bool IsBattery()`**
Returns `false`. Indicates this instance is not a battery-powered device.
- **`bool IsTSRAIR()`**
Returns `false`. Indicates this instance is not a TSRAIR device.
- **`bool IsSlice6Air()`**
Returns `false`. Indicates this instance is not a Slice6 Air device.
- **`bool IsSlice6AirTc()`**
Returns `false`. Indicates this instance is not a Slice6 Air TC device.
- **`bool IsScheduleEventCountSupported()`**
Returns `false`. Schedule event counting is not supported.
- **`HardwareTypes GetHardwareType()`**
Determines hardware type based on `SerialNumber` prefix:
- `"5M"` → `G5INDUMMY` or `G5VDS` (depending on `G5Mode`)
- `"DR"` → `TDAS_Pro_Rack`
- `"SM"` → `SIM`
- `"TOM"` → `TOM`
- `"LR"` → `TDAS_LabRack`
- Otherwise → `TDAS_Pro_Rack` (fallback)
- **`string SerialNumber`** *(inherited from `ICommunication`, overridden)*
Device serial number used for identification and equality comparison.
- **`bool StartRecord`**
Gets/sets whether recording has been started (protected setter).
- **`float InputLowVoltage`, `InputMediumVoltage`, `InputHighVoltage`**
Input voltage thresholds.
- **`float BatteryLowVoltage`, `BatteryMediumVoltage`, `BatteryHighVoltage`**
Battery voltage thresholds.
- **`double MinimumValidInputVoltage`, `MaximumValidInputVoltage`**
Valid input voltage range.
- **`double MinimumValidBatteryVoltage`, `MaximumValidBatteryVoltage`**
Valid battery voltage range.
- **`bool CheckAAF(float rate)`**
Returns `true`. Anti-aliasing filter validation is not implemented for TDAS.
- **`ulong GetPhaseShiftSamples(uint ModuleIndex, double ActualSampleRate, uint HardwareAAF, ulong originalT0)`**
Returns `0`. Phase shift is not known for TDAS modules.
### Configuration
- **`IConfigurationData ConfigData { get; set; }`**
Holds configuration data for the device.
### Diagnostics
- **`IDiagnosticActions[] ChannelDiagnostics { get; set; }`**
Diagnostic actions per channel.
- **`void SetChannelDiagnosticActions(IDiagnosticActions[] actions, bool setInDb = true)`**
Sets channel diagnostic actions.
- **`IDiagnosticResult[] ChannelDiagnosticsResults { get; set; }`**
Diagnostic results per channel.
- **`void ClearChannelDiagnosticsResults(bool bClearDb = true)`**
Clears diagnostic results.
- **`void SetChannelDiagnosticsResults(IDiagnosticResult[] results, bool setInDb)`**
Sets diagnostic results.
- **`IBaseInputValues BaseInput { get; set; }`**
Base input values for diagnostics.
- **`IOptimizationValues OptimizationValues { get; set; }`**
Optimization values for diagnostics.
- **`IDictionary<InputClockSource, bool> DASClockSyncStatus { get; set; }`**
Clock synchronization status per source.
- **`bool ClockSyncInUTC { get; set; }`**
Whether clock sync uses UTC.
- **`ClockSyncProfile DASClockSyncProfile { get; set; }`**
Clock sync profile.
- **`byte PTPDomainID { get; set; }`**
PTP domain ID.
- **`IArmCheckActions ArmCheckActions { get; set; }`**
Arm check actions.
- **`IArmCheckResults ArmCheckResults { get; set; }`**
Arm check results.
### Trigger Check
- **`void ITriggerCheckActions.PreStartTriggerCheck(ServiceCallback callback, object userData)`**
No-op; immediately calls `callback` with success.
- **`void ITriggerCheckActions.PostStartTriggerCheck(ServiceCallback callback, object userData)`**
No-op; immediately calls `callback` with success.
- **`void ITriggerCheckActions.StartTriggerCheck(ServiceCallback callback, object userData)`**
Initiates trigger check asynchronously via `LaunchAsyncWorker`. Executes `AsyncStartTriggerCheck`.
- **`void ITriggerCheckActions.DoTriggerCheck(ServiceCallback callback, object userData)`**
Performs trigger check asynchronously via `LaunchAsyncWorker`. Executes `AsyncDoTriggerCheck`.
- **`void ITriggerCheckActions.DoStartCheck(ServiceCallback callback, object userData)`**
Performs start check asynchronously via `LaunchAsyncWorker`. Executes `AsyncDoStartCheck`.
- **`void ITriggerCheckActions.DoTriggerCheckSync()`**
Throws `NotImplementedException` with message: `"DoTriggerCheckSync is not implemented for TDAS"`.
- **`void ITriggerCheckActions.CancelTriggerCheck(ServiceCallback callback, object userData)`**
Cancels trigger check asynchronously via `LaunchAsyncWorker`. Executes `AsyncCancelTriggerCheck`.
### Arming
- **`bool GetIsInArm()`**
Returns `DASArmStatus?.IsArmed ?? false`.
- **`bool GetIsInRealtime()`**
Returns `DASArmStatus?.IsInRealtime ?? false`.
- **`bool GetIsStreaming()`**
Returns `false`. Does not query hardware; only returns a flag.
- **`void SetInArm(bool WriteToDb)`**
Sets `DASArmStatus.IsArmed = true`, optionally writes to DB.
- **`void SetInRealtime(bool WriteToDb, bool ExitRealtimeIfPossible)`**
Sets `DASArmStatus.IsInRealtime = true`, optionally writes to DB.
- **`IArmStatusData DASArmStatus { get; set; }`**
Current arming status.
- **`void SetDASArmStatus(IArmStatusData status, bool bSetInDb)`**
Sets arming status and optionally writes to DB.
- **`void SetDASArmStatus()`**
Sets current `DASArmStatus` to DB.
- **`DFConstantsAndEnums.CommandStatus AutoArmStatus { get; set; }`**
Status of auto-arming.
### Downloading
- **`IDownloadRequest WhatToDownload { get; set; }`**
Request specifying what to download.
- **`void SetWhatToDownload(IDownloadRequest request, bool bSetInDb = true)`**
Sets download request.
- **`IDownloadReport EventInfo { get; set; }`**
Event download report.
- **`void SetEventInfo(IDownloadReport eventInfo, bool bSetInDb = true)`**
Sets event info.
- **`bool[] EventDownloadedStatus { get; set; }`**
Download status per event.
- **`void SetEventDownloadStatus(bool[] status, bool storeInDb = true)`**
Sets event download status.
- **`Guid[] EventGuids { get; set; }`**
GUIDs for events.
- **`void SetEventGuids(Guid[] guids, bool storeInDb = true)`**
Sets event GUIDs.
- **`uint[] IDownload.ExtendedFaultFlags1 { get; set; }`**
Extended fault flags (explicit interface).
- **`uint[] IDownload.ExtendedFaultFlags2 { get; set; }`**
Extended fault flags (explicit interface).
- **`uint[] IDownload.ExtendedFaultFlags3 { get; set; }`**
Extended fault flags (explicit interface).
- **`uint[] IDownload.ExtendedFaultFlags4 { get; set; }`**
Extended fault flags (explicit interface).
- **`void IDownload.SetExtendedFaultFlags(uint[][] flags)`**
Sets extended fault flags.
- **`ushort[] FaultFlags { get; set; }`**
Fault flags.
- **`void SetEventFaultFlags(ushort[] flags, bool storeInDb = true)`**
Sets event fault flags.
- **`byte[] ArmAttempts { get; set; }`**
Arm attempt counts.
- **`void SetEventArmAttemps(byte[] armAttempts, bool storeInDb = true)`**
Sets event arm attempts.
### Information
- **`new IInfoResult DASInfo { get; set; }`**
Device information (hides inherited `ICommunication.DASInfo`).
- **`void SetDASInfo(IInfoResult dasInfo, bool bSetInDb = true)`**
Sets device info.
- **`void SetDASInfo()`**
Sets device info (no DB write).
### Utility
- **`int NumberOfConfiguredChannels()`**
Returns `ConfigData?.NumberOfConfiguredChannels() ?? 0`.
- **`int NumberOfChannels()`**
Returns `ConfigData?.NumberOfChannels() ?? 0`.
- **`int CompareTo(IDASCommunication das)`**
Compares `SerialNumber` lexicographically.
- **`bool DiagnosticsHasBeenRun { get; set; }`**
Whether diagnostics have been run.
- **`bool ConfigureHasBeenRun { get; set; }`**
Whether configuration has been run.
- **`override string ToString()`**
Returns `SerialNumber` or `"Unknown DAS"`.
- **`override bool Equals(object right)`**
Compares `SerialNumber` for equality (null-safe).
- **`override int GetHashCode()`**
Returns hash of `SerialNumber` or `0`.
### Async Helper Classes
- **`class TDASDownloadServiceAsyncInfo`**
Holds `TDASServiceAsyncInfo info` and `TDASServiceSetupInfo setupInfo`.
- **`class TDASServiceQueryConfigAsyncInfo : TDASServiceAsyncInfo`**
Extends `TDASServiceAsyncInfo` with `bool ReadIds` property.
- **`class TDASServiceAsyncInfo`**
Base async info class with:
- `ServiceCallback callback`, `object userData`, `object functionData`
- Methods: `Error(string, Exception)`, `Progress(int)`, `NewData(...)`, `Success()`, `Cancel()`
### Subclasses for Connection Types
- **`class EthernetTDAS : TDAS<EthernetConnection>`**
TDAS using Ethernet connection.
- **`class SerialTDAS : TDAS<SerialConnection>`**
TDAS using serial connection.
## 3. Invariants
- **Connection Requirement**: All async operations (`StartTriggerCheck`, `DoTriggerCheck`, etc.) require `Connected == true`; otherwise, `NotConnectedException` is thrown.
- **Hardware Type Determination**: `GetHardwareType()` relies solely on `SerialNumber` prefix; invalid prefixes default to `TDAS_Pro_Rack`.
- **Arming State**: `DASArmStatus` must be initialized before use in arming/triggering methods; if `null`, a new `ArmStatus` is created and initialized.
- **Module Iteration**: Trigger check operations iterate over `DASInfo.Modules`, skipping `EMPTYBANK` modules and applying G5-specific logic when `IsG5()` is true.
- **G5 Module Handling**: For G5 devices (`SerialNumber.StartsWith("5M")`), only module index `0` is processed in trigger checks (other modules skipped).
- **Phase Shift**: `GetPhaseShiftSamples` always returns `0`; no phase shift is applied.
- **Equality**: Two `TDAS<T>` instances are equal if their `SerialNumber` values are equal (null/empty handled).
- **Async Callback Safety**: All `TDASServiceAsyncInfo` callback methods (`Error`, `Success`, etc.) wrap callback invocations in `try/catch` to prevent unhandled exceptions from propagating.
## 4. Dependencies
### Internal Dependencies (from source):
- **`Communication<T>`**: Base class providing core communication functionality.
- **`DTS.Common.ICommunication`**: Defines `ICommunication<T>`, `IInfoResult`, `IDownload`, etc.
- **`DTS.Common.Interface.Connection`**: Defines `IConnection` (generic type constraint `T : IConnection, new()`).
- **`DTS.Common.DASResource`**: Provides `Strings` (localized error messages).
- **`DTS.Common.Utilities.Logging`**: Provides `APILogger`.
- **`DTS.DASLib.Command.SLICE`**: Used in `TriggerCheck.cs` for `Command.TDAS.*` classes (e.g., `TestTrigger`, `QuerySerialNumber`, `TestAll`).
- **`DTS.Common.Interface.DASFactory.*`**: Multiple interfaces (`IDiagnosticsActions`, `IConfigurationActions`, `IArmActions`, `IDownloadActions`, `ITriggerCheckActions`, `IArmStatusData`, `IDownloadRequest`, `IDownloadReport`, `IDiagnosticActions`, `IDiagnosticResult`, `IBaseInputValues`, `IOptimizationValues`, `IArmCheckActions`, `IArmCheckResults`, `IInfoResult`, `IConfigurationData`).
- **`DTS.Common.Enums.*`**: Enums `HardwareTypes`, `DFConstantsAndEnums` (including `CommandStatus`, `ModuleType`, `VoltageStatusColor`, `ExcitationStatus`), `InputClockSource`, `ClockSyncProfile`.
- **`DTS.DASLib.Service.Classes.Diagnostics`**: Provides `DiagnosticsActions`, `DiagnosticsResultActions`.
### External Dependencies:
- **`System`**: Core types (`System.Collections.Generic`, `System.Threading`, `System.Windows.Forms`).
- **`DTS.Common.SerialConnection`**: For `SerialConnection` type.
### Inferred Usage:
- **Consumers**: Likely used by higher-level UI or orchestration layers (e.g., `DataPRO` application) to manage TDAS hardware.
- **Dependents**: Classes implementing `IDASCommunication` or consuming `TDAS<T>` instances (e.g., configuration managers, diagnostic tools, download services).
## 5. Gotchas
- **`DoTriggerCheckSync` Not Implemented**: The method `ITriggerCheckActions.DoTriggerCheckSync()` throws `NotImplementedException` with a comment indicating it was intentionally left unimplemented for TDAS due to minimal impact of the original issue (ECM event line check). Using this method will crash at runtime.
- **`IsG5()` Not Defined**: The method `IsG5()` is used in `TriggerCheck.cs` but is not defined in the provided source. It must be defined elsewhere (e.g., in `Communication<T>` or a partial class).
- **`G5Mode` Property**: Used in `GetHardwareType()` but not defined in the provided source. Must be defined elsewhere.
- **`Connected` Property**: Used in `LaunchAsyncWorker` and `CallSyncMethod` but not defined in the provided source. Must be defined in `Communication<T>`.
- **`ServiceCallback` and `ServiceCallbackData`**: Types used for async callbacks but not defined in the provided source. Their structure (e.g., `CallbackStatus` enum, `AddSampleData` overloads) is inferred from usage.
- **`TDASServiceSetupInfo` Type**: Referenced in `TDASDownloadServiceAsyncInfo` but not defined in the provided source.
- **`IsG5()` Assumption**: The trigger check logic assumes `IsG5()` returns `true` for `"5M"` serials, but this is not explicitly stated.
- **G5 Module Indexing**: In `AsyncStartTriggerCheck` and `AsyncCancelTriggerCheck`, G5 devices only process module index `0` (break after first non-empty module), but this is not documented in comments.
- **`GetIsStreaming()` Always Returns `false`**: Despite the comment, it does not track streaming state dynamically.
- **`SetInRealtime` Ignores `ExitRealtimeIfPossible`**: The parameter `ExitRealtimeIfPossible` is unused in the implementation.
- **`SetEventArmAttemps` Typo**: Method name has typo (`SetEventArmAttemps` instead of `SetEventArmAttempts`).
- **`TDASServiceAsyncInfo.NewData` Overloads**: Multiple overloads exist for `NewData`, but the `IList<short[][]>` overload hardcodes `sequenceNumber = 0` for all samples.
- **`Equals`/`GetHashCode` on Null `SerialNumber`**: Two devices with `null`/empty `SerialNumber` are considered equal, which may be unintended.
- **No-Op Trigger Check Pre/Post**: `PreStartTriggerCheck` and `PostStartTriggerCheck` do nothing—consumers may expect actual logic here.
- **`StartRecord` Protected Setter**: Only settable internally; external code must use `SetInArm`/`SetInRealtime` to influence state.

126
enriched-qwen3-coder-next/DataPRO/IService/Classes/TDAS.md Normal file
View File

@@ -0,0 +1,126 @@
---
source_files:
- DataPRO/IService/Classes/TDAS/TDASServiceSetupInfo.cs
- DataPRO/IService/Classes/TDAS/TDASServiceSetupInfoLookup.cs
- DataPRO/IService/Classes/TDAS/TDASConfig.cs
- DataPRO/IService/Classes/TDAS/TDASModuleConfig.cs
generated_at: "2026-04-16T03:59:19.825998+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "4eeb90f6bf6e5cce"
---
# TDAS
## Documentation: TDAS Configuration and Setup Info Classes
### 1. Purpose
This module provides data structures and configuration persistence for the TDAS (Test Data Acquisition System) service layer. It defines setup metadata (`TDASServiceSetupInfo`, `TDASServiceSetupInfoLookup`) used to configure acquisition parameters at runtime, and XML-serializable configuration classes (`TDASConfig`, `TDASModuleConfig`) that store per-module hardware and test settings to disk. These classes enable centralized management of DAS module configurations, channel definitions, and acquisition parameters across test sessions.
### 2. Public Interface
#### `TDASServiceSetupInfo`
- **Constructor**:
`TDASServiceSetupInfo(string setupDescription, double? samplesPerSecond, float hardwareFilterRateHz, DFConstantsAndEnums.RecordingMode recordingMode, bool? checkoutMode)`
Initializes a new instance with fixed (non-lookup) acquisition parameters. All parameters are required; `samplesPerSecond` and `checkoutMode` are nullable.
- **Properties**:
- `string SetupDescription` – Human-readable description of the setup.
- `double? SamplesPerSecond` – Fixed sample rate (Hz); nullable to allow optional specification.
- `float HardwareFilterRateHz` – Hardware anti-aliasing filter rate in Hz (non-nullable).
- `DFConstantsAndEnums.RecordingMode RecordingMode` – Recording mode enum value (e.g., continuous, triggered).
- `bool? CheckoutMode` – Optional flag indicating whether the setup is for hardware checkout.
#### `TDASServiceSetupInfoLookup`
- **Constructor**:
`TDASServiceSetupInfoLookup(string setupDescription, Dictionary<string, double> sampleRateLookup, Dictionary<string, float> aafLookup, DFConstantsAndEnums.RecordingMode recordingMode, bool? checkoutMode)`
Initializes a lookup-based setup info where sample rate and filter rate vary by DAS unit (identified by string key, likely serial number).
- **Properties**:
- `string SetupDescription` – Same as above.
- `Dictionary<string, double> SamplesPerSecondLookup` – Maps DAS identifier (e.g., serial number) to its sample rate.
- `Dictionary<string, float> HardwareFilterRateHzLookup` – Maps DAS identifier to its hardware filter rate.
- `DFConstantsAndEnums.RecordingMode RecordingMode` – Same as above.
- `bool? CheckoutMode` – Same as above.
#### `TDASConfig`
- **Constructor**:
`TDASConfig()` – Default constructor.
`TDASConfig(string fileName, bool deleteIfPresent)` – Loads config from `DASConfigs/<fileName>` (relative to executing assembly directory). If `deleteIfPresent` is `true`, deletes existing file before proceeding; otherwise, attempts to deserialize.
- **Properties**:
- `Dictionary<string, TDASModuleConfig> Modules` – Read-only dictionary of modules keyed by serial number.
- `string FileName` – Full path to the config file (read-only).
- **Methods**:
- `void SetModule(TDASModuleConfig module)` – Adds or updates a module in `_modules` by `SerialNumber`.
- `TDASModuleConfig GetModule(TDASModuleConfig module)` – Retrieves module by `SerialNumber`; if missing, adds the provided module and returns it.
- `void ReadXml(XmlReader reader)` – Deserializes XML into `_modules` (expects `<TDASConfig><Modules>...</Modules></TDASConfig>` structure).
- `void WriteXml(XmlWriter writer)` – Serializes `_modules` to XML.
- `XmlSchema GetSchema()` – Returns `null` (per `IXmlSerializable` convention for schema-less types).
#### `TDASModuleConfig`
- **Constructor**:
`TDASModuleConfig()` – Default constructor.
`TDASModuleConfig(string fileName)` – Loads module config from `DASConfigs/<fileName>`.
- **Properties**:
- `string SerialNumber` – Unique identifier for the module.
- `string TestId` – Test identifier string.
- `string TestDescription` – Human-readable test description.
- `DFConstantsAndEnums.RecordingMode RecordingMode` – Recording mode (default: `InvalidArmMode`).
- `float AAFilterRateHz` – Anti-aliasing filter rate (default: `0`).
- `double PreTriggerSeconds` – Pre-trigger hold time (default: `0`).
- `double PostTriggerSeconds` – Post-trigger record time (default: `0`).
- `string FirmwareVersion` – Module firmware version string.
- `UInt64? MaxEventStorageSpaceInBytes` – Optional max storage for event data.
- `int ModuleArrayIndex` – Zero-based index for module ordering (default: `0`).
- `string FileName` – Full path to config file (read-only).
- `Dictionary<int, DASChannel> Channels` – Internal dictionary of channels keyed by `ModuleChannelNumber` (not exposed directly; accessed via `SetChannel`/`GetChannel` overloads).
- **Methods**:
- `void SetChannel(OutputTOMDigitalChannel channel)` / `SetChannel(OutputSquibChannel channel)` / `SetChannel(AnalogInputDASChannel channel)` – Adds or updates channel by `ModuleChannelNumber`.
- `AnalogInputDASChannel GetChannel(AnalogInputDASChannel channel)` / `GetChannel(OutputSquibChannel channel)` / `GetChannel(OutputTOMDigitalChannel channel)` – Retrieves channel by `ModuleChannelNumber`; if missing, adds the provided channel and returns it.
- `void ReadXml(XmlReader reader)` – Deserializes XML into module properties and channels. Handles legacy configs (e.g., missing `ModuleArrayIndex` element).
- `void WriteXml(XmlWriter writer)` – Serializes module properties and channels to XML.
- `XmlSchema GetSchema()` – Returns `null`.
- `virtual void WriteElementStart(XmlWriter writer)` – Writes `<TDASModule xsi:type="...">` with concrete type.
- `virtual void WriteElementEnd(XmlWriter writer)` – Closes the `<TDASModule>` element.
### 3. Invariants
- **`TDASConfig`**:
- `_modules` dictionary is keyed by `TDASModuleConfig.SerialNumber`; duplicates are overwritten by `SetModule`.
- `FileName` is always an absolute path constructed relative to the executing assembly’s directory under `DASConfigs/`.
- **`TDASModuleConfig`**:
- `RecordingMode` defaults to `DFConstantsAndEnums.RecordingMode.InvalidArmMode` (invalid state); must be explicitly set to a valid mode.
- `AAFilterRateHz`, `PreTriggerSeconds`, `PostTriggerSeconds` default to `0`.
- `MaxEventStorageSpaceInBytes` is nullable; invalid values (negative or ≥ `ulong.MaxValue`) are logged and ignored.
- `ModuleArrayIndex` defaults to `0`; invalid values (negative or ≥ `int.MaxValue`) are logged and ignored.
- Channel dictionaries use `ModuleChannelNumber` as the key; duplicate channel numbers overwrite existing entries.
- **XML Serialization**:
- `TDASConfig` expects `<TDASConfig><Modules>...</Modules></TDASConfig>`.
- `TDASModuleConfig` expects `<TDASModule>...</TDASModule>` with child elements in a fixed order (e.g., `SerialNumber`, `TestId`, `RecordingMode`, etc.).
- Channel serialization uses `WriteElementStart`/`WriteElementEnd` to include `xsi:type` for polymorphic deserialization.
### 4. Dependencies
- **Imports/Usings**:
- `DTS.Common.DAS.Concepts` – Provides `DASChannel`, `AnalogInputDASChannel`, `OutputSquibChannel`, `OutputTOMDigitalChannel`.
- `DTS.Common.Enums.DASFactory` – Provides `DFConstantsAndEnums.RecordingMode`.
- `DTS.DASLib.Command.SLICE` – Referenced but not directly used in these classes (likely transitive dependency).
- `DTS.Common.Utilities.Logging` – Provides `APILogger` for error logging during XML deserialization.
- Standard .NET libraries: `System.Xml`, `System.IO`, `System.Collections.Generic`, `System`.
- **Consumers**:
- `TDASConfig` and `TDASModuleConfig` are used by the TDAS service layer to persist/load configurations.
- `TDASServiceSetupInfo`/`TDASServiceSetupInfoLookup` are likely used by higher-level configuration or initialization logic (e.g., service startup, test setup UI).
- XML serialization implies integration with external tools or UIs that read/write config files.
### 5. Gotchas
- **`TDASServiceSetupInfoLookup` naming**: The constructor parameter `aafLookup` is named inconsistently with the property `HardwareFilterRateHzLookup`; this may cause confusion.
- **`GetModule`/`GetChannel` behavior**: Both methods add the provided object to the dictionary if missing, which can silently mutate state. Callers must ensure the input object is fully initialized.
- **XML deserialization robustness**:
- `RecordingMode` and numeric fields (`AAFilterRateHz`, `PreTriggerSeconds`, etc.) use `try/catch` + `APILogger.Log` for errors, but silently default to `0`/`InvalidArmMode` on failure.
- `ModuleArrayIndex` is wrapped in a `try/catch` block to handle legacy configs (missing element), but other elements lack this fallback.
- **Path construction**: Config paths are hardcoded to `DASConfigs/` under the assembly directory; this may not work in all deployment scenarios (e.g., ClickOnce, containerized).
- **Channel polymorphism**: `WriteElementStart` uses `GetType()` to write `xsi:type`, but `ReadXml` relies on the `type` attribute to deserialize into `OutputSquibChannel`, `OutputTOMDigitalChannel`, or `AnalogInputDASChannel`. Mismatched types in XML will cause silent fallback to `AnalogInputDASChannel`.
- **No validation**: No validation is performed on `SetupDescription`, `SerialNumber`, or `TestId` (e.g., empty strings allowed).
- **`SamplesPerSecond` vs `SamplesPerSecondLookup`**: The nullable `double?` in `TDASServiceSetupInfo` vs. `Dictionary<string, double>` in `TDASServiceSetupInfoLookup` suggests two distinct use cases (single rate vs. per-DAS rates), but the distinction is not enforced programmatically.

221
enriched-qwen3-coder-next/DataPRO/IService/Interfaces.md Normal file
View File

@@ -0,0 +1,221 @@
---
source_files:
- DataPRO/IService/Interfaces/IAutoArmStatus.cs
- DataPRO/IService/Interfaces/ITimeActions.cs
- DataPRO/IService/Interfaces/IService.cs
- DataPRO/IService/Interfaces/IRealtime.cs
- DataPRO/IService/Interfaces/IDiagnos.cs
- DataPRO/IService/Interfaces/IDASCommunicationComparer.cs
- DataPRO/IService/Interfaces/IDASCommunicationEqComparer.cs
- DataPRO/IService/Interfaces/IUARTDownloadActions.cs
- DataPRO/IService/Interfaces/ITriggerCheckActions.cs
- DataPRO/IService/Interfaces/IRealTimeActions.cs
- DataPRO/IService/Interfaces/IDownloadActions.cs
- DataPRO/IService/Interfaces/IClockSyncActions.cs
- DataPRO/IService/Interfaces/IDiagnosticsActions.cs
- DataPRO/IService/Interfaces/IConfigurationActions.cs
- DataPRO/IService/Interfaces/IArmActions.cs
- DataPRO/IService/Interfaces/IDASCommunication.cs
generated_at: "2026-04-16T03:57:16.444957+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "b07fbe9a3474c9e8"
---
# DASLib.Service Interfaces Documentation
## 1. Purpose
This module defines a set of interfaces that collectively represent the service layer for Data Acquisition Systems (DAS) in the DataPRO ecosystem. These interfaces abstract hardware-specific operations—such as arming, diagnostics, real-time data streaming, clock synchronization, UART communication, configuration, and download management—into a standardized contract. They serve as the primary API surface for interacting with DAS hardware units, enabling decoupling of service logic from device-specific implementations. The interfaces are designed to support multiple DAS types (e.g., SLICE, TDAS, G5, S6) and coordinate complex workflows like event-triggered acquisition, diagnostics validation, and low-power state transitions.
## 2. Public Interface
### `IAutoArmStatus`
- **`AutoArmStatus`** (`DFConstantsAndEnums.CommandStatus`): Gets or sets the auto-arm status of the DAS unit.
### `ITimeActions` *(internal)*
- **`Synchronize(ServiceCallback callback, object userData, DateTime time)`**: Synchronizes the DAS clock to the specified `time`.
- **`QueryTime(ServiceCallback callback, object userData)`**: Queries the current time from the DAS.
### `IService`
- **`ServiceCallback`** delegate: `void ServiceCallback(ServiceCallbackData data)` — The callback signature used to return results from service operations.
### `IRealTime`
- **`RealtimeDASChannels`** (`List<int>`): Gets or sets the list of channel indices to stream in real-time mode.
- **`TiltAxisData`** (`List<double>`): Gets or sets the SLICE6 Axis 1/2/3 (X/Y/Z) tilt data in degrees.
### `IDiagnos`
- **`ChannelDiagnostics`** (`DiagnosticsActions[]`): Gets or sets the diagnostics actions to perform per channel.
- **`ChannelDiagnosticsResults`** (`DiagnosticsResult[]`): Gets or sets the results of channel diagnostics.
- **`ModuleDiagnosticsResults`** (`ModuleDiagnosticsResult[]`): Gets or sets the results of module-level diagnostics.
- **`BaseInput`** (`BaseInputValues`): Gets or sets base input voltage/temperature values.
- **`DASClockSyncStatus`** (`ClockSyncStatus`): Gets or sets the DAS clock synchronization status.
- **`ArmCheckActions`** (`ArmCheckActions`): Gets or sets the arm check actions to perform.
- **`ArmCheckResults`** (`ArmCheckResults`): Gets or sets the results of arm checks.
### `IDASCommunicationComparer`
- **`Compare(IDASCommunication x, IDASCommunication y)`** (`int`): Compares two `IDASCommunication` instances by `SerialNumber`. Handles nulls and reference equality.
### `IDASCommunicationEqComparer`
- **`Equals(IDASCommunication x, IDASCommunication y)`** (`bool`): Returns `true` if both instances have the same `SerialNumber`.
- **`GetHashCode(IDASCommunication idascom)`** (`int`): Returns hash code based on `SerialNumber`.
### `IUARTDownloadActions`
- **`UARTDownload(ServiceCallback callback, object userData)`**: Downloads data as specified in `WhatToDownload`.
- **`QueryUARTDownload(ServiceCallback callback, object userData, int eventIndex, TDASServiceSetupInfo setupInfo)`**: Queries available UART events for download.
- **`SetUARTSettings(ServiceCallback callback, object userData, uint baudRate, uint dataBits, uint stopBits, uint parity, uint flowControl)`**: Sets UART connection parameters (FB15268).
- **`GetUARTSettings(ServiceCallback callback, object userData)`**: Retrieves current UART settings.
### `ITriggerCheckActions` *(internal)*
- **`PreStartTriggerCheck(ServiceCallback callback, object userData)`**: Prepares hardware before `StartTriggerCheck` (e.g., for S6 ATD/SLICE PRO trigger check failures, issue #13820).
- **`PostStartTriggerCheck(ServiceCallback callback, object userData)`**: Performs post-`StartTriggerCheck` cleanup.
- **`StartTriggerCheck(ServiceCallback callback, object userData)`**: Sets DAS to latch signal lines for trigger checking.
- **`DoTriggerCheck(ServiceCallback callback, object userData)`**: Performs trigger check and stores result in `TriggerResult`.
- **`DoTriggerCheckSync()`**: Synchronous version of `DoTriggerCheck`.
- **`DoStartCheck(ServiceCallback callback, object userData)`**: Performs start check and stores result in `StartResult`.
- **`CancelTriggerCheck(ServiceCallback callback, object userData)`**: Resets DAS latching mechanism to normal mode.
### `IRealTimeActions` *(internal)*
- **`RealTime(...)`**: Starts real-time streaming with configurable sample rate, channels, AAF, UDP settings, etc.
- **`RealTimePolling(ServiceCallback callback, object userData, ManualResetEvent stopEvent, byte[] channels)`**: Polls DAS for real-time sample averages.
- **`ExitRealTimeMode(ServiceCallback callback, object userData)`**: Stops real-time data streaming.
- **`RealTimeTiltPolling(ServiceCallback callback, object userData, ManualResetEvent stopEvent)`**: Polls tilt data in real-time.
- **`SetUDPStreamProfile(...)`**: Configures UDP streaming for S6A (FB15313).
- **`GetUDPStreamProfile(ServiceCallback callback, object userData)`**: Retrieves current UDP streaming profile.
### `IDownloadActions` *(internal)*
- **`Download(ServiceCallback callback, object userData)`**: Downloads data as specified in `WhatToDownload`.
- **`Cancel()`**: Cancels current download operation.
- **`ForceCancel()`**: Cancels with shorter clear time.
- **`ClearCancel()`**: Clears the cancel flag.
- **`QueryDownload(...)`**: Queries available events for download.
- **`QueryDownloadedStatus(...)`**: Checks if events have been downloaded.
- **`SetTriggerSampleNumbers(...)`**: Updates trigger sample numbers in hardware.
- **`SetDownloaded(...)`**: Marks event as downloaded (used when no data exists).
- **`SetEventInfo(...)`**: Updates event metadata (ID, GUID, samples, etc.).
- **`CorrectT0s(...)`**: Recovers T0 and total sample counts via ADC rail/peak detection (issue #18469).
### `IClockSyncActions`
- **`GetClockSyncStatus(ServiceCallback callback, object userData)`**: Retrieves clock source and sync status (32-byte payload; see comments for layout).
- **`SetClockSyncConfig(ServiceCallback callback, object userData, ClockSyncProfile profile)`**: Sets input/output clock configuration (PTP, IRIG-B122, GPS/1PPS, etc.).
- **`GetPTPDomainID(ServiceCallback callback, object userData)`**: Gets PTP domain ID.
- **`SetPTPDomainID(ServiceCallback callback, object userData, byte domainID)`**: Sets PTP domain ID.
### `IDiagnosticsActions`
- **`ClearTriggerOut(ServiceCallback callback, object userData)`**: Clears trigger output line via `SetSwitchImmediate`.
- **`ClearLatches(ServiceCallback callback, object userData)`**: Clears latched FPGA via QATS.
- **`PerformVoltageCheck(...)`**: Performs voltage checks.
- **`PerformArmChecks(...)`**: Performs arm checks.
- **`SaveTiltSensorDataPre(...)` / `SaveTemperaturesPre(...)`**: Saves pre-event tilt/temperature data.
- **`PrepareForBridgeResistanceMeasurement(...)`**: Warms up analog circuits before bridge resistance measurement.
- **`PrepareForDiagnostics(...)`**: Prepares for diagnostics (sample rate, AAF, pre/post result type).
- **`SetStatusIndicator(...)`**: Sets diagnostics status indicator state.
- **`DiagnosAndGetResults(...)`**: Runs diagnostics and stores results.
- **`GetEventDiagnosticsResults(...)`**: Retrieves pre/post event diagnostics results.
- **`ClearDASTriggerLine(...)`**: Explicitly clears DAS trigger lines after `PreStartTriggerCheck` (issue #14229).
- **`SquibFireCheckArm(...)`**: Performs squib fire check during arming.
- **`TriggerCheckTrigger(...)` / `TriggerCheckDownload(...)`**: Triggers and downloads trigger check data.
- **`GetBridgeMeasurement(...)`**: Retrieves bridge resistance measurement.
- **`MeasureTransferSpeed(...)`**: Measures data transfer speed.
### `IConfigurationActions`
- **`AutoDetect(bool bQueryConfiguration, ServiceCallback callback, object userData)`**: Resets channels to auto-detect mode (e.g., for SLICE2 IEPE/bridge).
- **`VerifyConfig(bool DoStrictCheck)` / `VerifyConfig(bool DoStrictCheck, ErrorCallback FailedChallengeFunc)`**: Validates `ConfigData`.
- **`SetFirstUseDate(...)`**: Sets first-use date (use `MsqlDateTime.MinValue` to unset).
- **`StoreTestSetupXML(...)`**: Stores test setup XML; resets trigger/start lines.
- **`ResetHardwareLines(...)`**: Resets hardware trigger/start lines.
- **`CheckAAFilterRate(...)`**: Validates AAF rate.
- **`QueryTestSetup(...)`**: Retrieves test setup from DAS.
- **`Configure(...)`**: Applies configuration from `ConfigData` to DAS (supports UDP streaming, DSP filters, UART, etc.).
- **`ApplyLevelTriggers(...)`**: Applies only level triggers (no full config).
- **`QueryConfiguration(...)`**: Retrieves configuration from DAS into `ConfigData`.
- **`UpdateConfigurationFromFile(...)`**: Updates config from XML file (issue #17872).
- **`UpdateIDs(...)` / `UpdateId(...)`**: Retrieves EIDs or single module/channel ID.
- **`CheckSafetyState(...)`**: Checks safety state (armed/unarmed).
- **`Reboot(...)`**: Reboots device (FB15335).
### `IArmActions` *(internal)*
- **`TurnOffT0Lights(...)`**: Turns off T0 indicator lights.
- **`BeginBackgroundFlashErase(...)`**: Starts background flash erase (non-blocking).
- **`SupportsBackgroundFlashErase`** (`bool`): Indicates if background flash erase is supported.
- **`BackgroundFlashEraseStarted`** (`bool`): Indicates if background erase has started.
- **`BackgroundFlashEraseStartTime`** (`DateTime?`): Timestamp of background erase start.
- **`BeginFlashErase(...)`**: Starts asynchronous flash erase.
- **`QueryFlashEraseStatus(...)`**: Queries flash erase progress/errors.
- **`ReadyForArming(...)`**: Prepares DAS for arming (event GUID, timeout, testing mode, etc.).
- **`ArmNow(...)`**: Arms DAS immediately.
- **`PrepareForArmNow(...)` / `PreparedArmNow(...)`**: Pre-arming steps.
- **`ReArm(...)`**: Re-arms units with optional auto-arm/repeat flags.
- **`AutoArmUDPSetting`** (`string`): UDP broadcast address for auto-arm status (issue #17583).
- **`AutoArmNow(...)`**: Auto-arms DAS with diagnostics delay and repeat enable.
- **`EnableFaultChecking(...)`**: Arms multiple chained DAS units.
- **`CheckAlreadyLevelTriggered(...)`**: Checks if channels are level-triggered.
- **`Disarm(...)` / `DisAutoArm(...)`**: Disarms or disables auto-arm.
- **`GetArmStatus(...)` / `GetAutoArmStatus(...)`**: Retrieves current arm/auto-arm status.
- **`EnterLowPowerMode(...)`**: Sets DAS to low-power mode.
- **`StartRecord(...)`**: Instructs DAS to start recording.
- **`Trigger(...)`**: Sends hardware trigger signal.
- **`GetExtendedFaultIds(...)`**: Queries extended fault IDs.
### `IDASCommunication`
- **Inherits** from: `IConfiguration`, `IDiagnos`, `ITriggerCheck`, `IRealTime`, `IArmStatus`, `IDownload`, `IInformation`, `IAutoArmStatus`, `IAutoArmed`, `IRangeBandwidthLimited`, `ITimeSynchronization`.
- **`RecordId`** (`int`): Gets/sets the record ID.
- **`GetNominalRanges(BridgeType bridge)`** (`double[]`): Returns nominal voltage ranges for given bridge type.
- **Voltage properties** (`InputLow/Medium/HighVoltage`, `BatteryLow/Medium/HighVoltage`, `Minimum/MaximumValid...Voltage`): Hardware-specific voltage thresholds.
- **`SerialNumber`** (`string`): Base unit serial number.
- **`FirmwareVersion`** (`string`): Firmware version (read-only).
- **`DiagnosticsHasBeenRun`** / **`ConfigureHasBeenRun`** (`bool`): Flags indicating if diagnostics/configuration have been run.
- **`NumberOfConfiguredChannels()` / `NumberOfChannels()`** (`int`): Counts configured or total channels.
- **`MaxMemory()`** (`long`): Maximum memory capacity.
- **`MaxModules`** (`int`): Maximum module count.
- **`MinSampleRate()` / `MaxSampleRate()`** (`uint`): Sample rate limits.
- **Feature support flags** (`SupportsAutoArm`, `SupportsLevelTrigger`, `SupportsRealtime`, etc.): Hardware capability indicators.
- **`InvertTrigger` / `InvertStart`** (`bool`): Trigger/start line inversion (SLICE-specific).
- **`IgnoreShortedStart` / `IgnoreShortedTrigger`** (`bool`): Ignore shorted start/trigger lines.
- **`SupportsHardwareInputCheck()`** (`bool`): Hardware input status check support (SLICE Base firmware ≥ v7).
- **`SupportsMultipleSampleRealtime()`** (`bool`): Multiple sample real-time support.
- **`ControlsDAQ()`** (`bool`): Indicates if base unit controls module DAQ.
- **`CheckAAF(float rate)`** (`bool`): Validates new AAF rate (e.g., SLICE2 rate tables).
- **`RequireDiagnosticRateMatchSampleRate()`** (`bool`): Requires diagnostic sample rate to match data rate.
- **`GetPhaseShiftSamples(...)`** (`ulong`): Returns phase delay in samples (module-specific).
- **`IsEthernetDistributor()` / `IsSlice6Distributor()`** (`bool`): Identifies distributor devices (e.g., SLICEDb).
- **`MACAddress`** / **`DownstreamMACAddresses`** (`string[]`): Network identifiers.
- **`SupportsIndividualChannelRealtimeStreaming`** (`bool`): Per-channel real-time streaming (SPS only, issue #10572).
## 3. Invariants
- **`IDASCommunication`** instances must uniquely identify hardware units via `SerialNumber`. Comparers (`IDASCommunicationComparer`, `IDASCommunicationEqComparer`) enforce this via `SerialNumber`-based equality.
- **`ServiceCallback`** must be invoked exactly once per service operation, carrying `ServiceCallbackData` with operation result.
- **`RealtimeDASChannels`** and **`RealTime(...)`** `channels` parameter must contain valid channel indices for the DAS unit.
- **`DiagnosticsHasBeenRun`** and **`ConfigureHasBeenRun`** flags must be set only after successful completion of respective operations.
- **`AutoArmUDPSetting`** must be a valid UDP address string when auto-arm is enabled; otherwise, it may be null/empty.
- **`TiltAxisData`** must contain exactly 3 elements (X, Y, Z) for SLICE6 tilt reporting.
- **`IDownloadActions.Cancel()`** and **`ForceCancel()`** must set an internal cancel flag that is checked during download operations.
- **`ITriggerCheckActions.PreStartTriggerCheck`** and **`PostStartTriggerCheck`** are *not* generic services—they are called explicitly by the `StartTriggerCheck` service to handle hardware-specific timing (e.g., S6 ATD quirks, issue #13820).
## 4. Dependencies
### Dependencies *on* this module:
- **`DTS.Common.*`** namespaces:
- `DTS.Common.Enums.DASFactory` (e.g., `CommandStatus` in `IAutoArmStatus`)
- `DTS.Common.Interface.DASFactory` (e.g., `IDASCommunication` inherits from `IConfiguration`, `IDiagnos`, etc.)
- `DTS.Common.DAS.Concepts`, `DTS.Common.Enums.Sensors`, `DTS.Common.Classes.DSP`
- **System namespaces**: `System`, `System.Collections.Generic`, `System.IO.Ports`, `System.Threading`
- **Windows Forms**: `System.Windows.Forms` (only in `IService.cs`, likely for legacy UI integration)
### Dependencies *of* this module:
- **`IDASCommunication`** is the central abstraction; all service interfaces (`IArmActions`, `IDiagnosticsActions`, etc.) operate on `List<IDASCommunication>` (implied by usage).
- **`ServiceCallback`** is used by all service interfaces to return results.
- **`TDASServiceSetupInfo`** is referenced in `IUARTDownloadActions.QueryUARTDownload` and `IDownloadActions.QueryDownload`.
- **`PrePostResults`** is used in `IDiagnosticsActions` methods (e.g., `PrepareForDiagnostics`, `DiagnosAndGetResults`).
- **`UDPStreamProfile`**, **`ClockSyncProfile`**, **`DiagnosticsStatusIndicatorState`**, **`DiagnosticsActions`**, **`ArmCheckActions`**, etc., are defined in external `DTS.Common.*` assemblies.
## 5. Gotchas
- **`ITimeActions`** and **`IRealTimeActions`** are marked `internal`—they are not part of the public API surface and should not be used outside `DTS.DASLib.Service`.
- **`ITriggerCheckActions.PreStartTriggerCheck`/`PostStartTriggerCheck`** are *not* generic services; they are called by the `StartTriggerCheck` service to handle hardware-specific timing (e.g., S6 ATD/SLICE PRO trigger check failures, issue #13820).
- **`IDownloadActions.CorrectT0s(...)`** may return an error on devices that do not support T0 recovery (e.g., non-circular buffer/hybrid recorders, issue #18469).
- **`IUARTDownloadActions.SetUARTSettings(...)`** uses `uint` for all UART parameters (baudRate, dataBits, etc.), but actual hardware may have constrained ranges (e.g., dataBits ∈ {7,8}, stopBits ∈ {1,2}).
- **`IDiagnosticsActions.PrepareForBridgeResistanceMeasurement(...)`** must be called *only* if units were previously in low-power mode; otherwise, it is unnecessary but harmless (per comment).
- **`IDASCommunication.CheckAAF(float rate)`** is primarily used for SLICE2’s multiple AAF rate tables; other DAS types may ignore it.
- **`IArmActions.Background

39
enriched-qwen3-coder-next/DataPRO/IService/Properties.md Normal file
View File

@@ -0,0 +1,39 @@
---
source_files:
- DataPRO/IService/Properties/AssemblyInfo.cs
generated_at: "2026-04-16T03:56:25.268323+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "5a7e700d5630ac8c"
---
# Properties
## 1. Purpose
This module (`DataPRO/IService/Properties/AssemblyInfo.cs`) is an assembly-level configuration file for the `IService` .NET assembly. It defines metadata attributes (e.g., title, version, copyright) and COM visibility settings required for proper assembly identification, versioning, and interoperability. It does not contain business logic or runtime behavior—it serves as a build-time and runtime metadata descriptor for the assembly.
## 2. Public Interface
This file contains **no public types, functions, classes, or methods**. It exclusively defines assembly-level attributes via `Assembly*` attributes in the `System.Reflection` namespace. These attributes are consumed by the .NET runtime and tools (e.g., reflection, deployment systems), but are not callable APIs.
## 3. Invariants
- The assembly version is strictly defined as `1.06.0081` (both `AssemblyVersion` and `AssemblyFileVersion`).
- The assembly is **not visible to COM** (`ComVisible(false)`), meaning types within this assembly cannot be accessed via COM interop unless explicitly overridden at the type level.
- The GUID `7085ea4c-93ee-4ba6-b42d-4776598554e1` is permanently assigned as the typelib ID for COM exposure (though COM visibility is disabled, this GUID would be used if visibility were enabled).
- All attributes are compile-time constants; no runtime validation or enforcement occurs.
## 4. Dependencies
- **Dependencies**:
- `System.Reflection`
- `System.Runtime.CompilerServices`
- `System.Runtime.InteropServices`
(All are standard .NET Framework/BCL namespaces.)
- **Depended upon**: None—this file is internal to the assembly and not referenced by external modules. However, the `IService` assembly (of which this file is a part) is likely referenced by other modules (e.g., implementations or clients of service interfaces), though such references are not visible in this file.
## 5. Gotchas
- **No runtime behavior**: This file only affects assembly metadata; it does not influence logic execution. Misunderstanding this may lead developers to expect runtime side effects (e.g., version checks), which are absent here.
- **COM visibility disabled**: While the `ComVisible(false)` setting prevents *all* types in this assembly from being visible to COM by default, individual types *within* the assembly could override this via `[ComVisible(true)]`. However, this file itself does not define any types.
- **Version format**: The version `1.06.0081` uses a non-standard format (two-digit minor, four-digit build). Developers should verify whether build/deployment tooling expects strict semantic versioning or has compatibility constraints.
- **No source-level documentation**: The `AssemblyDescription` and `AssemblyConfiguration` attributes are empty strings—no human-readable description or build configuration is embedded.
- **Copyright year is outdated**: `2008` may be stale; verify if this reflects the actual copyright timeline.
None identified beyond the above.

81
enriched-qwen3-coder-next/DataPRO/IService/SLICE Service.md Normal file
View File

@@ -0,0 +1,81 @@
---
source_files:
- DataPRO/IService/SLICE Service/SystemAttribute.cs
- DataPRO/IService/SLICE Service/Attribute.cs
- DataPRO/IService/SLICE Service/EventAttribute.cs
generated_at: "2026-04-16T03:56:30.099134+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "61f87a0978ab0f91"
---
# SLICE Service
## Documentation: SLICE Service Attribute Infrastructure
### 1. Purpose
This module provides foundational infrastructure for handling SLICE device attributes within the `DTS.Slice.Service` namespace. It defines base abstractions (`Attribute`, `SystemAttribute`, `EventAttribute`) intended to encapsulate metadata and configuration data associated with system-level, event-level, and user-level attributes. Although the current source files contain only commented-out implementations (no active code), the structure indicates a planned design for typed attribute classes that map to specific data types (e.g., `UInt16`, `Ascii`, `DoubleDict`) and store categories (e.g., `System`, `Event`). The module supports serialization/deserialization of dictionary-based attributes (`Dictionary<byte, double>`) via helper methods in `Attribute`, and is intended to integrate with the `DTS.DASLib.Command.SLICE` command layer.
---
### 2. Public Interface
**No public types or members are currently active.** All classes and methods in the provided files are commented out. The following are *intended* public interfaces based on the commented code:
#### `SystemAttribute` (class)
- **Inherits from**: `Attribute`
- **Purpose**: Base class for system-level attributes (e.g., serial number, flash size).
- **Note**: Contains no active members; only commented-out nested `TypeValues` enum and subclasses (`SerialNumberAttribute`, `TotalEventsStoredAttribute`) are present.
#### `EventAttribute` (class)
- **Inherits from**: `Attribute`
- **Purpose**: Base class for event-level attributes (e.g., event number, sample rate, timestamps).
- **Note**: Contains no active members; only commented-out nested `TypeValues` enum and subclasses (e.g., `EventNumber`, `EventName`, `EventStartTime`, `PreEventScaleFactors`) are present.
#### `Attribute` (class)
- **Inherits from**: `object`
- **Protected members**:
- `protected enum AttributeInterface { Arm, Event, System, User }`
- `protected AttributeInterface Store { get; set; }`
- `protected AttributeTypes.AttributeDataTypes datatype;`
- `protected ushort key;`
- `protected object value;`
- **Public constants**:
- `public const int MaxSingleAttributeSize = 500;`
- `public const int BulkAttributeStartNumber = 3000;`
- **Protected methods**:
- `protected Dictionary<byte, double> ByteArrayToDict(byte[] bytes)`
Parses a byte array into a dictionary of `byte → double` pairs. Assumes format: `[byte][double][byte][double]...`, where each `double` is 8 bytes.
- `protected byte[] DictToByteArray(Dictionary<byte, double> dict)`
Serializes a `Dictionary<byte, double>` into a byte array in the same format as above.
---
### 3. Invariants
- **No runtime invariants can be verified** from the source, as all logic is commented out and no constructors, properties, or methods are active.
- Based on commented code, the *intended* invariants include:
- `MaxSingleAttributeSize = 500` bytes — likely a hard limit on serialized attribute size.
- `BulkAttributeStartNumber = 3000` — likely an offset indicating where bulk attributes begin (e.g., IDs ≥ 3000 are bulk).
- Dictionary serialization assumes fixed-size pairs: 1 byte key + 8 bytes double = 9 bytes per entry.
- `EventStartTime` serialization uses 8 bytes total: 4 bytes for seconds (since Unix epoch) + 4 bytes for milliseconds.
---
### 4. Dependencies
- **Internal dependencies**:
- `DTS.Common.Utils` — likely contains `ByteConvertor` (used in commented code for type conversion).
- `DTS.DASLib.Command.SLICE` — provides `AttributeTypes.AttributeDataTypes` (used in commented subclasses).
- **No external dependencies beyond these namespaces**.
- **Depended upon by**: Unknown — no usages are visible in the provided files.
---
### 5. Gotchas
- **Critical**: All functionality is commented out. This module is non-functional as-is and likely represents a work-in-progress or legacy design artifact.
- **Ambiguity in `EventStartTime` implementation**: The setter computes `UInt32 fractions = (UInt32)(leftOver.TotalSeconds - (double)seconds);`, which is incorrect — it should use `leftOver.TotalMilliseconds % 1000` or similar to extract milliseconds. This is a likely bug if uncommented.
- **Inconsistent enum references**: Subclasses reference `QueryArmAttribute.AttributeDataTypes` (e.g., `QueryArmAttribute.AttributeDataTypes.Ascii`), but the base `Attribute` class uses `AttributeTypes.AttributeDataTypes`. This suggests either:
- A naming inconsistency (e.g., `QueryArmAttribute` should be `AttributeTypes`), or
- A missing import/namespace alias.
- **Missing `ByteConvertor` usage context**: The helper methods `ByteArrayToDict`/`DictToByteArray` assume `ByteConvertor` exists and supports `Convert(byte[], int, out T)` and `ToByteArray(T)`, but its implementation is not provided.
- **No validation on dictionary keys**: `ByteArrayToDict` does not check for duplicate keys — adding an existing key would throw `ArgumentException`.
> **Note**: Since no active code exists, these "gotchas" pertain to the *commented design*, not runtime behavior.

41
enriched-qwen3-coder-next/DataPRO/IService/SLICE Service/Properties.md Normal file
View File

@@ -0,0 +1,41 @@
---
source_files:
- DataPRO/IService/SLICE Service/Properties/AssemblyInfo.cs
generated_at: "2026-04-16T04:01:50.001516+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "3622646b73ec5522"
---
# Properties
## 1. Purpose
This module is the `AssemblyInfo.cs` file for the **SLICE Service** assembly—a .NET assembly (likely part of a larger Windows service or COM-interoperable component) within the `DataPRO/IService/SLICE Service` project path. Its sole purpose is to define assembly-level metadata (title, version, GUID, COM visibility) and does not contain executable logic or business functionality. It serves as a configuration point for assembly identity, versioning, and COM interop settings.
## 2. Public Interface
**No public API surface is exposed by this file.**
This file contains only assembly-level attributes (via `System.Reflection` and `System.Runtime.InteropServices` attributes) applied to the assembly itself—not classes, methods, or interfaces. Therefore, there are no public functions, classes, or methods to document.
## 3. Invariants
- The assembly’s **version** is fixed at `1.06.0081` for both `AssemblyVersion` and `AssemblyFileVersion`.
- The assembly is **not visible to COM** by default (`ComVisible(false)`), meaning types within the assembly cannot be accessed via COM unless explicitly marked `[ComVisible(true)]` elsewhere.
- The **GUID** `f4f93524-9676-4060-8024-0f4c818cd154` is permanently assigned as the typelib ID for COM exposure (if/when the assembly becomes COM-visible).
- No culture-specific settings are declared (`AssemblyCulture()` is empty, indicating a neutral/satellite-assembly-independent assembly).
- All attributes must remain syntactically valid and non-conflicting (e.g., no duplicate `AssemblyVersion` declarations).
## 4. Dependencies
- **Direct dependencies**:
- `System.Reflection` (for `AssemblyTitleAttribute`, `AssemblyVersionAttribute`, etc.)
- `System.Runtime.CompilerServices` (implicitly used for standard assembly attributes)
- `System.Runtime.InteropServices` (for `ComVisibleAttribute`, `GuidAttribute`)
- **No runtime dependencies** on other project modules or external libraries are declared in this file.
- **Dependent modules**:
- Any other code that references this assembly (e.g., consumers of the `SLICE Service` functionality) will rely on this assembly’s identity and version.
- COM clients (if any) will use the GUID `f4f93524-9676-4060-8024-0f4c818cd154` to locate the typelib.
## 5. Gotchas
- **Versioning strategy**: Both `AssemblyVersion` and `AssemblyFileVersion` are set to the same value (`1.06.0081`). While not incorrect, this may obscure differences between internal build numbers (e.g., `AssemblyFileVersion` is often used for file system versioning while `AssemblyVersion` governs binding redirects and runtime compatibility).
- **COM visibility**: `ComVisible(false)` at the assembly level means *all* types are hidden from COM by default. If any types *are* intended for COM exposure, they must be explicitly marked `[ComVisible(true)]`—a common source of misconfiguration.
- **Empty attributes**: Several attributes (`AssemblyDescription`, `AssemblyConfiguration`, `AssemblyCompany`, `AssemblyTrademark`) are empty strings. While harmless, this may indicate incomplete metadata or legacy artifacts (note the copyright year `2008`, suggesting this assembly is outdated).
- **No strong name signing**: No `AssemblyKeyFile` or `AssemblyKeyName` attributes are present, implying the assembly is not strong-named. This may impact deployment (e.g., no side-by-side versioning in GAC, no secure referencing).
- **None identified from source alone** regarding logic or behavioral quirks—this file is purely declarative metadata.

134
enriched-qwen3-coder-next/DataPRO/IService/StateMachine.md Normal file
View File

@@ -0,0 +1,134 @@
---
source_files:
- DataPRO/IService/StateMachine/Triggers.cs
- DataPRO/IService/StateMachine/IDASState.cs
- DataPRO/IService/StateMachine/DASState.cs
- DataPRO/IService/StateMachine/States.cs
- DataPRO/IService/StateMachine/StateMachineBootstrap.cs
generated_at: "2026-04-16T03:56:17.184753+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "86e0fafc151b8d16"
---
# State Machine Module Documentation
## 1. Purpose
This module implements a state machine for managing the operational lifecycle of a data acquisition system (DAS), using the `Stateless` library. It defines a finite state machine over a set of discrete states (e.g., `Prepare`, `HardwareDiscovery`, `Configure`, `Realtime`) and triggers (e.g., `PingAndConnect`, `ApplyConfiguration`, `StartRealtime`) that govern transitions between those states. The module centralizes system state management and provides high-level methods (e.g., `PingAndConnect`, `UpdateConfig`, `StartRealtime`) that configure and fire state transitions with associated parameters and callbacks. It acts as the orchestrator for hardware initialization, configuration, diagnostics, and real-time data acquisition workflows.
## 2. Public Interface
### `enum Trigger`
- **Definition**: `enum Trigger { PingAndConnect, Reset, ResolveChannelsAuto, ResolveChannelsManual, ApplyConfiguration, TurnOffExcitation, Cancel, Finish, Arm, StartRealtime, RequeryDevice, Download }`
- **Behavior**: Defines the set of events that can cause state transitions in the state machine. Each trigger corresponds to a specific user or system-initiated action.
### `interface IDASState`
- **Properties**:
- `Status Status { get; }` — Returns the shared `Status` object (see `DASState`).
- `IDASFactory DASFactory { get; set; }` — Factory used to create DAS components.
- `Action OnEntry { get; }` — Action to execute on state entry (defaults to `OnEnterState`).
- `Action OnExit { get; }` — Action to execute on state exit (defaults to `OnExitState`).
- `State State { get; }` — The enum value representing this state.
- **Methods**:
- `void OnEnterState()` — Virtual method called on state entry (logs state name).
- `void OnExitState()` — Virtual method called on state exit (logs state name).
### `interface IDASStateWithSelector : IDASState`
- **Methods**:
- `IDASState StateSelector()` — Returns the next state to transition to dynamically (used for conditional transitions).
### `abstract class DASState : IDASState`
- **Properties**:
- `IDASFactory DASFactory { get; set; }`
- `abstract State State { get; }`
- `virtual Action OnEntry { get => OnEnterState; }`
- `virtual Action OnExit { get => OnExitState; }`
- **Properties**:
- `Status Status { get; }` — Returns the *shared static* `_status` instance (see **Gotchas**).
- **Methods**:
- `virtual void OnEnterState()` — Logs `"Enter {State} State"`.
- `virtual void OnExitState()` — Logs `"Exit {State} State"`.
### `abstract class DASStateSelector : DASState, IDASStateWithSelector`
- **Methods**:
- `public abstract IDASState StateSelector();` — Must be implemented to determine dynamic next state.
### `enum State`
- **Definition**: `enum State { Prepare, HardwareDiscovery, HardwareDiscoveryStart, Configure, ConfigureStart, Diagnose, Realtime, Arming, Arm, Download, RealtimeStart, DownloadStart }`
- **Behavior**: Defines the set of states in the state machine. Some states (`HardwareDiscoveryStart`, `ConfigureStart`, `RealtimeStart`, `DownloadStart`, `Diagnose`, `Configure`) are *selector states* (implement `IDASStateWithSelector`), others are simple states.
### `class States`
- **Properties** (singleton access to state instances):
- `IDASState Prepare`, `HardwareDiscovery`, `Download`, `Arming`, `Arm`, `Realtime`
- `IDASStateWithSelector HardwareDiscoveryStart`, `DownloadStart`, `Diagnose`, `Configure`, `ConfigureStart`, `RealtimeStart`
- **Methods**:
- `public static void SetDASFactory(IDASFactory dasFactory)` — Assigns the factory to all state instances.
- `public IDASState GetIDASState(State state)` — Returns the state object for a given `State` enum.
- `public static States Instance { get; }` — Singleton instance.
### `class StateMachineBootstrap`
- **Constructor**:
- `StateMachineBootstrap(IDASFactory dasFactory = null)` — Initializes the state machine with `Prepare` as the initial state, sets up logging, and calls `Configure()`.
- **Public Methods**:
- `void TurnOffExcitation(...)` — Configures `ConfigureStart` parameters to skip power and set `TurnOffExcitation = true`, then fires `Trigger.TurnOffExcitation`.
- `void PrepareForDiagnostics(...)` — Configures `ConfigureStart` parameters for diagnostics (`PrepareForDiagnostics = true`, `SetConfiguration = false`, etc.), then fires `Trigger.ApplyConfiguration`.
- `void UpdateConfig(...)` — Configures `ConfigureStart` parameters for full configuration, then fires `Trigger.ApplyConfiguration`.
- `void PingAndConnectAndCheckHardware(...)` — Configures `HardwareDiscovery` parameters with full hardware checks, then fires `Trigger.PingAndConnect`.
- `void PingAndConnect(...)` — Same as above, but sets `DoHardwareChecks = false`.
- `void RequeryDevice(IDASCommunication device, ...)` — Configures `HardwareDiscovery` to requery a specific device, then fires `Trigger.RequeryDevice`.
- `void Ping(bool UseUDPDiscovery, string[] ipAddresses, ...)` — Fires `Trigger.PingAndConnect` with `Connect = false`.
- `void StartRealtime(...)` — Configures `Realtime` parameters and fires `Trigger.StartRealtime`.
- `void StopRealtime()` — Calls `StopRealtime()` on the `Realtime` state’s status object.
- `bool IsInRealtime { get; }` — Returns `IsInRealtime` from `Realtime` state’s status.
- `void Reset()` — Fires `Trigger.Reset` and resets the shared `Status` object.
- **Private Helper Methods** (used internally by public methods):
- `GetConfigureStatus()`, `GetConfigureParameters()`
- `GetDiagnoseParameters()`
- `GetPingAndConnectParameters()`, `GetPingAndConnectStatus()`
- `GetRealtimeParameters()`, `GetRealtimeStatus()`
- **Private Methods (internal testing/simulation)**:
- `void Configure()` — Defines all state machine transitions (see **Dependencies**).
- `void GenerateStateMachineGraph()` — Outputs DOT graph for visualization.
- `void Start()`, `SimulatePingAndConnectComplete()`, `SimulatePingAndConnectWithCancel()`, `BasicInfoToDiagnostics()`, `BasicInfoToRealtime()`, `StartAndStopRealtime()`, `ResolveChannelsAuto()`, `ResolveChannelsManual()`, `ApplyConfiguration()` — Internal simulation/test methods.
## 3. Invariants
- **Shared Status Object**: All `DASState` instances share the *same* static `Status` instance (`_status`). This is explicitly noted in the source as a temporary design decision to prevent accidental duplication.
- **State Hierarchy**: States like `HardwareDiscoveryStart`, `ConfigureStart`, `RealtimeStart`, `DownloadStart` are substates of their parent states (`HardwareDiscovery`, `Configure`, `Realtime`, `Download` respectively).
- **Dynamic Transitions**: Transitions using `PermitDynamicIf` (e.g., `Trigger.Finish` from `HardwareDiscoveryStart`, `RealtimeStart`, `Diagnose`) rely on the `StateSelector()` method of the current state to determine the next state.
- **Trigger Semantics**:
- `Trigger.Finish` always transitions to the parent state (via `StateSelector()`).
- `Trigger.Cancel` transitions back to the parent state (e.g., `ConfigureStart` → `Configure`).
- `Trigger.Reset` transitions to `Prepare`.
- **State Entry/Exit Logging**: Every state logs entry/exit via `Console.WriteLine`, unless overridden.
## 4. Dependencies
### Imports/Usings (from source):
- `Stateless` — Core state machine library.
- `DTS.Common.Interface.DASFactory` — Defines `IDASFactory`.
- `DTS.Common.Interface.StatusAndProgressBar` — Defines `Status`, `StatusIntDelegate`, `StatusExIntDelegate`, `SetProgressValueDelegate`, `ActionCompleteDelegate`.
- `DTS.Common.Interface.DataRecorders` — Defines `IDASCommunication`, `IDASHardware`, `IDiscoveredDevice`.
- `DTS.Common.Utilities.Logging` — Defines `TextLogger`, `APILogger`.
- `DTS.Common.Classes.DSP` — Defines `DSPFilterType`.
- `System`, `System.Linq`, `System.Collections.Generic`, `System.Text`, `System.Windows.Forms`, `System` — Standard .NET types.
### Inferred Dependencies:
- **External Libraries**:
- `Stateless` (NuGet package for state machine).
- `DTS.Common.*` — Internal libraries for factory, status, data recorders, utilities, DSP, and logging.
- **Consumers**:
- `StateMachineBootstrap` is the primary public-facing class; it is instantiated and used by higher-level application logic (e.g., UI or service layer).
- `States.Instance` is used by `StateMachineBootstrap` to access state objects and by `Configure()` to set up transitions.
## 5. Gotchas
- **Shared Static Status**: All states share the same `Status` instance (`_status`). Modifying status in one state affects all others. This is explicitly flagged in `DASState.cs` as a short-term measure pending refactoring.
- **`Trigger.PingAndConnect` Reuse**: The `Ping`, `PingAndConnect`, `PingAndConnectAndCheckHardware`, and `RequeryDevice` methods all fire the *same* trigger (`Trigger.PingAndConnect`) but configure different parameters in `HardwareDiscovery`’s status/params. The behavior is determined entirely by parameter state, not the trigger itself.
- **`Trigger.ResolveChannelsAuto`/`ResolveChannelsManual`**: These triggers are `PermitReentry`, meaning they do not change state but re-trigger the current state (`Configure`). Their implementation is empty in `StateMachineBootstrap` (no-op stubs), suggesting logic is elsewhere or incomplete.
- **`Download` State Disabled**: The `Download` and `DownloadStart` state configurations are commented out in `Configure()`, indicating this functionality is not currently active.
- **Console Logging Only**: `OnEnterState`/`OnExitState` log to `Console.WriteLine`, not the `TextLogger`. Real logging is done manually in public methods via `APILogger.StateLog`.
- **Hardcoded Simulation Logic**: Methods like `SimulatePingAndConnectComplete()` and `BasicInfoToRealtime()` contain hardcoded IP ranges and test sequences, suggesting they are for unit testing or demos and should not be used in production.
- **`StateSelector()` Implementation Not Visible**: The `StateSelector()` implementations for selector states (e.g., `HardwareDiscoveryStart`, `ConfigureStart`) are not included in the provided source, so their transition logic is unknown.
- **`Trigger.Download` Not Used**: The `Download` state exists in the `State` enum but is not wired into the state machine configuration (`Configure()`), and no public method uses `Trigger.Download`.

128
enriched-qwen3-coder-next/DataPRO/IService/StateMachine/States.md Normal file
View File

@@ -0,0 +1,128 @@
---
source_files:
- DataPRO/IService/StateMachine/States/Arm.cs
- DataPRO/IService/StateMachine/States/Arming.cs
- DataPRO/IService/StateMachine/States/Realtime.cs
- DataPRO/IService/StateMachine/States/Download.cs
- DataPRO/IService/StateMachine/States/HardwareDiscovery.cs
- DataPRO/IService/StateMachine/States/Prepare.cs
- DataPRO/IService/StateMachine/States/ConfigureStart.cs
- DataPRO/IService/StateMachine/States/RealtimeStart.cs
- DataPRO/IService/StateMachine/States/Configure.cs
- DataPRO/IService/StateMachine/States/Diagnose.cs
- DataPRO/IService/StateMachine/States/DownloadStart.cs
- DataPRO/IService/StateMachine/States/HardwareDiscoveryStart.cs
generated_at: "2026-04-16T04:00:35.991960+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "dc1b1b8c07850591"
---
# States
## Documentation: StateMachine States Module
### 1. Purpose
This module defines the concrete state implementations for the DAS (Data Acquisition System) service state machine. Each class represents a terminal or selector state in the state transition graph, encapsulating entry actions and transition logic. The states manage transitions between operational modes such as hardware discovery, configuration, arming, real-time acquisition, and data download. The module serves as the behavioral core of the state machine, where transitions are determined by runtime status flags and configuration parameters.
### 2. Public Interface
All classes inherit from `DASState` (or `DASStateSelector` for selector states) in the `DTS.DASLib.Service.StateMachine` namespace. Only `Realtime`, `ConfigureStart`, `RealtimeStart`, `Configure`, `Diagnose`, `DownloadStart`, and `HardwareDiscoveryStart` are `public`; the rest are `internal`.
#### Terminal States (non-selector, inherit `DASState`)
- **`public class Realtime : DASState`**
Represents the active real-time acquisition state. Returns `State.Realtime` via the `State` property. No custom entry action.
- **`internal class Arm : DASState`**
Represents the armed (ready but not yet acquiring) state. Returns `State.Arm`.
- **`internal class Arming : DASState`**
Represents the transitional arming state. Returns `State.Arming`.
- **`internal class Download : DASState`**
Represents the data download state. Returns `State.Download`.
- **`internal class HardwareDiscovery : DASState`**
Represents the hardware discovery state. Returns `State.HardwareDiscovery`.
- **`internal class Prepare : DASState`**
Represents the prepare state. Overrides `OnEntry` to invoke `PrepareDASFactory`, which detaches all devices and clears host name arrays in `DASFactory` (if non-null). Returns `State.Prepare`.
#### Selector States (inherit `DASStateSelector`)
- **`public class ConfigureStart : DASStateSelector`**
Entry action: `ApplyConfig`, which calls `Status.ConfigureStatus.ApplyConfig()`.
Selector logic: Always returns `States.Instance.Diagnose`.
Returns `State.ConfigureStart`.
- **`public class RealtimeStart : DASStateSelector`**
Entry action: `Start`, which calls `Status.RealtimeStatus.StartRealtime()`.
Selector logic:
- If `Status.RealtimeStatus.CouldNotStartRealtime` is true → returns `States.Instance.RealtimeStart` (retry loop).
- Else → returns `States.Instance.Realtime`.
Returns `State.RealtimeStart`.
- **`public class Configure : DASStateSelector`**
Selector logic:
- `AllowApplyConfig()` currently always returns `true` (placeholder logic).
- If true → returns `States.Instance.ConfigureStart`.
- Else → returns `States.Instance.Configure` (self-loop).
Returns `State.Configure`.
- **`public class Diagnose : DASStateSelector`**
Selector logic:
- Returns `States.Instance.RealtimeStart` if either:
(a) `Status.DiagnoseParams.ProceedToRealtimeWhenDone && Status.DiagnoseParams.AllUnitsPassedDiagnostic`, or
(b) `Status.DiagnoseParams.ProceedToRealtimeWhenDone && !Status.DiagnoseParams.RequireAllUnitsPassDiagnostic`.
- Else → returns `States.Instance.Diagnose` (self-loop).
Returns `State.Diagnose`.
- **`public class DownloadStart : DASStateSelector`**
Entry action: `Start`, which calls `Status.DownloadStatusInfo.Download()`.
Selector logic:
- Returns `States.Instance.Prepare` if `CanTransitToPrepare()` is true:
`Status.DownloadParams.ProceedWhenDone && (Status.DownloadStatusInfo.AllDASFinished || !Status.DownloadParams.RequireAllDASFinish)`.
- Else → returns `States.Instance.Download` (self-loop).
Returns `State.DownloadStart`.
- **`public class HardwareDiscoveryStart : DASStateSelector`**
Entry action: `Start`, which calls either `RequeryDevice()` or `Ping()` on `Status.HardwareDiscoveryStatusInfo`, depending on whether `Status.HardwareDiscoveryParams.RequeryDevice` is non-null.
Selector logic (evaluated in order):
- `CanTransitToDownload()` → returns `States.Instance.Download`
- `CanTransitToConfigure()` → returns `States.Instance.Configure`
- `CanTransitToArm()` → returns `States.Instance.Arm`
- Else → returns `States.Instance.HardwareDiscovery` (self-loop)
Where:
- `CanTransitToConfigure()`: `Status.HardwareDiscoveryParams.ProceedWhenDone && (Status.HardwareDiscoveryStatusInfo.AllDASFound || !Status.HardwareDiscoveryParams.RequireAllDASFound)`
- `CanTransitToArm()`: `Status.HardwareDiscoveryParams.ProceedWhenDone && Status.HardwareDiscoveryStatusInfo.SomeUnitsInArmState`
- `CanTransitToDownload()`: `CanTransitToConfigure() && Status.HardwareDiscoveryParams.GoToDownload`
Returns `State.HardwareDiscoveryStart`.
### 3. Invariants
- Every state class must override the `State` property to return its corresponding `State` enum value (e.g., `State.Prepare`, `State.Realtime`).
- Selector states (`DASStateSelector` subclasses) must implement `StateSelector()` to return an `IDASState` (typically via `States.Instance.<StateName>`).
- Terminal states (`DASState` subclasses) may optionally override `OnEntry` to define entry behavior; if not overridden, no entry action is executed.
- The `OnEntry` action (if present) must call `OnEnterState()` as its first operation (observed in `Prepare`, `ConfigureStart`, `RealtimeStart`, `DownloadStart`, `HardwareDiscoveryStart`).
- Transition decisions in selector states are based solely on `Status.*` properties and `Status.*Params` configuration objects.
- No state class performs side effects outside of `OnEntry` or `StateSelector()`.
### 4. Dependencies
- **Internal dependencies (from source):**
- `DASState` and `DASStateSelector` base classes (not shown, but implied by inheritance).
- `State` enum (used in `State` property overrides).
- `States.Instance` singleton (used to reference other states, e.g., `States.Instance.Diagnose`).
- `Status` object with nested properties:
- `ConfigureStatus`, `RealtimeStatus`, `DiagnoseParams`, `DownloadStatusInfo`, `DownloadParams`, `HardwareDiscoveryParams`, `HardwareDiscoveryStatusInfo`.
- `DASFactory` (used in `Prepare.PrepareDASFactory()`; assumed to be a member of the base `DASState` class or accessible via `this`).
- **External dependencies (inferred):**
- `System` and related namespaces (e.g., `System.Threading.Tasks`).
- Likely depends on a larger `DTS.DASLib.Service` assembly containing `Status`, `States`, and base state classes.
### 5. Gotchas
- **Incomplete logic in `Configure.AllowApplyConfig()`**: Currently always returns `true`; no actual validation of channel resolution or placement is implemented despite comments indicating intent.
- **Selector state ordering matters**: In `HardwareDiscoveryStart`, transitions are evaluated in a specific order (Download → Configure → Arm → self-loop). Changing this order could alter behavior.
- **Self-loops may cause infinite loops**: States like `Configure`, `Diagnose`, `Download`, and `HardwareDiscovery` can loop to themselves if conditions are not met; external triggers or status changes are required to exit.
- **Ambiguous `DASFactory` usage**: `PrepareDASFactory()` references `DASFactory` without clear scoping—assumed to be a member of the base class, but not declared in the provided source.
- **No explicit error handling**: Entry actions (e.g., `StartRealtime()`, `Download()`) may throw exceptions; no try/catch is visible in the source.
- **`RealtimeStart` selector logic may retry indefinitely**: If `CouldNotStartRealtime` remains true, the state machine will loop back to `RealtimeStart` without backoff or failure reporting.
- **`RequeryDevice()` vs `Ping()` behavior**: The condition `null != Status.HardwareDiscoveryParams.RequeryDevice` suggests `RequeryDevice` is a delegate or method group, but its type and semantics are not evident from this file.

127
enriched-qwen3-coder-next/DataPRO/IService/StateMachine/StatusAndParameters.md Normal file
View File

@@ -0,0 +1,127 @@
---
source_files:
- DataPRO/IService/StateMachine/StatusAndParameters/IStatusInfo.cs
- DataPRO/IService/StateMachine/StatusAndParameters/IStatusParameters.cs
- DataPRO/IService/StateMachine/StatusAndParameters/GlobalStatusParameters.cs
- DataPRO/IService/StateMachine/StatusAndParameters/Status.cs
- DataPRO/IService/StateMachine/StatusAndParameters/GlobalStatusInformation.cs
generated_at: "2026-04-16T04:00:12.173977+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "9b91ae827f1dd2a6"
---
# StatusAndParameters
## Documentation: State Machine Status and Parameters Module
---
### 1. Purpose
This module defines the core data structures and interfaces for tracking and managing the runtime state and configuration parameters of a distributed acquisition system (DAS) within the state machine framework. It provides typed containers for *status information* (read-only or observation-oriented state, e.g., device presence in certain operational modes) and *status parameters* (configurable settings that influence behavior, e.g., multicast or auto-sense flags). The `Status` class aggregates all such state and parameter objects into a single, resettable snapshot used by the state machine to make decisions and coordinate subsystems.
---
### 2. Public Interface
#### Interfaces
- **`IStatusInfo`**
```csharp
void Reset();
```
Marker interface for status information types that support resetting to default state. No behavior beyond `Reset()` is defined here.
- **`IStatusParameters`**
```csharp
void Reset();
```
Marker interface for status parameter types that support resetting to default values. No behavior beyond `Reset()` is defined here.
#### Concrete Classes
- **`GlobalStatusParameters`** *(implements `IStatusParameters`)*
```csharp
public bool AllowUDPMulticast { get; set; } = true;
public bool DisableAutoSense { get; set; } = SensorConstants.DisableAutoSense;
public void Reset();
```
Holds global configuration flags. `Reset()` restores `AllowUDPMulticast` to `true` and `DisableAutoSense` to `SensorConstants.DisableAutoSense`.
- **`Status`** *(aggregate container)*
```csharp
public HardwareDiscoveryParameters HardwareDiscoveryParams;
public HardwareDiscoveryStatusInfo HardwareDiscoveryStatusInfo;
public GlobalStatusInformation GlobalStatusInformation;
public GlobalStatusParameters GlobalStatusParameters;
public ConfigureStatusInformation ConfigureStatus;
public ConfigureStatusParameters ConfigureParameters;
public RealtimeStatusInformation RealtimeStatus;
public RealtimeParameters RealtimeParams;
public DiagnoseParameters DiagnoseParams;
public DownloadParameters DownloadParams;
public DownloadStatusInformation DownloadStatusInfo;
public void Reset();
```
Central state container. `Reset()` invokes `Reset()` on all contained sub-objects *except* `DownloadStatusInfo` and `DownloadParams` (note: these are omitted from `Reset()`).
> ⚠️ **Observed omission**: `DownloadStatusInfo.Reset()` and `DownloadParams.Reset()` are *not* called in `Status.Reset()`, despite both being declared as fields.
- **`GlobalStatusInformation`** *(implements `IStatusInfo`)*
```csharp
public IDASCommunication[] GetUnitsInRealtime();
public void AddUnitInRealtime(IDASCommunication device);
public IDASCommunication[] GetUnitsInArm();
public void AddUnitInArm(IDASCommunication device);
public IDASCommunication[] GetUnitsAtLowPower();
public void AddUnitAtLowPower(IDASCommunication das);
public IDASCommunication[] GetUnitsAtHighPower();
public void AddUnitAtHighPower(IDASCommunication das);
public bool ExcitationOn { get; set; } = false;
public void Reset();
```
Tracks device presence and power/excitation state.
- `AddUnitInRealtime`, `AddUnitInArm`, `AddUnitAtLowPower`, `AddUnitAtHighPower` are idempotent (no-op if device already present).
- `AddUnitAtLowPower` removes device from `_unitsAtHighPower` if present.
- `AddUnitAtHighPower` removes device from `_unitsAtLowPower` if present.
- `Reset()` clears all device lists and sets `ExcitationOn = false`.
---
### 3. Invariants
- **Thread Safety**: All list-modifying operations in `GlobalStatusInformation` are guarded by a private static `lock (MyLock)`. Reads via `Get*()` methods are also lock-protected.
- **Mutual Exclusivity**: A device cannot be simultaneously in `_unitsAtLowPower` and `_unitsAtHighPower`. Adding to one list removes it from the other.
- **Idempotency**: `AddUnit*()` methods silently ignore duplicate additions (checked via `Contains()` before adding).
- **Reset Scope**: `Status.Reset()` does *not* reset `DownloadStatusInfo` or `DownloadParameters` (per source code).
- **Default Values**:
- `GlobalStatusParameters.AllowUDPMulticast` defaults to `true`.
- `GlobalStatusParameters.DisableAutoSense` defaults to `SensorConstants.DisableAutoSense`.
- `GlobalStatusInformation.ExcitationOn` defaults to `false`.
---
### 4. Dependencies
#### Imports/References
- **`DTS.Common.Enums.Sensors`**
Used in `GlobalStatusParameters` to initialize `DisableAutoSense` via `SensorConstants.DisableAutoSense`.
- **`DTS.Common.Interface.DASFactory`**
Used in `GlobalStatusInformation` for the `IDASCommunication` interface (device abstraction).
#### Consumed By
- The state machine logic (implied by namespace `DTS.DASLib.Service.StateMachine`).
- Any component needing to inspect or update device status (e.g., `Status` instance likely passed to state handlers).
#### Consumed By (Inferred)
- `GlobalStatusInformation`’s `IDASCommunication` usage implies integration with a device communication layer (e.g., factory-created units implementing `IDASCommunication`).
---
### 5. Gotchas
- **Incomplete Reset**: `Status.Reset()` omits `DownloadStatusInfo` and `DownloadParameters`. This is likely unintentional (both have `Reset()` methods per naming convention), and may cause stale download state to persist across resets.
- **No Removal Methods**: `GlobalStatusInformation` lacks explicit `RemoveUnit*()` methods. Devices are only removed via `Reset()` or implicitly via `AddUnitAtLowPower`/`AddUnitAtHighPower` (which remove from the *opposite* power list). There is no way to remove a device from `Realtime` or `Arm` lists except via `Reset()`.
- **Static Lock Scope**: The `MyLock` object is `static`, meaning all instances of `GlobalStatusInformation` share the same lock. This could cause contention if multiple `GlobalStatusInformation` instances are used concurrently (though only one is used via `Status.GlobalStatusInformation`).
- **No Validation in `Add*()`**: Methods like `AddUnitInRealtime` do not validate device state consistency (e.g., allowing a device to be added to both `Realtime` and `Arm` simultaneously is permitted).
- **`DisableAutoSense` Initialization**: Default value depends on `SensorConstants.DisableAutoSense`, whose value is not visible here. Its semantics (e.g., `true` = disable auto-sense?) must be verified in `DTS.Common.Enums.Sensors`.
None identified beyond those above.

339
enriched-qwen3-coder-next/DataPRO/IService/StateMachine/StatusAndParameters/Configure.md Normal file
View File

@@ -0,0 +1,339 @@
---
source_files:
- DataPRO/IService/StateMachine/StatusAndParameters/Configure/GroupChannelWithMeta.cs
- DataPRO/IService/StateMachine/StatusAndParameters/Configure/ConfigureStatusParameters.cs
- DataPRO/IService/StateMachine/StatusAndParameters/Configure/ConfigureStatusInformation.cs
generated_at: "2026-04-16T04:01:25.793483+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "14ca5b532e4bb3a2"
---
# Configure
## Documentation: `ConfigureStatusParameters` and `ConfigureStatusInformation` Module
---
### 1. **Purpose**
This module provides the state and control logic for the *configuration phase* of the DAS (Data Acquisition System) lifecycle, specifically handling channel assignment resolution, hardware configuration application, and power/excitation state transitions. It enables asynchronous configuration of multiple DAS units with rich metadata about channel conflicts, missing sensors, and hardware incompatibilities, while supporting both production and diagnostic workflows. The module decouples configuration intent (expressed via `ConfigureStatusParameters`) from runtime state and progress tracking (managed by `ConfigureStatusInformation`), allowing integration with UI, testing, or headless environments via delegates.
---
### 2. **Public Interface**
#### `ConfigureStatusParameters`
- **`public bool RequireIdFoundForSensorsWithIds { get; set; } = true;`**
If `true`, sensors with a non-empty EID must be found on the configured hardware; otherwise, configuration may proceed without them.
- **`public bool AllowMissingSensors { get; set; } = false;`**
If `true`, allows channels to be assigned without a corresponding sensor (e.g., for dummy testing).
- **`public bool AllowSensorsOutOfPosition { get; set; } = true;`**
If `true`, permits sensors to be assigned to channels other than their specified physical position.
- **`public ITestSetup TestSetupConfiguration { get; set; }`**
Reference to the test setup configuration used during channel resolution.
- **`public delegate ISensorData GetSensorDelegate(IGroupChannel groupChannel);`**
Delegate to retrieve sensor metadata (`ISensorData`) for a given group channel.
- **`public GetSensorDelegate GetSensorAction { get; set; }`**
Implementation of `GetSensorDelegate`; required for sensor lookup during channel resolution.
- **`public delegate ISensorCalibration GetSensorCalibrationDelegate(ISensorData sensor, ExcitationVoltageOptions.ExcitationVoltageOption excitation);`**
Delegate to retrieve calibration data for a sensor under a specific excitation.
- **`public GetSensorCalibrationDelegate GetCalibrationAction { get; set; }`**
Implementation of `GetSensorCalibrationDelegate`; used to apply calibration to hardware channels.
- **`public delegate int GetDatabaseIdDelegate(IDASCommunication das);`**
Delegate to map a DAS unit to its database ID.
- **`public GetDatabaseIdDelegate GetDatabaseIdAction { get; set; }`**
Implementation of `GetDatabaseIdDelegate`; used to correlate hardware units with database records.
- **`public delegate void SetSensorCalibrationDelegate(ISensorData sd, ISensorCalibration sc);`**
Delegate to persist calibration data back to the sensor.
- **`public SetSensorCalibrationDelegate SetSensorCalibrationAction { get; set; }`**
Implementation of `SetSensorCalibrationDelegate`.
- **`public bool AllowSensorIdToBlankChannel { get; set; }`**
If `true`, allows assignment of a sensor with an EID to a channel that has no EID (blank channel).
- **`public bool TurnOffExcitation { get; set; } = false;`**
Flag indicating that excitation should be turned off *before* applying configuration. Reverted upon starting the turn-off process.
- **`public IDASCommunication[] UnitsToConfigure { get; set; } = new IDASCommunication[0];`**
Array of DAS units to be configured.
- **`public bool DoStrictCheck { get; set; } = true;`**
If `true`, perform strict validation of configuration (e.g., hardware compatibility, EID match).
- **`public bool EventConfig { get; set; } = true;`**
If `true`, write configuration to the *event* file store (legacy SLICE feature); otherwise, use the *diagnostic* store.
- **`public bool DummyConfig { get; set; } = false;`**
If `true`, perform configuration for dummy (non-data-collecting) mode.
- **`public double[] MaxAAF { get; set; } = new double[0];`**
Array of maximum Anti-Alias Filter (AAF) rates per unit (used for SLICE/TDAS).
- **`public bool ConfigureDigitalOutputs { get; set; } = true;`**
If `true`, configure digital outputs; set to `false` to skip (e.g., for trigger checks).
- **`public ErrorCallback ErrorRequiringActionAction { get; set; }`**
Callback invoked when user interaction is required (e.g., AAF errors).
- **`public bool TurnOffAAFRealtime { get; set; } = true;`**
If `true`, disable AAF for real-time acquisition to reduce latency.
- **`public bool ResetHardwareEventLines { get; set; } = false;`**
If `true`, reset hardware event lines before applying configuration.
- **`public bool PrepareForDiagnostics { get; set; } = false;`**
If `true`, prepare units for diagnostics (e.g., turn on excitation, switches) after configuration.
- **`public IReadOnlyDictionary<string, double> SampleRateLookup { get; set; } = new Dictionary<string, double>();`**
Lookup table mapping unit serial numbers to data collection sample rates.
- **`public IReadOnlyDictionary<string, float> AAFRateLookup { get; set; } = new Dictionary<string, float>();`**
Lookup table mapping unit serial numbers to AAF rates.
- **`public bool SkipTurnOnPower { get; set; } = false;`**
If `true`, skip powering up units after configuration (e.g., to keep units in low-power state).
- **`public bool SetConfiguration { get; set; } = true;`**
If `true`, actually write configuration to hardware; if `false`, only prepare for diagnostics.
- **`public DSPFilterType DSPFilterType { get; set; }`**
DSP filter type to apply during configuration.
- **`public bool DiscardDiagnostics { get; set; } = true;`**
If `true`, discard existing diagnostic data before applying new configuration.
- **`public ConfigureStatusParameters()`**
Constructor; initializes `DSPFilterType` via `ResetDSPFilterType()`.
- **`public void Reset()`**
Resets all properties to their default values.
- **`public override string ToString()`**
Returns a human-readable string representation of all configuration parameters.
---
#### `ConfigureStatusInformation`
- **`public enum StatusValues { ... }`**
Enum of possible status notifications (e.g., `ApplyingConfiguration`, `Completed`, `ChannelOutOfPosition`, `EIDNotFound`, `LowPowerSuccess`, etc.).
- **`public bool NoChannelsAssigned { get; internal set; } = true;`**
`true` if no channels have been assigned yet.
- **`public bool AllChannelsResolved { get; internal set; } = false;`**
`true` if all channels requiring resolution have been successfully resolved.
- **`public bool ChannelsOutOfPosition { get; internal set; } = false;`**
`true` if one or more sensors are assigned to channels other than their specified position.
- **`public bool HaveAppliedConfigAllUnits { get; set; } = false;`**
`true` if all units in `UnitsToConfigure` were successfully configured.
- **`public ManualResetEvent CancelEvent { get; }`**
Signaled to request cancellation of ongoing tasks.
- **`public ManualResetEvent DoneEvent { get; }`**
Signaled when all work (configuration, power, diagnostics) is complete.
- **`public ActionCompleteDelegate CompleteAction { get; set; }`**
Callback invoked on completion of the configuration process.
- **`public SetProgressValueDelegate ProgressAction { get; set; }`**
Callback invoked with progress updates (0–100).
- **`public StatusIntDelegate StatusAction { get; set; }`**
Callback invoked with `StatusValues` enum values.
- **`public StatusExIntDelegate StatusExAction { get; set; }`**
Callback invoked with extended status (e.g., per-unit success/failure).
- **`public IDASCommunication[] UnitsConfigured { get; set; } = new IDASCommunication[0];`**
List of units successfully configured.
- **`public async Task Cancel()`**
Initiates cancellation: sets `CancelEvent`, waits for completion, and reports `Cancelling`/`Cancelled` status.
- **`public void TurnOffExcitation()`**
Asynchronously turns off excitation on all units, updates global `ExcitationOn` status, and signals `LowPowerSuccess`/`LowPowerFailure`.
- **`public void ApplyConfig()`**
Starts asynchronous configuration process:
- If `TurnOffExcitation` is set, invokes `TurnOffExcitation()` first.
- Otherwise, applies configuration via `ConfigurationService.SetConfiguration(...)`.
- If `PrepareForDiagnostics` is set and `SkipTurnOnPower` is `false`, calls `PrepareForDiagnostics()`.
- **`public void ManuallyResolveChannel(IGroupChannel channel, IDASChannel hardwareChannel)`**
Manually assigns a hardware channel to a group channel. Validates:
- Channel is not blank/disabled.
- Sensor exists and is compatible.
- Hardware channel is not already assigned.
- EID constraints (if sensor has EID, and `AllowSensorIdToBlankChannel` is `false`, EID must match).
Throws `InvalidAssignmentException` on failure.
- **`public void ManuallyUnresolveChannel(IGroupChannel channel)`**
Removes manual assignment of a channel. Fails if channel is not resolved or if assignment was EID-locked.
Throws `InvalidAssignmentException`.
- **`public class InvalidAssignmentException : Exception`**
Exception thrown on manual assignment errors.
- **`Reasons` enum**: `BlankChannel`, `NoSensor`, `ChannelDisabled`, `SensorNotFound`, `IncompatibleHardware`, `ChannelAlreadyAssigned`, `EID_Locked`, `EIDRequiredAndMissing`, `ChannelNotAssigned`.
- Contains `GroupChannel` and `Reason`.
- **`public void Reset()`**
Resets all status flags, clears channel resolution lists, and nullifies delegates.
---
#### `GroupChannelWithMeta` *(internal helper)*
- **`public bool ChannelConflict { get; set; }`**
`true` if this channel conflicts with another assignment.
- **`public IGroupChannel ConflictingChannel { get; set; }`**
Reference to the conflicting channel (if any).
- **`public IGroupChannel Channel { get; set; }`**
The group channel being described.
- **`public IGroup Group { get; set; }`**
The group containing the channel.
- **`public bool MissingID { get; set; }`**
`true` if sensor EID is missing (but expected).
- **`public bool MissingSensor { get; set; }`**
`true` if no sensor is associated with the channel.
- **`public bool EIDOutOfPlace { get; set; }`**
`true` if the sensor’s EID is present but assigned to a different channel than expected.
- **`public bool HWNotFound { get; set; }`**
`true` if the hardware channel could not be found.
- **`public bool HWChannelIncompatible { get; set; }`**
`true` if the hardware channel is incompatible with the sensor.
- **`public IDASChannel DASChannel { get; set; }`**
The resolved hardware channel (if any).
- **`public bool AssignedByEID { get; set; }`**
`true` if this channel was auto-resolved via EID matching.
---
### 3. **Invariants**
- **Channel Resolution State**:
A channel is *either* in `_resolvedChannels` *or* `_unresolvedChannels`, never both.
`IsResolved(ch)` and `IsUnresolved(ch)` are mutually exclusive.
- **Hardware Channel Uniqueness**:
A hardware channel (`IDASChannel`) may be assigned to *only one* group channel at a time. Enforced in `AddResolvedChannel` and `ManuallyResolveChannel`.
- **EID Locking**:
If a channel is resolved via EID (`AssignedByEID == true`), it cannot be manually reassigned to a different hardware channel (`EID_Locked` exception).
- **Sensor Compatibility**:
`IsSensorHwCompatible` enforces strict compatibility rules:
- Bridge mode must match.
- Digital input mode must match (if applicable).
- Supported excitation must exist *and* have calibration data.
- Squib/Digital Output sensors must match their respective hardware types.
- **Configuration Atomicity**:
`ApplyConfig` only proceeds to `PrepareForDiagnostics` if no cancellation occurred (`!CancelEvent.WaitOne(...)`).
- **Excitation State Consistency**:
Global `ExcitationOn` status is updated only after successful `TurnOffExcitation` or `PrepareForDiagnostics`.
- `TurnOffExcitation` → sets `ExcitationOn = false` on success.
- `PrepareForDiagnostics` → sets `ExcitationOn = true` on success.
---
### 4. **Dependencies**
#### **Imports / Dependencies Used**
- **`DTS.Common.Interface.*`**:
- `Channels` (`IGroupChannel`, `IDASChannel`, `AnalogInputDASChannel`, etc.)
- `DASFactory` (`IDASCommunication`, `IDASFactory`)
- `Sensors` (`ISensorData`, `ISensorCalibration`)
- `StatusAndProgressBar` (`IStatusInfo`, `IStatusParameters`, delegates)
- `Groups.GroupList` (`IGroup`)
- `TestSetups.TestSetupsList` (`ITestSetup`)
- **`DTS.Common.Classes.DSP`**: `DSPFilterCollection`, `DSPFilterType`
- **`DTS.Common.Enums`**: `ExcitationVoltageOptions`
- **`DTS.DASLib.Service.StateMachine.StatusAndParameters.Configure`**: `GroupChannelWithMeta`
- **`DTS.DASLib.Service.StateMachine`**: `States.Instance.ConfigureStart.Status.*`, `ConfigurationService`, `DiagnosticsService`, `ArmingService`
- **`System.Threading.Tasks`**: `Task`, `Task.Run`
- **`System.Collections.Generic`**, **`System.Linq`**, **`System.Text`**, **`System.Threading`**, **`System`**
#### **Consumers / Usage**
- **`ConfigureStatusParameters`** is used by:
- `ConfigurationService.SetConfiguration(...)` (to receive configuration intent)
- UI or test harness to configure behavior before invoking `ApplyConfig()`
- **`ConfigureStatusInformation`** is used by:
- `ConfigurationService.SetConfiguration(...)` (to report progress/status)
- `DiagnosticsService.PrepareForDiagnostics(...)`
- `ArmingService.EnterLowPowerMode(...)`
- UI to monitor and control configuration state (via delegates)
- **`GroupChannelWithMeta`** is used internally by `ConfigureStatusInformation` to track channel resolution state.
---
### 5. **Gotchas**
- **`AllChannelsResolved` Logic Inversion**:
`AllChannelsResolved` is set to `true` when `_unresolvedChannels.Any()` is `false` (i.e., *no unresolved channels*), but the property name suggests it should be `true` when *all are resolved*. This is counterintuitive and could cause bugs if misread.
- **`TurnOffExcitation` Flag Reset Timing**:
`param.TurnOffExcitation` is reset to `false` *inside* `TurnOffExcitation()` *before* the task completes. If `ApplyConfig()` is called again before `TurnOffExcitation()` finishes, it may skip re-initiating turn-off.
- **`UnitsToConfigure` Mutability During `ApplyConfig`**:
In `ApplyConfig()`, if a unit in `UnitsToConfigure` is not found in `dasFactory.GetDASList()`, it is *removed from the local list* (`unitsToConfigure`) but *not from the original `param.UnitsToConfigure`*. This can cause `HaveAppliedConfigAllUnits` to be `false` even though no error was reported for that unit.
- **`PrepareForDiagnostics` Spin-Wait**:
`PrepareForDiagnostics()` uses a fixed spin-wait loop (`PREPARE_SPIN_TIME = 200`, `EXPECTED_PREPARE_TIME = 8000`) instead of relying solely on `ManualResetEvent`. Progress is updated manually, but this is inefficient and not cancellation-aware.
- **`InvalidAssignmentException` Message Format**:
The exception message includes the `Reason` enum *and* the channel’s `ToString()` representation. If `IGroupChannel.ToString()` is not informative, debugging may be difficult.
- **`AllowSensorIdToBlankChannel` Default**:
Default is `false`, meaning sensors with EIDs *cannot* be assigned to blank channels unless explicitly allowed. This may be unexpected in test scenarios.
- **`ResetDSPFilterType()` Uses Empty String**:
`ResetDSPFilterType()` calls `GetFilter(string.Empty)`. If the filter collection does not define a default for empty string, this may return an unexpected or null filter.
- **Thread Safety of `UnitsConfigured`**:
`AddConfiguredDevice()` uses `lock(MyLock)` to safely append to `UnitsConfigured`, but `UnitsConfigured` is exposed as a public property. External code could modify the array directly, bypassing the lock.
- **`PrepareForDiagnostics` Fails if `UnitsConfigured` is Empty**:
`PrepareForDiagnostics()` checks `!status.UnitsConfigured.Any()` and fails early. However, `UnitsConfigured` is only populated *during* `ApplyConfig()`. If `PrepareForDiagnostics` is called independently (e.g., in diagnostics-only flow), it will always fail.
- **No Handling of `GetCalibrationAction` Returning `null`**:
In `AddResolvedChannel`, if `GetCalibrationAction` returns `null` for all supported excitations, no calibration is applied, but no error is raised. This may silently leave hardware uncalibrated.
- **`EIDOutOfPlace` Flag Misleading**:
`EIDOutOfPlace` is set only in `AddResolvedChannel`, but never set to `true` in `AddUnresolvedChannel`. It is unclear how out-of-position channels are tracked if they are unresolved.

55
enriched-qwen3-coder-next/DataPRO/IService/StateMachine/StatusAndParameters/Diagnose.md Normal file
View File

@@ -0,0 +1,55 @@
---
source_files:
- DataPRO/IService/StateMachine/StatusAndParameters/Diagnose/DiagnoseParameters.cs
generated_at: "2026-04-16T04:01:12.868254+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "df826cad6b98e03f"
---
# Diagnose
## 1. Purpose
The `DiagnoseParameters` class encapsulates configuration and state-tracking data for a diagnostic phase within a state machine. It determines how the system transitions out of the diagnostic state—specifically whether to proceed to the real-time operational state—and tracks whether all units have passed their diagnostics. This class serves as a parameter object passed to or managed by the diagnostic state handler, enabling configurable behavior (e.g., strict vs. permissive pass requirements) and runtime status updates during diagnostics execution.
## 2. Public Interface
- **`class DiagnoseParameters : IStatusParameters`**
Implements `IStatusParameters` (interface not shown in source) to provide status-related parameters for a diagnostic state.
- **`bool ProceedToRealtimeWhenDone { get; set; }`**
Controls whether the state machine should transition to the real-time state upon successful completion of diagnostics. Default: `true`.
- **`bool RequireAllUnitsPassDiagnostic { get; set; }`**
If `true`, the diagnostic phase is considered successful only if *all* units pass; if `false`, the phase may succeed even if some units fail. Default: `false`.
- **`bool AllUnitsPassedDiagnostic { get; set; }`**
Reflects the actual outcome of the diagnostic run: `true` if all units passed, `false` otherwise. Initialized to `false`.
- **`void Reset()`**
Resets all properties to their default values:
- `ProceedToRealtimeWhenDone` → `true`
- `RequireAllUnitsPassDiagnostic` → `false`
- `AllUnitsPassedDiagnostic` → `false`
## 3. Invariants
- `AllUnitsPassedDiagnostic` must be set by external logic (e.g., diagnostic execution logic) *before* the state machine evaluates transition conditions based on this flag.
- `RequireAllUnitsPassDiagnostic` and `AllUnitsPassedDiagnostic` jointly determine diagnostic success:
- If `RequireAllUnitsPassDiagnostic` is `true`, success requires `AllUnitsPassedDiagnostic == true`.
- If `RequireAllUnitsPassDiagnostic` is `false`, success is assumed regardless of `AllUnitsPassedDiagnostic` (though the exact semantics depend on downstream state machine logic, which is not provided).
- After `Reset()` is called, all properties revert to their documented default values; no partial resets occur.
- `DiagnoseParameters` is a mutable class—consumers must be cautious about shared instances and concurrent access (no thread-safety guarantees are implied by the source).
## 4. Dependencies
- **Depends on**:
- `System` (core .NET namespaces: `System`, `System.Collections.Generic`, `System.Linq`, `System.Text`, `System.Threading.Tasks`).
- `DTS.DASLib.Service.StateMachine` namespace (same assembly/project), specifically the `IStatusParameters` interface.
- **Used by**:
- State machine logic within `DTS.DASLib.Service.StateMachine` (inferred from namespace and class name), particularly code managing the diagnostic state.
- Likely consumed by diagnostic execution components that set `AllUnitsPassedDiagnostic` and by state transition logic that inspects `ProceedToRealtimeWhenDone` and `RequireAllUnitsPassDiagnostic`.
## 5. Gotchas
- **Ambiguous success semantics**: The source does not specify how diagnostic success is determined when `RequireAllUnitsPassDiagnostic` is `false`. It is unclear whether success is automatic, or if other conditions (e.g., `AllUnitsPassedDiagnostic == true`) still apply.
- **No validation in `Reset()`**: The method does not validate or guard against invalid states (e.g., resetting mid-diagnostic), potentially leading to inconsistent behavior if called at inappropriate times.
- **No thread-safety**: The class is a simple POCO with no synchronization primitives; concurrent use without external locking may cause race conditions.
- **No documentation on `IStatusParameters` contract**: Since `IStatusParameters` is not included, it is unknown whether `DiagnoseParameters` is expected to implement additional members or adhere to further constraints.
- **Default behavior may be surprising**: `ProceedToRealtimeWhenDone` defaults to `true`, meaning the system *will* proceed to real-time mode unless explicitly configured otherwise—even if diagnostics fail—unless downstream logic overrides this.

238
enriched-qwen3-coder-next/DataPRO/IService/StateMachine/StatusAndParameters/Download.md Normal file
View File

@@ -0,0 +1,238 @@
---
source_files:
- DataPRO/IService/StateMachine/StatusAndParameters/Download/DownloadParameters.cs
- DataPRO/IService/StateMachine/StatusAndParameters/Download/DownloadStatusInformation.cs
generated_at: "2026-04-16T04:02:01.449211+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "f0aeebaaaf645cc5"
---
# Documentation: Download Parameters and Status Module
## 1. Purpose
This module provides the data structures and execution logic for managing and executing data downloads from DAS (Data Acquisition System) units within a state machine workflow. It consists of two core types: `DownloadParameters`, which holds configuration and runtime state for a download operation, and `DownloadStatusInformation`, which orchestrates the asynchronous download process, handles status reporting, cancellation, and directory management—including special handling for ROI (Region of Interest), Recovery, and folder copying scenarios. The module integrates with the broader state machine (via `States.Instance.DownloadStart`) and depends on DAS communication interfaces and logging utilities.
## 2. Public Interface
### `DownloadParameters`
- **`bool ProceedWhenDone { get; set; } = false;`**
Controls whether the state machine should proceed to the next state after the download completes.
- **`bool RequireAllDASFinish { get; set; } = false;`**
Indicates whether *all* DAS units in `DASList` must successfully finish downloading for the operation to be considered complete.
- **`string DefaultDownloadFolder { get; set; } = string.Empty;`**
Holds the configured base download folder path from the application config file.
- **`bool DefaultUploadBinaries { get; set; } = false;`**
Config flag indicating whether binary data should be uploaded after download.
- **`bool DefaultUploadExports { get; set; } = false;`**
Config flag for uploading exports.
- **`bool DefaultUploadLogs { get; set; } = false;`**
Config flag for uploading logs.
- **`bool DefaultUploadReports { get; set; } = false;`**
Config flag for uploading reports.
- **`bool DefaultUploadSetups { get; set; } = false;`**
Config flag for uploading setup files (e.g., `SETUP`, `DASConfigs`).
- **`IDASCommunication[] DASList { get; set; } = new IDASCommunication[0];`**
Array of DAS units to download data from. Must be non-null and populated before download.
- **`string CurrentTestTestId { get; set; } = string.Empty;`**
Test ID string for the current test session.
- **`string CurrentTestTestIdNode { get; set; } = string.Empty;`**
Test ID node (e.g., folder name) used in the file path hierarchy.
- **`string CurrentTestTestDirectory { get; set; } = string.Empty;`**
Full path to the current test directory.
- **`string CurrentTestOriginalTestDirectory { get; set; } = string.Empty;`**
Full path to the original test directory (used in recovery scenarios).
- **`bool ROI { get; set; } = false;`**
Indicates whether the current download is in ROI mode.
- **`bool Recovery { get; set; } = false;`**
Indicates whether the current download is a recovery operation.
- **`bool FoldersCopied { get; set; }`**
Flag to prevent redundant copying of `DASConfigs`, `SETUP`, `Logs`, `Reports` folders during recovery or re-runs.
- **`ErrorCallback ErrorCallback { get; set; }`**
Callback delegate invoked for user prompts or error notifications (e.g., missing hardware, existing files).
- **`void Reset()`**
Resets all properties to their default values (e.g., empty `DASList`, `false` for all flags, `null` for `ErrorCallback`).
*Note:* Does *not* reset `ROI`, `Recovery`, or `FoldersCopied` to defaults—only explicitly listed properties in the method body.
- **`string ToString()`**
Returns an empty string (no-op implementation).
### `DownloadStatusInformation`
- **`enum StatusValues`**
Defines all possible status messages that can be sent via `StatusAction`:
- `Preparing`, `Downloading`, `CaptureAttributes`, `Failed`, `ROIFailed`, `Completed`, `Cancelling`, `Cancelled`, `CancelledPartial`, `DownloadDirectory`, `MissingHardware`, `NoDataToDownload`, `NotAllChannelsDownloaded`, `ExistingFiles`, `CleaningUp`, `QueryEventData`.
- **`ManualResetEvent CancelEvent = new ManualResetEvent(false);`**
Signaled to request cancellation of the download.
- **`ManualResetEvent DoneEvent = new ManualResetEvent(false);`**
Signaled when the download task completes (successfully, cancelled, or failed).
- **`ActionCompleteDelegate CompleteAction { get; set; }`**
Callback invoked upon successful completion of the download task.
- **`SetProgressValueDelegate ProgressAction { get; set; }`**
Callback to report progress (currently unused in `Download()`).
- **`StatusIntDelegate StatusAction { get; set; }`**
Callback to report status updates (takes `int` cast of `StatusValues`).
- **`StatusExIntDelegate StatusExAction { get; set; }`**
Callback for extended status (e.g., `NoDataToDownload` passes array of DAS with missing config).
- **`bool AllDASFinished { get; set; } = false;`**
Set to `true` if *all* DAS in `param.DASList` have finished downloading (only checked if `RequireAllDASFinish` is true).
- **`void Reset()`**
Clears all delegate references and resets `AllDASFinished` to `false`.
- **`void Download()`**
Starts the download process asynchronously on a background thread. Key behaviors:
- Invokes `StatusAction(StatusValues.Preparing)` at start.
- Validates DAS availability against `DASFactory.GetDASList()`, calls `ErrorCallback(StatusValues.MissingHardware)` if missing.
- Fails if `DASList` is empty or any DAS lacks `ConfigData`.
- Retrieves event info via `GetOneEvent()`; fails if no event found.
- Constructs download directory:
`<DownloadFolder>/<EventId>/<CurrentTestTestId>/Binary/<ROI|ALL>`.
- In **Recovery mode**, reuses the original `CurrentTestTestIdNode` path if test ID changed, and copies folders (`DASConfigs`, `Logs`, `Reports`, `SETUP`) from original test directory if needed (unless `FoldersCopied` is true).
- Uses a `ManualResetEvent` (`mre`) that waits indefinitely—**no actual download logic is implemented**; the task exits after setting `CompleteAction` and `StatusAction(Completed)`.
- Sets `DoneEvent` upon completion.
- **`Task Cancel()`**
Asynchronously cancels the download:
- Sets `CancelEvent`.
- Reports `StatusValues.Cancelling`.
- Waits 100ms (simulated delay).
- Waits for `DoneEvent`.
- Reports `StatusValues.Cancelled`.
- **`bool DirectoryCopy(...)`**
Copies files from `sourceDirName` to `destDirName`, with filtering based on upload flags (`DefaultUpload*`).
- Overwrites existing files (uses `File.Copy(..., true)`).
- Skips files if corresponding upload flag is `false` (e.g., skips `Binary` if `DefaultUploadBinaries` is `false`).
- Prompts user via `ErrorCallback(StatusValues.ExistingFiles)` if destination files exist.
- Logs success/failure via `APILogger`.
- Returns `true` only if *uploading data* (`uploadingData == true`) and copy succeeds; otherwise `false`.
- **`private static string GetHash(DownloadReport.EventInfo)`**
Helper: returns `"TestID_EventNumber"` formatted as uppercase (e.g., `"T123_05"`).
- **`private IEventInfoAggregate GetOneEvent(List<IDASCommunication>)`**
Helper: aggregates event info from DAS units.
- Collects unique events by hash (`TestID_EventNumber`).
- Returns the first aggregated event (or `null` if none found).
*Note:* The `TODO` comment indicates incomplete event aggregation logic.
## 3. Invariants
- **`DASList` must be non-null and populated before calling `Download()`**
The method checks for empty `dasList` and fails if `!dasList.Any()`.
- **Each DAS in `DASList` must have non-null `ConfigData`**
Checked via `das.ConfigData == null`; triggers `StatusExAction(StatusValues.NoDataToDownload)`.
- **At least one DAS must have valid `EventInfo` with events**
`GetOneEvent()` must return non-null; otherwise, `StatusAction(StatusValues.Failed)` is invoked.
- **Download directory must be creatable**
If `Directory.CreateDirectory(directory)` throws, `StatusAction(StatusValues.Failed)` is invoked.
- **`StatusAction` must be assigned for status reporting**
All status updates are conditional on `StatusAction?.Invoke(...)`.
- **`ErrorCallback` must handle user prompts synchronously**
The code calls `errorCallback?.Invoke(...)` and expects a `DialogResult` return.
- **Recovery mode path reuse**
When `Recovery == true` and `CurrentTestTestId != CurrentTestTestIdNode`, the download directory reuses `currentTestTestIdNode` (original test ID node) to avoid duplicating folders.
- **`FoldersCopied` prevents redundant copying**
Folder copying only occurs if `Recovery && (!foldersCopied)`.
## 4. Dependencies
### Imports/References
- **`DTS.Common.Interface.DASFactory`**
Provides `IDASCommunication`, `IDASFactory`, and `IEventInfoAggregate`.
- **`DTS.Common.Interface.StatusAndProgressBar`**
Provides `IStatusParameters`, `IStatusInfo`, `ErrorCallback`, `ActionCompleteDelegate`, `SetProgressValueDelegate`, `StatusIntDelegate`, `StatusExIntDelegate`.
- **`DTS.Common.Utilities.Logging`**
Provides `APILogger`.
- **`System.Windows.Forms`**
Used for `DialogResult` (e.g., `DialogResult.OK` in `ErrorCallback` usage).
- **`System.IO`**
For `Directory`, `DirectoryInfo`, `File`, `Path`, `Uri`.
### Internal Dependencies
- **`States.Instance.DownloadStart`**
Accessed to retrieve:
- `Status.DownloadParams` (`DownloadParameters`)
- `Status.GlobalStatusParameters`
- `DASFactory` (`IDASFactory`)
- **`Common.Constants`**
Used for folder names: `DAS_CONFIGS`, `REPORT_DIR_NAME` (values not visible in source).
- **`Resources.UploadData_Files_Exist`**
String resource used in `DirectoryCopy` for existing files prompt.
## 5. Gotchas
- **`DirectoryCopy` does not actually upload data**
Despite the name and upload-related flags, it only copies files *within the local filesystem*. The `uploadingData` parameter controls filtering but not network upload.
- **No actual download logic in `Download()`**
The method sets up directories and runs validation, but the core download loop is missing—`mre.WaitOne()` blocks indefinitely, and the task exits without performing I/O. This suggests incomplete implementation or placeholder logic.
- **`DirectoryCopy` has confusing return semantics**
Returns `true` *only* if `uploadingData == true` and copy succeeds; otherwise returns `false`. This makes it unsuitable for generic copying.
- **`DirectoryCopy` uses `Uri` for relative path calculation**
Builds URIs with `"file:\\\\"` prefix and uses `MakeRelativeUri`—non-standard and potentially fragile for Windows paths.
- **`GetOneEvent` is incomplete**
The `TODO` comment and missing `IEventInfoAggregate` constructor call (`new IEventInfoAggregate(...)`) indicate the event aggregation logic is not implemented.
- **`Reset()` does not reset `ROI`, `Recovery`, or `FoldersCopied`**
Only resets explicitly listed properties—these flags retain their values unless manually cleared.
- **`ToString()` is a no-op**
Returns empty string; no debugging value.
- **`DirectoryCopy` may throw if `sourceDirName`/`destDirName` are invalid**
`Uri` construction and `DirectoryInfo` access lack explicit error handling beyond the outer `try-catch`.
- **Hardcoded folder names**
`"Binary"`, `"ROI"`, `"ALL"`, `"Logs"`, `"SETUP"`, `"Reports"`, `"DASConfigs"` are used directly—should be constants.
- **`Thread.Sleep(100)` and `Thread.Sleep(10)` in async path**
Blocking calls in cancellation and upload paths may cause UI freezes or delays.
- **Missing `NotAllChannelsDownloaded` handling**
Status value exists but is never invoked in `Download()`.
- **`ExistingFiles` prompt may show multiple times**
`DirectoryCopy` is called per folder (e.g., `DASConfigs`, `Logs`, etc.), and each may prompt for existing files.
- **No validation of `CurrentTest*` path components**
Invalid characters or null values could cause path construction errors.

100
enriched-qwen3-coder-next/DataPRO/IService/StateMachine/StatusAndParameters/HardwareDiscovery.md Normal file
View File

@@ -0,0 +1,100 @@
---
source_files:
- DataPRO/IService/StateMachine/StatusAndParameters/HardwareDiscovery/HardwareDiscoveryParameters.cs
generated_at: "2026-04-16T04:01:01.723717+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "d09b358f05b11ecc"
---
# HardwareDiscovery
## Documentation: `HardwareDiscoveryParameters`
---
### **Purpose**
The `HardwareDiscoveryParameters` class encapsulates configuration and control flags for the hardware discovery phase within the state machine of the DAS (Data Acquisition System) service. It defines *how* hardware devices (SLICE and TDAS units) are discovered—via explicit IPs, IP ranges, or multicast—and *what* actions should follow discovery (e.g., hardware validation, connection, firmware checks). It serves as the input contract for the discovery state, allowing callers to customize discovery behavior (e.g., skip connection, require specific devices, trigger post-discovery transitions) without modifying the discovery logic itself.
---
### **Public Interface**
#### **Properties**
| Property | Type | Default | Description |
|---------|------|---------|-------------|
| `ReadIds` | `bool` | `false` | Whether to read device identifiers (e.g., serial, firmware) after connection. |
| `Addresses` | `string[]` | `new string[0]` | Explicit IP addresses to attempt connection to. If not in known lists, tried as both SLICE and TDAS. |
| `AddressRanges` | `Tuple<string, string>[]` | `new Tuple<string, string>[0]` | IP ranges to ping (inclusive on last octet). Format: `("aaa.bbb.ccc.ddd", "aaa.bbb.ccc.eee")`. Responding IPs added to connection list. |
| `KnownTDASIPAddresses` | `string[]` | `new string[0]` | IPs *confirmed* to be TDAS units. Only tried as TDAS (not SLICE). |
| `KnownSLICEIPAddresses` | `string[]` | `new string[0]` | IPs *confirmed* to be SLICE units. Only tried as SLICE (not TDAS). |
| `ProceedWhenDone` | `bool` | `false` | If `false`, remain in discovery state after completion (e.g., for inspection). If `true`, proceed to next state. |
| `RequireAllDASFound` | `bool` | `false` | If `true`, discovery fails if any device in `Addresses`, `AddressRanges`, or `RequiredSerials` is not found. |
| `GoToDownload` | `bool` | `false` | If `true`, transition to *Download* state after successful discovery (implies `ProceedWhenDone = true`). |
| `Connect` | `bool` | `false` | If `false`, only perform ICMP ping (no socket connection). If `true`, attempt full connection. |
| `UseMulticastDiscover` | `bool` | `false` | Whether to use UDP/Multicast discovery protocol (e.g., SSDP-like). |
| `ConnectTimeoutMS` | `int` | `30000` | Timeout (ms) for connection attempts. |
| `RunAutoSense` | `bool` | `true` | Whether to run auto-sense logic (e.g., fallback discovery). *Note:* Overridden if `DisableAutoSense` is set elsewhere (not in this class). |
| `RequeryDevice` | `IDASCommunication` | `null` | A specific device to re-query (e.g., after config change). If non-null, discovery targets only this device. |
| `RequiredSerials` | `string[]` | `new string[0]` | Serial numbers of devices *required* to be discovered. Used for validation (`RequireAllDASFound` may apply). |
| `DoHardwareChecks` | `bool` | `false` | Whether to perform hardware validation (voltage, memory, firmware) *after* connection. |
| `ExpectedHardware` | `IDASHardware[]` | `new IDASHardware[0]` | Hardware expected to be present post-discovery. Used in `DoHardwareChecks`. |
| `DoVoltageChecks` | `bool` | `true` | Whether to include input/battery voltage checks as part of `DoHardwareChecks`. |
| `UnitIsInDbQuery` | `UnitIsInDbDelegate` | `null` | Callback: `bool UnitIsInDb(IDASCommunication das)` — checks if device is registered in DB. |
| `UnitExpectedFirmwareQuery` | `FirmwareExpectedVersionDelegate` | `null` | Callback: `string ExpectedFirmware(IDASCommunication das)` — returns expected firmware version for device. |
| `CalDateExpiredQuery` | `IsCalDateExpiredDelegate` | `null` | Callback: `bool IsCalExpired(IDASCommunication das)` — checks if calibration date is expired. |
| `UnitExpectedMaxMemoryDelegate` | `UnitExpectedMaxMemoryDelegate` | `null` | Callback: `long ExpectedMaxMemory(IDASCommunication das)` — returns expected max memory for device. |
| `UpdateMaxMemoryAction` | `UpdateMaxMemoryDelegate` | `null` | Callback: `void UpdateMaxMemory(IDASCommunication das)` — updates max memory metadata (e.g., after reflash). |
#### **Methods**
| Method | Signature | Description |
|--------|-----------|-------------|
| `Reset()` | `public void Reset()` | Resets all properties to default values (e.g., empty arrays, `false` flags, `null` delegates). Does *not* reset `ConnectTimeoutMS` (remains `30000`). |
| `ToString()` | `public override string ToString()` | Returns a human-readable summary of all properties, including delegate presence (`[null]`/`[defined]`). |
---
### **Invariants**
- **IP Format**: `Addresses`, `AddressRanges.Item1/Item2`, `KnownTDASIPAddresses`, and `KnownSLICEIPAddresses` must be valid IPv4 strings (`aaa.bbb.ccc.ddd`). Invalid formats may cause ping/connection failures but are *not validated* by this class.
- **Range Validity**: For `AddressRanges`, `Item1` and `Item2` must share the first three octets; otherwise, iteration logic may behave unexpectedly (no validation enforced).
- **Mutual Exclusivity**: `RequeryDevice != null` implies discovery is *device-centric*; `Addresses`, `AddressRanges`, `Known*IPAddresses`, and `RequiredSerials` are likely ignored (behavior depends on consumer).
- **Delegate Consistency**: If `DoHardwareChecks = true`, at least one of `UnitIsInDbQuery`, `UnitExpectedFirmwareQuery`, `CalDateExpiredQuery`, `UnitExpectedMaxMemoryQuery`, or `UpdateMaxMemoryAction` *should* be non-null for meaningful checks—but this is not enforced.
- **Timeout**: `ConnectTimeoutMS` must be ≥ 0. Negative values are not validated and may cause undefined behavior in connection logic.
---
### **Dependencies**
#### **Imports/References**
- `DTS.Common.Interface.DASFactory` → Provides `IDASCommunication` and `IDASHardware`.
- `DTS.Common.Interface.DataRecorders` → Likely provides additional DAS-related interfaces (used via `IDASCommunication`/`IDASHardware`).
- `System` → Core types (`Tuple`, `StringBuilder`, `Delegate`).
#### **Consumers (Inferred)**
- State machine logic in `DTS.DASLib.Service.StateMachine` (namespace implies usage).
- Discovery-related state handlers (e.g., `HardwareDiscoveryState`) that consume this class to configure discovery behavior.
- UI or service layer that populates this class before invoking discovery.
#### **Dependencies on External Types**
- `IDASCommunication`: Interface for device communication (used in delegates and `RequeryDevice`).
- `IDASHardware`: Interface for hardware metadata (used in `ExpectedHardware`).
---
### **Gotchas**
- **`RequeryDevice` takes precedence**: If `RequeryDevice` is non-null, discovery may *ignore* `Addresses`, `AddressRanges`, `Known*IPAddresses`, and `RequiredSerials`. This is implied by the summary but not enforced—consumers must handle this.
- **`GoToDownload` implies `ProceedWhenDone`**: While not enforced in this class, `GoToDownload = true` logically requires `ProceedWhenDone = true` (to transition states). Consumers must ensure this.
- **`RunAutoSense` is *not* overridable here**: The summary notes `DisableAutoSense` overrules `RunAutoSense`, but `DisableAutoSense` is *not a property of this class*. Likely set elsewhere (e.g., in discovery state logic).
- **No validation of IP ranges**: `AddressRanges` items are used as-is. If `Item1` > `Item2` in the last octet, iteration may produce no results or throw (source not shown).
- **`ToString()` omits `ConnectTimeoutMS` and `UseMulticastDiscover`**: These properties are *not* included in the `ToString()` output despite being public—potential debugging pitfall.
- **`Reset()` does not reset `ConnectTimeoutMS`**: Despite resetting other properties, `ConnectTimeoutMS` remains `30000` after `Reset()`. Intentional? Unclear from source.
- **`Known*IPAddresses` are *additive* to discovery scope**: IPs in `KnownTDASIPAddresses`/`KnownSLICEIPAddresses` are *not* exclusive—they are *preferred* paths, but discovery may still try other methods if `Connect = true` and `Addresses`/`AddressRanges` are also set.
---
*Documentation generated from `HardwareDiscoveryParameters.cs` alone. Behavior of discovery logic (e.g., how `AddressRanges` are iterated, how `RequeryDevice` is handled) is inferred from comments and property names but not verifiable without consumer code.*

144
enriched-qwen3-coder-next/DataPRO/IService/StateMachine/StatusAndParameters/Realtime.md Normal file
View File

@@ -0,0 +1,144 @@
---
source_files:
- DataPRO/IService/StateMachine/StatusAndParameters/Realtime/RealtimeParameters.cs
- DataPRO/IService/StateMachine/StatusAndParameters/Realtime/RealtimeStatusInformation.cs
generated_at: "2026-04-16T04:01:39.522280+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "13ae579216023a96"
---
# Realtime
## Documentation: Realtime Parameters and Status Module
---
### 1. **Purpose**
This module encapsulates the configuration (`RealtimeParameters`) and runtime state management (`RealtimeStatusInformation`) for initiating and controlling *realtime data acquisition* in the DAS (Distributed Acoustic Sensing) system. It serves as the interface between the state machine and the underlying `RealtimeService`, handling parameter propagation, sample rate/AAF (Anti-Alias Filter) configuration, and synchronization primitives for starting/stopping realtime acquisition across multiple DAS units. It enables both single-sample and multi-sample polling modes, with configurable delays, channel selection, and hardware-specific AAF computation.
---
### 2. **Public Interface**
#### `RealtimeParameters` (class)
- **`List<IDASCommunication> UnitsToStartRealtime { get; set; }`**
List of DAS units to be started in realtime mode.
- **`int RealtimeDelayBetweenPollsInMilliSecond { get; set; }`**
Delay (in ms) between successive polling attempts during realtime acquisition.
- **`bool AllowMultipleSampleRealtime { get; set; }`**
Flag indicating whether multiple samples per poll are allowed.
- **`bool UseSingleSampleMode { get; set; }`**
Flag to enable single-sample mode (overrides multi-sample behavior).
- **`List<int> ModuleIndices { get; set; }`**
List of module indices to be used in realtime acquisition.
- **`Dictionary<IDASCommunication, byte[]> IdasToActiveChannels { get; set; }`**
Mapping from DAS unit to its active channel bitmask (each byte represents 8 channels).
- **`double RealtimeSampleRate { get; set; }`**
Target sample rate (Hz) for realtime acquisition.
- **`byte RealtimeSampleRateAAFilterRatio { get; set; }`**
Ratio used to compute AAF cutoff: `AAF = sampleRate / RealtimeSampleRateAAFilterRatio`.
- **`bool SliceTurnOffAAFRealtime { get; set; }`**
Flag to override AAF and disable it for hardware that supports it (see `DFConstantsAndEnums.SupportsTurnOffAAFRealtime`).
- **`void Reset()`**
Initializes all properties to default values (empty collections, zero numerics, `false` booleans).
#### `RealtimeStatusInformation` (class)
- **`bool IsInRealtime { get; }`**
Returns `true` if realtime acquisition is currently active (based on `stopRealtimeEvent` state). Uses a 2ms timeout for non-blocking check.
- **`void StopRealtime()`**
Signals termination of realtime acquisition by setting `stopRealtimeEvent`.
- **`void StartRealtime()`**
Overload that reads parameters from `States.Instance.Realtime.Status.RealtimeParams` and invokes the full `StartRealtime(...)` overload on a background `Task`.
- **`void StartRealtime(List<IDASCommunication> ldas, List<int> moduleArrayIndicies, bool useSingleSampleMode, double realtimeSampleRate, int realtimeDelayBetweenPolls, bool allowMultipleSampleRealtime, Action<double, double> SetRealtimeSampleRateAAF, Action CompleteAction, Dictionary<IDASCommunication, byte[]> idasToActiveChannels, Callback StartRealtimeCallback)`**
Core method that:
- Wraps `StartRealtimeCallback` in a `Callback` delegate and appends status completion/failure handlers.
- Resets `stopRealtimeEvent` and instantiates `RealtimeService`.
- If `useSingleSampleMode` is `true`: calls `RealtimeService.StartActivePolling(...)`.
- Else: calls `RealtimeService.Start(...)` with computed AAF via `GetRealtimeAAFForHardware`.
- Invokes `SetRealtimeSampleRateAAF` with `(sampleRate, AAF)` for the first DAS (or `NaN, NaN` if no DAS).
- Waits for either `stopRealtimeEvent` (external stop) or `mr` (service availability), then waits for `realtimeDoneFromService` (service completion).
- Logs exceptions, sets `CouldNotStartRealtime = true`, and always invokes `CompleteAction` in `finally`.
- **`Action<double, double> SetRealtimeSampleRateAAF { get; set; }`**
Callback to notify caller of current sample rate and computed AAF (used for UI updates or validation).
- **`Action CompleteAction { get; set; }`**
Action invoked upon completion (success or failure) of `StartRealtime(...)`.
- **`bool CouldNotStartRealtime { get; set; }`**
Set to `true` if an exception occurs during `StartRealtime(...)`.
- **`Callback StartRealtimeCallback { get; set; }`**
User-provided callback invoked by `RealtimeService` during acquisition.
- **`private float GetRealtimeAAFForHardware(IDASCommunication idas, double samplerate)`**
Computes AAF cutoff based on:
- If `SliceTurnOffAAFRealtime` is `true` *and* hardware supports it → returns `Common.Constants.SLICE2_NO_AAF_REALTIME_RATE`.
- Else if `RealtimeSampleRateAAFilterRatio == 0` → returns `samplerate`.
- Else → returns `samplerate / RealtimeSampleRateAAFilterRatio`.
- **`void Reset()`**
Clears `CompleteAction`, resets `realtimeDoneFromService`, sets `stopRealtimeEvent`, and clears `CouldNotStartRealtime`.
---
### 3. **Invariants**
- `RealtimeDelayBetweenPollsInMilliSecond` must be ≥ 0 (no validation enforced in code; assumed caller responsibility).
- `RealtimeSampleRateAAFilterRatio` must be ≥ 0 (zero implies AAF = sample rate).
- `RealtimeSampleRate` must be > 0 when `UseSingleSampleMode == false`, otherwise behavior is undefined (no explicit check).
- `UnitsToStartRealtime` and `IdasToActiveChannels` must be consistent: every `IDASCommunication` in `UnitsToStartRealtime` must have an entry in `IdasToActiveChannels` (no enforcement; caller responsibility).
- `ModuleIndices` is only used when `UseSingleSampleMode == false`.
- `IsInRealtime` is `true` iff `stopRealtimeEvent` is *not* signaled (i.e., `WaitOne(2, false)` returns `false`).
- `CompleteAction` is **always** invoked in `StartRealtime(...)`’s `finally` block, regardless of success/failure.
- `realtimeDoneFromService.WaitOne()` is called *after* `stopRealtimeEvent.Set()` in `StartRealtime(...)`, ensuring the service has fully stopped before proceeding.
---
### 4. **Dependencies**
#### Dependencies *of this module*:
- **`DTS.Common.Interface.DASFactory.IDASCommunication`**: Interface for DAS units.
- **`DTS.Common.Enums.DASFactory.DFConstantsAndEnums`**: Used for `SupportsTurnOffAAFRealtime`.
- **`DTS.Common.Constants.SLICE2_NO_AAF_REALTIME_RATE`**: Hardcoded AAF value when AAF is disabled.
- **`DTS.DASLib.Service.StateMachine.States`**: Access to global state (`States.Instance.Realtime.Status.RealtimeParams`).
- **`DTS.DASLib.Service.RealtimeService`**: Core service for starting/stopping acquisition.
- **`DTS.Common.Interface.StatusAndProgressBar.Callback` & `CallbackData`**: For async completion callbacks.
- **`DTS.Common.Utilities.Logging.APILogger`**: For exception logging.
- **`System.Threading`**: `ManualResetEvent`, `Task`, `Thread`.
#### Dependencies *on this module*:
- **`RealtimeStatusInformation.StartRealtime()`** is invoked by the state machine (likely via `States.Instance.Realtime.Status.RealtimeStatus.StartRealtime()`).
- **`RealtimeParameters`** is used as `RealtimeStatus.RealtimeParams` (inferred from usage in `RealtimeStatusInformation`).
- **`SetRealtimeSampleRateAAF`** callback is likely implemented by UI or monitoring components to update sample rate/AAF displays.
---
### 5. **Gotchas**
- **`RealtimeDelayBetweenPollsInMilliSecond` is passed as `int` but may be interpreted as `ms` by `RealtimeService`** — ensure caller uses integer milliseconds (no fractional values).
- **`GetRealtimeAAFForHardware` uses only the *first DAS* (`ldas[0]`) to compute AAF** when setting `SetRealtimeSampleRateAAF`, even if multiple DAS units are present. This assumes identical AAF behavior across units (not validated).
- **`UseSingleSampleMode` bypasses AAF computation and calls `StartActivePolling`**, which may have different behavior than `Start` (e.g., no AAF, no module indices).
- **`RealtimeService.ServiceAvailable` event is subscribed inside `StartRealtime(...)`, but the wait loop (`mr.WaitOne`) may exit prematurely if `mr` is set before `stopRealtimeEvent` is signaled**, potentially leading to race conditions if `RealtimeService` becomes available slowly.
- **`stopRealtimeEvent` is set twice** — once in `StopRealtime()` and again in `StartRealtime(...)`’s `finally` block. While idempotent for `ManualResetEvent`, this could confuse debugging.
- **No validation of `IdasToActiveChannels` entries** — e.g., mismatched channel counts or invalid bitmasks are not caught.
- **`CouldNotStartRealtime` is set on *any* exception**, but the `catch` block does *not* rethrow or provide structured error info — callers must inspect this flag after `StartRealtime`.
- **`Reset()` does *not* clear `SetRealtimeSampleRateAAF`, `CompleteAction`, or `StartRealtimeCallback`** — only `CompleteAction` is cleared in `Reset()`. Other properties retain their values unless explicitly overwritten.
None identified beyond these.