DP44/enriched-qwen3-coder-next/DataPRO/RibeyeCommands.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/RibeyeCommands/CommandBase.cs DataPRO/RibeyeCommands/CalibrationCommands.cs DataPRO/RibeyeCommands/InformationCommands.cs DataPRO/RibeyeCommands/CommandPacket.cs DataPRO/RibeyeCommands/ArmCommands.cs	2026-04-16T03:49:10.362478+00:00	Qwen/Qwen3-Coder-Next-FP8	1	fc23195a4e943669

Ribeye Command Library Documentation

1. Purpose

This module provides a structured command abstraction layer for interacting with the Ribeye data acquisition system hardware. It implements concrete command classes for diagnostics, information retrieval, and arm/trigger control, built atop a common base (CommandBase) that handles low-level packet serialization, deserialization, and communication via the ICommunication interface. The library enables developers to issue structured commands (e.g., query serial number, arm device, retrieve current positions) and retrieve structured results, abstracting away the underlying ASCII-based protocol with #-delimited parameters and checksums.

2. Public Interface

CommandBase (abstract class)

• Namespace: DTS.DASLib.Command.Ribeye
• Inherits: AbstractCommandBase
• Purpose: Base class for all Ribeye commands; manages CommandPacket for command/response and provides string conversion utilities.

Constructors

• CommandBase(ICommunication sock)
  Initializes a new command instance with default timeout, creates a new CommandPacket for command.
• CommandBase(ICommunication sock, int TimeoutMillisec)
  Initializes with explicit timeout, creates a new CommandPacket for command.

Overridden Methods

• void CommandToString(ref List<List<string>> lines)
  Appends the ASCII representation of command.OriginalBytes (excluding \r/\n) to lines.
• void ResponseToString(ref List<List<string>> lines)
  Appends up to the first 30 ASCII characters of response.OriginalBytes (excluding \r/\n) to lines, or "Empty response!" if null.
• CommandPacketBase GetCommandPacket()
  Returns a new empty CommandPacket.
• CommandPacketBase GetCommandPacket(byte[] buffer)
  Returns a new CommandPacket initialized from buffer.

---

DiagnosticsCommands (abstract class)

• Namespace: DTS.DASLib.Command.Ribeye
• Inherits: CommandBase
• Purpose: Base class for diagnostics commands; sets command.Type = CommandType.Diagnostics.

Constructors

• DiagnosticsCommands(ICommunication sock)
• DiagnosticsCommands(ICommunication sock, int TimeoutMillisec)
  Both set command.Type = CommandType.Diagnostics and call command.SetCommand((byte)_Command, _Command.ToString()).

Protected Members

• abstract Commands _Command { get; }
  Must be implemented by derived classes to specify the command byte and name.

---

QueryCurrentPositions (concrete class)

• Inherits: DiagnosticsCommands
• Purpose: Queries current deflection positions (in mV) for all stack channels.

Constructors

• QueryCurrentPositions(ICommunication sock)
• QueryCurrentPositions(ICommunication sock, int TimeoutMillisec)
  Initializes command.Parameter[0] = "CURRENT_POSITIONS".

Properties

• int NumberOfChannels { get; }
  Number of stack channels returned in Positions.
• float[] Positions { get; }
  Array of deflection values (mV) per channel.

Overridden Methods

• CommandReceiveAction WholePackage()
  Parses response:
  • response.GetParameter(1, out int NumberOfPositions) → sets _numChannels.
  • response.GetParameter(2, out string PositionString) → splits by ,, then handles firmware quirk where last element contains space-separated values.
  • Parses each element as float into _Positions.

---

InformationCommands (abstract class)

• Namespace: DTS.DASLib.Command.Ribeye
• Inherits: CommandBase
• Purpose: Base class for information queries; sets command.Type = CommandType.Information.

Constructors

• InformationCommands(ICommunication sock)
• InformationCommands(ICommunication sock, int TimeoutMillisec)
  Both set command.Type = CommandType.Information and call command.SetCommand((byte)_Command, _Command.ToString()).

Protected Members

• abstract Commands _Command { get; }
  Must be implemented by derived classes.

---

QuerySerialNumber (concrete class)

