DP44/enriched-qwen3-coder-next/DataPRO/SLICECommands.md

---
source_files:
  - DataPRO/SLICECommands/StackSetupCommands.cs
  - DataPRO/SLICECommands/CommandBase.cs
  - DataPRO/SLICECommands/CommandPacket.cs
  - DataPRO/SLICECommands/StackUtilityCommands.cs
  - DataPRO/SLICECommands/FirmwareUpdateCommands.cs
  - DataPRO/SLICECommands/Ptp1588Commands.cs
generated_at: "2026-04-16T03:46:47.989856+00:00"
model: "Qwen/Qwen3-Coder-Next-FP8"
schema_version: 1
sha256: "fe72794d5a98f1f5"
---

# SLICE Command Module Documentation

## 1. Purpose

This module implements the command-layer abstraction for the SLICE protocol, providing strongly-typed command classes for interacting with SLICE hardware devices. It defines a hierarchy of command classes grouped by functional domain—stack setup, stack utility, firmware update, and PTP 1588 time synchronization—each inheriting from `CommandBase`. Commands are serialized into `CommandPacket` instances, which handle protocol-level details such as sequence numbering, type identification, and parameter encoding. The module serves as the primary interface between application logic and the underlying communication layer (`ICommunication`), enabling structured, type-safe command execution and response parsing.

## 2. Public Interface

### Core Base Classes

- **`Commands_Stack_Setup`** *(abstract class)*  
  Base class for stack setup commands. Sets `command.Type = CommandPacket.CommandType.StackSetup`.  
  Constructors:  
  - `Commands_Stack_Setup(ICommunication sock)`  
  - `Commands_Stack_Setup(ICommunication sock, int TimeoutMillisec)`

- **`Commands_Stack_Utility`** *(abstract class)*  
  Base class for stack utility commands (e.g., flash operations, power control). Sets `command.Type = CommandPacket.CommandType.StackUtility`.  
  Defines internal `Commands` enum with values like `BusPowerControl`, `ForceEnumeration`, etc.  
  Constructors:  
  - `Commands_Stack_Utility(ICommunication sock)`  
  - `Commands_Stack_Utility(ICommunication sock, int TimeoutMillisec)`

- **`FirmwareUpdateCommands`** *(abstract class)*  
  Base class for firmware update commands. Sets `command.Type = CommandPacket.CommandType.FirmwareUpdate`.  
  Defines internal `Commands` enum with values like `QueryFirmwareUpdateBlockSize`, `ProgramFirmwareUpdateBlock`, `Load_SliceProStackFirmwareImage`, etc.  
  Defines `FirmwareMode` enum (`FW`, `BL`, `BLL`).  
  Constants: `MAX_FILE_ID = 30`, `MAX_FILE_LENGTH = 400`.  
  Abstract property `_Command` must be implemented by derived classes.  
  Constructors:  
  - `FirmwareUpdateCommands(ICommunication sock)`  
  - `FirmwareUpdateCommands(ICommunication sock, int TimeoutMillisec)`

- **`Ptp1588Commands`** *(abstract class)*  
  Base class for PTP 1588 time synchronization commands. Sets `command.Type = CommandPacket.CommandType.Ptp1588`.  
  Defines enums: `PtpClockType`, `PtpMode`, `PtpDelayMechanism`, `PtpSyncStatus`, `PtpTimestampUnits`.  
  Defines internal `Commands` enum (e.g., `SetMode`, `GetTime`, `SetAutoTriggerTime`).  
  Static helper: `ToTimestampString(uint s, uint ns)` → formats as `"s.fffffffff"`.  
  Abstract property `_Command` must be implemented.  
  Constructors:  
  - `Ptp1588Commands(ICommunication sock)`  
  - `Ptp1588Commands(ICommunication sock, int TimeoutMillisec)`

### Concrete Command Classes

#### Stack Utility Commands

- **`BusPowerControl`**  
  Controls bus power on/off.  
  Properties:  
  - `PowerOn: bool` — sets parameter[0] to `1` (on) or `0` (off).  
  Constructors:  
  - `BusPowerControl(ICommunication sock)`  
  - `BusPowerControl(ICommunication sock, int TimeoutMillisec)`  
  Overrides: `CommandToString()`, `ResponseToString()`.

- **`ForceEnumeration`**  
  Triggers enumeration of connected SLICE modules.  
  Properties:  
  - `SLICECount: int` — populated from response parameter[0] on success.  
  Constructors:  
  - `ForceEnumeration(ICommunication sock)`  
  - `ForceEnumeration(ICommunication sock, int TimeoutMillisec)`  
  Overrides: `WholePackage()` (parses response), `CommandToString()`, `ResponseToString()`.

#### Firmware Update Commands

