init

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

@@ -0,0 +1,172 @@
+---
+source_files:
+  - Common/DTS.CommonCore/Classes/Hardware/ExternalTilt.cs
+  - Common/DTS.CommonCore/Classes/Hardware/DragAndDropPayload.cs
+  - Common/DTS.CommonCore/Classes/Hardware/SerializableAAF.cs
+  - Common/DTS.CommonCore/Classes/Hardware/DASDBRecord.cs
+  - Common/DTS.CommonCore/Classes/Hardware/DASChannelDBRecord.cs
+  - Common/DTS.CommonCore/Classes/Hardware/DASMonitorInfo.cs
+generated_at: "2026-04-16T02:39:04.354265+00:00"
+model: "Qwen/Qwen3-Coder-Next-FP8"
+schema_version: 1
+sha256: "ae82d579176b397b"
+---
+
+# Hardware Data Models Documentation
+
+## 1. Purpose  
+This module defines core data models for representing hardware devices, channels, and associated metadata within the DTS (Data Acquisition System) ecosystem. It provides structured classes for serializing/deserializing hardware configuration data to/from databases (via `DASDBRecord`, `DASChannelDBRecord`), file-based monitoring state (`DASMonitorInfo`), and lightweight data transfer objects (`ExternalTilt`, `DragAndDropPayload`). These models serve as the canonical in-memory representation of hardware state for configuration, persistence, and UI binding, enabling consistent handling of DAS (Data Acquisition System) units, modules, channels, and tilt sensors across the system.
+
+## 2. Public Interface  
+
+### `ExternalTilt`
+- **`ExternalTilt()`**  
+  Parameterless constructor.
+- **`SerialNumber`** (`string`, public get/set)  
+  Serial number of the external tilt sensor.
+- **`TiltID`** (`byte`, public get/set)  
+  Identifier for the tilt sensor.
+- **`SystemID`** (`string`, public get/set)  
+  Identifier of the system the tilt sensor belongs to.
+- **`SystemLocation`** (`string`, public get/set)  
+  Physical or logical location of the tilt sensor within the system.
+
+### `DragAndDropPayload`
+- **`FORMAT`** (`const string`)  
+  `"RESOLVECHANNELS_HARDWARETABLE"` — Primary clipboard/data transfer format identifier.
+- **`ALT_FORMAT`** (`const string`)  
+  `"ALT_RESOLVECHANNELS_HARDWARETABLE"` — Alternate format identifier.
+- **`CTRL_FORMAT`** (`const string`)  
+  `"CTRL_RESOLVECHANNELS_HARDWARETABLE"` — Control-modifier variant format identifier.
+
+### `SerializableAAF`
+- **`DAS_TYPE`** (`enum`)  
+  - `TDAS = 0`  
+  - `SLICE = 1`  
+- **`GetSerializedKey()`** (`string`)  
+  Returns a string key in the format `"{DAS_TYPE}_{SampleRate}"` (e.g., `"0_10000"`).  
+- **`GetSerializedValue()`** (`string`)  
+  Returns the AAF value as a culture-invariant string.  
+- **`FromSerializedStrings(string key, string value)`**  
+  Parses `key` and `value` to populate internal fields. Throws `NotSupportedException` if the key format is invalid (must contain exactly two tokens separated by `"_x_"`).  
+  *Note: All properties (`DasType`, `SampleRate`, `AAF`) are currently commented out in the source and not active.*
+
+### `DASDBRecord`
+- **`INVALID_DATE`** (`static DateTime`)  
+  `new DateTime(1970, 1, 1)` — Sentinel value for unset date fields.
+- **Constructors**  
+  - `DASDBRecord()` — Default constructor.  
+  - `DASDBRecord(IDASDBRecord copy)` — Deep copy constructor.  
+  - `DASDBRecord(IDataReader reader)` — Populates fields from database reader. Handles `DBNull` and special date parsing (e.g., `FIRST_USE_DATE_NOT_SET`).  
+- **Key Properties**  
+  - `DASId` (`int`, `[Key]`, `[Column("DASId")]`) — Primary key.  
+  - `SerialNumber` (`string`, `[Required]`, `[StringLength(50)]`) — Unique hardware identifier.  
+  - `DASType` (`int`) — Numeric type code (e.g., `0` = TDAS, `1` = SLICE).  
+  - `MaxSampleRate`, `MinSampleRate` (`double`, `[Column(TypeName = "decimal(18, 0)")]`) — Hardware sample rate limits.  
+  - `CalDate` (`DateTime`, defaults to `INVALID_DATE`) — Calibration date.  
+  - `ChannelTypes` (`int[]`, `[StringLength(255)]`) — Array of channel type codes. Parsed from comma-separated string.  
+  - `FirstUseDate` (`DateTime?`) — Nullable first-use date. `IsFirstUseValid` indicates if it is set and valid.  
+  - `MaxAAFRate` (`double`, `[Column("MaxAAFRate", TypeName = "decimal(18, 0)")]`) — Maximum analog anti-aliasing filter rate.  
+  - `IsFirstUseValid` (`bool`) — Indicates whether `FirstUseDate` is supported and set.  
+  - `StandIn`, `IsModule`, `IsProgrammable`, `IsReconfigurable` (`bool`) — Hardware capability flags.  
+  - `Position`, `Connection`, `FirmwareVersion`, `LastModifiedBy`, `LastUsedBy` (`string`) — Metadata strings.  
+  - `PositionOnChain`, `PositionOnDistributor`, `Port`, `ProtocolVersion`, `Version`, `Channels`, `MaxModules`, `MaxMemory` (`int`/`long`) — Configuration parameters.  
+  - `ParentDAS` (`string`, `[Column("ParentDAS")]`) — Serial number of parent DAS (for modules).  
+  - `TestId`, `GroupId` (`int?`) — Nullable foreign keys.  
+
+### `DASChannelDBRecord`
+- **`HardwareId`** (`string`) — Identifier for the parent hardware (`serialnumber_dastype`).  
+- **`DaschannelId`** (`int`, `[Key]`, `[Column("DASChannelId")]`) — Primary key.  
+- **`Dasid`** (`int?`) — Foreign key to `DASDBRecord.DASId`.  
+- **`ChannelIdx`** (`int`, with `SetProperty` change notification) — Physical channel index on the DAS.  
+- **`SupportedBridges`** (`int`, default `DEFAULT_SUPPORTED_BRIDGES = 12`)  
+  Bitmask:  
+  - Bit 1 (value 2): Quarter bridge  
+  - Bit 2 (value 4): Half bridge  
+  - Bit 3 (value 8): Full bridge  
+  *(IEPE, digital input, squib fire, etc., are defined in other bitmasks below)*  
+- **`SupportedExcitations`** (`int`, default `DEFAULT_SUPPORTED_EXCITATIONS = 16`)  
+  Bitmask:  
+  - Bit 4 (value 16): 5V (default)  
+  - Bits 0–6: Invalid, 2V, 2.5V, 3V, 5V, 10V, 1V  
+- **`DASDisplayOrder`** (`int`) — Display order (may differ from physical order).  
+- **`SupportedDigitalInputModes`** (`int`, default `16`)  
+  Bitmask for digital input modes (e.g., CCNC, TLH, THL).  
+- **`SupportedSquibFireModes`** (`int`, default `16`)  
+  Bitmask for squib fire modes (capacitor discharge, constant current, AC discharge).  
+- **`SupportedDigitalOutputModes`** (`int`, default `16`)  
+  Bitmask for digital output modes (FVLH, FVHL, CCNO, CCNC).  
+- **`ModuleSerialNumber`** (`string`) — Serial number of the module this channel belongs to.  
+- **`ModuleArrayIndex`** (`int`) — Array index of the module among modules on the DAS/rack.  
+- **Constructors**  
+  - `DASChannelDBRecord()` — Default.  
+  - `DASChannelDBRecord(IDataReader reader)` — Populates from database.  
+  - `DASChannelDBRecord(IDASChannelDBRecord copy)` — Copy constructor.  
+
+### `DASMonitorInfo`
+- **`ReadFromFile(string path)`**  
+  Reads monitor info from a text file (one field per line, in `Fields` enum order). Silently returns on file not found or parse errors (logs via `APILogger`).  
+- **`WriteToFile(string path)`**  
+  Writes monitor info to a text file. Logs exceptions via `APILogger`.  
+- **`GetChannelName(int index)`** (`string`)  
+  Returns channel name (format: `"Ch#XX"` if not set). Uses `_channelNames` array.  
+- **`GetOffsetTolerancemVHigh(int index)` / `GetOffsetTolerancemVLow(int index)`** (`double`)  
+  Returns tolerance values (0 if index out of bounds).  
+- **Constructors**  
+  - `DASMonitorInfo(string path)` — Loads from file.  
+  - `DASMonitorInfo(IDASCommunication das, IsoViewMode mode)` — Populates from live DAS communication object.  
+- **Properties**  
+  - `SerialNumber` (`string`)  
+  - `TiltSensorCals` (`double[18]`) — Calibration coefficients.  
+  - `TiltSensorDataPre` (`short[3]`) — Pre-processed tilt sensor data.  
+  - `TiltAxes` (`DFConstantsAndEnums.TiltAxes`) — Axis configuration (default `IXIYIZ`).  
+  - `AxisIgnored` (`int`) — Bitmask of ignored axes.  
+  - `MountOffsetAxisOne`, `MountOffsetAxisTwo` (`double`) — Mounting offsets (default `NaN`).  
+  - `_channelNames` (`string[]`) — Channel names (private).  
+  - `_offsetTolerancesHigh`, `_offsetTolerancesLow` (`double[6]`) — Tolerance arrays (private).  
+- **`Fields`** (`enum`) — Defines ordered file fields:  
+  `SerialNumber`, `TiltSensorCals`, `TiltSensorDataPre`, `TiltAxes`, `AxesIgnored`, `MountOffsetAxisOne`, `MountOffsetAxisTwo`, `ChannelNames`, `OffsetTolerancesLow`, `OffsetTolerancesHigh`.  
+
+## 3. Invariants  
+- **`DASDBRecord`**  
+  - `SerialNumber` is required and non-empty (enforced by `[Required]`).  
+  - `Position` is required and non-empty (enforced by `[Required]`).  
+  - `CalDate` defaults to `INVALID_DATE` (1970-01-01) if unset.  
+  - `FirstUseDate` is nullable; `IsFirstUseValid` must be `true` for it to be considered valid.  
+  - `ChannelTypes` is parsed from a comma-separated string; invalid tokens are silently skipped.  
+  - `IsProgrammable` is mapped from database column `"Reprogramable"` (note the typo).  
+- **`DASChannelDBRecord`**  
+  - `SupportedBridges`, `SupportedExcitations`, etc., use default bitmasks (e.g., `12` for bridges, `16` for excitations).  
+  - `ChannelIdx` uses `SetProperty` for change notifications (implements `INotifyPropertyChanged`).  
+- **`DASMonitorInfo`**  
+  - File format is strictly ordered by `Fields` enum values (10 lines).  
+  - Parsing uses `CultureInfo.InvariantCulture` for numeric values.  
+  - `TiltSensorCals` is fixed-length (`double[18]`); arrays from file are truncated/padded to this length.  
+  - `NoModules(das)` check returns empty arrays/`NaN` if `das.ConfigData` or `das.ConfigData.Modules` is null/empty.  
+
+## 4. Dependencies  
+- **Imports/Usings**  
+  - `DTS.Common.Base` (`BasePropertyChanged`)  
+  - `DTS.Common.Enums`, `DTS.Common.Enums.DASFactory` (e.g., `TiltAxes`, `IsoViewMode`)  
+  - `DTS.Common.Interface.DataRecorders` (`IDASDBRecord`, `IDASChannelDBRecord`)  
+  - `DTS.Common.Interface.Hardware` (`IDASCommunication`, `ITiltSensorCalAware`)  
+  - `System.Data` (`IDataReader`)  
+  - `System.ComponentModel.DataAnnotations` (EF Core attributes)  
+  - `DTS.Common.Utilities.Logging` (`APILogger`)  
+- **External Dependencies**  
+  - `Utility` class (static helper for `GetDateTime`, `GetString`, `GetInt`, etc.).  
+  - `DFConstantsAndEnums.FIRST_USE_DATE_NOT_SET` (for date validation).  
+  - `Strings.Strings.Ch` (for default channel names).  
+- **Depended Upon**  
+  - `DASDBRecord` and `DASChannelDBRecord` implement `IDASDBRecord`/`IDASChannelDBRecord` interfaces, likely consumed by data access layers.  
+  - `DASMonitorInfo` depends on `IDASCommunication` and `IsoViewMode` (from `DTS.Common.Enums`).  
+
+## 5. Gotchas  
+- **`SerializableAAF`** is **non-functional** in the current source: All properties and the constructor are commented out. The class is effectively a stub.  
+- **`DASDBRecord.IsProgrammable`** maps to database column `"Reprogramable"` (misspelled).  
+- **`DASChannelDBRecord.SupportedBridges`** defaults to `12` (half + full bridge), but the summary comments incorrectly state "half (4) + full (8)" — this sums to `12`, but bit positions are 2 and 3 (values 4 and 8), not 4 and 8.  
+- **`DASMonitorInfo`** uses `float.NaN` in `GetMountOffsetAxisOne/Two` but assigns to `double` properties (implicit conversion).  
+- **`DASMonitorInfo.ToShortArray`** has a bug: It parses `line` instead of `token` in `short.TryParse`.  
+- **`DASMonitorInfo`** file format assumes exactly 10 fields in `Fields` order; extra/missing lines are ignored or cause misalignment.  
+- **`DASDBRecord.ChannelTypes`** is stored as a comma-separated string in the DB but mapped to `int[]` in code; parsing silently drops invalid tokens.  
+- **`DASMonitorInfo`** uses `double[]` arrays of fixed size (e.g., `TiltSensorCals[18]`), but file parsing may produce arrays of arbitrary length (truncated to size in code? Not explicitly handled).