init

enriched-qwen3-coder-next/DataPRO/IService/StateMachine/StatusAndParameters.md

@@ -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.