- **`QueryFirmwareUpdateBlockSize`**  
  Queries maximum firmware block size.  
  Properties:  
  - `BlockSize: ushort` — populated from response parameter[0] on success.  
  Constructors:  
  - `QueryFirmwareUpdateBlockSize(ICommunication sock)`  
  - `QueryFirmwareUpdateBlockSize(ICommunication sock, int TimeoutMillisec)`  
  Overrides: `WholePackage()`, `ResponseToString(ref List<List<string>> lines)`.

- **`QueryBootloaderVersion`**  
  Queries bootloader version string.  
  Properties:  
  - `Version: string` — populated from response parameter[0] on success.  
  Constructors:  
  - `QueryBootloaderVersion(ICommunication sock)`  
  - `QueryBootloaderVersion(ICommunication sock, int TimeoutMillisec)`  
  Overrides: `WholePackage()`, `ResponseToString(ref List<List<string>> lines)`.

- **`ProgramFirmwareUpdateBlock`**  
  Programs a firmware block.  
  Properties:  
  - `BlockBaseAddress: uint` — sets parameter[0–3].  
  - `BlockSize: ushort` — set internally from `Data` length; sets parameter[4–5].  
  - `BlockCRC16: ushort` — sets parameter[6–7].  
  - `Upper: bool` — sets parameter[8] to `1` if true.  
  - `Data: byte[]` — sets parameter[10..] (requires `command.Parameter` expansion).  
  Constructors:  
  - `ProgramFirmwareUpdateBlock(ICommunication sock)`  
  - `ProgramFirmwareUpdateBlock(ICommunication sock, int TimeoutMillisec)`  
  Overrides: `CommandToString(ref List<List<string>> lines)`.

- **`FinishFirmwareUpdate`**  
  Finalizes firmware update with image CRC.  
  Properties:  
  - `ImageCRC16: ushort` — sets parameter[0–1].  
  Constructors:  
  - `FinishFirmwareUpdate(ICommunication sock)`  
  - `FinishFirmwareUpdate(ICommunication sock, int TimeoutMillisec)`  
  Overrides: `CommandToString(ref List<List<string>> lines)`, `ResponseToString(ref List<List<string>> lines)`.

- **`QueryInFirmwareUpdateMode`**  
  Queries current firmware update mode.  
  Properties:  
  - `InUpdateMode: bool` — `true` if not in `FW` mode.  
  - `IsFwMode`, `IsBlMode`, `IsBllMode: bool` — mode flags.  
  - `Mode: FirmwareMode` — actual mode enum.  
  Constructors:  
  - `QueryInFirmwareUpdateMode(ICommunication sock)`  
  - `QueryInFirmwareUpdateMode(ICommunication sock, int TimeoutMillisec)`  
  Overrides: `WholePackage()`.

- **`Load_SliceProStackFirmwareImage`**  
  Loads a 400-byte firmware block to base NAND (requires protocol ≥137).  
  Properties:  
  - `StartByteCount: uint` — sets parameter[2–5].  
  - `Data: byte[]` — sets parameter[6..]; throws `NotImplementedException` if length > `MAX_FILE_LENGTH` (400).  
  - `Size: int` — length of `Data`.  
  - `MaximumFileStreamBytes: int` → `400`.  
  - `_fileID = 20` (hardcoded for firmware).  
  - `MinimumProtocolVersion` set via `sock.GetMinProto(ProtocolLimitedCommands.StackFirmwareUpdate)`.  
  - `command.ShouldLog = false`.  
  Constructors:  
  - `Load_SliceProStackFirmwareImage(ICommunication sock)`  
  - `Load_SliceProStackFirmwareImage(ICommunication sock, int TimeoutMillisec)`  
  Overrides: `CommandToString(ref List<List<string>> lines)`.

- **`Start_SliceProStackFirmwareUpdate`**, **`Set_SliceProStackFirmwareUpdateMode`**, **`Get_SliceProStackFirmwareUpdateMode`**  
  Support Slice Pro stack firmware updates (protocol ≥137).  
  - `Set_SliceProStackFirmwareUpdateMode`:  
    - `SliceModuleCount: int` — sets `_sliceProUpdateMode` array size.  
    - `SliceModuledateMode: byte[]` — sets `command.Parameter`.  
  - `Get_SliceProStackFirmwareUpdateMode`:  
    - `SliceModuleCount: int` — populated from `response.Parameter.Length`.  
    - `SliceModuledateMode: byte[]` — populated from response parameters.  
    Overrides `WholePackage()`.

#### PTP 1588 Commands

- **`Ptp1588SetMode`**  
  Sets PTP mode.  
  Methods:  
  - `SetClockType(PtpClockType)` — sets parameter[0–1].  
  - `SetDelayMechanism(PtpDelayMechanism)` — sets parameter[2–3].  
  Constructors:  
  - `Ptp1588SetMode(ICommunication sock)`  
  - `Ptp1588SetMode(ICommunication sock, int TimeoutMillisec)`  
  Overrides: `CommandToString(ref List<List<string>> lines)`.

