DP44/enriched-qwen3-coder-next/DataPRO/SLICECommands/DownloadCommands.md

---
source_files:
  - DataPRO/SLICECommands/DownloadCommands/QueryEventDataReport.cs
  - DataPRO/SLICECommands/DownloadCommands/ResetEventList.cs
  - DataPRO/SLICECommands/DownloadCommands/QueryTotalEventCount.cs
  - DataPRO/SLICECommands/DownloadCommands/EventDataCommands.cs
  - DataPRO/SLICECommands/DownloadCommands/StartDownloadStreamData.cs
  - DataPRO/SLICECommands/DownloadCommands/DownloadByteConverter.cs
  - DataPRO/SLICECommands/DownloadCommands/QueryEthernetEventInfo.cs
  - DataPRO/SLICECommands/DownloadCommands/QueryEthernetEventData.cs
  - DataPRO/SLICECommands/DownloadCommands/QueryUARTEventData.cs
  - DataPRO/SLICECommands/DownloadCommands/QueryUARTEventInfo.cs
  - DataPRO/SLICECommands/DownloadCommands/QueryEventDataBase.cs
  - DataPRO/SLICECommands/DownloadCommands/GetNextDownloadStreamDataSamples.cs
generated_at: "2026-04-16T03:55:13.365793+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "cc8105887de8cbfa"
---

# Documentation: SLICE Event Data Download Commands

## 1. Purpose

This module provides a set of command classes for querying, downloading, and managing event data from SLICE2 firmware devices. It implements a family of commands for retrieving event metadata (e.g., `QueryTotalEventCount`, `QueryUARTEventInfo`, `QueryEthernetEventInfo`) and event payload data (e.g., `QueryEventData`, `QueryUARTEventData`, `QueryEthernetEventData`), as well as streaming download mechanisms (`StartDownloadStreamData`, `GetNextDownloadStreamDataSamples`). The module serves as the software-side counterpart to firmware event recording functionality, enabling structured retrieval of ADC samples, UART logs, and Ethernet recorder data via command/response protocol over an `ICommunication` interface.

## 2. Public Interface

### Classes

#### `QueryEventDataReport`
- **Purpose**: A report object returned via callback after executing event data download commands.
- **Properties**:
  - `object CallbackObject { get; set; }` — User-provided callback data.
  - `CommandStatus Status { get; set; }` — Execution status of the command.
  - `short[][] Data { get; set; }` — Downloaded ADC data, organized as `[channel][sample]`. *Note: This property is declared but not currently assigned in any `WholePackagePost` implementation in the provided source.*
- **Constructor**:
  - `QueryEventDataReport(CommandStatus status, object cbData)` — Initializes the report with status and callback data.

#### `ResetEventList`
- **Inherits**: `EventDataCommands`
- **Purpose**: Sends command to reset the event list on the device.
- **Constructors**:
  - `ResetEventList(ICommunication sock)`
  - `ResetEventList(ICommunication sock, int timeoutMillisec)`

#### `QueryTotalEventCount`
- **Inherits**: `EventDataCommands`
- **Purpose**: Queries the total number of events stored on the device.
- **Properties**:
  - `ushort Count { get; }` — Total event count returned by the device.
- **Constructors**:
  - `QueryTotalEventCount(ICommunication sock)`
  - `QueryTotalEventCount(ICommunication sock, int timeoutMillisec)`
- **Overrides**:
  - `protected override CommandReceiveAction WholePackage()` — Parses response to extract `Count`.
  - `public override void ResponseToString(ref List<List<string>> lines)` — Appends `"Count: {Count}"`.

