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

source_files, generated_at, model, schema_version, sha256

source_files	generated_at	model	schema_version	sha256
DataPRO/SLICEDBCommands/CommandBase.cs DataPRO/SLICEDBCommands/CommandPacket.cs DataPRO/SLICEDBCommands/CalibrationCommands.cs DataPRO/SLICEDBCommands/PowerCommands.cs DataPRO/SLICEDBCommands/ArmCommands.cs DataPRO/SLICEDBCommands/NetworkCommands.cs DataPRO/SLICEDBCommands/InformationCommands.cs	2026-04-16T03:47:13.107401+00:00	Qwen/Qwen3-Coder-Next-FP8	1	054bcdedfc9b5182

SLICEDB Command Library Documentation

1. Purpose

This module provides a structured command framework for interacting with the SLICE DB (Data Acquisition System Electronics) hardware device over a communication interface. It defines an extensible hierarchy of command classes—each representing a specific operation (e.g., querying voltage, setting IP address, arming the system)—that encapsulate protocol-specific details such as command type, sequence numbering, parameter encoding/decoding, and response parsing. The library enables type-safe, consistent, and testable command construction and execution within the DAS (Data Acquisition System) ecosystem.

2. Public Interface

Core Base Classes

CommandBase

• Namespace: DTS.DASLib.Command.SLICEDB
• Inherits: SliceCommandBase
• Constructors:
  • CommandBase(ICommunication sock)
    Initializes a new command instance using the provided communication socket.
  • CommandBase(ICommunication sock, int TimeoutMillisec)
    Initializes with a custom timeout (in milliseconds).
• Protected Overrides:
  • GetCommandPacket() → CommandPacketBase
    Returns a new empty CommandPacket.
  • GetCommandPacket(byte[] buffer) → CommandPacketBase
    Returns a CommandPacket initialized from raw bytes.

CommandPacket

• Namespace: DTS.DASLib.Command.SLICEDB
• Inherits: SliceCommandPacketBase
• Nested Types:
  • CommandType enum:
    Reserved = 0x00, Diagnostics, GPIO, Information, Network, Power, Arm
• Static Members:
  • GlobalSequenceNumber (UInt16): Thread-safe global sequence counter.
  • GlobalSequenceNumberLock (object): Lock object for sequence number increment.
• Constructors:
  • CommandPacket()
    Default constructor.
  • CommandPacket(byte[] Bytes)
    Constructor from raw byte buffer.
• Overrides:
  • GetNextSequenceNumber()
    Atomically assigns the current GlobalSequenceNumber to SequenceNumber, then increments the global counter.
  • ConvertByteToCommandType(byte b) → object
    Casts the byte to a CommandType enum value.

Command Category Abstractions (Abstract Classes)

DiagnosticsCommands

• Namespace: DTS.DASLib.Command.SLICEDB
• Inherits: CommandBase
• Nested Enums:
  • Measurements: V1, BatteryVoltage, BatteryChargeCurrent, SliceBusCurrent, SliceBusVoltage
  • Commands: Reserved, QueryOffset = 0x01, SetOffset = 0x02, QueryMultiplier = 0x03, SetMultiplier = 0x04
• Constructors:
  • DiagnosticsCommands(ICommunication sock)
  • DiagnosticsCommands(ICommunication sock, int TimeoutMillisec)
    Sets command.Type = CommandType.Diagnostics.
• Note: Concrete command classes (QueryOffset, SetOffset, etc.) are commented out in source.

PowerCommands

• Namespace: DTS.DASLib.Command.SLICEDB
• Inherits: CommandBase
• Nested Enum:
  • Commands: Includes query/set commands for voltages, currents, thresholds, delays, and overvoltage/overcurrent limits (e.g., QueryV1VoltageMV = 0x01, SetSliceBusVoltageMV = 0x06, QueryBatteryChargeCurrentOvercurrentLimitMA = 0x17, etc.)
• Abstract Members:
  • _Command (Commands): Must be implemented by derived classes to specify the command.
