hitl_tester.modules.bms_types

  1"""
  2Various types shared between modules.
  3
  4(c) 2020-2024 TurnAround Factor, Inc.
  5
  6CUI DISTRIBUTION CONTROL
  7Controlled by: DLA J68 R&D SBIP
  8CUI Category: Small Business Research and Technology
  9Distribution/Dissemination Controls: PROTECTED BY SBIR DATA RIGHTS
 10POC: GOV SBIP Program Manager Denise Price, 571-767-0111
 11Distribution authorized to U.S. Government Agencies only, to protect information not owned by the
 12U.S. Government and protected by a contractor’s ‘limited rights’ statement, or received with the understanding that
 13it is not routinely transmitted outside the U.S. Government (determination made September 14, 2024). Other requests
 14for this document shall be referred to ACOR DLA Logistics Operations (J-68), 8725 John J. Kingman Rd., Suite 4317,
 15Fort Belvoir, VA 22060-6221
 16
 17SBIR DATA RIGHTS
 18Contract No.:SP4701-23-C-0083
 19Contractor Name: TurnAround Factor, Inc.
 20Contractor Address: 10365 Wood Park Ct. Suite 313 / Ashland, VA 23005
 21Expiration of SBIR Data Rights Period: September 24, 2029
 22The Government's rights to use, modify, reproduce, release, perform, display, or disclose technical data or computer
 23software marked with this legend are restricted during the period shown as provided in paragraph (b)(4) of the Rights
 24in Noncommercial Technical Data and Computer Software--Small Business Innovative Research (SBIR) Program clause
 25contained in the above identified contract. No restrictions apply after the expiration date shown above. Any
 26reproduction of technical data, computer software, or portions thereof marked with this legend must also reproduce
 27the markings.
 28"""
 29
 30from __future__ import annotations
 31
 32import inspect
 33import time
 34import traceback
 35from dataclasses import dataclass
 36from enum import Enum, auto, IntFlag, IntEnum
 37from pathlib import Path
 38from types import TracebackType
 39from typing import Protocol, runtime_checkable, Any, Type
 40
 41import _pytest
 42
 43try:
 44    from pyvisa.constants import StatusCode
 45except ModuleNotFoundError:
 46    pass  # Allow hitl_tester to import bms_types
 47
 48try:
 49    from hitl_tester.modules.logger import logger
 50    from hitl_tester.modules.file_lock import ResourceLock
 51except ModuleNotFoundError:
 52    pass  # Allow hitl_tester to import bms_types
 53
 54
 55# Test Hardware Type Definitions
 56@dataclass
 57class DMMImpedance:
 58    """Impedance config for DMM."""
 59
 60    pulse_current: int
 61    total_readings: int  # Used for averaging results
 62
 63
 64class BatteryType(Enum):
 65    """Supported battery types."""
 66
 67    UNDEFINED = auto()
 68    NICD = auto()
 69    LI = auto()
 70
 71
 72class NiCdChargeCycle(Enum):
 73    """Supported NiCad charge cycle types."""
 74
 75    UNDEFINED = 0
 76    STANDARD = 1  # 0.1C for 16 hours
 77    CUSTOM = 2
 78    DV_DT = 3  # C/2 for 2.5 hours
 79
 80
 81class DischargeType(Enum):
 82    """Supported discharge types."""
 83
 84    UNDEFINED = 0
 85    CONSTANT_CURRENT = 1
 86    CONSTANT_RESISTANCE = 2
 87    CONSTANT_VOLTAGE = 3
 88
 89
 90# Other
 91class StopWatch:
 92    """Record time with support for suspension."""
 93
 94    def __init__(self) -> None:
 95        self._start_time: float = time.perf_counter()
 96        self._suspend_time: float | None = None
 97
 98    @property
 99    def elapsed_time(self) -> float:
100        """How much time has passed since reset()."""
101        if self._suspend_time is None:
102            return time.perf_counter() - self._start_time
103        return self._suspend_time - self._start_time
104
105    def reset(self) -> None:
106        """Reset the timer to 0."""
107        self._start_time = time.perf_counter()
108
109    def start(self) -> None:
110        """Start the timer."""
111        if self._suspend_time is not None:
112            self._start_time += time.perf_counter() - self._suspend_time
113            self._suspend_time = None
114
115    def stop(self) -> None:
116        """Stop the timer."""
117        self._suspend_time = time.perf_counter()
118
119
120# Enums
121class ControlStatusRegister(IntFlag):
122    """Reset flags from the CSR."""
123
124    LOW_POWER = 0x80000000
125    WINDOW_WATCHDOG = 0x40000000
126    INDEPENDANT_WATCHDOG = 0x20000000
127    SOFTWARE = 0x10000000
128    POWER = 0x08000000
129    RESET_PIN = 0x04000000
130    OPTION_BYTE_LOADER = 0x02000000
131
132    def __str__(self) -> str:
133        return " | ".join(str(flag.name).title() for flag in ControlStatusRegister if self.value & flag)
134
135
136class CellState(IntEnum):
137    """The current state of a cell."""
138
139    UNKNOWN = 0
140    RESTING = 1
141    CHARGING_EXCITED = 2
142    DISCHARGING_EXCITED = 3
143    CHARGING_TIMER = 4
144    DISCHARGING_TIMER = 5
145
146    def __str__(self) -> str:
147        return self.name.title().replace("_", " ")
148
149    @classmethod
150    def _missing_(cls, _: object):
151        return cls(cls.UNKNOWN)
152
153
154class BMSState(IntEnum):
155    """The current state of the BMS."""
156
157    UNKNOWN = 0
158    SLOW_SAMPLE = 1
159    FAST_SAMPLE = 2
160    DEEP_SLUMBER = 3
161    CALIBRATION = 4
162    PREFAULT = 5
163    FAULT = 6
164    FAULT_SLUMBER = 7
165    FAULT_PERMANENT_DISABLE = 8
166
167    def __str__(self) -> str:
168        return self.name.title().replace("_", " ")
169
170    @classmethod
171    def _missing_(cls, _: object):
172        return cls(cls.UNKNOWN)
173
174
175# BMS HW Enums
176class CellCompMode(Enum):
177    """
178    This circuit compensates the output of the dc source according to the input capacitance of the device being tested
179    as well as the type of output connections being used.
180    """
181
182    HREMOTE = auto()  # (DEFAULT) Used for faster response with long load leads using remote sensing.
183    HLOCAL = auto()  # Use for faster response with short load leads or bench operation (no external cap needed).
184    LREMOTE = auto()  # Used for slower response with long load leads using remote sensing.
185    LLOCAL = auto()  # Used for slower response with short load leads or bench operation.
186
187
188class NGIMode(Enum):
189    """
190    This circuit compensates the output of the dc source according to the input capacitance of the device being tested
191    as well as the type of output connections being used.
192    """
193
194    SOURCE = 0  # N83624 source mode includes constant voltage.
195    CHARGE = 1  # Under Charge mode, battery charging and discharging.
196    SOC = 2  # The SOC function simulates battery charging.
197    SEQ = 3  # Executes sequentially according to the output parameters of a step file.
198
199
200# Exceptions
201class LoggingError(Exception):
202    """Log the exception before raising it."""
203
204    def __init__(self, message):
205        """Output error message and raise exception."""
206        logger.write_critical_to_report(f"{type(self).__name__} - {message}")
207        super().__init__(message)
208
209
210class PacketError(LoggingError):
211    """Raised when a packet in malformed."""
212
213
214class ResourceNotFoundError(LoggingError):
215    """Raised when a hardware resource is not found."""
216
217
218class OverTemperatureError(LoggingError):
219    """Raised when an over-temperature is triggered."""
220
221
222class OverVoltageError(LoggingError):
223    """Raised when an overvoltage is triggered."""
224
225
226class UnderVoltageError(LoggingError):
227    """Raised when an undervoltage is triggered."""
228
229
230class TimeoutExceededError(LoggingError):
231    """Some event did not occur in the specified amount of time."""
232
233
234class VisaSystemError(LoggingError):
235    """The instrument reported a system error."""
236
237
238class ValueLogError(LoggingError):
239    """A value error that gets logged."""
240
241
242class ChargerOrLoad(Protocol):
243    """Protocol for a charger or load object"""
244
245    def enable(self):
246        """Enables instrument output"""
247
248    def disable(self):
249        """Disables instrument output"""
250
251    def reset(self):
252        """Resets the instrument"""
253
254
255class SuppressExceptions:
256    """Suppresses all exceptions."""
257
258    def __enter__(self):
259        """NOP"""
260
261    def __exit__(
262        self, exc_type: Type[BaseException] | None, exc_value: BaseException | None, exc_traceback: TracebackType | None
263    ) -> bool:
264        """Suppress all exceptions by returning True."""
265        whitelist = [None, _pytest.outcomes.Exit, KeyboardInterrupt, SystemExit]
266        if result := exc_type not in whitelist:
267            exception_message = "".join(traceback.format_exception(exc_type, exc_value, exc_traceback))
268            logger.write_debug_to_report(exception_message.rstrip("\n"))
269        return result
270
271
272class SafeResource:
273    """Gives multiprocess-safe access to Pyvisa resources without raising exceptions."""
274
275    def __init__(self, resource_address: str | tuple[str, str, str]):
276        self.resource_address = resource_address
277        self.lock = ResourceLock(resource_address)
278        self.default_result = "0"
279
280    def log_caller(self):
281        """Log the calling function."""
282        caller = (
283            f"File {inspect.stack()[2].filename}, line {inspect.stack()[2].lineno}, "
284            f"in {inspect.stack()[2].function}\n    {(''.join(inspect.stack()[2].code_context or [])).strip(chr(10))}"
285        )
286        logger.write_debug_to_report(caller)
287
288    @property
289    def baud_rate(self) -> int:
290        """The baud rate for the serial connection."""
291        return int(self.lock.baud_rate)
292
293    @baud_rate.setter
294    def baud_rate(self, new_baud_rate: int):
295        self.lock.baud_rate = new_baud_rate
296
297    @property
298    def last_status(self) -> StatusCode:
299        """PyVISA status code suppressing exceptions."""
300        with SuppressExceptions(), self.lock:
301            assert self.lock.resource
302            return self.lock.resource.last_status
303        return StatusCode.success
304
305    @property
306    def timeout(self) -> float:
307        """Get PyVISA timeout value."""
308        with SuppressExceptions(), self.lock:
309            assert self.lock.resource
310            return self.lock.resource.timeout
311        return 0.0
312
313    @timeout.setter
314    def timeout(self, new_timeout: float):
315        """Set PyVISA timeout value."""
316        with SuppressExceptions(), self.lock:
317            assert self.lock.resource
318            self.lock.resource.timeout = new_timeout
319
320    def write(self, command: str):
321        """PyVISA write suppressing exceptions."""
322        with SuppressExceptions(), self.lock:
323            assert self.lock.resource
324            self.lock.resource.write(command)
325            return
326        self.log_caller()
327
328    def query(self, command: str) -> str:
329        """PyVISA query suppressing exceptions."""
330        with SuppressExceptions(), self.lock:
331            assert self.lock.resource
332            return self.lock.resource.query(command)
333        self.log_caller()
334        return self.default_result
335
336    def read_raw(self) -> bytes:
337        """PyVISA read_raw suppressing exceptions."""
338        with SuppressExceptions(), self.lock:
339            assert self.lock.resource
340            return self.lock.resource.read_raw()
341        self.log_caller()
342        return b""
343
344
345# Flags
346@runtime_checkable
347class BMSFlags(Protocol):
348    """The flags passed from hitl_tester to bms_hw."""
349
350    plateset_id: str = ""
351    dry_run: bool = False
352    doc_generation: bool = False
353    cell_chemistry: str = ""
354    config: dict[str, str | dict[str, Any]] = {}  # FIXME(JA): break out into separate attributes with sane defaults
355    report_filename: Path = Path()
356    properties: dict[str, Any] | None = {}
357    test_plan: Path = Path()
358
359
360class TestFlags(BMSFlags):
361    """The flags to be passed from hitl_tester to bms_hw."""
362
363    def __init__(
364        self,
365        dry_run: bool = False,
366        doc_generation: bool = False,
367        cell_chemistry: str = "",
368        properties: dict[str, Any] | None = None,
369        test_plan: Path = Path(),
370    ):
371        self.dry_run = dry_run
372        self.doc_generation = doc_generation
373        self.cell_chemistry = cell_chemistry
374        self.properties = properties or {}
375        self.config = {}
376        self.test_plan = test_plan