#### `EventDataCommands`
- **Abstract base class** for all event data commands.
- **Protected Enum** `Commands` (values: `Reserved=0x00`, `ResetEventList=0x01`, `QueryTotalEventCount=0x02`, `QueryMatchingEvents=0x03`, `QueryEventData=0x04`, `SetEventData=0x05`, `StartDownloadStreamData=0x06`, `GetNextDownloadStreamDataSamples=0x07`, `QueryUartEventInfo=0x09`, `QueryUartEventData=0x0A`, `SetUartEventData=0x0B`, `GenerateEvent=0x0C`, `QueryEthernetEventInfo=0x0D`, `QueryEthernetEventData=0x0E`, `SetEthernetEventData=0x0F`)
- **Abstract Property**:
  - `protected abstract Commands Command { get; }`
- **Constructors**:
  - `EventDataCommands(ICommunication sock)`
  - `EventDataCommands(ICommunication sock, int timeoutMillisec)`
- **Behavior**: Sets `command.Type = CommandPacket.CommandType.EventData` and calls `command.SetCommand((byte)Command, Command.ToString())`.

#### `StartDownloadStreamData`
- **Inherits**: `EventDataCommands`
- **Purpose**: Initiates streaming event data download mode on the device (requires firmware ≥ A1N4). Any subsequent command stops streaming.
- **Constants**:
  - `public const byte AllChannels = 0xFF`
- **Properties**:
  - `ushort EventNumber { get; set; }` — Event number to stream. Sets parameter at offset 0.
  - `virtual ulong FirstSample { get; set; }` — First sample to stream. Sets parameter at offset 2.
  - `virtual ulong LastSample { get; set; }` — Last sample to stream. Sets parameter at offset 10.
- **Constructors**:
  - `StartDownloadStreamData(ICommunication sock)`
  - `StartDownloadStreamData(ICommunication sock, int timeoutMillisec)`
- **Behavior**: Allocates `command.Parameter = new byte[18]`.

#### `DownloadByteConverter`
- **Purpose**: Parses raw byte stream from streaming download packets (`GetNextDownloadStreamDataSamples`).
- **Nested Enum** `DlByteIndex` (offsets into packet header):
  - `Sync=0`, `Type=1`, `Command=2`, `Status=3`, `Group=4`, `Id=5`, `Datalength=6`, `SequenceNumber=8`, `HeaderCRC=10`, `DataCRC=12`, `DataADCStartOffset=14`, `DataADCEndOffset=22`, `DataStart=30`
- **Properties**:
  - `ushort SeqNumber { get; }` — Sequence number of current packet.
  - `ushort SeqNumberPrev { get; }` — Previous sequence number (updated after parsing).
  - `ulong DlAdcStartOffset { get; }` — Start offset in ADC samples.
  - `ulong DlAdcEndOffset { get; }` — End offset in ADC samples.
  - `ulong DlStreamSampleNumber { get; }` — *Not assigned in constructor; appears unused.*
  - `ushort[] DlData { get; }` — ADC data samples (little-endian, signed offset not applied).
  - `uint[] DlChannels { get; }` — *Declared but not assigned; appears unused.*
- **Constructor**:
  - `DownloadByteConverter(byte[] bytes)` — Parses packet header and data. Performs sequence number ordering check (logs out-of-order sequences to `Debug.WriteLine`).
- **Helper Methods**:
  - `GetULong(byte[] bytes, int offset)` — Reads 8-byte little-endian value.
  - `GetUShort(byte[] bytes, int offset)` — Reads 2-byte big-endian value (parameter order).
  - `GetUInt(byte[] bytes, int offset)` — Reads 4-byte big-endian value.
  - `GetDownloadUShort(byte[] bytes, int offset)` — Reads 2-byte little-endian value (data order).

#### `QueryEthernetEventInfo`
- **Inherits**: `EventDataCommands`
- **Purpose**: Retrieves metadata about an Ethernet event recorder event.
- **Properties**:
  - `ushort EventID { get; set; }` — Event ID to query (parameter input).
  - `ushort DataDownloaded { get; }` — Downloaded flag (1 = data present).
  - `ulong TotalByteCount { get; }` — Total bytes recorded.
  - `ulong TriggerByteCount { get; }` — Bytes recorded before trigger.
  - `ulong FaultByteCount { get; }` — Bytes recorded during fault condition.
  - `uint[] DataStartTimeStamp { get; }` — Timestamp array: `[seconds, nanoseconds]`.