• Constructors:
  • PowerCommands(ICommunication sock)
  • PowerCommands(ICommunication sock, int TimeoutMillisec)
    Sets command.Type = CommandType.Power, and calls command.SetCommand((byte)_Command, _Command.ToString()).
• Overrides:
  • CommandToString(ref List<List<string>> lines)
    Appends recorder.ConnectString to first line.
  • ResponseToString(ref List<List<string>> lines)
    Appends recorder.ConnectString to first line.

Concrete Power Commands (Examples)

• QueryV1VoltageMV
  • _Command: Commands.QueryV1VoltageMV
  • V1VoltageMV (uint): Input voltage (+V1 on P1) in millivolts.
  • WholePackage(): Parses response parameter 0 into _val.
• QueryBatteryVoltageMV
  • _Command: Commands.QueryBatteryVoltageMV
  • BatteryVoltageMV (uint): Battery voltage (+BAT on J1) in millivolts.
  • Sets MinimumProtocolVersion via sock.GetMinProto(...).
• QueryBatteryChargeCurrentMA
  • _Command: Commands.QueryBatteryChargeCurrentMA
  • BatteryChargeCurrentMA (uint): Battery charge current in milliamps.
• QuerySliceBusInputCurrentMA
  • _Command: Commands.QuerySliceBusInputCurrentMA
  • SliceBusInputCurrentMA (uint): Slice bus current in milliamps.
• QuerySliceBusVoltageMV
  • _Command: Commands.QuerySliceBusVoltageMV
  • SliceBusVoltageMV (uint): Slice bus voltage in millivolts.
• SetSliceBusVoltageMV
  • _Command: Commands.SetSliceBusVoltageMV
  • SliceBusVoltageMV (uint, get/set): Sets command.Parameter to 4-byte value.

ArmCommands

• Namespace: DTS.DASLib.Command.SLICEDB
• Inherits: CommandBase
• Nested Enum:
  • Commands: arm_reserved, arm_arm = 0x01, arm_disarm = 0x02, arm_enablefaultchecking = 0x03, arm_disablefaultchecking = 0x04, arm_setinverttriggerpolarity = 0x05, arm_setinvertstartpolarity = 0x06, arm_setrecordingmode = 0x07, arm_setpretriggersec = 0x08, arm_setposttriggersec = 0x09, arm_setmaxevent = 0x0A, arm_setonoverride = 0x0B
• Abstract Members:
  • _Command (Commands): Must be implemented.
• Constructors:
  • ArmCommands(ICommunication sock)
  • ArmCommands(ICommunication sock, int TimeoutMillisec)
    Sets command.Type = CommandType.Arm, and calls command.SetCommand(...).
• Overrides:
  • CommandToString(ref List<List<string>> list)
    Appends recorder.SerialNumber to first line.

Concrete Arm Commands (Examples)

• Arm
  • _Command: Commands.arm_arm
  • Sets MinimumProtocolVersion via sock.GetMinProto(ProtocolLimitedCommands.Arm).
• Disarm
  • _Command: Commands.arm_disarm
  • Sets MinimumProtocolVersion via sock.GetMinProto(ProtocolLimitedCommands.Arm).
• EnableFaultChecking
  • _Command: Commands.arm_enablefaultchecking
  • Sets MinimumProtocolVersion via sock.GetMinProto(ProtocolLimitedCommands.EnableFaultChecking).
• DisableFaultChecking
  • _Command: Commands.arm_disablefaultchecking
  • Sets MinimumProtocolVersion via sock.GetMinProto(ProtocolLimitedCommands.EnableFaultChecking).
• SetRecordingMode
  • _Command: Commands.arm_setrecordingmode
  • Value (byte, get/set): Sets command.Parameter to 1-byte value.
• SetPostTriggerSec
  • _Command: Commands.arm_setposttriggersec
  • Value (float, get/set): Sets command.Parameter to 4-byte float.
• SetONOverride
  • _Command: Commands.arm_setonoverride
  • Value (bool, get/set): Converts to/from byte for command.Parameter.
