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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/IService/StateMachine/StatusAndParameters/Realtime/RealtimeParameters.cs DataPRO/IService/StateMachine/StatusAndParameters/Realtime/RealtimeStatusInformation.cs	2026-04-16T04:01:39.522280+00:00	Qwen/Qwen3-Coder-Next-FP8	1	13ae579216023a96

Realtime

Documentation: Realtime Parameters and Status Module

---

1. Purpose

This module encapsulates the configuration (RealtimeParameters) and runtime state management (RealtimeStatusInformation) for initiating and controlling realtime data acquisition in the DAS (Distributed Acoustic Sensing) system. It serves as the interface between the state machine and the underlying RealtimeService, handling parameter propagation, sample rate/AAF (Anti-Alias Filter) configuration, and synchronization primitives for starting/stopping realtime acquisition across multiple DAS units. It enables both single-sample and multi-sample polling modes, with configurable delays, channel selection, and hardware-specific AAF computation.

---

2. Public Interface

RealtimeParameters (class)

• List<IDASCommunication> UnitsToStartRealtime { get; set; }
  List of DAS units to be started in realtime mode.

• int RealtimeDelayBetweenPollsInMilliSecond { get; set; }
  Delay (in ms) between successive polling attempts during realtime acquisition.

• bool AllowMultipleSampleRealtime { get; set; }
  Flag indicating whether multiple samples per poll are allowed.

• bool UseSingleSampleMode { get; set; }
  Flag to enable single-sample mode (overrides multi-sample behavior).

• List<int> ModuleIndices { get; set; }
  List of module indices to be used in realtime acquisition.

• Dictionary<IDASCommunication, byte[]> IdasToActiveChannels { get; set; }
  Mapping from DAS unit to its active channel bitmask (each byte represents 8 channels).

• double RealtimeSampleRate { get; set; }
  Target sample rate (Hz) for realtime acquisition.

• byte RealtimeSampleRateAAFilterRatio { get; set; }
  Ratio used to compute AAF cutoff: AAF = sampleRate / RealtimeSampleRateAAFilterRatio.

• bool SliceTurnOffAAFRealtime { get; set; }
  Flag to override AAF and disable it for hardware that supports it (see DFConstantsAndEnums.SupportsTurnOffAAFRealtime).

• void Reset()
  Initializes all properties to default values (empty collections, zero numerics, false booleans).

RealtimeStatusInformation (class)

• bool IsInRealtime { get; }
  Returns true if realtime acquisition is currently active (based on stopRealtimeEvent state). Uses a 2ms timeout for non-blocking check.

• void StopRealtime()
  Signals termination of realtime acquisition by setting stopRealtimeEvent.

• void StartRealtime()
  Overload that reads parameters from States.Instance.Realtime.Status.RealtimeParams and invokes the full StartRealtime(...) overload on a background Task.

• void StartRealtime(List<IDASCommunication> ldas, List<int> moduleArrayIndicies, bool useSingleSampleMode, double realtimeSampleRate, int realtimeDelayBetweenPolls, bool allowMultipleSampleRealtime, Action<double, double> SetRealtimeSampleRateAAF, Action CompleteAction, Dictionary<IDASCommunication, byte[]> idasToActiveChannels, Callback StartRealtimeCallback)
  Core method that:

  • Wraps StartRealtimeCallback in a Callback delegate and appends status completion/failure handlers.
  • Resets stopRealtimeEvent and instantiates RealtimeService.
  • If useSingleSampleMode is true: calls RealtimeService.StartActivePolling(...).
  • Else: calls RealtimeService.Start(...) with computed AAF via GetRealtimeAAFForHardware.
  • Invokes SetRealtimeSampleRateAAF with (sampleRate, AAF) for the first DAS (or NaN, NaN if no DAS).
  • Waits for either stopRealtimeEvent (external stop) or mr (service availability), then waits for realtimeDoneFromService (service completion).
  • Logs exceptions, sets CouldNotStartRealtime = true, and always invokes CompleteAction in finally.

• Action<double, double> SetRealtimeSampleRateAAF { get; set; }
  Callback to notify caller of current sample rate and computed AAF (used for UI updates or validation).

• Action CompleteAction { get; set; }
  Action invoked upon completion (success or failure) of StartRealtime(...).

• bool CouldNotStartRealtime { get; set; }
  Set to true if an exception occurs during StartRealtime(...).

• Callback StartRealtimeCallback { get; set; }
  User-provided callback invoked by RealtimeService during acquisition.