- **`Ptp1588GetMode`**  
  Gets PTP mode.  
  Properties:  
  - `ClockType: PtpClockType`  
  - `DelayMechanism: PtpDelayMechanism`  
  Constructors:  
  - `Ptp1588GetMode(ICommunication sock)`  
  - `Ptp1588GetMode(ICommunication sock, int TimeoutMillisec)`  
  Overrides: `WholePackage()`.

- **`Ptp1588GetSyncStatus`**  
  Gets PTP sync status.  
  Properties:  
  - `SyncStatus: PtpSyncStatus`  
  - `OFM: int` — offset from master (ns).  
  - `FreqAdj: int` — frequency adjustment.  
  Constructors:  
  - `Ptp1588GetSyncStatus(ICommunication sock)`  
  - `Ptp1588GetSyncStatus(ICommunication sock, int TimeoutMillisec)`  
  Overrides: `WholePackage()` (requires `response.ParameterLength > 6` for full data).

- **`Ptp1588SetTime`**, **`Ptp1588GetTime`**, **`Ptp1588SetAutoTriggerTime`**, **`Ptp1588GetAutoTriggerTime`**  
  Time setting/getting commands.  
  - `SetTime`/`SetAutoTriggerTime`: `SetSeconds(uint)`, `SetNanoseconds(uint)`.  
  - `GetTime`/`GetAutoTriggerTime`:  
    - `Seconds: uint`, `Nanoseconds: uint`, `Timestamp: string` (via `ToTimestampString`).  
  Constructors and overrides similar to above.

- **`Ptp1588GetTimestamp`**  
  Gets timestamp for a specified trigger source.  
  Properties:  
  - `TimestampUnit: PtpTimestampUnits` (set via property).  
  - `Seconds`, `Nanoseconds`, `Timestamp`, `IsValid: bool`.  
  Constructors:  
  - `Ptp1588GetTimestamp(ICommunication sock)`  
  - `Ptp1588GetTimestamp(ICommunication sock, int TimeoutMillisec)`  
  Overrides: `CommandToString(ref List<List<string>> lines)`, `ResponseToString(ref List<List<string>> lines)`.

- **`Ptp1588SetEnableTimestamping`**  
  Enables/disables trigger timestamping.  
  Methods:  
  - `SetEnable(bool)` — sets parameter[0] to `1` or `0`.  
  Constructors:  
  - `Ptp1588SetEnableTimestamping(ICommunication sock)`  
  - `Ptp1588SetEnableTimestamping(ICommunication sock, int TimeoutMillisec)`.

- **`Ptp1588SetAdcClockFrequency`**  
  Requests ADC clock frequency.  
  Properties:  
  - `RequestedFrequency: uint` (set via property).  
  - `ActualFrequency: uint` — populated from response parameter[0] on success.  
  Constructors:  
  - `Ptp1588SetAdcClockFrequency(ICommunication sock)`  
  - `Ptp1588SetAdcClockFrequency(ICommunication sock, int TimeoutMillisec)`  
  Overrides: `WholePackage()`, `CommandToString(ref List<List<string>> lines)`, `ResponseToString(ref List<List<string>> lines)`.

- **`Ptp1588RunClockAdjustmentCalibration`**  
  Runs clock calibration.  
  Methods:  
  - `SetDuration(ushort)` — sets parameter[0–1].  
  - `SetSaveAttribute(bool)` — sets parameter[2].  
  Constructors:  
  - `Ptp1588RunClockAdjustmentCalibration(ICommunication sock)`  
  - `Ptp1588RunClockAdjustmentCalibration(ICommunication sock, int TimeoutMillisec)`.

- **`QueryClockSyncStatus`**  
  Queries clock sync configuration (requires protocol ≥ version from `ProtocolLimitedCommands.QueryClockSyncStatus`).  
  Properties:  
  - `InputState`, `OutputState`, `SyncStatus: byte`.  
  - `ClockSyncProfile: ClockSyncProfile` (enum from `DTS.Common.Enums`).  
  - `InputSources`, `OutputSources: List<T>` (populated from `Enum.GetValues`).  
  - `InputSyncStatus: IDictionary<InputClockSource, bool>` — built by masking `SyncStatus` with each source enum value.  
  Overrides: `WholePackage()`.

- **`SetClockSyncConfig`**  
  Sets clock sync configuration (requires protocol ≥ version from `ProtocolLimitedCommands.SetClockSyncConfig`).  
  Overrides: `ResponseToString(ref List<List<string>> lines)` (reports success/failure).

## 3. Invariants

