93 lines
5.5 KiB
Markdown
93 lines
5.5 KiB
Markdown
---
|
||
source_files:
|
||
- DataPRO/MODSensorFile/SensorFile.cs
|
||
- DataPRO/MODSensorFile/MODSensor.cs
|
||
generated_at: "2026-04-16T03:50:51.428687+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "d23802c1d2555e6e"
|
||
---
|
||
|
||
# Module Documentation: `MODSensorFile`
|
||
|
||
## 1. Purpose
|
||
This module provides data structures and a parser for reading sensor configuration data from a text-based file format used in the DataPRO system. Specifically, `SensorFile` loads and parses a space-delimited file into a list of `MODSensor` objects, each representing a single sensor’s metadata (e.g., channel, calibration, polarity, type). It serves as the ingestion layer for sensor configuration in data acquisition workflows, enabling downstream components to access structured sensor definitions without parsing raw text.
|
||
|
||
## 2. Public Interface
|
||
|
||
### `SensorFile` class
|
||
- **`SensorFile()`**
|
||
Default constructor; initializes an empty `Sensors` list.
|
||
- **`SensorFile(string filename)`**
|
||
Constructor that reads and parses a file at `filename`. Each line is interpreted as a space-delimited record of 13 fields, used to instantiate a `MODSensor` and add it to the `Sensors` list. Throws exceptions on malformed data (e.g., `FormatException`, `IndexOutOfRangeException`, `IOException`).
|
||
- **`List<MODSensor> Sensors`**
|
||
Public field containing the parsed list of `MODSensor` instances. Not read-only; callers may modify the list contents.
|
||
|
||
### `MODSensor` class
|
||
- **`int PhysicalChannel`**
|
||
3-digit sensor record ID (e.g., channel number).
|
||
- **`string SensorName`**
|
||
Human-readable name of the sensor.
|
||
- **`string SensorSerial`**
|
||
Alphanumeric serial number.
|
||
- **`int SignalReverse`**
|
||
Polarity flag: `0` = normal, `1` = inverse.
|
||
- **`int CFCClass`**
|
||
SAE J211 Channel Frequency Class (e.g., 100, 600, 1000).
|
||
- **`char PhysicalProperty`**
|
||
Single-character code representing the physical property measured (e.g., `'V'`, `'A'`, `'P'`). *Exact mapping is not documented.*
|
||
- **`string EngineeringUnits`**
|
||
Unit string (e.g., `"V"`, `"g"`, `"N·m"`).
|
||
- **`float Sensibility`**
|
||
Sensor sensitivity (e.g., mV/V or counts/unit).
|
||
- **`float FullScale`**
|
||
Full-scale range in engineering units (±symmetric; e.g., `1000` means ±1000 EU).
|
||
- **`float ExcitationVoltage`**
|
||
Excitation voltage applied to the sensor (e.g., `10.0` V).
|
||
- **`int Type`**
|
||
Bridge configuration: `0` = full bridge, `1` = half bridge, `2` = voltage.
|
||
- **`string ExpectedDallasID`**
|
||
Expected Dallas Semiconductor (1-Wire) ID string for the sensor.
|
||
- **`int RemoveOffset`**
|
||
Offset removal flag: `0` = none, `1` = remove (typically half of pretrigger).
|
||
- **`bool IsInverted()`**
|
||
Returns `true` if `SignalReverse == 1` (inverse polarity).
|
||
- **`SensorType GetSensorType()`**
|
||
Returns the `SensorType` enum (`FullBridge`, `HalfBridge`, or `Voltage`) based on `Type`.
|
||
- **`OffsetRemoval GetOffsetRemoval()`**
|
||
Returns the `OffsetRemoval` enum (`None` or `Remove`) based on `RemoveOffset`.
|
||
|
||
### Nested Enums in `MODSensor`
|
||
- **`Polarity`**: `Normal = 0`, `Inverse = 1`
|
||
- **`SensorType`**: `FullBridge = 0`, `HalfBridge = 1`, `Voltage = 2`
|
||
- **`OffsetRemoval`**: `None = 0`, `Remove = 1`
|
||
|
||
## 3. Invariants
|
||
- Each line in the input file must contain **exactly 13 non-empty space-delimited tokens**. Missing or extra tokens will cause a runtime exception (e.g., `ArgumentOutOfRangeException` or `FormatException`).
|
||
- `PhysicalChannel`, `SignalReverse`, `CFCClass`, `Type`, and `RemoveOffset` must be parseable as integers.
|
||
- `Sensibility`, `FullScale`, and `ExcitationVoltage` must be parseable as `float`.
|
||
- `PhysicalProperty` must be a single non-whitespace character.
|
||
- `Sensors` list is populated in the order lines appear in the file.
|
||
- No validation is performed on semantic correctness (e.g., `CFCClass` values, `Type` ranges, or `ExpectedDallasID` format).
|
||
|
||
## 4. Dependencies
|
||
- **Depends on**:
|
||
- `System.IO` (for `File.ReadAllLines`)
|
||
- `System.Collections.Generic`, `System.Linq`, `System.Text`, `System.Threading.Tasks` (standard .NET libraries)
|
||
- **Used by**:
|
||
- Likely consumed by data acquisition or calibration modules (e.g., to map physical channels to sensor metadata during signal processing).
|
||
- *No explicit references to other modules are visible in the source.*
|
||
|
||
## 5. Gotchas
|
||
- **Whitespace handling**: Empty tokens (e.g., from multiple consecutive spaces) are removed via `RemoveAll(p => string.IsNullOrWhiteSpace(p))`. This may mask formatting errors (e.g., a missing field replaced by extra spaces).
|
||
- **No error recovery**: Parsing stops on the first malformed line; no partial loading or error reporting.
|
||
- **`Sensors` is a public field, not a property**: Direct list mutation (e.g., `sensorFile.Sensors.Add(...)`) is allowed, bypassing encapsulation.
|
||
- **Ambiguous fields**:
|
||
- `PhysicalProperty`’s meaning is not documented beyond "Physical Property?".
|
||
- `ExpectedDallasID`’s format (e.g., 64-bit hex, null-terminated) is unspecified.
|
||
- **No encoding specified**: `File.ReadAllLines` uses UTF-8 by default in modern .NET, but behavior may vary if the file uses a different encoding (e.g., ANSI/Windows-1252).
|
||
- **No async support**: Constructor is synchronous; large files may block the calling thread.
|
||
- **Hard-coded delimiters**: Assumes space (`' '`) as the *only* delimiter; tabs or other whitespace are not handled.
|
||
- **No versioning**: No mechanism to detect or reject incompatible file formats.
|
||
|
||
None identified from source alone. |