DP44/enriched-qwen3-coder-next/Common/DTS.Common/Interface/DASFactory/Download.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
Common/DTS.Common/Interface/DASFactory/Download/IDownloadReport.cs Common/DTS.Common/Interface/DASFactory/Download/IEventInfoAggregate.cs Common/DTS.Common/Interface/DASFactory/Download/IUARTDownload.cs Common/DTS.Common/Interface/DASFactory/Download/IUARTDownloadRequest.cs Common/DTS.Common/Interface/DASFactory/Download/IUARTEventInfo.cs Common/DTS.Common/Interface/DASFactory/Download/IDownloadRequest.cs Common/DTS.Common/Interface/DASFactory/Download/IEventInfo.cs Common/DTS.Common/Interface/DASFactory/Download/IDownload.cs	2026-04-16T03:10:59.435560+00:00	Qwen/Qwen3-Coder-Next-FP8	1	eb0f522ba1432603

Documentation: DASFactory Download Interfaces

1. Purpose

This module defines a set of interfaces that collectively model the data structures and contracts required for downloading event data (both analog/digital channel data and UART stream data) from a DAS (Data Acquisition System). It serves as the contract layer between the DAS hardware/firmware and the DASFactory application, enabling structured querying, reporting, and state tracking of event downloads. The interfaces standardize how event metadata (e.g., timestamps, fault flags, GUIDs), download requests (e.g., sample ranges, sub-sampling), and UART-specific data descriptors are represented and exchanged.

2. Public Interface

Interfaces

IDownloadReport

• IEventInfo[] Events { get; set; }
  Gets or sets an array of all standard (non-UART) event metadata stored on the DAS. Index corresponds to event number (0-based or 1-based depending on system convention).
• IUARTEventInfo[] UARTEvents { get; set; }
  Gets or sets an array of UART-specific event metadata. Each entry corresponds to a UART event, indexed by event number.

IEventInfoAggregate

• string EventId { get; set; }
  Unique identifier for the event (e.g., user-assigned or auto-generated).
• string EventDescription { get; set; }
  Human-readable description of the event.
• double DurationSeconds { get; set; }
  Total duration of the event in seconds.
• string GUID { get; set; }
  Globally unique identifier for the event.
• bool HasBeenDownloaded { get; set; }
  Indicates whether this event has been successfully downloaded.
• bool WasTriggered { get; set; }
  Indicates whether the event was triggered (as opposed to being a pre-trigger buffer).
• int NumberOfChannels { get; set; }
  Number of channels included in the event.
• ulong NumberOfSamples { get; set; }
  Total number of samples across all channels.
• ulong NumberOfBytes { get; set; }
  Total size of raw data (in bytes) for the event.
• bool Faulted { get; set; }
  Indicates whether the event completed with faults.
• int EventNumber { get; set; }
  Sequential event number assigned by the DAS.
• void Add(IEventInfo newEvent)
  Aggregates additional IEventInfo data into this aggregate (e.g., for multi-part events).

IUARTDownload

• uint BaudRate { get; }
  Current UART baud rate (read-only, populated by DASFactory).
• uint DataBits { get; }
  UART data bits configuration.
• StopBits StopBits { get; }
  UART stop bits configuration (from System.IO.Ports).
• Parity Parity { get; }
  UART parity configuration.
• Handshake FlowControl { get; }
  UART flow control setting.
• UartDataFormat DataFormat { get; }
  UART data format (e.g., ASCII, binary).
• IUARTDownloadRequest WhatUARTToDownload { get; set; }
  Request specifying which UART event and data range to download.
• void SetWhatUARTToDownload(IUARTDownloadRequest request, bool bSetInDb = true)
  Sets the UART download request; optionally persists to database.

IUARTDownloadRequest

• ushort EventNumber { get; set; }
  Event number of the UART event to download.
• ulong TotalByteCount { get; set; }
  Total number of bytes in the UART stream for the event.
• ulong TriggerByteCount { get; set; }
  Byte offset where the trigger occurred in the UART stream.
• ulong FaultByteCount { get; set; }
  Byte offset where the first fault occurred (if any).
• ulong StartTimestamp { get; set; }
  Start time of the UART stream (in ticks or system time units).
• ulong EndTimestamp { get; set; }
  End time of the UART stream.