• Inherits: InformationCommands
• Purpose: Queries device serial number.

Constructors

• QuerySerialNumber(ICommunication sock)
• QuerySerialNumber(ICommunication sock, int TimeoutMillisec)
  Sets command.Parameter[0] = "SERIAL_NUMBER".

Properties

• string SerialNumber { get; }
  Serial number string from response.Parameter[1].

Overridden Methods

• CommandReceiveAction WholePackage()
  On success, extracts serial number via response.GetParameter(1, out _serialnumber); silently ignores exceptions.

---

QueryNumberOfLEDs (concrete class)

• Inherits: InformationCommands
• Purpose: Queries number of LEDs on device.

Constructors

• QueryNumberOfLEDs(ICommunication sock)
• QueryNumberOfLEDs(ICommunication sock, int TimeoutMillisec)
  Sets command.Parameter[0] = "HOW_MANY_LEDS".

Properties

• uint NumberOfLEDs { get; }
  LED count from response.Parameter[1].

Overridden Methods

• CommandReceiveAction WholePackage()
  On success, extracts LED count via response.GetParameter(1, out _numberOfLEDs).
• void ResponseToString(ref List<List<string>> lines)
  Appends "NumberOfLEDs: {value}" to lines.

---

QueryDataAvailable (concrete class)

• Inherits: InformationCommands
• Purpose: Queries data collection timing parameters (note: uses Commands.QueryNumberOfLEDs command enum, but "DUMPINFO" parameter).

Constructors

• QueryDataAvailable(ICommunication sock)
• QueryDataAvailable(ICommunication sock, int TimeoutMillisec)
  Sets command.Parameter[0] = "DUMPINFO".

Properties

• float TotalMS { get; }
  Sum of PreTriggerMS and PostTriggerMS.
• float PreTriggerMS { get; }
  Absolute value of negative pre-trigger time (ms).
• float PostTriggerMS { get; }
  Post-trigger time (ms).

Overridden Methods

• CommandReceiveAction WholePackage()
  On success:
  • response.GetParameter(1, out int NegativePreTriggerMS) → _preTriggerMS = Math.Abs(NegativePreTriggerMS)
  • response.GetParameter(2, out _postTriggerMS)
  • _totalMS = _preTriggerMS + _postTriggerMS

---

ArmCommands (abstract class)

• Namespace: DTS.DASLib.Command.Ribeye
• Inherits: CommandBase
• Purpose: Base class for arm/trigger commands; sets command.Type = CommandType.Arm.

Constructors

• ArmCommands(ICommunication sock)
• ArmCommands(ICommunication sock, int TimeoutMillisec)
  Both set command.Type = CommandType.Arm and call command.SetCommand((byte)_Command, _Command.ToString()).

Protected Members

• abstract Commands _Command { get; }

---

Arm (concrete class)

• Inherits: ArmCommands
• Purpose: Arms the device for data collection.

Constructors

• Arm(ICommunication sock)
• Arm(ICommunication sock, int TimeoutMillisec)
  Sets command.Parameter[0] = "ARM".

Properties (setters)

• uint TStopMS { set; }
  Sets command.Parameter[1].
• uint TPostMS { set; }
  Sets command.Parameter[2].

---

QueryArmAndTriggerStatus (concrete class)

• Inherits: ArmCommands
• Purpose: Queries current arm/trigger status.

Constructors

• QueryArmAndTriggerStatus(ICommunication sock)
• QueryArmAndTriggerStatus(ICommunication sock, int TimeoutMillisec)
  Sets command.Parameter[0] = "S".

Properties

• bool IsArmed { get; set; }
• bool IsRecording { get; set; }
• bool IsTriggered { get; set; }

Overridden Methods

• CommandReceiveAction WholePackage()
  Parses response.Parameter[1] as int StatusCode. Maps via StatusCodeEnum:
  • Idle → all false
  • Armed → IsArmed = IsRecording = true
  • Busy → all true
  • DataAvailable/default → all false

---

Disarm (concrete class)

• Inherits: ArmCommands
• Purpose: Disarms the device.

Constructors

• Disarm(ICommunication sock)
• Disarm(ICommunication sock, int TimeoutMillisec)
  Sets command.Parameter[0] = "D".