• SetInvertTriggerPolarity, SetInvertStartPolarity
  • Similar to SetONOverride, with bool Value property.

NetworkCommands

• Namespace: DTS.DASLib.Command.SLICEDB
• Inherits: CommandBase
• Nested Enum:
  • Commands: Reserved, QueryIPAddress = 0x01, SetIPAddress = 0x02, QueryNetmask = 0x03, SetNetmask = 0x04, QueryDefaultRoute = 0x05, SetDefaultRoute = 0x06, QueryMACAddress = 0x07, SetMACAddress = 0x08
• Abstract Members:
  • _Command (Commands): Must be implemented.
• Constructors:
  • NetworkCommands(ICommunication sock)
  • NetworkCommands(ICommunication sock, int TimeoutMillisec)
    Sets command.Type = CommandType.Network, and calls command.SetCommand(...).
• Overrides:
  • CommandToString(ref List<List<string>> list)
    Appends recorder.ConnectString to first line.
  • ResponseToString(ref List<List<string>> lines)
    Appends recorder.ConnectString to first line.

Concrete Network Commands (Examples)

• QueryIPAddress, SetIPAddress
  • IPAddress (string): Read-only for query, read/write for set. Set allocates command.Parameter as new byte[value.Length + 1].
• QueryNetmask, SetNetmask
  • Netmask (string): Same pattern as IP.
• QueryDefaultRoute, SetDefaultRoute
  • DefaultRoute (string): Same pattern.
• QueryMACAddress, SetMACAddress
  • MACAddress (string): Same pattern.

InformationCommands

• Namespace: DTS.DASLib.Command.SLICEDB
• Inherits: CommandBase
• Nested Enum:
  • Commands: Reserved, QuerySerialNumber = 0x01, SetSerialNumber = 0x02, QueryFirmwareVersion = 0x03, QueryTime = 0x04, SetTime = 0x05, QueryDebugLevel = 0x06, SetDebugLevel = 0x07, QueryKernelVersion = 0x08, QueryMSPFirmwareVersion = 0x09, QueryProtocolVersion = 0x0A, QueryCalibrationDaysSince1970_01_01 = 0x0F, SetCalibrationDaysSince1970_01_01 = 0x10
• Abstract Members:
  • _Command (Commands): Must be implemented.
• Constructors:
  • InformationCommands(ICommunication sock)
  • InformationCommands(ICommunication sock, int TimeoutMillisec)
    Sets command.Type = CommandType.Information, and calls command.SetCommand(...).
• Overrides:
  • CommandToString(ref List<List<string>> list)
    Appends recorder.SerialNumber to first line.

Concrete Information Commands (Examples)

• QuerySerialNumber, SetSerialNumber
  • SerialNumber (string): Read-only for query, read/write for set. Set allocates command.Parameter as new byte[value.Length + 1].
• QueryFirmwareVersion, QueryKernelVersion, QueryMSPFirmwareVersion
  • FirmwareVersion, KernelFirmwareVersion, MSPFirmwareVersion (string): Read-only, parsed from response parameter 0.
• QueryTime, SetTime
  • CurrentTime (DateTime): Query parses seconds/microseconds from parameters 0/4 into a DateTime (epoch-based). Set converts DateTime to seconds/microseconds and writes to command.Parameter.
• QueryProtocolVersion
  • ProtocolVersion (byte): Read-only, parsed from parameter 0.
• QueryCalibrationDaysSince1970_01_01, SetCalibrationDaysSince1970_01_01
  • CalibrationDaysSince1970_01_01 (string): Read-only for query, read/write for set. Set allocates command.Parameter as new byte[value.Length + 1].

3. Invariants