• int BaudRate { get; set; }
  Baud rate used during UART recording.

IUARTEventInfo

• ushort EventNumber { get; set; }
  Event number of the UART event.
• bool DataPresent { get; set; }
  Indicates whether UART data exists for this event.
• bool DataDownloaded { get; set; }
  Indicates whether UART data has been successfully downloaded.
• ulong TotalByteCount { get; set; }
  Total bytes of UART data.
• ulong TriggerByteCount { get; set; }
  Byte offset of the trigger in the UART stream.
• ulong FaultByteCount { get; set; }
  Byte offset of the first fault in the UART stream.
• ulong StartTimestamp { get; set; }
  Start timestamp of the UART stream.
• ulong EndTimestamp { get; set; }
  End timestamp of the UART stream.
• uint BaudRate { get; set; }
  Baud rate during UART recording.

IDownloadRequest

• ushort EventNumber { get; set; }
  Event number to download.
• byte DASChannelNumber { get; set; }
  Channel number to download; ALL_CHANNELS (value not shown, assumed constant) for all.
• ulong StartSample { get; set; }
  First sample index to include.
• ulong EndSample { get; set; }
  Last sample index to include.
• ulong SamplesToSkip { get; set; }
  Sub-sampling factor: 0 or 1 = no sub-sampling; n > 1 = keep every n-th sample.
  Constraint: (EndSample - StartSample + 1) must be divisible by SamplesToSkip.
• double StartRecordTimestampSec { get; set; }
  Start time of recording in seconds (integer part).
• double TriggerTimestampSec { get; set; }
  Trigger time in seconds (integer part).
• double StartRecordTimestampNanoSec { get; set; }
  Fractional (nanosecond) part of start time.
• double TriggerTimestampNanoSec { get; set; }
  Fractional (nanosecond) part of trigger time.
• bool PTPMasterSync { get; set; }
  Indicates whether PTP (Precision Time Protocol) master synchronization was used.

IDownload

• IDownloadRequest WhatToDownload { get; set; }
  Request specifying which event/channel/sample range to download.
• void SetWhatToDownload(IDownloadRequest request, bool bSetInDb = true)
  Sets the download request; optionally persists to database.
• IDownloadReport EventInfo { get; set; }
  Report containing all event metadata retrieved from the DAS.
• void SetEventInfo(IDownloadReport eventInfo, bool bSetInDb = true)
  Sets the event metadata report; optionally persists to database.
• bool[] EventDownloadedStatus { get; set; }
  Array (indexed by event number) indicating whether each event has been downloaded.
• void SetEventDownloadStatus(bool[] status, bool storeInDb = true)
  Sets the downloaded status array.
• Guid[] EventGuids { get; set; }
  Array (indexed by event number) of GUIDs for events.
• void SetEventGuids(Guid[] guids, bool storeInDb = true)
  Sets the event GUIDs array.
• ushort[] FaultFlags { get; set; }
  Array (indexed by event number) of fault flags.
• void SetEventFaultFlags(ushort[] flags, bool storeInDb = true)
  Sets the fault flags array.
• uint[] ExtendedFaultFlags1 { get; set; }
  Array of extended fault flags (1 of 4).
• uint[] ExtendedFaultFlags2 { get; set; }
  Array of extended fault flags (2 of 4).
• uint[] ExtendedFaultFlags3 { get; set; }
  Array of extended fault flags (3 of 4).
• uint[] ExtendedFaultFlags4 { get; set; }
  Array of extended fault flags (4 of 4).
• void SetExtendedFaultFlags(uint[][] flags)
  Populates all four ExtendedFaultFlags* arrays from a jagged array (first dimension = events, second = up to 4 flags per event).
• byte[] ArmAttempts { get; set; }
  Array (indexed by event number) of arm attempt counts.
• void SetEventArmAttemps(byte[] armAttempts, bool storeInDb = true)
  Sets the arm attempts array.

IDownloadPathAware

• string EventPath { get; set; }
  Filesystem or logical path where event data is stored.

DownloadExtendedFaultFunctions (static helper class)

• static void SetExtendedFaultFlags(uint[][] flags, IDownload download)
  Helper to populate ExtendedFaultFlags1–4 arrays from a jagged array. If flags is null or empty, calls ClearExtendedFaultFlags.
