125 lines
9.0 KiB
Markdown
125 lines
9.0 KiB
Markdown
---
|
||
source_files:
|
||
- DataPRO/IService/Classes/BaseInput/SLICEBaseInputValues.cs
|
||
- DataPRO/IService/Classes/BaseInput/SLICE.Base.Input.Reader.cs
|
||
- DataPRO/IService/Classes/BaseInput/BaseInputValues.cs
|
||
generated_at: "2026-04-16T03:58:02.897735+00:00"
|
||
model: "Qwen/Qwen3-Coder-Next-FP8"
|
||
schema_version: 1
|
||
sha256: "371fccf4478077de"
|
||
---
|
||
|
||
# Documentation: SLICE Base Input Module
|
||
|
||
## 1. Purpose
|
||
|
||
This module provides data acquisition and status reporting for power-related inputs on SLICE-based hardware units. It enables reading raw diagnostic values (e.g., input voltage, battery voltage, temperature, charging status) via the `SLICEBaseInputReader` class and encapsulating them into a standardized data model (`BaseInputValues` and its SLICE-specific subclass `SLICEBaseInputValues`). The `SLICEBaseInputValues` subclass implements domain-specific logic to compute battery voltage status (e.g., `GREEN`, `YELLOW`, `RED`, `NOBATTERY`, `OFF`) based on battery voltage, input voltage, and charge capacity, while also handling device-specific behavior for backup power measurement and enablement.
|
||
|
||
## 2. Public Interface
|
||
|
||
### `SLICEBaseInputValues` (inherits `BaseInputValues`)
|
||
|
||
- **`PossibleVoltageStatus` enum**
|
||
Defines voltage status levels: `GREEN`, `YELLOW`, `RED`, `OFF`.
|
||
*Note: This enum is declared but not used in the current implementation.*
|
||
|
||
- **`PossibleBatteryStatus` enum**
|
||
Defines battery status levels: `GREEN`, `YELLOW`, `RED`, `NOBATTERY`, `OFF`.
|
||
|
||
- **`BatteryVoltageStatus` (override property)**
|
||
*Read-only computed property.* Returns a string representation of `PossibleBatteryStatus` based on the following logic:
|
||
- If `BatteryMilliVoltsValid` is `false`, returns `"NOBATTERY"`.
|
||
- Else if `ChargeCapacityValid` is `true`:
|
||
- `> 70%` → `"GREEN"`
|
||
- `> 40%` → `"YELLOW"`
|
||
- else → `"RED"`
|
||
- Else if `InputMilliVoltsValid` is `true`, computes status using thresholds on `InputMilliVolts` and `BatteryMilliVolts` (see detailed logic in source).
|
||
- Else → `"RED"`.
|
||
*Write setter is a no-op; value is always regenerated on read.*
|
||
|
||
### `SLICEBaseInputReader`
|
||
|
||
- **Constructor**
|
||
`SLICEBaseInputReader(ICommunication comm)`
|
||
Initializes the reader with a communication interface (`ICommunication`). Throws no exceptions documented.
|
||
|
||
- **`InputMilliVolts` (virtual property)**
|
||
Returns the input voltage in millivolts by querying the `MeasureBaseDiagnosticChannel` for `BaseDiagnosticChannelList.InputVoltage`. Multiplies raw measurement by `1000.0`.
|
||
|
||
- **`TemperatureC` (virtual property)**
|
||
Returns the temperature in degrees Celsius by querying `MeasureBaseDiagnosticChannel` for `BaseDiagnosticChannelList.TemperatureC`.
|
||
|
||
- **`BatteryIsCharging` (property)**
|
||
Returns `true` if the base unit’s charge status switch (via `QuerySwitchImmediate` for `Switches.BaseSwitches.ChargeStatus`) is set to `1`.
|
||
|
||
- **`DirectBackupMilliVolts` (virtual property)**
|
||
Returns backup voltage in millivolts *without* enabling/disabling backup power. Returns `0D` if `ShouldMeasureBackupPower()` returns `false`.
|
||
|
||
- **`BackupMilliVolts` (property)**
|
||
Returns backup voltage in millivolts *with* power management:
|
||
- If `ShouldEnableBackupPower()` returns `true`, enables backup power, waits 1.5 seconds, reads via `DirectBackupMilliVolts`, then disables backup power in a `finally` block.
|
||
- If `ShouldEnableBackupPower()` returns `false`, directly returns `DirectBackupMilliVolts`.
|
||
|
||
- **`ShouldEnableBackupPower()` (private method)**
|
||
Returns `false` for SLICE6, SLICE2, and USB variants (`EthernetSlice6`, `EthernetSlice2`, `EthernetSlice6Air`, `EthernetSlice6AirBridge`, `EthernetTsrAir`, `WinUSBSlice6`, `CDCUSBSlice`); `true` otherwise.
|
||
|
||
- **`ShouldMeasureBackupPower()` (public method)**
|
||
Returns `false` for SLICE6 and USB variants (`EthernetSlice6`, `EthernetSlice6Air`, `EthernetSlice6AirBridge`, `WinUSBSlice6`, `CDCUSBSlice`), `true` for `EthernetSlice2` and `EthernetTsrAir`, and defaults to `true` for other types.
|
||
|
||
- **`EnableBackupPower()` (private method)**
|
||
Sends `SetSwitchImmediate` command to set `Switches.BaseSwitches.BackupPower` to `1`, but only if `ShouldEnableBackupPower()` returns `true`.
|
||
|
||
- **`DisableBackupPower()` (private method)**
|
||
Sends `SetSwitchImmediate` command to set `Switches.BaseSwitches.BackupPower` to `0`, but only if `ShouldEnableBackupPower()` returns `true`.
|
||
|
||
### `BaseInputValues` (base class)
|
||
|
||
- **Properties**
|
||
- `InputMilliVolts`, `InputVoltage` (both `double`)
|
||
- `InputMilliVoltsValid` (virtual `bool`) — `true` if `InputMilliVolts` is within `(MinimumValidInputVoltage, MaximumValidInputVoltage)` (default: 6–16 V).
|
||
- `MinimumValidInputVoltage`, `MaximumValidInputVoltage` (both `double`, default 6 and 16).
|
||
- `BatteryMilliVolts`, `BatteryVoltage` (both `double`)
|
||
- `BatteryMilliVoltsValid` (virtual `bool`) — `true` if `BatteryMilliVolts` is within `(MinimumValidBatteryVoltage, MaximumValidBatteryVoltage)` (default: 6–16 V).
|
||
- `BatterySoC` (`double?`) — battery state of charge (percentage), `null` if not queried.
|
||
- `MinimumValidBatteryVoltage`, `MaximumValidBatteryVoltage` (both `double`, default 6 and 16).
|
||
- `BatteryIsCharging` (`bool`)
|
||
- `TemperatureC` (`double`)
|
||
- `BatteryVoltageStatus`, `InputVoltageStatus`, `StatusDisplayBattery`, `StatusDisplayInput` (all `string`, default `null`)
|
||
- `BatteryVoltageStatusColor`, `InputVoltageStatusColor` (both `DFConstantsAndEnums.VoltageStatusColor`, default `null`)
|
||
- `ChargeCapacity` (`double`, default `double.NaN`)
|
||
- `ChargeCapacityValid` (`bool`) — `true` if `ChargeCapacity` is not `NaN`, and `0 < ChargeCapacity < 100`.
|
||
|
||
- **Constructors**
|
||
- Default constructor.
|
||
- Copy constructor: `BaseInputValues(IBaseInputValues copy)` — copies all properties from another `IBaseInputValues` instance.
|
||
|
||
## 3. Invariants
|
||
|
||
- `BatteryVoltageStatus` in `SLICEBaseInputValues` is *always* computed on read and never settable; the setter is a no-op.
|
||
- `InputMilliVoltsValid` and `BatteryMilliVoltsValid` depend on configurable min/max thresholds (default 6–16 V), but are validated against raw millivolt values.
|
||
- `ChargeCapacityValid` requires `ChargeCapacity` to be in `(0, 100)` and not `NaN`.
|
||
- `BackupMilliVolts` always disables backup power after measurement, regardless of success or failure, via `finally` block.
|
||
- `ShouldEnableBackupPower()` and `ShouldMeasureBackupPower()` may differ in behavior (e.g., `EthernetTsrAir` returns `true` for `ShouldMeasureBackupPower()` but `false` for `ShouldEnableBackupPower()`).
|
||
- Backup power is *not* enabled for SLICE6 or USB variants (`EthernetSlice6`, `EthernetSlice6Air`, `EthernetSlice6AirBridge`, `WinUSBSlice6`, `CDCUSBSlice`), per `ShouldEnableBackupPower()`.
|
||
|
||
## 4. Dependencies
|
||
|
||
### Imports/Usings
|
||
- `System.Threading` → used for `Thread.Sleep(1500)` in `BackupMilliVolts`.
|
||
- `DTS.Common.Interface.DASFactory` → provides `ICommunication`, `MeasureBaseDiagnosticChannel`, `QuerySwitchImmediate`, `SetSwitchImmediate`, `Switches`, `MeasureBaseDiagnosticChannel.BaseDiagnosticChannelList`.
|
||
- `DTS.DASLib.Command.SLICE` → provides SLICE-specific command types (`MeasureBaseDiagnosticChannel`, `QuerySwitchImmediate`, `SetSwitchImmediate`, `Switches`).
|
||
- `DTS.Common.Enums.DASFactory` → provides `DFConstantsAndEnums.VoltageStatusColor`.
|
||
- `DTS.Common.Interface.DASFactory.Diagnostics` → used via `IBaseInputValues`.
|
||
|
||
### Inferred Usage
|
||
- `SLICEBaseInputReader` is used by higher-level services (e.g., `DiagnosticsService.Diagnose`) to populate `BaseInputValues` instances.
|
||
- `SLICEBaseInputValues` is likely instantiated or assigned where SLICE-specific battery status logic is required.
|
||
|
||
## 5. Gotchas
|
||
|
||
- **`BatteryVoltageStatus` logic is complex and voltage-threshold-dependent**: The fallback logic for battery status when `ChargeCapacityValid` is `false` but `InputMilliVoltsValid` is `true` uses multiple nested `if` conditions with overlapping voltage ranges (e.g., `InputMilliVolts > 11000`, `> 9000`, `< 9`). This may be error-prone and could lead to unexpected status if input voltage is exactly at boundary values (e.g., `9000`, `11000`, `9000` mV).
|
||
- **`BackupMilliVolts` has side effects**: It enables/disables backup power *even if the device does not support it* (guarded by `ShouldEnableBackupPower()`), but the 1.5-second delay (`Thread.Sleep`) may block the calling thread. This is not async-friendly.
|
||
- **`ShouldEnableBackupPower()` vs `ShouldMeasureBackupPower()` divergence**: `EthernetTsrAir` is explicitly excluded from enabling backup power but *should* measure it — a subtle distinction that could cause confusion if not understood.
|
||
- **`ChargeCapacityValid` excludes `0`**: A valid battery at 0% charge would be considered invalid (`ChargeCapacityValid = false`), potentially forcing fallback to voltage-based status even when charge data is present.
|
||
- **No validation on `BatteryMilliVolts` vs `InputMilliVolts`**: The logic assumes `BatteryMilliVolts` is always ≤ `InputMilliVolts` when input is present, but no explicit checks exist.
|
||
- **`InputMilliVoltsValid` uses `1000D * MinimumValidInputVoltage`**: This is redundant since `InputMilliVolts` is already in millivolts; could be simplified to `InputMilliVolts > MinimumValidInputVoltage * 1000`. |