init

enriched-qwen3-coder-next/Common/DTS.Common/Classes/Hardware.md

@@ -0,0 +1,321 @@
+---
+source_files:
+  - Common/DTS.Common/Classes/Hardware/ExternalTilt.cs
+  - Common/DTS.Common/Classes/Hardware/DragAndDropPayload.cs
+  - Common/DTS.Common/Classes/Hardware/SerializableAAF.cs
+  - Common/DTS.Common/Classes/Hardware/DASDBRecord.cs
+  - Common/DTS.Common/Classes/Hardware/DASChannelDBRecord.cs
+  - Common/DTS.Common/Classes/Hardware/DASMonitorInfo.cs
+generated_at: "2026-04-16T03:14:40.842937+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "f2a89e74efee1556"
+---
+
+# Hardware Data Models Documentation
+
+## 1. Purpose
+
+This module defines core data models for representing hardware components in the DTS (Data Acquisition System) ecosystem. It provides structured classes for serializing, deserializing, and persisting hardware metadata—including DAS (Data Acquisition System) units, their channels, external tilt sensors, and monitoring configurations—to and from databases and files. These models serve as the canonical data structures for hardware inventory management, configuration synchronization, and system diagnostics across the application.
+
+## 2. Public Interface
+
+### `ExternalTilt`
+A simple POCO representing metadata for an external tilt sensor.
+
+- **`ExternalTilt()`**  
+  Parameterless constructor.
+
+- **`string SerialNumber { get; set; }`**  
+  Serial number of the tilt sensor.
+
+- **`byte TiltID { get; set; }`**  
+  Unique identifier for the tilt sensor within a system.
+
+- **`string SystemID { get; set; }`**  
+  Identifier of the system the tilt sensor is associated with.
+
+- **`string SystemLocation { get; set; }`**  
+  Physical or logical location of the tilt sensor within the system.
+
+---
+
+### `DragAndDropPayload`
+A static class defining string constants used as clipboard/data transfer formats for hardware table drag-and-drop operations.
+
+- **`const string FORMAT = "RESOLVECHANNELS_HARDWARETABLE"`**  
+  Primary format identifier for hardware table data transfer.
+
+- **`const string ALT_FORMAT = "ALT_RESOLVECHANNELS_HARDWARETABLE"`**  
+  Alternate format identifier (likely for legacy or variant workflows).
+
+- **`const string CTRL_FORMAT = "CTRL_RESOLVECHANNELS_HARDWARETABLE"`**  
+  Control-key modifier variant format identifier.
+
+---
+
+### `SerializableAAF`
+A class for serializing/deserializing AAF (Anti-Aliasing Filter) configuration data. *Note: All core functionality is currently commented out.*
+
+- **`enum DAS_TYPE { TDAS = 0, SLICE = 1 }`**  
+  Defines DAS hardware types.
+
+- **`string GetSerializedKey()`** *(commented out)*  
+  Would return a key string of the form `"{DAS_TYPE}_{SampleRate}"`.
+
+- **`string GetSerializedValue()`** *(commented out)*  
+  Would return the AAF value as a culture-invariant string.
+
+- **`void FromSerializedStrings(string key, string value)`** *(commented out)*  
+  Would parse `key` and `value` strings to reconstruct internal state.
+
+*No active public methods or properties are available in the current source.*
+
+---
+
+### `DASDBRecord`
+A database-mapped entity representing a DAS unit in the `DAS` table.
+
+- **`static DateTime INVALID_DATE => new DateTime(1970, 1, 1)`**  
+  Sentinel value for unset date fields.
+
+- **`DASDBRecord()`**  
+  Default constructor.
+
+- **`DASDBRecord(IDASDBRecord copy)`**  
+  Copy constructor; initializes fields from another `IDASDBRecord` instance.
+
+- **`DASDBRecord(IDataReader reader)`**  
+  Constructor that populates fields from a database `IDataReader`.
+
+- **`int DASId { get; set; }`**  
+  Primary key (`[Key]`, `[Column("DASId")]`).
+
+- **`string SerialNumber { get; set; }`**  
+  Required; max length 50 (`[Required]`, `[StringLength(50)]`).
+
+- **`int DASType { get; set; }`**  
+  Numeric type identifier for the DAS.
+
+- **`int MaxModules { get; set; }`**, **`long MaxMemory { get; set; }`**, **`double MaxSampleRate { get; set; }`**, **`double MinSampleRate { get; set; }`**  
+  Hardware specifications.
+
+- **`string FirmwareVersion { get; set; }`**  
+  Firmware version string; defaults to `""`.
+
+- **`DateTime CalDate { get; set; }`**  
+  Calibration date; defaults to `INVALID_DATE`.
+
+- **`int ProtocolVersion { get; set; }`**  
+  Protocol version number.
+
+- **`DateTime LastModified { get; set; }`**, **`string LastModifiedBy { get; set; }`**  
+  Timestamp and user who last modified the record.
+
+- **`int Version { get; set; }`**  
+  Concurrency/version tracking.
+
+- **`bool LocalOnly { get; set; }`**  
+  Flag indicating local-only storage (deprecated per `DASChannelDBRecord`).
+
+- **`DateTime LastUsed { get; set; }`**, **`string LastUsedBy { get; set; }`**  
+  Last usage timestamp and user.
+
+- **`string Connection { get; set; }`**, **`int Channels { get; set; }`**, **`string Position { get; set; }`**  
+  Connection type, channel count, and physical/logical position.
+
+- **`int[] ChannelTypes { get; set; }`**  
+  Array of channel type identifiers; defaults to `new int[0]`.
+
+- **`bool IsProgrammable { get; set; }`**, **`bool IsReconfigurable { get; set; }`**, **`bool IsModule { get; set; }`**  
+  Hardware capability flags.
+
+- **`int PositionOnDistributor { get; set; }`**, **`int PositionOnChain { get; set; }`**, **`int Port { get; set; }`**  
+  Positioning metadata.
+
+- **`string ParentDAS { get; set; }`**  
+  Serial number of parent DAS (for modular systems).
+
+- **`DateTime? FirstUseDate { get; set; }`**, **`bool IsFirstUseValid { get; set; }`**  
+  Optional first-use date and validity flag.
+
+- **`bool StandIn { get; set; }`**  
+  Flag indicating this is a stand-in (replacement) unit.
+
+- **`int? TestId { get; set; }`**, **`int? GroupId { get; set; }`**  
+  Optional test and group identifiers.
+
+- **`double MaxAAFRate { get; set; }`**  
+  Maximum AAF rate supported.
+
+---
+
+### `DASChannelDBRecord`
+A database-mapped entity representing a channel on a DAS unit.
+
+- **`string HardwareId { get; set; }`**  
+  Composite hardware identifier: `serialnumber_dastype`.
+
+- **`int DaschannelId { get; set; }`**  
+  Primary key (`[Key]`, `[Column("DASChannelId")]`).
+
+- **`int? Dasid { get; set; }`**  
+  Foreign key to `DAS.DASId`.
+
+- **`int ChannelIdx { get; set; }`**  
+  Physical channel index on the DAS.
+
+- **`const int DEFAULT_SUPPORTED_BRIDGES = 12`**  
+  Default bridge support mask (half + full bridge).
+
+- **`int SupportedBridges { get; set; }`**  
+  Bitmask of supported bridge types:
+  - Bit 0: IEPE  
+  - Bit 1: Quarter bridge  
+  - Bit 2: Half bridge  
+  - Bit 3: Full bridge  
+  - Bit 4: Digital input  
+  - Bit 5: Squib fire  
+  - Bit 6: Digital output  
+  - Bit 7: Half bridge signal plus (G5)  
+  - Bit 8: Real-time clock  
+  - Bit 9: UART  
+
+- **`const int DEFAULT_SUPPORTED_EXCITATIONS = 16`**  
+  Default excitation mask (5V).
+
+- **`int SupportedExcitations { get; set; }`**  
+  Bitmask of supported excitation voltages:
+  - Bit 0: Invalid  
+  - Bit 1: 2V  
+  - Bit 2: 2.5V  
+  - Bit 3: 3V  
+  - Bit 4: 5V  
+  - Bit 5: 10V  
+  - Bit 6: 1V  
+
+- **`int DASDisplayOrder { get; set; }`**  
+  Logical display order (may differ from physical order).
+
+- **`bool LocalOnly { get; set; }`**  
+  Deprecated; indicates local-only storage.
+
+- **`const int DEFAULT_SUPPORTED_DI_MODES = 16`**, **`int SupportedDigitalInputModes { get; set; }`**  
+  Default and configurable digital input modes bitmask.
+
+- **`const int DEFAULT_SQUIB_FIRE_MODES = 16`**, **`int SupportedSquibFireModes { get; set; }`**  
+  Default and configurable squib fire modes bitmask.
+
+- **`const int DEFAULT_SUPPORTED_DO_MODES = 16`**, **`int SupportedDigitalOutputModes { get; set; }`**  
+  Default and configurable digital output modes bitmask.
+
+- **`string ModuleSerialNumber { get; set; }`**  
+  Serial number of the module the channel belongs to.
+
+- **`int SettingId { get; set; }`**  
+  Configuration setting ID.
+
+- **`int ModuleArrayIndex { get; set; }`**  
+  Array index of the module on the DAS or rack.
+
+- **`DASChannelDBRecord()`**, **`DASChannelDBRecord(IDataReader reader)`**, **`DASChannelDBRecord(IDASChannelDBRecord copy)`**  
+  Constructors for default, database, and copy initialization.
+
+---
+
+### `DASMonitorInfo`
+A class for reading/writing and constructing monitor configuration data for a DAS unit, primarily used for tilt sensor calibration and channel diagnostics.
+
+- **`string SerialNumber { get; private set; }`**  
+  DAS serial number.
+
+- **`double[] TiltSensorCals { get; private set; }`**  
+  Calibration coefficients for 18 tilt sensors.
+
+- **`short[] TiltSensorDataPre { get; private set; }`**  
+  Pre-processed tilt sensor raw data (3 values).
+
+- **`DFConstantsAndEnums.TiltAxes TiltAxes { get; private set; }`**  
+  Axis configuration (e.g., `IXIYIZ`).
+
+- **`int AxisIgnored { get; private set; }`**  
+  Bitmask indicating ignored axes.
+
+- **`double MountOffsetAxisOne { get; private set; }`**, **`double MountOffsetAxisTwo { get; private set; }`**  
+  Mounting offsets for two axes.
+
+- **`string GetChannelName(int index)`**  
+  Returns channel name based on internal `_channelNames` array or a default `"Ch#XX"`.
+
+- **`double GetOffsetTolerancemVHigh(int index)`**, **`double GetOffsetTolerancemVLow(int index)`**  
+  Returns high/low offset tolerance (mV) for a given channel index.
+
+- **`void ReadFromFile(string path)`**  
+  Reads monitor info from a text file (10 lines, one per `Fields` enum value). Silently fails on file not found or parse errors.
+
+- **`void WriteToFile(string path)`**  
+  Writes monitor info to a text file. Logs exceptions via `APILogger`.
+
+- **`DASMonitorInfo(IDASCommunication das, IsoViewMode mode)`**  
+  Constructor that populates fields from an active DAS communication object (`das`) and view mode.
+
+- **`DASMonitorInfo(string path)`**  
+  Constructor that calls `ReadFromFile(path)`.
+
+*Note: Several private helper methods (`GetTiltSensorCals`, `GetTiltSensorData`, `GetChannelNames`, etc.) are used internally during construction.*
+
+---
+
+## 3. Invariants
+
+- **`DASDBRecord`**  
+  - `SerialNumber` and `Position` are required (`[Required]` attribute) and must be ≤50 characters.  
+  - `CalDate` and `LastUsed` default to `INVALID_DATE` (1970-01-01) if unset.  
+  - `ChannelTypes` is always initialized to a non-null array (default `new int[0]`).  
+  - `IsFirstUseValid` is `false` by default; `FirstUseDate` is `null` if invalid or unset.
+
+- **`DASChannelDBRecord`**  
+  - `SupportedBridges`, `SupportedExcitations`, `SupportedDigitalInputModes`, `SupportedDigitalOutputModes`, and `SupportedSquibFireModes` use specific bitmasks defined by constants.  
+  - `ChannelIdx` defaults to `-1` if not set.  
+  - `ModuleArrayIndex` is mutable only via direct assignment (no `SetProperty` call).
+
+- **`DASMonitorInfo`**  
+  - `_channelNames`, `_offsetTolerancesHigh`, `_offsetTolerancesLow` arrays are initialized to empty arrays by default.  
+  - `ReadFromFile` silently ignores missing files or malformed lines.  
+  - `TiltSensorCals` is always 18 elements; `TiltSensorDataPre` is always 3 elements.
+
+- **`SerializableAAF`**  
+  - No active invariants (all functionality is commented out).
+
+---
+
+## 4. Dependencies
+
+### This Module Depends On:
+- **`DTS.Common.Base`** (`BasePropertyChanged` base class for `DASDBRecord`, `DASChannelDBRecord`).  
+- **`DTS.Common.Enums`**, **`DTS.Common.Enums.DASFactory`** (`DFConstantsAndEnums.TiltAxes`, `IsoViewMode`).  
+- **`DTS.Common.Interface.DataRecorders`** (`IDASDBRecord`, `IDASChannelDBRecord`).  
+- **`DTS.Common.Interface.DASFactory`** (`IDASCommunication`).  
+- **`DTS.Common.Interface.Hardware`** (`ITiltSensorCalAware`).  
+- **`DTS.Common.Utilities.Logging`** (`APILogger`).  
+- **`System.ComponentModel.DataAnnotations`**, **`System.Data`** (EF Core attributes, `IDataReader`).  
+- **`System`**, **`System.Linq`**, **`System.Text`**, **`System.Globalization`**, **`System.IO`**.
+
+### This Module Is Used By:
+- Database persistence layers (via `DASDBRecord`, `DASChannelDBRecord`).  
+- Hardware configuration UIs (via `DASMonitorInfo`, `ExternalTilt`).  
+- Drag-and-drop handlers (via `DragAndDropPayload` constants).  
+- Serialization/deserialization utilities (though `SerializableAAF` is currently unused).
+
+---
+
+## 5. Gotchas
+
+- **`SerializableAAF` is non-functional**: All public members are commented out. Do not rely on this class for serialization.  
+- **`DASChannelDBRecord.LocalOnly` is deprecated**: Despite being present, it should not be used for new logic.  
+- **`DASDBRecord.IsProgrammable` maps to `"Reprogramable"` column**: Note the typo in the column name (`Reprogramable` vs. `IsProgrammable`).  
+- **`DASMonitorInfo` tolerances are per-channel but stored flat**: `_offsetTolerancesHigh`/`_offsetTolerancesLow` arrays are indexed per channel, but their length depends on the number of analog input channels in the DAS configuration.  
+- **`DASMonitorInfo.GetChannelName` falls back to default naming**: If `_channelNames` is shorter than `index`, it returns `"Ch#XX"` instead of throwing.  
+- **`DASMonitorInfo.ToShortArray` has a bug**: In `ToShortArray`, it parses `line` instead of `token` (`short.TryParse(line, ...)`)—likely a typo.  
+- **`DASMonitorInfo` uses `float.NaN` for mount offsets**: Despite `MountOffsetAxisOne/Two` being `double`, `GetMountOffsetAxisOne/Two` return `float.NaN` when no modules exist. This may cause precision loss or unexpected behavior.  
+- **`DASDBRecord` uses `INVALID_DATE` for unset dates**: Code must explicitly check for `DateTime(1970, 1, 1)` to detect unset values.