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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
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	2026-04-16T03:55:13.365793+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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