- **Constructors**:
  - `QueryEthernetEventInfo(ICommunication sock)`
  - `QueryEthernetEventInfo(ICommunication sock, int timeoutMillisec)`
- **Overrides**:
  - `protected override CommandReceiveAction WholePackage()` — Parses 36-byte response.
  - `public override void ResponseToString(ref List<List<string>> lines)` — Appends all metadata fields.

#### `QueryEthernetEventData`
- **Inherits**: `EventDataCommands`
- **Purpose**: Retrieves payload data for an Ethernet event recorder event.
- **Properties**:
  - `ushort EventID { get; set; }` — Event ID (parameter input).
  - `uint RequestByteCount { get; set; }` — Number of bytes to request.
  - `ulong StartDataOffsetBytes { get; set; }` — Byte offset to start reading.
  - `byte[] Data { get; }` — Downloaded payload bytes.
- **Constants**:
  - `private const int PARAMETER_BYTE_COUNT = 14`
- **Constructors**:
  - `QueryEthernetEventData(ICommunication sock)`
  - `QueryEthernetEventData(ICommunication sock, int timeoutMS)`
- **Overrides**:
  - `protected override CommandReceiveAction WholePackage()` — Parses response header and payload.
  - `public override void CommandToString(...)` / `ResponseToString(...)` — Logs key parameters.

#### `QueryUARTEventData`
- **Inherits**: `EventDataCommands`
- **Purpose**: Retrieves payload data for a UART event recorder event.
- **Constants**:
  - `public const int MAX_DATA_LENGTH = 2000`
  - `public const int PAYLOAD_HEADER_LENGTH = 14`
- **Properties**:
  - `ushort EventNumber { get; set; }` — Event number.
  - `uint RequestByteCount { get; set; }` — Requested byte count.
  - `ulong RequestOffsetByteCount { get; set; }` — Byte offset.
  - `uint PayloadByteCount { get; }` — Actual bytes returned.
  - `ulong PayloadOffsetByteCount { get; }` — Offset of returned data.
  - `byte[] PayloadData { get; }` — Downloaded payload bytes.
- **Constructors**:
  - `QueryUARTEventData(ICommunication sock)`
  - `QueryUARTEventData(ICommunication sock, int timeoutMillisec)`
- **Overrides**:
  - `public override void Execute(...)` / `SyncExecute()` — Clears `_data` before execution.
  - `protected override CommandReceiveAction WholePackage()` — Parses header and payload.
  - `protected override CommandReceiveAction WholePackagePost()` — Creates `QueryEventDataReport` with status.
  - `public override void CommandToString(...)` / `ResponseToString(...)` — Logs key fields.

#### `QueryUARTEventInfo`
- **Inherits**: `EventDataCommands`
- **Purpose**: Retrieves metadata about a UART event recorder event.
- **Properties**:
  - `ushort EventNumber { get; set; }` — Event number (parameter input).
  - `bool DataPresent { get; }` — `1 == _dataPresent`.
  - `bool DataDownloaded { get; }` — `1 == _dataDownloaded`.
  - `ulong TotalByteCount { get; }`
  - `ulong TriggerByteCount { get; }`
  - `ulong FaultByteCount { get; }`
  - `uint StartTimestamp { get; }`
  - `uint EndTimestamp { get; }`
  - `uint BaudRate { get; }`
- **Constructors**:
  - `QueryUARTEventInfo(ICommunication sock)`
  - `QueryUARTEventInfo(ICommunication sock, int timeoutMillisec)`