• Sequence Numbering: Sequence numbers are globally unique and monotonically increasing across all command instances due to the lock around GlobalSequenceNumber in GetNextSequenceNumber().
• Command Type Assignment: All concrete command classes must set command.Type to the appropriate CommandPacket.CommandType (e.g., Power, Arm, Network) in their base constructor.
• Command Code Assignment: All concrete command classes must call command.SetCommand((byte)_Command, _Command.ToString()) in their base constructor.
• Parameter Encoding for Strings: For commands accepting string parameters (e.g., SetIPAddress, SetSerialNumber), the parameter buffer is allocated as new byte[value.Length + 1] to accommodate a null terminator.
• Parameter Encoding for Numeric Types:
  • uint parameters use sizeof(uint) (4 bytes).
  • float parameters use sizeof(float) (4 bytes).
  • byte/bool parameters use sizeof(byte) (1 byte).
• Protocol Version Handling: Commands that require minimum protocol versions (e.g., QueryBatteryVoltageMV, Arm) set MinimumProtocolVersion via sock.GetMinProto(...) in their constructors.
• Response Parsing: All WholePackage() overrides parse response parameters only when response.Status == CommandStatus.StatusNoError; otherwise, they initialize output fields to default values (e.g., 0, string.Empty, DateTime(1970,1,1)).
• Thread Safety: Sequence number generation is thread-safe via lock (GlobalSequenceNumberLock).

4. Dependencies

External Dependencies (from imports):

• System.*: Core .NET libraries (System, System.Collections.Generic, System.Text, System.Threading, System.Reflection, System.IO, System.Diagnostics).
• DTS.Common.ICommunication: Provides ICommunication interface.
• DTS.Common.Interface.DASFactory: Provides ICommunication (redundant import) and DASFactory types.
• DTS.Common.Enums.DASFactory: Provides DFConstantsAndEnums.CommandStatus and DFConstantsAndEnums.ProtocolLimitedCommands.

Internal Dependencies:

• Inherits from SliceCommandBase and SliceCommandPacketBase (not shown in source, but referenced).
• Uses recorder object (inferred from recorder.ConnectString, recorder.SerialNumber), likely a property of the base class.
• Uses response and command objects (inferred from base class and usage), likely properties of SliceCommandBase.

Inferred Usage:

• This module is used by higher-level components that construct and execute commands via ICommunication.
• The CommandBase hierarchy is the primary public interface for command execution.

5. Gotchas

• Duplicate Class Name: SetCalibrationDaysSince1970_01_01 and QueryCalibrationDaysSince1970_01_01 are defined twice in InformationCommands.cs (lines 1 and 2), both with identical names and implementations. This will cause compilation errors unless one is commented out or renamed.
• Incorrect ResponseToString in QueryProtocolVersion: Outputs "Firmware Version: {ProtocolVersion}" instead of "Protocol Version: {ProtocolVersion}".
• Incorrect ResponseToString in QueryKernelVersion & QueryMSPFirmwareVersion: Both output "Firmware Version: {Version}" instead of distinguishing "Kernel Firmware Version" or "MSP Firmware Version".
• String Parameter Allocation: All string-setting commands allocate new byte[value.Length + 1], but there is no validation that value is non-null or within expected length limits. Passing null will throw a NullReferenceException.
• Float Parameter Precision: SetPostTriggerSec converts float to command.Parameter without rounding or validation; floating-point precision errors may occur.
• Epoch Assumption: QueryTime and SetTime assume Unix epoch (1970-01-01 00:00:00 UTC) and do not account for time zones or leap seconds.
• Missing Concrete Commands: DiagnosticsCommands defines QueryOffset, SetOffset, etc., but their implementations are commented out—no concrete classes exist for these.
• Protocol Version Mismatch: DisableFaultChecking uses ProtocolLimitedCommands.EnableFaultChecking for MinimumProtocolVersion, likely a copy-paste error.
• Redundant ICommunication Import: InformationCommands.cs imports both DTS.Common.ICommunication and DTS.Common.Interface.DASFactory, and uses ICommunication directly in SetCalibrationDaysSince1970_01_01 constructor—suggests inconsistent usage or legacy code.
• No Error Handling in WholePackage(): Some WholePackage() methods (e.g., QueryBatteryChargeCurrentMA) check StatusNoError only for success path, but others (e.g., QueryV1VoltageMV) do not—leading to inconsistent behavior on error.