init

enriched-qwen3-coder-next/Common/DTS.Common/Interface/DASFactory/ARM.md

@@ -0,0 +1,157 @@
+---
+source_files:
+  - Common/DTS.Common/Interface/DASFactory/ARM/IArmStatus.cs
+  - Common/DTS.Common/Interface/DASFactory/ARM/IArmStatusData.cs
+generated_at: "2026-04-16T03:11:25.846617+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "5782109e320aeb67"
+---
+
+# ARM
+
+## Documentation: `IArmStatus` and `IArmStatusData` Interfaces
+
+### 1. Purpose  
+This module defines the contract for tracking and managing the operational state of a DAS (Data Acquisition System) unit within the DASFactory ARM (Armed) subsystem. It provides a standardized interface (`IArmStatus`) to query and update high-level DAS states (e.g., *Arm*, *Realtime*, *Streaming*) and exposes detailed status metadata via the `IArmStatusData` interface. The interfaces decouple state management from hardware-specific implementations, enabling consistent state tracking without direct hardware polling—critical for coordinating test sequencing, diagnostics, and database persistence in the DAS factory workflow.
+
+---
+
+### 2. Public Interface  
+
+#### `IArmStatus` Interface  
+- **`void SetInArm(bool WriteToDb)`**  
+  Marks the unit as being in *Arm* state. If `WriteToDb` is `true`, persists the state to the database.
+
+- **`void SetInRealtime(bool WriteToDb, bool ExitRealtimeIfPossible)`**  
+  Marks the unit as being in *Realtime* mode. If `WriteToDb` is `true`, persists the state. If `ExitRealtimeIfPossible` is `true`, allows exiting *Realtime* if conditions permit (e.g., if already in a conflicting state).
+
+- **`bool GetIsInArm()`**  
+  Returns `true` if the unit is *known* to be in *Arm* state (based on internal flags only—no hardware query).
+
+- **`bool GetIsInRealtime()`**  
+  Returns `true` if the unit is *known* to be in *Realtime* state (based on internal flags only—no hardware query).
+
+- **`bool GetIsStreaming()`**  
+  Returns `true` if the unit is *known* to be *streaming* (based on internal flags only—no hardware query).
+
+- **`IArmStatusData DASArmStatus { get; set; }`**  
+  Gets or sets the detailed status object (`IArmStatusData`) for the DAS unit.
+
+- **`void SetDASArmStatus(IArmStatusData status, bool bSetInDb)`**  
+  Sets the `DASArmStatus` property to `status`. If `bSetInDb` is `true`, persists the new status to the database.
+
+- **`void SetDASArmStatus()`**  
+  Persists the *current* `DASArmStatus` value to the database (if connected). Does *not* modify the in-memory status object.
+
+#### `IArmStatusData` Interface  
+- **`bool ReceivedInvalidModeDuringSetup { get; set; }`**  
+  Indicates if the unit received an `InvalidMode` error during initial setup (used as a proxy for *streaming* detection in some contexts).
+
+- **`void ClearTriggerCheckStatus()`**  
+  Clears flags related to trigger-check diagnostics (e.g., `IsTriggerShorted`, `IsStartShorted`).
+
+- **`bool IsArmed { get; set; }`**  
+  Indicates if the DAS is currently armed.
+
+- **`bool IsTriggered { get; set; }`**  
+  Indicates if the DAS has sensed a trigger event.
+
+- **`bool IsTriggerShorted { get; set; }`**  
+  Indicates if the trigger was shorted *during a trigger-check procedure* (distinct from `IsTriggered`).
+
+- **`bool IsStartShorted { get; set; }`**  
+  Indicates if the start signal was shorted *during a trigger-check procedure*.
+
+- **`bool IsRecording { get; set; }`**  
+  Indicates if the DAS is currently recording sample data.
+
+- **`bool IsFaulted { get; set; }`**  
+  Indicates if the DAS has faulted.
+
+- **`bool IsInRealtime { get; set; }`**  
+  Indicates if the DAS is in real-time mode.
+
+- **`bool IsInFlashWrite { get; set; }`**  
+  Indicates if the DAS is in flash-write mode (G5-specific).
+
+- **`bool IsUndefined { get; set; }`**  
+  Used when `TDAS ARM STAT READ` returns no data (fallback state).
+
+- **`bool IsInPostTestDiagnostics { get; set; }`**  
+  Indicates if the DAS is running post-test diagnostics.
+
+- **`double TimeRemainingSeconds { get; set; }`**  
+  Estimated seconds remaining in the current recording.
+
+- **`double PercentComplete { get; set; }`**  
+  Completion percentage for flash-write operations.
+
+- **`ulong TotalSamples { get; set; }`**  
+  Total number of samples to be recorded in the current test.
+
+- **`ulong CurrentSample { get; set; }`**  
+  Current sample index being recorded.
+
+- **`uint SampleRate { get; set; }`**  
+  Current sample rate (samples per second).
+
+- **`double? InputMilliVolts { get; set; }`**  
+  Current input voltage (in millivolts), or `null` if unavailable.
+
+- **`double? BatteryMilliVolts { get; set; }`**  
+  Current battery voltage (in millivolts), or `null` if no battery is present.
+
+- **`int? EventNumber { get; set; }`**  
+  Current event number being recorded, or `null` if not applicable.
+
+- **`ushort? MaxEventsPossible { get; set; }`**  
+  Maximum number of events supported by the device (per issue FB 26817).
+
+- **`int RecordingMode { get; set; }`**  
+  Numeric recording mode identifier (e.g., 0 = normal, 1 = burst).
+
+- **`string FaultMessage { get; set; }`**  
+  Human-readable fault description (e.g., "Overvoltage on input channel 3").
+
+- **`bool IsRearming { get; set; }`**  
+  Indicates if the DAS is in the rearming phase after a test.
+
+- **`bool HasBeenRecording { get; set; }`**  
+  Indicates if the DAS has ever recorded in the current session.
+
+- **`double? TimeLeftInArm { get; set; }`**  
+  Estimated time remaining in the *Arm* state (in seconds), or `null` if unknown.
+
+---
+
+### 3. Invariants  
+- **State Flags Are Software-Only**: `GetIsInArm()`, `GetIsInRealtime()`, and `GetIsStreaming()` return *only* software-tracked flags—no hardware queries are performed.  
+- **`DASArmStatus` Is Mutable**: The `DASArmStatus` property is read-write; consumers may replace the entire `IArmStatusData` instance.  
+- **Database Persistence Is Optional**: Methods like `SetInArm`, `SetInRealtime`, and `SetDASArmStatus` accept a `bool` parameter to control database writes.  
+- **`IsTriggerShorted`/`IsStartShorted` Are Trigger-Check-Specific**: These flags are *only* set during trigger-check diagnostics and are cleared by `ClearTriggerCheckStatus()`.  
+- **`ReceivedInvalidModeDuringSetup` Is a Heuristic**: Used as a fallback to infer *streaming* status when direct state queries fail, but is not a primary state indicator.
+
+---
+
+### 4. Dependencies  
+- **Depends On**:  
+  - None explicitly (pure interface definitions; no implementation or external library references in source).  
+- **Depended On By**:  
+  - Likely consumed by DAS factory control logic (e.g., test sequencers, diagnostics tools) that need to monitor DAS state without hardware coupling.  
+  - `IArmStatusData` is used as a data carrier for database persistence (via `SetDASArmStatus()`).  
+  - Concrete implementations (not shown) would depend on hardware communication layers (e.g., ARM-specific drivers) to populate `IArmStatusData`.
+
+---
+
+### 5. Gotchas  
+- **`GetIsInRealtime()` vs. `IsInRealtime`**:  
+  `GetIsInRealtime()` is a *state flag* (set by `SetInRealtime()`), while `IsInRealtime` in `IArmStatusData` is a *data field* that may be updated independently (e.g., by hardware polling). They are not guaranteed to be synchronized.  
+- **`IsTriggerShorted` ≠ `IsTriggered`**:  
+  Confusingly, `IsTriggerShorted` is *only* set during trigger-checks, whereas `IsTriggered` is set in many contexts (e.g., actual trigger events). Do not assume equivalence.  
+- **`ReceivedInvalidModeDuringSetup` Is Legacy Heuristic**:  
+  Its use as a streaming indicator is explicitly noted as a workaround for incomplete state reporting (see XML comment). Avoid relying on it for new logic unless legacy compatibility is required.  
+- **`SetDASArmStatus()` Persists Current State**:  
+  The parameterless overload persists the *current* `DASArmStatus` value but does *not* update it—consumers may mistakenly assume it refreshes or validates the data.  
+- **Nullable Value Semantics**:  
+  Properties like `InputMilliVolts`, `EventNumber`, and `TimeLeftInArm` use `double?`/`int?`/`ushort?`—`null` indicates *unknown/unavailable*, not a default value (e.g., `0`).