init

docs/ai/DataPRO/RibeyeCommands.md

@@ -0,0 +1,356 @@
+---
+source_files:
+  - DataPRO/RibeyeCommands/CommandBase.cs
+  - DataPRO/RibeyeCommands/CalibrationCommands.cs
+  - DataPRO/RibeyeCommands/InformationCommands.cs
+  - DataPRO/RibeyeCommands/CommandPacket.cs
+  - DataPRO/RibeyeCommands/ArmCommands.cs
+generated_at: "2026-04-17T15:52:59.500502+00:00"
+model: "zai-org/GLM-5-FP8"
+schema_version: 1
+sha256: "eecaf47313af0712"
+---
+
+# Ribeye Commands Module Documentation
+
+## 1. Purpose
+
+This module implements a command/response protocol for communicating with "Ribeye" hardware devices (likely a data acquisition system or test equipment). It provides a class hierarchy for constructing, sending, and receiving command packets over a communication interface (`ICommunication`). The module handles serialization/deserialization of command packets, timeout management, and parsing of binary response data. It exists to abstract the low-level protocol details from higher-level application code, providing strongly-typed command classes for operations like arming triggers, querying device status, downloading test data, and retrieving calibration information.
+
+---
+
+## 2. Public Interface
+
+### CommandBase (Abstract)
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Base class for all Ribeye commands. Inherits from `AbstractCommandBase`.
+
+**Constructors:**
+- `CommandBase(DTS.Common.Interface.DASFactory.ICommunication sock)` — Initializes with a communication socket and default timeout.
+- `CommandBase(DTS.Common.Interface.DASFactory.ICommunication sock, int TimeoutMillisec)` — Initializes with a communication socket and custom timeout in milliseconds.
+
+**Protected Properties:**
+- `CommandPacket command { get; set; }` — The command packet to send.
+- `CommandPacket response { get; set; }` — The response packet received.
+
+**Public Methods:**
+- `override void CommandToString(ref List<List<string>> lines)` — Serializes the command's original bytes to a string representation, filtering out `\n` and `\r` characters.
+- `override void ResponseToString(ref List<List<string>> lines)` — Serializes the response's first 30 bytes to a string representation, or reports "Empty response!" if null.
+
+**Protected Methods:**
+- `override CommandPacketBase GetCommandPacket()` — Factory method returning a new `CommandPacket`.
+- `override CommandPacketBase GetCommandPacket(byte[] buffer)` — Factory method returning a new `CommandPacket` initialized from bytes.
+
+---
+
+### CommandPacket
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Represents a serialized command/response packet. Inherits from `CommandPacketBase`.
+
+**Nested Enum:**
+```csharp
+public enum CommandType {
+    Reserved = 0x00,
+    Arm = 0x01,
+    Attribute = 0x02,
+    Diagnostics = 0x03,
+    EventData = 0x04,
+    FirmwareUpdate = 0x05,
+    Information = 0x06,
+    QAandUtility = 0x07,
+    Realtime = 0x08
+}
+```
+
+**Constructors:**
+- `CommandPacket()` — Initializes with empty parameter array and `ShouldLog = true`.
+- `CommandPacket(byte[] Bytes)` — Parses raw bytes into a packet, splitting on `#` delimiters.
+
+**Public Fields:**
+- `string[] Parameter` — Array of parameter strings.
+
+**Public Properties:**
+- `byte[] OriginalBytes` (inherited) — Raw bytes of the packet.
+
+**Public Methods:**
+- `override PacketState VerifyPacket(byte[] Bytes)` — Validates packet structure. Returns `PacketState.Unknown` if null or starts with `?`, `PacketState.TooShort` if less than 4 bytes or missing `\r\n` terminator, `PacketState.OK` otherwise.
+- `override byte[] ToBytes()` — Serializes parameters to byte array with `#` delimiters, checksum, and `\r\n` terminator. Stores result in `OriginalBytes`.
+- `override void ComputeCRCs()` — Computes the checksum for the packet.
+- `override object ConvertByteToCommandType(byte b)` — Converts a byte to `CommandType` enum.
+- `override void GetNextSequenceNumber()` — Thread-safe incrementing sequence number assignment.
+
+**GetParameter Overloads:**
+- `void GetParameter(int Position, out double Value)`
+- `void GetParameter(int Position, out UInt64 Value)`
+- `void GetParameter(int Position, out Int64 Value)`
+- `void GetParameter(int Position, out Int32 Value)`
+- `void GetParameter(int Position, out UInt32 Value)`
+- `void GetParameter(int Position, out Int16 Value)`
+- `void GetParameter(int Position, out UInt16 Value)`
+- `void GetParameter(int Position, out float Value)`
+- `void GetParameter(int Position, out string Value)`
+
+**SetParameter Overloads:**
+- `void SetParameter(int Position, double Value)`
+- `void SetParameter(int Position, Int64 Value)`
+- `void SetParameter(int Position, UInt64 Value)`
+- `void SetParameter(int Position, Int32 Value)`
+- `void SetParameter(int Position, UInt32 Value)`
+- `void SetParameter(int Position, Int16 Value)`
+- `void SetParameter(int Position, UInt16 Value)`
+- `void SetParameter(int Position, float Value)`
+- `void SetParameter(int Position, string Value)`
+
+---
+
+### DownloadPacket
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Extends `CommandPacket` for binary data downloads.
+
+**Constructor:**
+- `DownloadPacket(byte[] Bytes)` — Parses header parameters (delimited by `#`, terminated by `\n`) and extracts binary `Data` payload.
+
+**Public Field:**
+- `byte[] Data` — Binary payload following the header.
+
+**Static Method:**
+- `static PacketState VerifyPacket(byte[] Bytes, ref uint BytesExpected)` — Validates download packet, calculating expected byte count from header parameters (number of channels × samples × 2 bytes + checksums).
+
+---
+
+### DiagnosticsCommands (Abstract)
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Base class for diagnostic commands. Inherits from `CommandBase`.
+
+**Protected Enum:**
+```csharp
+protected enum Commands {
+    Reserved = 0x00,
+    QueryCurrentPositions = 0x01
+}
+```
+
+**Constructors:**
+- `DiagnosticsCommands(DTS.Common.Interface.DASFactory.ICommunication sock)`
+- `DiagnosticsCommands(DTS.Common.Interface.DASFactory.ICommunication sock, int TimeoutMillisec)`
+
+Both constructors set `command.Type = CommandPacket.CommandType.Diagnostics` and call `SetCommand` with the derived class's `_Command` value.
+
+---
+
+### QueryCurrentPositions
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Retrieves current position values from the device. Inherits from `DiagnosticsCommands`.
+
+**Constructors:**
+- `QueryCurrentPositions(DTS.Common.Interface.DASFactory.ICommunication sock)`
+- `QueryCurrentPositions(DTS.Common.Interface.DASFactory.ICommunication sock, int TimeoutMillisec)`
+
+**Public Properties:**
+- `int NumberOfChannels { get; }` — Number of position values returned.
+- `float[] Positions { get; }` — Array of position values.
+
+**Protected Method:**
+- `override CommandReceiveAction WholePackage()` — Parses response parameters 1 (count) and 2 (comma-separated position string) into `_Positions` array.
+
+---
+
+### InformationCommands (Abstract)
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Base class for information query commands. Inherits from `CommandBase`.
+
+**Protected Enum:**
+```csharp
+protected enum Commands {
+    Reserved = 0x00,
+    QueryNumberOfLEDs = 0x01,
+    QueryDataAvailable = 0x02,
+    QuerySerialNumber = 0x03
+}
+```
+
+**Constructors:**
+- `InformationCommands(DTS.Common.Interface.DASFactory.ICommunication sock)`
+- `InformationCommands(DTS.Common.Interface.DASFactory.ICommunication sock, int TimeoutMillisec)`
+
+Both constructors set `command.Type = CommandPacket.CommandType.Information`.
+
+---
+
+### QuerySerialNumber
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Queries the device serial number. Inherits from `InformationCommands`.
+
+**Constructors:**
+- `QuerySerialNumber(DTS.Common.Interface.DASFactory.ICommunication sock)`
+- `QuerySerialNumber(DTS.Common.Interface.DASFactory.ICommunication sock, int TimeoutMillisec)`
+
+**Public Property:**
+- `string SerialNumber { get; }` — The retrieved serial number.
+
+**Protected Method:**
+- `override CommandReceiveAction WholePackage()` — Extracts serial number from response parameter 1.
+
+---
+
+### QueryNumberOfLEDs
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Queries the number of LEDs in the device. Inherits from `InformationCommands`.
+
+**Constructors:**
+- `QueryNumberOfLEDs(DTS.Common.Interface.DASFactory.ICommunication sock)`
+- `QueryNumberOfLEDs(DTS.Common.Interface.DASFactory.ICommunication sock, int TimeoutMillisec)`
+
+**Public Property:**
+- `uint NumberOfLEDs { get; }` — The number of LEDs.
+
+**Public Method:**
+- `override void ResponseToString(ref List<List<string>> lines)` — Appends formatted LED count to output.
+
+**Protected Method:**
+- `override CommandReceiveAction WholePackage()` — Extracts LED count from response parameter 1.
+
+---
+
+### QueryDataAvailable
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Queries available data timing information. Inherits from `InformationCommands`.
+
+**Constructors:**
+- `QueryDataAvailable(DTS.Common.Interface.DASFactory.ICommunication sock)`
+- `QueryDataAvailable(DTS.Common.Interface.DASFactory.ICommunication sock, int TimeoutMillisec)`
+
+**Public Properties:**
+- `float TotalMS { get; }` — Total milliseconds (`PreTriggerMS + PostTriggerMS`).
+- `float PreTriggerMS { get; }` — Pre-trigger milliseconds (absolute value of negative value from device).
+- `float PostTriggerMS { get; }` — Post-trigger milliseconds.
+
+**Protected Method:**
+- `override CommandReceiveAction WholePackage()` — Extracts timing values from response parameters 1 (pre-trigger, converted to absolute) and 2 (post-trigger).
+
+---
+
+### ArmCommands (Abstract)
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Base class for arm/trigger related commands. Inherits from `CommandBase`.
+
+**Protected Enum:**
+```csharp
+protected enum Commands {
+    Reserved = 0x00,
+    Arm = 0x01,
+    Disarm = 0x02,
+    QueryArmAndTriggerStatus = 0x03,
+    PrepareForDataCollection = 0x04,
+    DownloadTestData = 0x05,
+    Trigger = 0x06
+}
+```
+
+**Constructors:**
+- `ArmCommands(DTS.Common.Interface.DASFactory.ICommunication sock)`
+- `ArmCommands(DTS.Common.Interface.DASFactory.ICommunication sock, int TimeoutMillisec)`
+
+Both constructors set `command.Type = CommandPacket.CommandType.Arm`.
+
+---
+
+### Arm
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Arms the device for data collection. Inherits from `ArmCommands`.
+
+**Constructors:**
+- `Arm(DTS.Common.Interface.DASFactory.ICommunication sock)`
+- `Arm(DTS.Common.Interface.DASFactory.ICommunication sock, int TimeoutMillisec)`
+
+**Public Properties (setters only):**
+- `uint TStopMS { set; }` — Sets parameter 1 (stop time in ms).
+- `uint TPostMS { set; }` — Sets parameter 2 (post-trigger time in ms).
+
+---
+
+### QueryArmAndTriggerStatus
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Queries the current arm/trigger status. Inherits from `ArmCommands`.
+
+**Constructors:**
+- `QueryArmAndTriggerStatus(DTS.Common.Interface.DASFactory.ICommunication sock)`
+- `QueryArmAndTriggerStatus(DTS.Common.Interface.DASFactory.ICommunication sock, int TimeoutMillisec)`
+
+**Public Fields:**
+- `bool IsArmed`
+- `bool IsRecording`
+- `bool IsTriggered`
+
+**Protected Method:**
+- `override CommandReceiveAction WholePackage()` — Parses status code from response parameter 1 and sets `IsArmed`, `IsRecording`, `IsTriggered` based on `StatusCodeEnum` (Idle=0, Armed=1, Busy=2, DataAvailable=3).
+
+---
+
+### Disarm
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Disarms the device. Inherits from `ArmCommands`.
+
+**Constructors:**
+- `Disarm(DTS.Common.Interface.DASFactory.ICommunication sock)`
+- `Disarm(DTS.Common.Interface.DASFactory.ICommunication sock, int TimeoutMillisec)`
+
+---
+
+### PrepareForDataCollection
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Prepares device for data collection (sends "ERASE" command). Inherits from `ArmCommands`.
+
+**Constructors:**
+- `PrepareForDataCollection(DTS.Common.Interface.DASFactory.ICommunication sock)`
+- `PrepareForDataCollection(DTS.Common.Interface.DASFactory.ICommunication sock, int TimeoutMillisec)`
+
+---
+
+### DownloadTestData
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Downloads binary test data from the device. Inherits from `ArmCommands`.
+
+**Constructors:**
+- `DownloadTestData(DTS.Common.Interface.DASFactory.ICommunication sock)`
+- `DownloadTestData(DTS.Common.Interface.DASFactory.ICommunication sock, int TimeoutMillisec)`
+
+**Public Properties:**
+- `ushort[] Data { get; }` — Raw downloaded data.
+- `uint NumberOfChannels { get; }` — Number of channels from response.
+- `int StartTimeMS { set; }` — Sets parameter 1.
+- `int StopTimeMS { set; }` — Sets parameter 2.
+
+**Public Methods:**
+- `void GetChannelData(int channel, out short[] signedADC)` — Extracts per-channel data from interleaved raw data.
+
+**Protected Methods:**
+- `override CommandReceiveAction ReceiveBlockOK(Common.Interface.Communication.ICommunicationReport report)` — Handles binary download packets using `DownloadPacket.VerifyPacket`.
+- `override CommandReceiveAction WholePackage()` — Parses binary data from `DownloadPacket.Data` into `_Data` array.
+- `override CommandReceiveAction WholePackagePost()` — Invokes user callback with `QueryEventDataReport`.
+
+**Nested Class:**
+- `QueryEventDataReport : ICommandReport` — Contains `Status`, `CallbackObject`, and `short[][] data`.
+
+---
+
+### Trigger
+**Namespace:** `DTS.DASLib.Command.Ribeye`
+
+Sends a trigger command. Inherits from `ArmCommands`.
+