110 lines
8.5 KiB
Markdown
110 lines
8.5 KiB
Markdown
---
|
|
source_files:
|
|
- DataPRO/IService/Classes/SLICEService/SLICE Service.TriggerCheck.cs
|
|
- DataPRO/IService/Classes/SLICEService/SLICE Service.cs
|
|
- DataPRO/IService/Classes/SLICEService/SLICE Service.Public.cs
|
|
generated_at: "2026-04-16T03:59:44.857737+00:00"
|
|
model: "Qwen/Qwen3-Coder-Next-FP8"
|
|
schema_version: 1
|
|
sha256: "358379cedd1a8fff"
|
|
---
|
|
|
|
# Documentation: `Slice<T>` Trigger Check Module
|
|
|
|
## 1. Purpose
|
|
|
|
This module implements the trigger check functionality for the `Slice<T>` DAS (Data Acquisition System) service class, providing asynchronous and synchronous methods to prepare, execute, and cancel hardware-level trigger and start-record integrity checks. It validates hardware input line states (e.g., short circuits on trigger/start inputs) before arming the system, and supports configurable polarity inversion for trigger and start signals. The module ensures safe pre-arm conditions by querying hardware via `InitializeHardwareLines` and reporting status via `ArmStatus`, while integrating with the broader `Slice<T>` service infrastructure for async callbacks and state management.
|
|
|
|
## 2. Public Interface
|
|
|
|
The interface is implemented explicitly via `ITriggerCheckActions`. All methods follow an async pattern using `LaunchAsyncWorker` and `SliceServiceAsyncInfo` for callback reporting.
|
|
|
|
### `void ITriggerCheckActions.PreStartTriggerCheck(ServiceCallback callback, object userData)`
|
|
- **Behavior**: Performs pre-startup configuration before trigger checks. If supported, sets `StartRecordPolarity` and `TriggerPolarity` attributes based on `InvertStart` and `InvertTrigger` properties using `SetSystemAttribute`. Logs exceptions but does not fail the operation on error.
|
|
- **Async worker**: `AsyncPreStartTriggerCheck`
|
|
|
|
### `void ITriggerCheckActions.PostStartTriggerCheck(ServiceCallback callback, object userData)`
|
|
- **Behavior**: No-op placeholder; immediately reports success. Presumably reserved for future or subclass use.
|
|
|
|
### `void ITriggerCheckActions.StartTriggerCheck(ServiceCallback callback, object userData)`
|
|
- **Behavior**: Initiates the main trigger check sequence. Executes `AsyncStartTriggerCheck`, which:
|
|
- Runs `InitializeHardwareLines` (if supported).
|
|
- Checks for `TriggerInputShorted` or `StartRecordShorted` conditions; reports specific errors if detected.
|
|
- Handles `CanceledException` and other exceptions via `info.Error`/`info.Cancel`.
|
|
- **Async worker**: `AsyncStartTriggerCheck`
|
|
|
|
### `void ITriggerCheckActions.DoStartCheck(ServiceCallback callback, object userData)`
|
|
- **Behavior**: Performs a *start-record-only* check. Executes `AsyncDoStartCheck`, which:
|
|
- Queries hardware via `InitializeHardwareLines`.
|
|
- Sets `ArmStatus.IsArmed = !ihl.TriggerInputShorted`
|
|
- Sets `ArmStatus.IsRecording = ihl.StartRecordShorted`
|
|
- Calls `SetDASArmStatus(status, true)` to persist status.
|
|
- **Async worker**: `AsyncDoStartCheck`
|
|
|
|
### `void ITriggerCheckActions.DoTriggerCheck(ServiceCallback callback, object userData)`
|
|
- **Behavior**: Performs a *full trigger check*. Executes `AsyncDoTriggerCheck`, which internally calls `DoTriggerCheckSync()`. Reports success/failure/cancel via `SliceServiceAsyncInfo`.
|
|
|
|
### `void ITriggerCheckActions.DoTriggerCheckSync()`
|
|
- **Behavior**: Synchronous variant of `DoTriggerCheck`. Directly queries hardware via `InitializeHardwareLines` (no async wrapper), constructs an `ArmStatus` object with:
|
|
- `IsTriggered = ihl.TriggerInputShorted`
|
|
- `IsArmed = !ihl.TriggerInputShorted`
|
|
- `IsTriggerShorted = ihl.TriggerInputShorted`
|
|
- `IsStartShorted = ihl.StartRecordShorted`
|
|
- Calls `SetDASArmStatus(status, true)` to update internal and persistent state.
|
|
|
|
### `void ITriggerCheckActions.CancelTriggerCheck(ServiceCallback callback, object userData)`
|
|
- **Behavior**: Cancels any pending trigger check. Currently a no-op; reports success immediately via `AsyncCancelTriggerCheck`.
|
|
|
|
### Supporting Types (from `Slice<T>` base class)
|
|
|
|
#### `protected virtual void AsyncPreStartTriggerCheck(object asyncInfo)`
|
|
- Actual worker method for `PreStartTriggerCheck`. Validates `asyncInfo` is `SliceServiceAsyncInfo`, configures polarity attributes if supported, logs exceptions, and calls `info.Success()`.
|
|
|
|
#### `protected virtual void AsyncStartTriggerCheck(object asyncInfo)`
|
|
- Actual worker for `StartTriggerCheck`. Executes `InitializeHardwareLines`, checks for shorted inputs, and reports errors (`"TriggerInputShorted"`, `"StartInputShorted"`) or success.
|
|
|
|
#### `private void AsyncDoTriggerCheck(object asyncInfo)`
|
|
- Wraps `DoTriggerCheckSync()` in async callback handling.
|
|
|
|
#### `private void AsyncDoStartCheck(object asyncInfo)`
|
|
- Wraps synchronous start-check logic in async callback handling.
|
|
|
|
#### `private void AsyncCancelTriggerCheck(object asyncInfo)`
|
|
- Wraps no-op cancellation logic.
|
|
|
|
## 3. Invariants
|
|
|
|
- **Hardware Query Dependency**: Trigger checks rely on `InitializeHardwareLines` command support. If `IsCommandSupported(DFConstantsAndEnums.ProtocolLimitedCommands.InitHardwareInputLines)` returns `false`, the check is skipped (no error), but shorted-line detection is bypassed.
|
|
- **Polarity Configuration**: `InvertStart` and `InvertTrigger` are only applied if `SupportsStartInversion()` and `SupportsTriggerInversion()` return `true`, respectively. Default implementations return `true`.
|
|
- **State Consistency**: After `DoTriggerCheckSync` or `DoStartCheck`, `SetDASArmStatus(status, true)` is called, ensuring `DASArmStatus` reflects current hardware state. `IsArmed` is always `!ihl.TriggerInputShorted`.
|
|
- **Error Reporting**: Shorted inputs (`TriggerInputShorted`, `StartRecordShorted`) result in immediate `info.Error()` with a literal string message; no exception is thrown.
|
|
- **Callback Safety**: All async workers wrap callback invocations in `try/catch` blocks to prevent unhandled exceptions from crashing the worker thread.
|
|
|
|
## 4. Dependencies
|
|
|
|
### Dependencies *on*:
|
|
- `DTS.DASLib.Command.SLICE.InitializeHardwareLines` — for querying hardware input line states.
|
|
- `DTS.DASLib.Command.SLICE.SetSystemAttribute` — for polarity configuration.
|
|
- `DTS.Common.Interface.DASFactory.IArmStatusData` and `ArmStatus` — for status reporting.
|
|
- `DTS.Common.Interface.Connection.IConnection` (via `Communication<T>`) — for transport.
|
|
- `DTS.Common.Enums.DASFactory.DFConstantsAndEnums.ProtocolLimitedCommands` — to check command support.
|
|
- `DTS.Common.Interface.DASFactory.IDASCommunication` — base interface.
|
|
- `DTS.Common.Utilities.Logging.APILogger` — for error logging.
|
|
- `SliceServiceAsyncInfo` — for async callback handling.
|
|
|
|
### Dependencies *of*:
|
|
- This module is used by higher-level arming workflows (e.g., `IArmActions`, `IRealTimeActions`) to ensure safe pre-arm conditions.
|
|
- Subclasses (`WinUSBSlice6Air`, `EthernetTsrAir`, etc.) inherit this behavior unless overridden.
|
|
|
|
## 5. Gotchas
|
|
|
|
- **`DoTriggerCheckSync` is synchronous but used in async wrappers**: `DoTriggerCheckSync()` performs blocking I/O; its async wrappers (`AsyncDoTriggerCheck`) do not offload the actual hardware query — only the callback dispatch. This may cause UI thread blocking if invoked on the UI thread.
|
|
- **No cancellation support in hardware checks**: `AsyncStartTriggerCheck` and `AsyncDoStartCheck` catch `CanceledException`, but there is no mechanism to *cancel* a pending `InitializeHardwareLines.SyncExecute()` call — cancellation only affects post-query callback dispatch.
|
|
- **Polarity inversion is hardware-dependent**: `SupportsStartInversion()` and `SupportsTriggerInversion()` are virtual and return `true` by default, but subclasses may override. If overridden to `false`, polarity settings are silently ignored.
|
|
- **`PostStartTriggerCheck` is a stub**: Its implementation does nothing; relying on it for post-check cleanup may be unsafe.
|
|
- **`DoStartCheck` conflates armed and recording states**: `IsArmed = !ihl.TriggerInputShorted`, but `IsRecording = ihl.StartRecordShorted`. This implies a device can be armed but *not* recording (e.g., trigger armed, start not yet pressed), which may be counterintuitive.
|
|
- **`TriggerResult` is public but not populated**: The `ITriggerCheckResult TriggerResult` property is declared but never set by this module — callers must interpret `DASArmStatus` instead.
|
|
- **No timeout configuration**: `SliceServiceAsyncInfo` has a `MaxTimeout` property, but it is never used or propagated to the underlying `SyncExecute()` calls — all hardware commands use fixed timeouts.
|
|
- **`InvertStart`/`InvertTrigger` defaults to `false`**: If not explicitly set, polarity remains non-inverted. No validation ensures these are set consistently with hardware wiring.
|
|
|
|
None identified beyond those above. |