- **Command Type Consistency**:  
  Each command class sets `command.Type` to a specific `CommandPacket.CommandType` value in its constructor (e.g., `StackSetup`, `StackUtility`, `FirmwareUpdate`, `Ptp1588`). Derived classes must not override this.

- **Sequence Number Uniqueness**:  
  `CommandPacket.GetNextSequenceNumber()` uses a static `GlobalSequenceNumber` incremented under lock (`GlobalSequenceNumberLock`). Sequence numbers are monotonically increasing and unique per process.

- **Parameter Initialization**:  
  Commands initialize `command.Parameter` to a fixed-size `byte[]` in constructors. Dynamic expansion occurs only in `ProgramFirmwareUpdateBlock.Data` and `Load_SliceProStackFirmwareImage.Data` when data exceeds initial capacity.

- **Protocol Version Enforcement**:  
  Commands requiring specific protocol versions (e.g., `Load_SliceProStackFirmwareImage`, `SetClockSyncConfig`) set `MinimumProtocolVersion` via `sock.GetMinProto(...)`.

- **Response Parsing Guard**:  
  `WholePackage()` overrides check `response.Status == CommandStatus.StatusNoError` before parsing parameters.

- **Command Parameter Layout**:  
  Parameter offsets are fixed and documented by command (e.g., `ProgramFirmwareUpdateBlock.BlockBaseAddress` → parameter[0–3], `BlockSize` → parameter[4–5]). Offsets are not inferred dynamically.

## 4. Dependencies

### Dependencies *on* this module:
- **`DTS.DASLib.Command.SLICE.CommandBase`** → Base for all command classes.
- **`DTS.DASLib.Command.SLICE.CommandPacket`** → Packet structure and sequence numbering.
- **`DTS.Common.Interface.DASFactory.ICommunication`** → Communication channel abstraction (passed to constructors).
- **`DTS.Common.Enums.DASFactory.DFConstantsAndEnums`** → `CommandStatus`, `ProtocolLimitedCommands`, `InputClockSource`, `OutputClockSource`, `ClockSyncProfile`.
- **`DTS.Common.ICommunication`** → Used in `ICommunication` interface (likely aliased or re-exported).

### Dependencies *of* this module:
- **`DTS.DASLib.Communication`** (namespace) — referenced in `StackUtilityCommands.cs` but not used (likely legacy).
- **`DTS.DASLib.Utility`** — referenced but unused in `StackUtilityCommands.cs`.
- **`DTS.Common`** — for enums, logging, utilities.
- **`System`**, **`System.Collections.Generic`**, **`System.Text`**, **`System.Threading`**, **`System.Reflection`**, **`System.IO`**, **`System.Diagnostics`** — standard libraries.

## 5. Gotchas

- **`Load_SliceProStackFirmwareImage.Data` throws `NotImplementedException`** if input data length exceeds `MAX_FILE_LENGTH` (400 bytes). This is a hard limit; no fallback or chunking is provided.

- **`Ptp1588GetSyncStatus` silently degrades**: If `response.ParameterLength ≤ 6`, `SyncStatus` defaults to `NotSynced` without error logging.

- **`Set_SliceProStackFirmwareUpdateMode.SliceModuledateMode` setter copies values but does not validate array length against `SliceModuleCount`** — mismatched lengths may cause silent truncation or `IndexOutOfRangeException`.

- **`QueryClockSyncStatus.InputSyncStatus` is populated only for `InputClockSource` enum values *except the first* (`sources[0]`)** due to `for (int i = 1; i < sources.Count; i++)`. The first source is skipped.

- **`ProgramFirmwareUpdateBlock.Data` setter expands `command.Parameter` only if current length is insufficient**, but does not shrink it. Repeated use may retain unused bytes.

- **`FirmwareUpdateCommands` and `Ptp1588Commands` use `command.SetCommand((byte)_Command, _Command.ToString())`**, but `_Command.ToString()` is not used elsewhere in the codebase — likely for debugging only.

- **`BusPowerControl.PowerOn` setter always writes to parameter[0]**, regardless of prior state — no idempotency or validation.

- **`QueryInFirmwareUpdateMode.InUpdateMode` logic is inverted**: `InUpdateMode = (Mode != FirmwareMode.FW)`, but `IsFwMode = (Mode == FirmwareMode.FW)`. This may cause confusion.

- **`Ptp1588SetAdcClockFrequency` uses typo in command name**: `Commands.SetAdcClockFrquency` (missing 'e' in "Frequency").

- **`Load_SliceProStackFirmwareImage._fileID` is hardcoded to `20`** (firmware ID), but `MAX_FILE_ID = 30` suggests user IDs (1–10) are possible — no public API to change `_fileID`.

- **No validation of `command.Parameter` bounds** in setters like `ProgramFirmware