--- 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> 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> 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> 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> lines)`, `ResponseToString(ref List> 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> 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> 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> lines)`, `ResponseToString(ref List> 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> lines)`, `ResponseToString(ref List> 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` (populated from `Enum.GetValues`). - `InputSyncStatus: IDictionary` — 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> 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