287 lines
10 KiB
Markdown
287 lines
10 KiB
Markdown
---
|
||
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 |