--- source_files: - DataPRO/ICommand/CommandReport.cs - DataPRO/ICommand/ICommand.cs - DataPRO/ICommand/CommandLogEntryBase.cs - DataPRO/ICommand/SliceCommandBase.cs - DataPRO/ICommand/CommandPacketBase.cs - DataPRO/ICommand/SliceCommandPacketBase.cs generated_at: "2026-04-17T15:51:10.156319+00:00" model: "zai-org/GLM-5-FP8" schema_version: 1 sha256: "90b03a612c0a7173" --- # DTS.DASLib.Command Module Documentation ## 1. Purpose This module provides a command execution framework for hardware communication in a data acquisition system (DAS). It defines the core abstractions for command lifecycle management, including interfaces for command execution (`ICommand`), status reporting (`ICommandReport`, `CommandReport`), and packet serialization/deserialization (`CommandPacketBase`, `SliceCommandPacketBase`). The module supports multiple hardware device types (notably "Slice" and "Ribeye" per source comments) with device-specific packet formats, CRC computation, and logging infrastructure. It handles the complete flow from command construction through execution to response parsing and logging. --- ## 2. Public Interface ### ICommand.cs **Enum: `CommandStatus`** ```csharp public enum CommandStatus { Success, Failure, Canceled } ``` Represents the outcome of a command execution. **Enum: `CommandErrorReason`** ```csharp public enum CommandErrorReason { SendFailed, ReceiveFailed, InvalidMode, Canceled } ``` Specifies the reason for a command failure. **Class: `CommandException`** ```csharp public class CommandException : ApplicationException { public CommandErrorReason Error { get; set; } public CommandException(CommandErrorReason _err) public CommandException(CommandErrorReason _err, string msg) } ``` Application exception that carries a `CommandErrorReason`. **Enum: `CommandReceiveAction`** ```csharp public enum CommandReceiveAction { StopReceiving, ContinueReceiving } ``` Controls whether a callback continues receiving data. **Interface: `ICommandReport`** ```csharp public interface ICommandReport { object CallbackObject { get; set; } CommandStatus Status { get; set; } } ``` Contract for command execution reports. **Delegate: `CommandCallback`** ```csharp public delegate CommandReceiveAction CommandCallback(ICommandReport report); ``` Callback signature for asynchronous command completion. **Interface: `ICommand`** ```csharp public interface ICommand { void Execute(CommandCallback Callback, object CallbackObject); void SyncExecute(); } ``` Contract for executable commands with both async and sync execution modes. --- ### CommandReport.cs **Class: `CommandReport`** ```csharp public class CommandReport : ICommandReport { public object CallbackObject { get; set; } public CommandStatus Status { get; set; } public CommandReport(CommandStatus _Status, object _CallbackObject) } ``` Concrete implementation of `ICommandReport`. --- ### CommandLogEntryBase.cs **Class: `CommandLogEntryBase`** (abstract) ```csharp public abstract class CommandLogEntryBase { protected StringBuilder sb; protected CommandPacketBase command; public CommandLogEntryBase(CommandPacketBase _command) public void TagCommonCommandData(string CommandName) public void TagCommonResponseData(string CommandName) public override string ToString() } ``` Base class for formatting command log entries. Initializes with a sequence number header. --- ### SliceCommandBase.cs **Class: `SliceCommandBase`** (abstract) ```csharp public abstract class SliceCommandBase : AbstractCommandBase { protected SliceCommandPacketBase command { get; set; } protected SliceCommandPacketBase response { get; set; } public byte DeviceID { get; set; } public byte DeviceGroup { get; set; } public SliceCommandBase(DTS.Common.Interface.DASFactory.ICommunication sock) public SliceCommandBase(DTS.Common.Interface.DASFactory.ICommunication sock, int TimeoutMillisec) public static void Initialize(int spots, int delayMs) public override void CommandToString(ref List> list) public override void ResponseToString(ref List> lines) public override void SyncExecute() } ``` Base class for Slice device commands with `DeviceID` and `DeviceGroup` addressing. Includes a static semaphore pool for throttling concurrent communications. --- ### CommandPacketBase.cs **Class: `CommandPacketBase`** (abstract) ```csharp public abstract class CommandPacketBase { public enum PacketState { OK, TooShort, Unknown } public static String[] StatusLabels; // 256-element array mapping status bytes to strings public DFConstantsAndEnums.CommandStatus Status; public bool ShouldLog; public bool AlreadyRun { get; set; } public byte[] OriginalBytes; public object Type; public UInt16 SequenceNumber; public void SetCommand(byte command, string commandDescription) public byte GetCommand() public string GetCommandDescription() public abstract byte[] ToBytes(); public abstract object ConvertByteToCommandType(byte b); public abstract PacketState VerifyPacket(byte[] Bytes); public abstract void GetNextSequenceNumber(); public abstract void ComputeCRCs(); public void GetPacketLogHeader(CommandPacketBase commandPacket, ref List> lines, DateTime executeTime) public void GetPacketLogHeader(ref List> lines) public override string ToString() } ``` Abstract base for all command packets with status labels, sequence numbering, and logging support. --- ### SliceCommandPacketBase.cs **Class: `SliceCommandPacketBase`** (abstract) ```csharp public abstract class SliceCommandPacketBase : CommandPacketBase { public const byte MAGIC_BYTE = 0xFA; protected const int HEADER_SIZE_BYTES = 12; protected const int DATA_CRC_SIZE_BYTES = 2; public UInt16 ParameterLength; public byte DeviceGroup; public byte DeviceID; public UInt16 HeaderCRC; public byte[] Parameter; public UInt16 ParameterCRC; public SliceCommandPacketBase() public SliceCommandPacketBase(byte[] Bytes) public override PacketState VerifyPacket(byte[] Bytes) public override void ComputeCRCs() public override byte[] ToBytes() // GetParameter overloads public void GetParameter(int Offset, out double Value) public void GetParameter(int Offset, out UInt64 Value) public void GetParameter(int Offset, out Int64 Value) public void GetParameter(int Offset, out Int32 Value) public void GetParameter(int Offset, out UInt32 Value) public void GetParameter(int Offset, out Int16 Value) public void GetParameter(int Offset, out UInt16 Value) public void GetParameter(int Offset, out byte Value) public void GetParameter(int Offset, out bool Value) public void GetParameter(int Offset, out float Value) public void GetParameter(int Offset, out string Value) // SetParameter overloads public void SetParameter(int Offset, double Value) public void SetParameter(int Offset, Int64 Value) public void SetParameter(int Offset, UInt64 Value) public void SetParameter(int Offset, Int32 Value) public void SetParameter(int Offset, UInt32 Value) public void SetParameter(int Offset, Int16 Value) public void SetParameter(int Offset, UInt16 Value) public void SetParameter(int Offset, byte Value) public void SetParameter(int Offset, bool Value) public void SetParameter(int Offset, byte[] Value) public void SetParameter(int Offset, string Value) public void SetParameter(int Offset, char[] Value) public void SetParameter(int Offset, char Value) public void SetParameter(int Offset, float Value) } ``` Slice-specific packet format with 12-byte header, CCITT CRC computation, and typed parameter accessors. --- ## 3. Invariants - **Magic Byte**: All Slice command packets must begin with `MAGIC_BYTE` (0xFA) at position 0. - **Header Size**: Slice packet headers are exactly 12 bytes (`HEADER_SIZE_BYTES = 12`). - **CRC Initialization**: Both `HeaderCRC` and `ParameterCRC` computations initialize to `0xFFFF`. - **Sequence Number Independence**: SliceDB, Slice, and Ribeye maintain independent sequence number counters (per `GetNextSequenceNumber()` documentation). - **Parameter CRC Presence**: When `Parameter.Length > 0`, a 2-byte parameter CRC is included; otherwise, no parameter CRC is present. - **Endianness**: Multi-byte parameter values use big-endian byte order in `GetParameter`/`SetParameter` methods. - **Status Labels Array**: `StatusLabels` is a 256-element array indexed by status byte value (0x00–0xFF). --- ## 4. Dependencies ### This module depends on: - `System`, `System.Collections.Generic`, `System.Text`, `System.Threading`, `System.Diagnostics` (BCL) - `DTS.Common.ICommunication` — Communication interface - `DTS.Common.Interface.DASFactory.ICommunication` — Communication factory interface - `DTS.Common.DASResource.Strings` — Localized status label strings - `DTS.Common.Enums.DASFactory.DFConstantsAndEnums.CommandStatus` — Status enumeration - `DTS.Common.Utilities.Logging.APILogger` — Logging infrastructure - `DTS.Common.Utils.ByteConvertor` — Byte conversion utilities - `DTS.Common.Utils.Math_DoCRCCCITTStep` — CRC computation ### What depends on this module: - Not determinable from the provided source files alone. --- ## 5. Gotchas 1. **Semaphore Logic Commented Out**: In `SliceCommandBase.SyncExecute()`, the semaphore acquisition, release, and delay logic is entirely commented out. The static `_slicePool` and `_slicePoolDelayMs` fields exist but are unused in the execution path. 2. **CRC Verification Not Implemented**: `SliceCommandPacketBase.VerifyPacket()` contains a TODO comment: `// TODO: Why isn't this checking the CRCs?` — the method validates structure but does not verify CRC correctness. 3. **Uncertain Class Usage**: `CommandLogEntryBase` source comments state: `"I'm not sure these classes are in use?"` — indicating potential dead code. 4. **Initialize Timing Requirement**: `SliceCommandBase.Initialize(int