init
This commit is contained in:
@@ -0,0 +1,212 @@
|
||||
---
|
||||
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-17T15:41:27.157987+00:00"
|
||||
model: "zai-org/GLM-5-FP8"
|
||||
schema_version: 1
|
||||
sha256: "0a25ce0aa4784f4b"
|
||||
---
|
||||
|
||||
# Documentation: Configure State Machine Module
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
This module provides the configuration state machine for Data Acquisition System (DAS) units, managing the complete lifecycle of hardware configuration including channel resolution, sensor-to-hardware mapping, configuration application, and diagnostic preparation. It serves as the orchestration layer between high-level test setup definitions and low-level hardware communication, supporting both automatic channel resolution (via EID lookup) and manual channel assignment with validation.
|
||||
|
||||
---
|
||||
|
||||
## 2. Public Interface
|
||||
|
||||
### `ConfigureStatusParameters` (Class)
|
||||
**Namespace:** `DTS.DASLib.Service.StateMachine`
|
||||
**Implements:** `IStatusParameters`
|
||||
|
||||
Configuration options container for the configure state machine.
|
||||
|
||||
#### Properties
|
||||
|
||||
| Property | Type | Default | Description |
|
||||
|----------|------|---------|-------------|
|
||||
| `RequireIdFoundForSensorsWithIds` | `bool` | `true` | Requires that sensors with IDs have their EID found during resolution |
|
||||
| `AllowMissingSensors` | `bool` | `false` | Permits channels without assigned sensors |
|
||||
| `AllowSensorsOutOfPosition` | `bool` | `true` | Allows sensors on different channels than originally specified |
|
||||
| `AllowSensorIdToBlankChannel` | `bool` | `false` | Permits assigning sensors with EIDs to unassigned hardware channels |
|
||||
| `TestSetupConfiguration` | `ITestSetup` | `null` | The test setup containing channel/group definitions |
|
||||
| `TurnOffExcitation` | `bool` | `false` | Triggers excitation shutdown process |
|
||||
| `UnitsToConfigure` | `IDASCommunication[]` | empty array | Target DAS units for configuration |
|
||||
| `DoStrictCheck` | `bool` | `true` | Enables strict validation during configuration |
|
||||
| `EventConfig` | `bool` | `true` | Writes to event/diagnostic file stores (SLICE legacy feature) |
|
||||
| `DummyConfig` | `bool` | `false` | Configures units without actual data collection |
|
||||
| `MaxAAF` | `double[]` | empty array | Maximum Anti-Alias Filter values for SLICE/TDAS |
|
||||
| `ConfigureDigitalOutputs` | `bool` | `true` | Whether to apply digital output configuration |
|
||||
| `TurnOffAAFRealtime` | `bool` | `true` | Disables AAF for realtime mode (performance optimization) |
|
||||
| `ResetHardwareEventLines` | `bool` | `false` | Resets hardware event lines before configuration |
|
||||
| `PrepareForDiagnostics` | `bool` | `false` | Enables excitation/switch preparation for diagnostics |
|
||||
| `SkipTurnOnPower` | `bool` | `false` | Skips power-on step to maintain low-power state |
|
||||
| `SetConfiguration` | `bool` | `true` | Whether to apply configuration at all |
|
||||
| `DiscardDiagnostics` | `bool` | `true` | Discards diagnostics during configuration |
|
||||
| `DSPFilterType` | `DSPFilterType` | from collection | DSP filter configuration |
|
||||
| `SampleRateLookup` | `IReadOnlyDictionary<string, double>` | empty | Serial number to sample rate mapping |
|
||||
| `AAFRateLookup` | `IReadOnlyDictionary<string, float>` | empty | Serial number to AAF rate mapping |
|
||||
|
||||
#### Delegates
|
||||
|
||||
| Delegate | Signature | Description |
|
||||
|----------|-----------|-------------|
|
||||
| `GetSensorDelegate` | `ISensorData(IGroupChannel)` | Retrieves sensor data for a group channel |
|
||||
| `GetSensorCalibrationDelegate` | `ISensorCalibration(ISensorData, ExcitationVoltageOption)` | Retrieves calibration for sensor/excitation combo |
|
||||
| `GetDatabaseIdDelegate` | `int(IDASCommunication)` | Retrieves database ID for a DAS unit |
|
||||
| `SetSensorCalibrationDelegate` | `void(ISensorData, ISensorCalibration)` | Sets calibration on a sensor |
|
||||
|
||||
#### Methods
|
||||
|
||||
- **`ConfigureStatusParameters()`** - Constructor; initializes `DSPFilterType` from `DSPFilterCollection`
|
||||
- **`void Reset()`** - Resets all properties to default values
|
||||
- **`string ToString()`** - Returns formatted string of all parameter values
|
||||
|
||||
---
|
||||
|
||||
### `ConfigureStatusInformation` (Class)
|
||||
**Namespace:** `DTS.DASLib.Service.StateMachine`
|
||||
**Implements:** `IStatusInfo`
|
||||
|
||||
Runtime status tracking and orchestration for the configuration process.
|
||||
|
||||
#### Nested Types
|
||||
|
||||
**`StatusValues` (Enum)**
|
||||
```
|
||||
ApplyingConfiguration, AutoResolvingChannels, ManuallyResolvedChannels,
|
||||
Completed, Cancelling, Cancelled, ChannelOutOfPosition, NoChannelsAssigned,
|
||||
AllChannelsResolved, EIDNotFound, ApplyConfigFailed, AppliedConfiguration,
|
||||
PrepareForDiagnostics, PrepareForDiagnosticsFailed, PrepareForDiagnosticsSuccess,
|
||||
LowPower, LowPowerSuccess, LowPowerFailure
|
||||
```
|
||||
|
||||
**`InvalidAssignmentException` (Exception)**
|
||||
- `Reasons` enum: `BlankChannel, NoSensor, ChannelDisabled, SensorNotFound, IncompatibleHardware, ChannelAlreadyAssigned, EID_Locked, EIDRequiredAndMissing, ChannelNotAssigned`
|
||||
- Properties: `IGroupChannel GroupChannel`, `Reasons Reason`
|
||||
|
||||
**`SensorCompatiblilityResponse` (Enum)** - `internal`
|
||||
```
|
||||
Compatible, DigitalInputNotSupportedOnHWChannel, DigitalInputModeNotSupportedOnHWChannel,
|
||||
BridgeModeNotSupportedOnHWChannel, SquibFireModeNotSupportedOnHWChannel,
|
||||
NoSupportedExcitationOnHWChannel
|
||||
```
|
||||
|
||||
#### Properties
|
||||
|
||||
| Property | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `NoChannelsAssigned` | `bool` | `true` when no channels are assigned |
|
||||
| `AllChannelsResolved` | `bool` | `true` when all channels are resolved |
|
||||
| `ChannelsOutOfPosition` | `bool` | `true` when channels are on different hardware than specified |
|
||||
| `HaveAppliedConfigAllUnits` | `bool` | `true` when all target units are configured |
|
||||
| `UnitsConfigured` | `IDASCommunication[]` | Successfully configured units |
|
||||
| `CancelEvent` | `ManualResetEvent` | Signals cancel request |
|
||||
| `DoneEvent` | `ManualResetEvent` | Signals work completion |
|
||||
| `CompleteAction` | `ActionCompleteDelegate` | Completion callback |
|
||||
| `ProgressAction` | `SetProgressValueDelegate` | Progress notification callback |
|
||||
| `StatusAction` | `StatusIntDelegate` | Status notification callback |
|
||||
| `StatusExAction` | `StatusExIntDelegate` | Extended status notification callback |
|
||||
|
||||
#### Methods
|
||||
|
||||
- **`Task Cancel()`** - Async; sets cancel event, waits for task completion, reports `Cancelling` then `Cancelled` status
|
||||
- **`void ApplyConfig()`** - Starts configuration process; checks `TurnOffExcitation` flag first; runs configuration in background task
|
||||
- **`void TurnOffExcitation()`** - Initiates low-power mode on all DAS units; runs in background task
|
||||
- **`void ManuallyResolveChannel(IGroupChannel channel, IDASChannel hardwareChannel)`** - Manually assigns a sensor channel to hardware; validates compatibility and throws `InvalidAssignmentException` on failure
|
||||
- **`void ManuallyUnresolveChannel(IGroupChannel channel)`** - Removes manual channel assignment; throws if channel not assigned or EID-locked
|
||||
- **`void Reset()`** - Resets all status properties to defaults
|
||||
|
||||
---
|
||||
|
||||
### `GroupChannelWithMeta` (Class)
|
||||
**Namespace:** `DTS.DASLib.Service.StateMachine.StatusAndParameters.Configure`
|
||||
**Access:** `internal`
|
||||
|
||||
Helper class for tracking channel resolution state.
|
||||
|
||||
#### Properties
|
||||
|
||||
| Property | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `ChannelConflict` | `bool` | Channel has conflicting assignment |
|
||||
| `ConflictingChannel` | `IGroupChannel` | Reference to conflicting channel |
|
||||
| `Channel` | `IGroupChannel` | The group channel being tracked |
|
||||
| `Group` | `IGroup` | Parent group reference |
|
||||
| `MissingID` | `bool` | EID not found during resolution |
|
||||
| `MissingSensor` | `bool` | No sensor assigned to channel |
|
||||
| `EIDOutOfPlace` | `bool` | EID found on different hardware than expected |
|
||||
| `HWNotFound` | `bool` | Hardware channel not found |
|
||||
| `HWChannelIncompatible` | `bool` | Hardware incompatible with sensor |
|
||||
| `DASChannel` | `IDASChannel` | Resolved hardware channel |
|
||||
| `AssignedByEID` | `bool` | Channel was auto-assigned via EID lookup |
|
||||
|
||||
---
|
||||
|
||||
## 3. Invariants
|
||||
|
||||
1. **Mutual Exclusion of Channel State**: A channel exists in either `_resolvedChannels` or `_unresolvedChannels`, never both simultaneously. Methods `AddResolvedChannel` and `AddUnresolvedChannel` both remove from the opposite list before adding.
|
||||
|
||||
2. **Thread-Safe Unit Tracking**: The `UnitsConfigured` array is modified exclusively through `AddConfiguredDevice`, which uses a static lock object (`MyLock`) to prevent race conditions.
|
||||
|
||||
3. **EID Lock Immutability**: Channels assigned via EID (`AssignedByEID = true`) cannot be manually unresolved or reassigned to different hardware.
|
||||
|
||||
4. **Task Synchronization**: `CancelEvent` and `DoneEvent` coordinate task lifecycle; `DoneEvent` is reset at the start of `ApplyConfig` and set upon completion.
|
||||
|
||||
5. **Configuration Bypass**: If `SetConfiguration` is `false`, the configuration application step is skipped entirely, proceeding directly to power/diagnostic preparation.
|
||||
|
||||
---
|
||||
|
||||
## 4. Dependencies
|
||||
|
||||
### This Module Depends On
|
||||
|
||||
| Namespace | Purpose |
|
||||
|-----------|---------|
|
||||
| `DTS.Common.Interface.Channels` | Channel interfaces (`IDASChannel`, `AnalogInputDASChannel`, `OutputSquibChannel`, `OutputTOMDigitalChannel`) |
|
||||
| `DTS.Common.Interface.DASFactory` | DAS communication and configuration interfaces (`IDASCommunication`, `IDASFactory`) |
|
||||
| `DTS.Common.Interface.DASFactory.Config` | Configuration data structures |
|
||||
| `DTS.Common.Interface.Sensors` | Sensor interfaces (`ISensorData`, `ISensorCalibration`) |
|
||||
| `DTS.Common.Interface.StatusAndProgressBar` | Status/callback delegates |
|
||||
| `DTS.Common.Interface.TestSetups.TestSetupsList` | Test setup interfaces (`ITestSetup`) |
|
||||
| `DTS.Common.Interface.Groups.GroupList` | Group/channel interfaces (`IGroup`, `IGroupChannel`) |
|
||||
| `DTS.Common.Classes.DSP` | DSP filter types and collections |
|
||||
| `DTS.Common.Enums` | `ExcitationVoltageOptions`, `DSPFilterType` |
|
||||
| `DTS.Common.Utilities.Logging` | `APILogger` for exception logging |
|
||||
| `DTS.DASLib.Service.StateMachine.StatusAndParameters.Configure` | `GroupChannelWithMeta` (same namespace) |
|
||||
|
||||
### External Service Dependencies (instantiated within)
|
||||
|
||||
| Service | Usage |
|
||||
|---------|-------|
|
||||
| `DiagnosticsService` | Prepare units for diagnostic mode |
|
||||
| `ArmingService` | Enter low-power mode |
|
||||
| `ConfigurationService` | Apply hardware configuration |
|
||||
|
||||
### Global State Dependencies
|
||||
|
||||
- **`States.Instance.Configure`** - Configuration state access
|
||||
- **`States.Instance.ConfigureStart`** - Alternate state access path
|
||||
- **`States.Instance.Configure.Status.GlobalStatusInformation`** - Global status tracking (e.g., `ExcitationOn` flag)
|
||||
|
||||
---
|
||||
|
||||
## 5. Gotchas
|
||||
|
||||
1. **Dual State Access Paths**: The code accesses `States.Instance.Configure` and `States.Instance.ConfigureStart` interchangeably. The relationship between these two paths is unclear from source alone—this may indicate a refactoring artifact or intentional state sharing.
|
||||
|
||||
2. **Hardcoded Timing Constants**: `PREPARE_SPIN_TIME` (200ms) and `EXPECTED_PREPARE_TIME` (8000ms) are hardcoded in `PrepareForDiagnostics`. These may not be appropriate for all hardware configurations.
|
||||
|
||||
3. **Cancel Latency**: The `Cancel` method includes a fixed 100ms `Thread.Sleep` to "simulate time spent waiting for cancel to be acknowledged." This may cause unexpected delays in time-sensitive scenarios.
|
||||
|
||||
4. **Exception Re-throw Pattern**: In `PrepareForDiagnostics`, exceptions are caught and re-thrown with `throw ex`, which destroys the original stack trace. This should be `throw` instead.
|
||||
|
||||
5. **Legacy SLICE Features**: The `EventConfig` property references a "legacy feature of sliceware" for multiple file stores. Not all units support this, but the source does not indicate which units do.
|
||||
|
||||
6. **Delegate Nullability**: Several delegate properties (`GetSensorAction`, `GetCalibrationAction`, `GetDatabaseIdAction`, `SetSensorCalibrationAction`) are not validated for null before invocation. Callers must ensure these are set.
|
||||
|
||||
7. **Array Initialization Pattern**: Properties like `MaxAAF`, `UnitsToConfigure`, `SampleRateLookup`, and `AAFRateLookup` are initialized to empty collections rather than null, but the source does not document whether consumers should replace these or modify them in-place.
|
||||
Reference in New Issue
Block a user