DP44/docs/ai/DataPRO/ICommand.md

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/ICommand/CommandReport.cs DataPRO/ICommand/ICommand.cs DataPRO/ICommand/CommandLogEntryBase.cs DataPRO/ICommand/SliceCommandBase.cs DataPRO/ICommand/CommandPacketBase.cs DataPRO/ICommand/SliceCommandPacketBase.cs	2026-04-17T15:51:10.156319+00:00	zai-org/GLM-5-FP8	1	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

public enum CommandStatus
{
    Success,
    Failure,
    Canceled
}

Represents the outcome of a command execution.

Enum: CommandErrorReason

public enum CommandErrorReason
{
    SendFailed,
    ReceiveFailed,
    InvalidMode,
    Canceled
}

Specifies the reason for a command failure.

Class: CommandException

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

public enum CommandReceiveAction
{
    StopReceiving,
    ContinueReceiving
}

Controls whether a callback continues receiving data.

Interface: ICommandReport

public interface ICommandReport
{
    object CallbackObject { get; set; }
    CommandStatus Status { get; set; }
}

Contract for command execution reports.

Delegate: CommandCallback

public delegate CommandReceiveAction CommandCallback(ICommandReport report);

Callback signature for asynchronous command completion.

Interface: ICommand

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

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)

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)

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<string>> list)
    public override void ResponseToString(ref List<List<string>> 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)

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<List<string>> lines, DateTime executeTime)
    public void GetPacketLogHeader(ref List<List<string>> lines)
    public override string ToString()
}

Abstract base for all command packets with status labels, sequence numbering, and logging support.

---

SliceCommandPacketBase.cs

Class: SliceCommandPacketBase (abstract)

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