DP44/enriched-qwen3-coder-next/Common/DTS.Common/Events/TSRAIRGo.md

---
source_files:
  - Common/DTS.Common/Events/TSRAIRGo/StartStopDASScan.cs
  - Common/DTS.Common/Events/TSRAIRGo/StartStopOverallStatusStateMachine.cs
  - Common/DTS.Common/Events/TSRAIRGo/Trigger.cs
  - Common/DTS.Common/Events/TSRAIRGo/Download.cs
  - Common/DTS.Common/Events/TSRAIRGo/RemoveDAS.cs
  - Common/DTS.Common/Events/TSRAIRGo/NavigateToDashboard.cs
  - Common/DTS.Common/Events/TSRAIRGo/Arm.cs
  - Common/DTS.Common/Events/TSRAIRGo/NavigateFromTSRAIRGoToDataPRO.cs
  - Common/DTS.Common/Events/TSRAIRGo/ClearIpAddress.cs
  - Common/DTS.Common/Events/TSRAIRGo/IpAddressToPing.cs
  - Common/DTS.Common/Events/TSRAIRGo/RecordingModeChanged.cs
  - Common/DTS.Common/Events/TSRAIRGo/SystemStatus.cs
  - Common/DTS.Common/Events/TSRAIRGo/DASSampleRateChanged.cs
  - Common/DTS.Common/Events/TSRAIRGo/SystemSettingsSampleRateChanged.cs
  - Common/DTS.Common/Events/TSRAIRGo/LevelTrigger.cs
generated_at: "2026-04-16T03:24:54.024483+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "60eefa60bead6fb1"
---

# TSRAIRGo Event Definitions

## 1. Purpose  
This module defines a set of Prism `PubSubEvent<T>`-based events used for inter-component communication within the TSRAIRGo subsystem. These events coordinate high-level system operations such as starting/stopping DAS scans, managing system status and errors, handling DAS device lifecycle (add/remove), configuring sampling rates and recording modes, triggering downloads, managing IP address pinging, and navigating between UI views (e.g., dashboard, DataPRO). The events serve as a decoupled messaging mechanism to synchronize state and actions across loosely coupled modules without direct dependencies.

## 2. Public Interface  

### Event Classes (all inherit from `Prism.Events.PubSubEvent<T>`)

| Event Name | Payload Type | Payload Description |
|------------|--------------|---------------------|
| `StartStopDASScanEvent` | `bool` | `true` to start DAS scan, `false` to stop. |
| `StartStopOverallStatusStateMachineEvent` | `bool` | `true` to start the overall status state machine, `false` to stop. |
| `TriggerEvent` | `TriggerArg` | Generic trigger event; `TriggerArg` is currently empty. |
| `DownloadEvent` | `DownloadArg` | Request to initiate a download; `DownloadArg` is currently empty. |
| `RemoveDASEvent` | `string` | Identifier (e.g., serial number or name) of the DAS device to remove. |
| `AddDASEvent` | `string` | Identifier of the DAS device to add. |
| `NavigateToDashboardEvent` | `NavigateToDashboardArg` | Request to navigate to the dashboard view; `NavigateToDashboardArg` is currently empty. |
| `ArmEvent` | `ArmArg` | Arm/disarm command. `Arm` property: `true` to arm, `false` to disarm. |
| `ClearIpAddressEvent` | `ClearIpAddressArg` | Request to clear an IP address. `Clear` property: `true` to clear, `false` otherwise. |
| `IpAddressToPingEvent` | `IpAddressToPingArg` | IP address to ping. `IpAddress` property: non-null string. |
| `SystemSettingsRecordingModeChangedEvent` | `RecordingModeArg` | Recording mode has changed. `RecordingModeDisplayString` property: human-readable mode string. |
| `SystemStatusEvent` | `SystemStatusArg` | General system status update. `Message` property: status message. |
| `SystemErrorEvent` | `SystemErrorArg` | System error notification. `Error` property: error message. |
| `DASSampleRateChangedEvent` | `DASSampleRateArg` | DAS sample rate changed. `SampleRate` property: integer (e.g., Hz). |
| `DASListChangedEvent` | `bool` | DAS device list has changed. Payload indicates presence/absence of devices (e.g., `true` if at least one DAS is present). |
| `SystemSettingsSampleRateChangedEvent` | `SystemSettingsSampleRateArg` | System settings sample rate changed. `SampleRate` property: integer. |
| `SystemSettingsDurationChangedEvent` | `SystemSettingsDurationChangedArg` | System settings duration changed. `Duration` property: `double` (e.g., seconds). |
| `SystemSettingsLevelTriggerChangedEvent` | `LevelTriggerArg` | Level trigger configuration changed in system settings. |
| `DASLevelTriggerChangedEvent` | `LevelTriggerArg` | Level trigger configuration changed for DAS. |

> **Note**: `NavigateToDashboardEvent` and `NavigateFromTSRAIRGoToDataPROEvent` (see below) reside in `DTS.Common.Events` (not `DTS.Common.Events.TSRAIRGo`), indicating cross-subsystem navigation.

