DP44/docs/ai/Common/DTS.Common.DataModel/StateMachines.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.DataModel/StateMachines/OverallArmStatusStateMachine.cs	2026-04-17T15:42:56.746110+00:00	zai-org/GLM-5-FP8	1	5d72a0ae768f3eb3

Documentation: OverallArmStatusStateMachine

1. Purpose

The OverallArmStatusStateMachine class manages the lifecycle and state transitions for a Data Acquisition System's (DAS) arm status. It encapsulates complex state logic for recording operations, data downloading, flash clearing, and various waiting states (trigger, schedule, interval). The class uses the Stateless library to define valid state transitions and notifies subscribers via an event when state changes occur. This state machine appears to be part of a larger test/recording system where equipment must be armed, configured, and monitored through various operational phases.

2. Public Interface

Constructor

public OverallArmStatusStateMachine()

Initializes the state machine by resolving an IEventAggregator from the Prism container and calling the private Initialize() method. The initial state is set to ArmStateMachineStates.States.CheckingForDAS.

Enum: Triggers

public enum Triggers

Defines 35 trigger values that cause state transitions, including:

• bFillingBuffer, CheckingForData, ConfigurationIsSet, DASNotFound, DataNeverDownloaded, Disarm, DoneRecording, Downloading, DownloadCleaningUp, DownloadFinished, Error, Faulted, FlashClear, GettingEventInfo, IDLE, IntervalRecording, NoDataToDownload, NonIntervalRecording, PostTestProcessing, ReadyForDownload, Rearming, Recording, RunButton, Streaming, WaitingForTrigger, WaitingForSchedule, WaitingForInterval
• Single-character values: a, c, d, e, h, n, rr, tt, uu, yy

Event: OverallStatusStateChange

public event OverallStatusStateChangeDelegate OverallStatusStateChange;

Event raised when the state machine transitions to a new state. The delegate signature is:

public delegate void OverallStatusStateChangeDelegate(ArmStateMachineStates.States previousState, ArmStateMachineStates.States nextState);

Method: GetDASStatus

public ArmStateMachineStates.States GetDASStatus()

Returns the current state stored in CurrentOverallStatusState.

Method: FireTrigger

public void FireTrigger(Triggers trigger, ArmStateMachineStates.States state)

Fires a trigger with an associated state parameter. Uses a switch statement to map triggers to their corresponding TriggerWithParameters instances and calls overallArmStatusStateMachine.Fire(). Catches and logs any exceptions without re-throwing.

Handled triggers in switch: DASNotFound, NoDataToDownload, DataNeverDownloaded, DoneRecording, FlashClear, WaitingForTrigger, WaitingForSchedule, WaitingForInterval, Recording, PostTestProcessing, CheckingForData, GettingEventInfo, ReadyForDownload, Error, Streaming, Disarm, Rearming

Note: PostTestProcessing trigger fires DoneRecordingTrigger internally.

3. Invariants

• The state machine always starts in ArmStateMachineStates.States.CheckingForDAS.
• CurrentOverallStatusState is only updated via SetOverallStatus() and only when the new state differs from the current state.
• State transitions are constrained by the Stateless configuration; invalid triggers will cause the Stateless library to throw (caught silently in FireTrigger).
• SetOverallStatus() is only called from OnEntryFrom handlers configured in the state machine.
• The IEventAggregator must be registered in the Prism container at construction time.

4. Dependencies

External Dependencies

• Stateless - Third-party state machine library used for state transition management
• Prism.Ioc - ContainerLocator for service resolution
• Prism.Events - IEventAggregator interface (resolved but not used in visible code)
• DTS.Common.Enums.TSRAIRGo - Provides ArmStateMachineStates.States enum
• DTS.Common.Utilities.Logging - APILogger for logging state transitions and errors

Internal Dependencies

• ArmStateMachineStates.States - External enum defining all possible states (referenced but not defined in this file)

Consumers

• Unknown from source alone; consumers would subscribe to OverallStatusStateChange event and call FireTrigger().

5. Gotchas

1. Unused cryptic trigger values: The Triggers enum contains unexplained single-character values (a, c, d, e, h, n, rr, tt, uu, yy) that are never referenced elsewhere in the code.

2. Unimplemented trigger handling: Several triggers in the enum are not handled in the FireTrigger switch statement, including: bFillingBuffer, ConfigurationIsSet, DownloadCleaningUp, DownloadFinished, Faulted, IntervalRecording, NonIntervalRecording, RunButton, and the single-character triggers. Firing these will silently do nothing (fall through to default).

3. Error trigger not configured: The ErrorTrigger field is initialized but no state configures transitions using it. Firing Triggers.Error will likely cause a Stateless exception (caught and logged silently).

4. PostTestProcessing fires wrong trigger: The Triggers.PostTestProcessing case fires DoneRecordingTrigger instead of a dedicated trigger. This appears to be a workaround or potential bug.

5. Unused graph generation: The Initialize() method generates a UML dot graph string but stores it in a local variable that is never used or exposed.

6. Silent failure mode: FireTrigger() catches all exceptions and only logs them; callers have no way to know if a trigger failed.

7. Questionable parameter design: As noted in the source comment, FireTrigger takes a state parameter, which the developer questioned: "why specify state here? shouldn't that be done based on current state/trigger?" This suggests potential confusion about the state machine's design intent.

8. Unused IEventAggregator: The _eventAggregator field is resolved but never used in the visible code.