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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/SLICECommands/StackSetupCommands.cs DataPRO/SLICECommands/CommandBase.cs DataPRO/SLICECommands/CommandPacket.cs DataPRO/SLICECommands/StackUtilityCommands.cs DataPRO/SLICECommands/FirmwareUpdateCommands.cs DataPRO/SLICECommands/Ptp1588Commands.cs	2026-04-16T03:46:47.989856+00:00	Qwen/Qwen3-Coder-Next-FP8	1	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