- **Overrides**:
  - `protected override CommandReceiveAction WholePackage()` — Parses 48-byte response.
  - `protected override CommandReceiveAction WholePackagePost()` — Creates `QueryEventDataReport` with status.
  - `public override void CommandToString(...)` / `ResponseToString(...)` — Logs key fields.

#### `QueryEventDataBase`
- **Inherits**: `EventDataCommands`
- **Purpose**: Base class for querying ADC event data. Supports single-channel or multi-channel (up to 3) downloads.
- **Constants**:
  - `public const byte ALL_CHANNELS = 0xFF`
  - `private const ushort ADC_OFFSET = 0x8000`
- **Properties**:
  - `ushort EventNumber { get; set; }` — Event number.
  - `virtual ulong FirstSample { get; set; }` — First sample index.
  - `virtual ulong LastSample { get; set; }` — Last sample index.
  - `byte Channel { get; set; }` — Channel selector. `0xFF` → 3 channels; else → 1 channel.
  - `int ChannelsDownloaded { get; set; }`
  - `int Count { get; }` — Number of samples downloaded (`_samplesDownloaded`).
- **Constructors**:
  - `QueryEventDataBase(ICommunication sock)`
  - `QueryEventDataBase(ICommunication sock, int timeoutMillisec)`
- **Overrides**:
  - `public override void Execute(...)` / `SyncExecute()` — Validates `FirstSample ≤ LastSample`.
  - `protected override CommandReceiveAction WholePackage()` — Parses raw `ushort[]` data.
  - `protected override CommandReceiveAction WholePackagePost()` — Converts `ushort[]` to `short[][]` (signed ADC), populates `QueryEventDataReport.Data`.
  - `public virtual void GetChannelData(int channel, out short[] signedADC)` — Extracts signed ADC data for a channel, applying `ADC_OFFSET` subtraction and channel ordering logic.
  - `public virtual void GetRawIndexedData(int index, out ushort[] data)` — Extracts raw (unsigned) data for a channel index.
  - `public override void CommandToString(...)` / `ResponseToString(...)` — Logs key parameters.

#### `GetNextDownloadStreamDataSamples`
- **Inherits**: `EventDataCommands`
- **Purpose**: Retrieves next packet of streaming event data. Does *not* send a command; reads buffered data.
- **Properties**:
  - `DownloadByteConverter DlData { get; private set; }` — Parsed packet data.
- **Constructors**:
  - `GetNextDownloadStreamDataSamples(ICommunication sock)`
  - `GetNextDownloadStreamDataSamples(ICommunication sock, int msTimeout)`
- **Overrides**:
  - `public override void SyncExecute()` — Custom implementation to avoid sending command; reads response directly.
  - `public void ProcessData()` — Parses `baseResponse.ToBytes()` into `DlData`, validates CRC and sequence numbers.
- **Behavior**:
  - `LogCommands = false` and `baseCommand.ShouldLog = false` (in constructors).
  - Sequence validation: throws `Exception("sequence number overflow")` if `|Δseq| > MAX_SEQUENCE_DIFF` (1000) and not initial packet.

## 3. Invariants