• static void ClearExtendedFaultFlags(IDownload download)
  Sets all ExtendedFaultFlags* arrays to null.

IEventInfo

• IDASModule[] Modules { get; set; }
  Array of module info objects, indexed by ModuleArrayIndex.
• int EventNumber { get; set; }
  Event number.
• Guid TestGUID { get; set; }
  GUID of the event.
• ushort FaultFlags { get; set; }
  Primary fault flags.
• ushort FaultFlagsEx { get; set; }
  Extended fault flags (legacy, separate from ExtendedFaultFlags* arrays).
• byte ArmAttempts { get; set; }
  Number of arm attempts.
• DateTime TestTime { get; set; }
  Timestamp of the event.
• string TestID { get; set; }
  Event ID string.
• string Description { get; set; }
  Event description.
• bool HasBeenDownloaded { get; set; }
  Download status.
• bool WasTriggered { get; set; }
  Trigger status.
• void ClearFaults()
  Clears fault flags (implementation-specific).

3. Invariants

• Event indexing: Arrays like Events, UARTEvents, EventDownloadedStatus, EventGuids, FaultFlags, ExtendedFaultFlags*, and ArmAttempts are indexed by event number. The exact mapping (0-based vs. 1-based) is not specified and must be inferred from usage.
• Sample range constraint: For IDownloadRequest.SamplesToSkip, (EndSample - StartSample + 1) must be divisible by SamplesToSkip. This is enforced by the caller.
• UART event data consistency: In IUARTEventInfo and IUARTDownloadRequest, TriggerByteCount and FaultByteCount are byte offsets within the UART stream (TotalByteCount), and StartTimestamp ≤ EndTimestamp.
• Extended fault flags: Exactly 4 extended fault flag arrays exist (ExtendedFaultFlags1–4), and SetExtendedFaultFlags expects each inner array to have at most 4 elements.
• Download atomicity: Downloads are performed one event at a time (per comments on ExtendedFaultFlags*), though metadata may be batched.

4. Dependencies

Dependencies of this module:

• DTS.Common.Interface.DownloadEvent (via IDownloadReport): Defines IEventInfo and IUARTEventInfo interfaces (not included here, but referenced).
• DTS.Common.Enums (via IUARTDownload): Defines UartDataFormat, StopBits, Parity, Handshake enums.
• System.IO.Ports (via IUARTDownload): For StopBits, Parity, Handshake.
• DTS.Common.Interface.DASFactory.Config (via IEventInfo): Defines IDASModule interface (not included here).

Dependencies on this module:

• DASFactory application logic (e.g., download workflows, UI, persistence).
• Any module implementing IDownload, IDownloadRequest, IDownloadReport, etc., to interact with DAS hardware or storage.

5. Gotchas

• SamplesToSkip validation is caller responsibility: The interface does not enforce divisibility of (EndSample - StartSample + 1) by SamplesToSkip; violation may cause runtime errors.
• EventNumber indexing ambiguity: Arrays are indexed by event number, but whether event numbers start at 0 or 1 is not specified. This is a common source of off-by-one bugs.
• FaultFlagsEx vs. ExtendedFaultFlags*: IEventInfo.FaultFlagsEx is a single ushort, while IDownload exposes four uint[] arrays (ExtendedFaultFlags1–4). These are likely related but not directly synchronized—caution is needed when updating one without the other.
• DownloadExtendedFaultFunctions is static: Its methods operate on an IDownload instance but do not modify the IDownload interface itself; callers must ensure the instance is valid before calling.
• bSetInDb parameter semantics: Many Set* methods include bSetInDb/storeInDb parameters. Their behavior (e.g., whether they overwrite or merge) is not documented.
• UART and analog event separation: IDownloadReport separates Events (analog/digital) and UARTEvents (serial), but there is no explicit link between them (e.g., same EventNumber may appear in both). This could lead to inconsistencies if not managed carefully.
• Timestamp units: StartTimestamp/EndTimestamp in UART interfaces are ulong, but their unit (e.g., ticks, nanoseconds, microseconds) is not specified. Similarly, StartRecordTimestampSec and StartRecordTimestampNanoSec are split—ensure correct reconstruction of full timestamps.
• Missing ALL_CHANNELS constant: The DASChannelNumber comment references ALL_CHANNELS, but its value is not defined in the provided source.

None identified beyond those above.