| Event Name | Payload Type | Payload Description |
|------------|--------------|---------------------|
| `NavigateFromTSRAIRGoToDataPROEvent` | `NavigateFromTSRAIRGoToDataPROArg` | Request to navigate from TSRAIRGo to DataPRO view; `NavigateFromTSRAIRGoToDataPROArg` is currently empty. |

### Argument Classes

| Class | Properties | Notes |
|-------|------------|-------|
| `TriggerArg` | *(none)* | Placeholder; may be extended in future. |
| `DownloadArg` | *(none)* | Placeholder; may be extended in future. |
| `ArmArg` | `public bool Arm { get; set; }` | Controls arming state. |
| `ClearIpAddressArg` | `public bool Clear { get; set; }` | Controls whether to clear IP address. |
| `IpAddressToPingArg` | `public string IpAddress { get; set; }` | IP address to ping; must be non-null. |
| `RecordingModeArg` | `public string RecordingModeDisplayString { get; set; }` | Human-readable display string for recording mode. |
| `SystemStatusArg` | `public string Message { get; set; }` | Status message (e.g., "Ready", "Recording"). |
| `SystemErrorArg` | `public string Error { get; set; }` | Error message (e.g., exception text). |
| `DASSampleRateArg` | `public int SampleRate { get; set; }` | Sample rate in Hz. |
| `SystemSettingsSampleRateArg` | `public int SampleRate { get; set; }` | Sample rate in Hz. |
| `SystemSettingsDurationChangedArg` | `public double Duration { get; set; }` | Duration in seconds. |
| `LevelTriggerArg` | `string LevelTriggerText`, `bool? LevelTriggerAxis1`, `bool? LevelTriggerAxis2`, `bool? LevelTriggerAxis3` | Level trigger configuration. Implements custom `Equals()` logic for comparison. |

## 3. Invariants  

- All events derive from `Prism.Events.PubSubEvent<T>` and are intended for use with Prism’s event aggregation pattern.
- Payload types are strictly typed (`bool`, `string`, `int`, `double`, or custom argument classes).
- `LevelTriggerArg.Equals()` implements *partial equivalence*: two instances are equal if **any one** of the following matches:
  - Both `LevelTriggerAxis1` are `true` (and non-null),
  - Both `LevelTriggerAxis2` are `true`,
  - Both `LevelTriggerAxis3` are `true`,
  - Both `LevelTriggerText` are non-empty and equal.
  - Otherwise, `false`.
- `DASLevelTriggerChangedEvent` has a `SuppressMessage` attribute for naming convention (`S101`), indicating intentional deviation from PascalCase naming for compatibility with DAS domain terminology.
- Navigation events (`NavigateToDashboardEvent`, `NavigateFromTSRAIRGoToDataPROEvent`) reside in the top-level `DTS.Common.Events` namespace, implying broader system scope beyond TSRAIRGo.

## 4. Dependencies  

### Dependencies *of* this module:
- **Prism.Events**: All events rely on `Prism.Events.PubSubEvent<T>`, indicating a dependency on the Prism library (likely Prism.Core).
- **System**: Minimal usage (`System`, `System.Collections.Generic`, etc.) only in `DASSampleRateChanged.cs` (likely auto-generated using `using` directives).

### Dependencies *on* this module:
- Any module requiring TSRAIRGo coordination (e.g., UI modules, DAS service modules, status managers) will subscribe to these events.
- Specifically:
  - `StartStopDASScanEvent`, `StartStopOverallStatusStateMachineEvent`: Likely consumed by DAS control and state machine modules.
  - `AddDASEvent`/`RemoveDASEvent`: Consumed by device management modules.
  - `SystemStatusEvent`/`SystemErrorEvent`: Likely consumed by status display/UI modules.
  - Navigation events: Consumed by shell/navigation modules.

## 5. Gotchas  

- **Empty argument classes**: Several argument types (`TriggerArg`, `DownloadArg`, `NavigateToDashboardArg`, `NavigateFromTSRAIRGoToDataPROArg`) are currently empty. This may indicate incomplete design or future extensibility—consumers should not assume payload semantics beyond the event name.
- **`LevelTriggerArg.Equals()` semantics**: The custom equality logic is non-standard (only checks for *true* values in axis flags or text match). This may cause unexpected behavior if used in collections (e.g., `HashSet`, `Dictionary`) or comparisons expecting full structural equality.
- **Namespace inconsistency**: `NavigateToDashboardEvent` and `NavigateFromTSRAIRGoToDataPROEvent` are in `DTS.Common.Events`, while most others are in `DTS.Common.Events.TSRAIRGo`. This may reflect legacy or cross-module design decisions—verify intended scope.
- **No validation on payload values**: Events accept raw payloads (e.g., `IpAddress` may be invalid, `SampleRate` may be negative). Validation (if any) must occur at subscriber/consumer level.
- **`bool?` in `LevelTriggerArg`**: The use of nullable booleans (`bool?`) for axis flags suggests three-state logic (e.g., `true`/`false`/not applicable), but the `Equals()` implementation only considers `true` values—this may be a source of confusion or bugs.