DP44/enriched-qwen3-coder-next/Common/DTS.Common.DataModel/Classes/Arming.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common.DataModel/Classes/Arming/Arming.cs	2026-04-16T03:33:38.565199+00:00	Qwen/Qwen3-Coder-Next-FP8	1	030ceff579d3b0a9

Arming

Purpose

The Arming class orchestrates the hardware arming sequence for DAS (Data Acquisition System) units in the TSRAIRGo system. It prepares, configures, clears flash memory, and arms one or more DAS units for data acquisition, handling both success and failure paths—including rollback via disarming—while integrating progress reporting and error handling. It serves as the central coordinator between high-level test configuration (TestTemplate), low-level DAS communication (IDASCommunication), and the underlying ArmingService, ensuring safe, deterministic transitions through the arming workflow.

---

Public Interface

public bool SetConfigAndFlashClear(...)

public bool SetConfigAndFlashClear(
    DataModel.TestTemplate currentTest,
    List<IDASCommunication> dasList,
    Dictionary<string, int> dasSampleRateList,
    double duration,
    StatusHelpers.SetProgressValueDelegate setProgressFunction,
    ServiceBase.ServiceCallbackErrorEventHandler onError)

• Behavior: Public entry point to configure DAS modules (set pre/post-trigger times, event count, wake-up timeout), flash erase, and arm. Internally calls SetConfigAndStartFlashClear(..., diagnosticsVoltage: false). Returns true on full success; false on any failure (with errors logged and reported via onError).

public void SoftwareTrigger(List<IDASCommunication> dasList)

• Behavior: Sends a software trigger command to all DAS units in dasList via ArmingService.Trigger. Logs failures via APILogger. Non-blocking with respect to caller (synchronous internally, but no return value or exception propagation to caller).

public void DisarmAsync(List<IDASCommunication> dasList)

• Behavior: Public wrapper that invokes Disarm(dasList) synchronously. Despite the name, no actual async behavior—it blocks until disarm completes.

---

Invariants

1. Thread Safety: All arming/disarming operations are guarded by lock (DASHardware.GetArmStatusLock), ensuring only one arming sequence runs at a time across the system.
2. Flash Erase Completion: Flash erase is considered successful only if all DAS units report CallbackStatus.Success or AllFinished without Failure. Partial failures abort the sequence.
3. Armed State Consistency: A DAS unit is marked as armed (DASArmStatus.IsArmed = true) only after PreparedArmNow succeeds for that unit. If any unit fails to arm, the system attempts to disarm all units (including those that may have partially armed) to prevent inconsistent states.
4. Progress Reporting: Progress callbacks (setProgressFunction) are invoked at defined stages: PREPARING_FOR_ARMING, PREPARING_DATA_MEMORY.
5. Timeout Enforcement: All blocking waits use ManualResetEvent.WaitOne(50, false) loops with cumulative timeWaited tracking, but no explicit timeout enforcement beyond ARM_NOW_TIMEOUT = 30000 (30s) for PrepareForArmNow.

---

Dependencies

Imports/Usings (Direct Dependencies)

• DTS.Common.Interface.DASFactory.IDASCommunication — Interface for DAS unit communication.
• DTS.DASLib.Service.ArmingService — Core service for low-level arming operations (BeginFlashErase, GetFlashEraseStatus, ReadyForArm, PrepareForArmNow, PreparedArmNow, Trigger, Disarm, EnableFaultChecking, CheckAlreadyLevelTriggered).
• DTS.Common.DataModel.Classes.TSRAIRGo.TSRAIR — Used for TSRAIR.TSRAIR_MAX_PRE_TRIGGER_SAMPLES.
• DTS.Common.Constant.DASSpecific.*, DTS.Common.Enums.TSRAIRGo.*, DTS.Common.SharedResource.Strings.* — Constants, enums, and localized strings (e.g., StringResources.FailedToArm).
• DTS.Common.DataModel.Common.* — Includes TestTemplate, AnalogInputDASChannel.
• DTS.Common.Utilities.Logging.APILogger — For logging exceptions and errors.

Inferred Consumers

• High-level test orchestration code (e.g., test runner, UI controller) that calls SetConfigAndFlashClear to arm hardware before a test.
• Any code needing to trigger acquisition (SoftwareTrigger) or abort (DisarmAsync/DisarmSync).

---

Gotchas

1. DisarmAsync is Misnamed: Despite the name, DisarmAsync calls DisarmSync, which blocks until disarm completes. No actual asynchronous behavior is implemented.
2. Hardcoded Timeout Values:
   • ARM_NOW_TIMEOUT = 30000 (30s) for PrepareForArmNow.
   • 30000 (30s) timeout in PreparedArmNow call (commented as ///////////fix the 30000 and 1 (at least)).
     These may need tuning per deployment.
3. PreTriggerSeconds Calculation:

   mod.PreTriggerSeconds = (double)TSRAIR.TSRAIR_MAX_PRE_TRIGGER_SAMPLES / Convert.ToInt32(dasSampleRateList[das.SerialNumber]);
   

   Assumes dasSampleRateList contains an entry for das.SerialNumber; missing entries will throw KeyNotFoundException.
4. AlreadyLevelTriggered Check:
   • Only checks analog channels (ch is AnalogInputDASChannel).
   • Fails arming if any channel reports AlreadyLevelTriggered, but does not expose which channels beyond logging to onError.
5. Fault Checking Limitation:
   EnableFaultChecking is only called for das.Count > 1, but the comment notes it’s limited to single unit at a time for TDAS—this logic may be incomplete or inconsistent.
6. No Cancellation Support:
   cancelEvent is created but never set externally (only internally on failure). No mechanism exists for a caller to abort mid-arming.
7. Flash Erase Failure Handling (FB 39345):
   If flash erase fails, the system returns false but may still attempt PrepareArmFunc if cancelEvent is not set—though bFailed blocks this. The logic is complex and error-prone.
8. PreparedArmNow Modifies State In-Place:
   Sets cbd.Target.DASArmStatus.IsArmed = true directly on the DAS object, which could cause race conditions if accessed concurrently outside the lock (though the lock mitigates this).