init
This commit is contained in:
287
docs/ai/DataPRO/ICommand.md
Normal file
287
docs/ai/DataPRO/ICommand.md
Normal file
@@ -0,0 +1,287 @@
|
||||
---
|
||||
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<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)
|
||||
```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<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)
|
||||
```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
|
||||
Reference in New Issue
Block a user