• private float GetRealtimeAAFForHardware(IDASCommunication idas, double samplerate)
  Computes AAF cutoff based on:

  • If SliceTurnOffAAFRealtime is true and hardware supports it → returns Common.Constants.SLICE2_NO_AAF_REALTIME_RATE.
  • Else if RealtimeSampleRateAAFilterRatio == 0 → returns samplerate.
  • Else → returns samplerate / RealtimeSampleRateAAFilterRatio.

• void Reset()
  Clears CompleteAction, resets realtimeDoneFromService, sets stopRealtimeEvent, and clears CouldNotStartRealtime.

---

3. Invariants

• RealtimeDelayBetweenPollsInMilliSecond must be ≥ 0 (no validation enforced in code; assumed caller responsibility).
• RealtimeSampleRateAAFilterRatio must be ≥ 0 (zero implies AAF = sample rate).
• RealtimeSampleRate must be > 0 when UseSingleSampleMode == false, otherwise behavior is undefined (no explicit check).
• UnitsToStartRealtime and IdasToActiveChannels must be consistent: every IDASCommunication in UnitsToStartRealtime must have an entry in IdasToActiveChannels (no enforcement; caller responsibility).
• ModuleIndices is only used when UseSingleSampleMode == false.
• IsInRealtime is true iff stopRealtimeEvent is not signaled (i.e., WaitOne(2, false) returns false).
• CompleteAction is always invoked in StartRealtime(...)’s finally block, regardless of success/failure.
• realtimeDoneFromService.WaitOne() is called after stopRealtimeEvent.Set() in StartRealtime(...), ensuring the service has fully stopped before proceeding.

---

4. Dependencies

Dependencies of this module:

• DTS.Common.Interface.DASFactory.IDASCommunication: Interface for DAS units.
• DTS.Common.Enums.DASFactory.DFConstantsAndEnums: Used for SupportsTurnOffAAFRealtime.
• DTS.Common.Constants.SLICE2_NO_AAF_REALTIME_RATE: Hardcoded AAF value when AAF is disabled.
• DTS.DASLib.Service.StateMachine.States: Access to global state (States.Instance.Realtime.Status.RealtimeParams).
• DTS.DASLib.Service.RealtimeService: Core service for starting/stopping acquisition.
• DTS.Common.Interface.StatusAndProgressBar.Callback & CallbackData: For async completion callbacks.
• DTS.Common.Utilities.Logging.APILogger: For exception logging.
• System.Threading: ManualResetEvent, Task, Thread.

Dependencies on this module:

• RealtimeStatusInformation.StartRealtime() is invoked by the state machine (likely via States.Instance.Realtime.Status.RealtimeStatus.StartRealtime()).
• RealtimeParameters is used as RealtimeStatus.RealtimeParams (inferred from usage in RealtimeStatusInformation).
• SetRealtimeSampleRateAAF callback is likely implemented by UI or monitoring components to update sample rate/AAF displays.

---

5. Gotchas

• RealtimeDelayBetweenPollsInMilliSecond is passed as int but may be interpreted as ms by RealtimeService — ensure caller uses integer milliseconds (no fractional values).
• GetRealtimeAAFForHardware uses only the first DAS (ldas[0]) to compute AAF when setting SetRealtimeSampleRateAAF, even if multiple DAS units are present. This assumes identical AAF behavior across units (not validated).
• UseSingleSampleMode bypasses AAF computation and calls StartActivePolling, which may have different behavior than Start (e.g., no AAF, no module indices).
• RealtimeService.ServiceAvailable event is subscribed inside StartRealtime(...), but the wait loop (mr.WaitOne) may exit prematurely if mr is set before stopRealtimeEvent is signaled, potentially leading to race conditions if RealtimeService becomes available slowly.
• stopRealtimeEvent is set twice — once in StopRealtime() and again in StartRealtime(...)’s finally block. While idempotent for ManualResetEvent, this could confuse debugging.
• No validation of IdasToActiveChannels entries — e.g., mismatched channel counts or invalid bitmasks are not caught.
• CouldNotStartRealtime is set on any exception, but the catch block does not rethrow or provide structured error info — callers must inspect this flag after StartRealtime.
• Reset() does not clear SetRealtimeSampleRateAAF, CompleteAction, or StartRealtimeCallback — only CompleteAction is cleared in Reset(). Other properties retain their values unless explicitly overwritten.

None identified beyond these.