---

PrepareForDataCollection (concrete class)

• Inherits: ArmCommands
• Purpose: Prepares device for data collection (e.g., erases buffer).

Constructors

• PrepareForDataCollection(ICommunication sock)
• PrepareForDataCollection(ICommunication sock, int TimeoutMillisec)
  Sets command.Parameter[0] = "ERASE".

---

DownloadTestData (concrete class)

• Inherits: ArmCommands
• Purpose: Downloads test data (note: uses Commands.QueryArmAndTriggerStatus enum, but "DUMPBIN" parameter).

Constructors

• DownloadTestData(ICommunication sock)
• DownloadTestData(ICommunication sock, int TimeoutMillisec)
  Sets command.Parameter[0] = "DUMPBIN".

Properties

• ushort[] Data { get; }
  Raw unsigned 16-bit sample data.
• int StartTimeMS { set; }
  Sets command.Parameter[1].
• int StopTimeMS { set; }
  Sets command.Parameter[2].
• uint NumberOfChannels { get; }
  Extracted from response.Parameter[1].
• int ExpectedNumberOfSamples { get; }
  Extracted from response.Parameter[2].

Methods

• void GetChannelData(int channel, out short[] signedADC)
  Converts ushort[] _Data to signed short[] per channel (interleaved → deinterleaved). Throws if channel out of range.

Overridden Methods

• CommandReceiveAction WholePackage()
  Parses response.Parameter[1] (channels), [2] (samples), then converts DownloadPacket.Data to _Data (16-bit unsigned, little-endian with per-sample checksum byte).
• CommandReceiveAction ReceiveBlockOK(ICommunicationReport report)
  Custom handling for DownloadPacket verification and parsing.
• CommandReceiveAction WholePackagePost()
  Builds QueryEventDataReport with short[][] data.

---

Trigger (concrete class)

• Inherits: ArmCommands
• Purpose: Manually triggers data acquisition.

Constructors

• Trigger(ICommunication sock)
• Trigger(ICommunication sock, int TimeoutMillisec)
  Sets command.Parameter[0] = "T".

---

CommandPacket (concrete class)

• Namespace: DTS.DASLib.Command.Ribeye
• Inherits: CommandPacketBase
• Purpose: Represents a command/response packet in the Ribeye protocol.

Nested Types

• enum CommandType { Reserved, Arm, Attribute, Diagnostics, EventData, FirmwareUpdate, Information, QAandUtility, Realtime }
• enum PacketState { Unknown, TooShort, OK }

Fields

• string[] Parameter
  Array of #-delimited parameters.
• byte Checksum
  Computed checksum over parameters.

Constructors

• CommandPacket()
  Initializes Parameter = new string[0], ShouldLog = true.
• CommandPacket(byte[] Bytes)
  Parses ASCII packet: splits on #, ignores \r/\n.

Methods

• PacketState VerifyPacket(byte[] Bytes)
  Returns PacketState.OK if Bytes.Length >= 4, ends with \r\n, and not error indicator (?).
  Returns TooShort if length < 4 or missing \r\n.
• byte[] ToBytes()
  Serializes to ASCII: param1#param2#...#checksum\r\n.