- **Command Type**: All `EventDataCommands` subclasses set `command.Type = CommandPacket.CommandType.EventData`.
- **Parameter Initialization**: All subclasses initialize `command.Parameter` to a fixed size (e.g., `new byte[18]` for `StartDownloadStreamData`, `new byte[14]` for `QueryEthernetEventData`/`QueryUARTEventData`).
- **Parameter Offsets**: Command parameters are written at specific byte offsets (e.g., `EventNumber` at offset 0, `FirstSample` at offset 2, `LastSample` at offset 10, `Channel` at offset 18). Offsets are hardcoded in `SetParameter` calls.
- **Response Parsing**: `WholePackage()` methods parse response parameters using `response.GetParameter(offset, out T value)`, where offsets are fixed per command specification.
- **ADC Data Format**: Raw ADC data is stored as `ushort[]` in `QueryEventDataBase`. Conversion to signed `short[]` applies `ADC_OFFSET = 0x8000` subtraction.
- **Channel Ordering**: `GetChannelData` implements a non-trivial channel ordering scheme (e.g., for 9-channel stacks: `7 8 9 4 5 6 1 2 3` repeated).
- **Callback Report**: All event data download commands (`QueryEventDataBase`, `QueryUARTEventData`, `QueryUARTEventInfo`) produce a `QueryEventDataReport` in `WholePackagePost()`, with `Status` set to `Success` or `Failure` based on `response.Status`.
- **Streaming Sequence Validation**: `GetNextDownloadStreamDataSamples.ProcessData()` enforces sequence number ordering: `SeqNumberPrev == SeqNumber - 1` (or initial packet `SeqNumber == 0`), logging out-of-order sequences.

## 4. Dependencies

### Internal Dependencies
- **`DTS.Common.ICommunication`**: Provides `ICommunication` interface for socket communication.
- **`DTS.Common.Enums.DASFactory`**: Defines `CommandStatus`, `Commands` enum (in `EventDataCommands`), and `DFConstantsAndEnums`.
- **`DTS.Common.Interface.DASFactory`**: Contains `ICommunication` type alias.
- **`DTS.Common.DASResource`**: Provides `Strings` class (used in `QueryEventDataBase` for exception messages).
- **`DTS.Common.Utilities.Logging`**: Provides `APILogger` (used in `QueryUARTEventData`, `QueryUARTEventInfo`).
- **`DTS.Common.Strings`**: Used in `QueryUARTEventInfo` for logging.

### External Dependencies
- **`System.Collections.Generic`**, **`System`**, **`System.Linq`**, **`System.Threading.Tasks`**, **`System.Diagnostics`**, **`System.Text`**: Standard .NET libraries.
- **Firmware**: Requires SLICE2 firmware ≥ A1N4 for `StartDownloadStreamData` to function.

### Inheritance/Usage
- **Inherits from**: `CommandBase` (via `EventDataCommands`).
- **Used by**: Higher-level code that orchestrates event data retrieval (not visible in source).
- **Implements**: `ICommandReport` (via `QueryEventDataReport`).

## 5. Gotchas

- **`DownloadByteConverter.DlAdcStartOffset` Assignment Bug**: In constructor, `DlAdcStartOffset = GetUInt(...)` is overwritten by `DlAdcStartOffset = GetULong(...)`. The second assignment overwrites the first, but the `GetUInt` call is redundant and likely a typo. The correct field is `DlAdcEndOffset`, which uses `GetULong`.
- **`DownloadByteConverter.DlStreamSampleNumber` Unused**: Declared but never assigned; appears to be incomplete.
- **`DownloadByteConverter.DlChannels` Unused**: Declared but never assigned; likely a placeholder.
- **`QueryEventDataReport.Data` Not Populated**: The `Data` property is declared but never assigned in any `WholePackagePost()` method (e.g., `QueryEventDataBase` computes `short[][]` but does not assign it to `cbReport.Data`).
- **`QueryEventDataBase.Channel` Side Effect**: Setting `Channel` to `0xFF` sets `ChannelsDownloaded = 3`; otherwise `ChannelsDownloaded = 1`. This is implicit and not obvious from property definition.
- **`GetNextDownloadStreamDataSamples.SyncExecute()` Avoids Sending Command**: This is intentional (per comment) but may be surprising. It reads buffered data without sending a new command.
- **Sequence Number Overflow Handling**: `ProcessData()` throws `Exception("sequence number overflow")` if `|Δseq| > 1000`, but the comment notes this is unintentional (preserved from legacy code). This could crash the caller.
- **Byte Order Inconsistency**: `DownloadByteConverter` distinguishes between parameter byte order (big-endian for offsets) and data byte order (little-end