• void ComputeCRCs()
  Calls ComputeChecksum() (sum of all parameter bytes + #).
• void GetParameter(int Position, out T Value)
  Parses Parameter[Position] as T (supports double, float, int, string, etc.).
• void SetParameter(int Position, T Value)
  Sets Parameter[Position] = value.ToString().

Static Members

• void GetNextSequenceNumber()
  Thread-safe increment of global sequence number.

---

DownloadPacket (concrete class)

• Inherits: CommandPacket
• Purpose: Specialized packet for binary data downloads.

Fields

• byte[] Data
  Binary payload after header.

Constructors

• DownloadPacket(byte[] Bytes)
  Parses header (up to \r), then copies remaining bytes to Data.

Static Methods

• PacketState VerifyPacket(byte[] Bytes, ref uint BytesExpected)
  • If BytesExpected == 0: parses header (3 params), computes expected length:
    BytesExpected = (numChannels * 2 + 1) * numSamples + headerLength.
  • Returns OK if Bytes.Length >= BytesExpected, else TooShort.

---

3. Invariants

• Packet Protocol: All commands/responses use ASCII with # as parameter delimiter, terminated by \r\n. Checksum is computed over parameters only (sum of bytes).
• Parameter Indexing: GetParameter/SetParameter use 0-based indexing. Index 0 is always the command name (e.g., "ARM", "SERIAL_NUMBER").
• Command Type: Each command class sets command.Type to its category (Diagnostics, Information, Arm, etc.) in the constructor.
• Response Parsing: WholePackage() is only invoked after response is fully populated (via VerifyPacket and DownloadPacket/CommandPacket construction).
• Checksum Verification: CommandPacket.VerifyPacket does not validate checksum correctness—only checks for presence of \r\n terminator. Checksum is computed but not validated in VerifyPacket.
• Thread Safety: GetNextSequenceNumber uses a lock on GlobalSequenceNumberLock.
• Data Conversion: DownloadTestData interprets binary data as little-endian 16-bit samples with interleaved checksum bytes (per sample), but conversion logic appears flawed (i / _NumberOfChannels offset is suspicious).

---

4. Dependencies

External Dependencies (from imports)

• DTS.Common.ICommunication.ICommunication
  Interface for network/socket communication.
• DTS.Common.Enums.DASFactory.DFConstantsAndEnums.CommandStatus
  Used for response.Status and StatusNoError.
• DTS.Common.DASResource.Strings
  Used for localized error strings (e.g., QueryEventData_GetChannelData_Err1).
• DTS.Common.Utilities.Logging.APILogger
  Used for logging failures in WholePackagePost.
• DTS.DASLib.Command.CommandPacketBase
  Base class for CommandPacket (not shown, but assumed to define SequenceNumber, Status, OriginalBytes, etc.).

Inherited Dependencies

• AbstractCommandBase (from DTS.DASLib.Command)
  Provides core command execution logic, timeout handling, and baseCommand/baseResponse.

Inherited By

• All Ribeye command classes (QueryCurrentPositions, QuerySerialNumber, Arm, etc.) depend on CommandBase.
• DownloadTestData depends on DownloadPacket for binary data handling.

---

5. Gotchas

• Incorrect Command Enum Usage:
  • QueryDataAvailable sets _Command = Commands.QueryNumberOfLEDs (0x01) but uses "DUMPINFO" parameter.
  • DownloadTestData sets _Command = Commands.QueryArmAndTriggerStatus (0x03) but uses "DUMPBIN" parameter.
    This suggests historical copy-paste errors preserved intentionally.
• Checksum Handling:
  CommandPacket.VerifyPacket does not validate checksum correctness—only checks for \r\n termination. Checksum is computed but never checked for validity.
• Firmware Workaround:
  QueryCurrentPositions.WholePackage() contains a hack to split the last position value if it contains a space (e.g., "1.23 4.56" → two values). This masks a firmware bug.
• Parameter Indexing:
  QuerySerialNumber and QueryDataAvailable use Parameter[1] for the first data value (not Parameter[0]), since Parameter[0] holds the command name. This is consistent but non-intuitive.
• Data Conversion in DownloadTestData:
  The conversion loop for _Data has a suspicious offset:
  ByteArray[2 * i + i / _NumberOfChannels]
  This implies a variable-length checksum per channel, which contradicts the comment "per sample checksum". Likely incorrect.
• Silent Error Handling:
  QuerySerialNumber.WholePackage() catches exceptions during GetParameter but only logs via e.ToString() (no actual logging). Errors may go unnoticed.
• DownloadTestData.Data Type:
  Returns ushort[] but GetChannelData converts to short[]. Users must be aware of signed/unsigned mismatch.
• QueryArmAndTriggerStatus Status Mapping:
  DataAvailable state maps to all flags false, which may be counterintuitive (data available but not armed/recording/triggered).
• QueryDataAvailable Enum Mismatch:
  Uses Commands.QueryNumberOfLEDs enum value but "DUMPINFO" command string—likely a typo preserved for compatibility.
• No Validation of Timeout:
  TimeoutMillisec is passed to base class, but no validation or sanity checks are present in constructors.