obsidian/Main
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

vault backup: 2026-01-13 15:23:47

Browse Source 
Affected files:
0 Journal/0 Daily/2026-01-07.md
This commit is contained in:
Obsidian-MBPM4
2026-01-13 15:23:47 +01:00
parent 1c884f5a4b
commit 99468cf03c
1 changed files with 164 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
0 Journal/0 Daily/2026-01-07.md
View File

@@ -208,4 +208,167 @@ Structure:
- The Battery Manager module shall initialize into a safe state where missing/invalid data results in conservative warnings rather than optimistic “OK”.
- The Battery Manager module shall rate-limit error reporting to avoid log flooding during repeated comms failures.
- The Battery Manager module shall bound its CPU usage and bus transaction rate to avoid starving higher priority real-time control tasks.
- The Battery Manager module shall ensure thread-safe access to shared state if multiple drivers/sources update concurrently.
- The Battery Manager module shall ensure thread-safe access to shared state if multiple drivers/sources update concurrently.
---
# **Upper PDB Driver Formalized Requirements (EARS)**
This document captures formal requirements for the Upper Power Distribution Board (PDB) software module and its associated sensor drivers using the Easy Approach to Requirements Syntax (EARS).  Citations from the Texas Instruments datasheets justify the origin of the requirements.
## **HDC2010 Driver Requirements**
- **Ubiquitous – configurable measurement mode:**  The HDC2010 driver shall allow the Upper PDB Manager to set the measurement resolution and measurement mode via the HDC2010 Measurement Configuration register (0x0E), enabling the application to select 14‑, 11‑ or 9‑bit conversion and continuous or one‑shot acquisition as described in the register map.
- **Event‑driven – data ready:**  When the Data Ready (DRDY_STATUS) bit in the Interrupt/DRDY register is asserted, the HDC2010 driver shall read the Temperature (0x00/0x01) and Humidity (0x02/0x03) registers, convert the raw 16‑bit values to degrees Celsius and percent relative humidity using the datasheet’s conversion formulas, and clear the interrupt by reading the status register.
- **Optional – calibration offsets:**  Where calibration parameters include temperature or humidity offsets, the HDC2010 driver shall write the provided offset values into the Temperature Offset (0x08) and Humidity Offset (0x09) Adjustment registers and adjust subsequent measurements accordingly.
- **Event‑driven – threshold alerts:**  When any of the high/low threshold bits (TL_STATUS, TH_STATUS, HL_STATUS, HH_STATUS) in the Interrupt register are set, the HDC2010 driver shall read the threshold registers (0x0A–0x0D) to determine which threshold was exceeded and raise a corresponding warning.
- **Event‑driven – self‑test heater:**  When commanded to perform a self‑test or heater cycle, the HDC2010 driver shall enable the integrated heater via the appropriate bit in the configuration register, allow the humidity to drop as specified in the datasheet and then disable the heater.
- **State‑driven – polling:**  While operating in polling mode, the HDC2010 driver shall sample temperature and humidity at the configured interval.  If no valid measurement is received within the configured timeout, the driver shall mark the measurement as invalid and publish an error.
- **Ubiquitous – soft reset:**  The HDC2010 driver shall provide a soft reset capability via the Soft Reset register (0x0F) to recover from bus errors or sensor lock‑ups.
- **Optional – interrupt configuration:**  Where interrupts are enabled, the HDC2010 driver shall configure the Interrupt/DRDY Configuration register (0x07) to enable or disable data‑ready and threshold interrupts and set the interrupt polarity and mode bits according to the application requirements.
## **BQ76942 Driver Requirements**
- **Ubiquitous – configurable sampling rate:**  The BQ76942 driver shall initialize the analog front‑end (AFE) with measurement loop speed parameters defined in the configuration file.  It shall set the FASTADC and LOOP_SLOW bits to adjust the slot time (3 ms or 1.5 ms) and the overall loop cycle (45 ms, 90 ms, 180 ms or 360 ms).
- **Ubiquitous – current unit scaling:**  The BQ76942 driver shall configure the user‑defined current units via the USER_AMPS bits so that coulomb counter readings are represented in 0.1 mA, 1 mA, 10 mA or 100 mA units as required.
- **Ubiquitous – cell voltage acquisition:**  The BQ76942 driver shall read each differential cell voltage using the 16‑bit commands 0x14/0x15 through 0x26/0x27, convert the results to millivolts and publish the array of cell voltages.  The driver shall compute and publish the minimum cell voltage, maximum cell voltage and their associated cell indices.
- **Ubiquitous – pack and stack voltage:**  The BQ76942 driver shall read the stack (VC10) voltage, pack voltage and LD pin voltage using commands 0x34/0x35, 0x36/0x37 and 0x38/0x39 and convert these measurements to volts for publication.
- **Event‑driven – scan completion:**  When the voltage measurement loop completes (FULLSCAN bit) or a single ADC scan completes (ADSCAN bit) in Alarm Raw Status, the BQ76942 driver shall update the voltage and temperature values and publish them.
- **Ubiquitous – current measurement:**  The BQ76942 driver shall read the CC2 Current measurement (0x3A) at the configured polling interval, apply the configured USER_AMPS scaling and report the instantaneous pack current.  Where averaged current is required, the driver shall also read CC3 from the DASTATUS subcommands and report the average.
- **Optional – integrated charge:**  Where discharged capacity must be tracked, the BQ76942 driver shall read the integrated passed charge from DASTATUS6 and convert it to mAh using the userAmps scaling.
- **Ubiquitous – temperature sensing:**  The BQ76942 driver shall read internal die temperature and external thermistor temperatures from the measurement loop and convert them to degrees Celsius.  It shall identify and publish the maximum and minimum temperatures across internal, cell and MOSFET sensors.
- **Ubiquitous – FET status:**  The BQ76942 driver shall read the FET Status command (0x7F) and report whether the discharge and charge FETs are enabled or disabled.
- **Event‑driven – FET faults:**  When the FET Status indicates that a FET is disabled due to a fault (for example, XDSG or XCHG bits set), the driver shall publish a fault message and may attempt to re‑enable the FETs by issuing ALL_FETS_ON() after the fault condition has cleared.
- **Event‑driven – safety alerts:**  When safety alert or safety status bits in the Safety Alert A/B/C (0x02, 0x04, 0x06) or Safety Status A/B/C (0x03, 0x05, 0x07) commands indicate overcurrent, overvoltage, undervoltage or temperature fault conditions, the BQ76942 driver shall collect the fault bitmask, identify the fault type and publish a warning or error message.
- **Event‑driven – cell imbalance:**  When a cell imbalance or cell over/undervoltage fault is detected, the BQ76942 driver shall compare all cell voltage measurements to determine the cell with the minimum and maximum voltage and include these indices in the fault message.
- **Optional – cell balancing status:**  Where cell balancing is enabled, the BQ76942 driver shall read the cell balancing status bit (CB) from the Alarm Raw Status register and any additional cell balancing registers, publish a bitmask indicating which cells are being balanced and report the number of cells balancing.
- **Ubiquitous – FET control:**  The BQ76942 driver shall expose commands to enable or disable the charge and discharge FETs (e.g., FET_CONTROL, ALL_FETS_OFF and ALL_FETS_ON).  The driver shall honour manual commands from higher layers while ensuring that protection conditions do not prevent re‑enablement.
- **State‑driven – stale data:**  If a measurement loop or current polling cycle does not complete within the configured timeout, the BQ76942 driver shall mark the data as stale and refrain from publishing it until fresh data is obtained.
- **Event‑driven – alert handling:**  When an ALERT interrupt is asserted by the AFE, the BQ76942 driver shall read the Alarm Status register (0x62), process the cause of the interrupt and clear latched alarm bits by writing back to the Alarm Status register as described in the datasheet.
## **BQ34Z100 Driver Requirements**
- **Ubiquitous – initialization:**  The BQ34Z100 driver shall initialize the fuel gauge using configuration parameters provided by the Upper PDB Manager, including design capacity, chemID and scaling factors.  It shall ensure the device is in the correct access mode (SEALED or UNSEALED) for reading or writing configuration.
- **Ubiquitous – state of charge:**  The BQ34Z100 driver shall read the StateOfCharge() command (0x02) to obtain the predicted remaining battery capacity expressed as a percentage of the full charge capacity.
- **Ubiquitous – remaining capacity:**  The BQ34Z100 driver shall read RemainingCapacity() (0x04/0x05), multiply the value by CurrScale() (0x21) when greater than one and report the remaining capacity in milliampere‑hours.
- **Ubiquitous – full charge capacity:**  The driver shall read FullChargeCapacity() (0x06/0x07), apply CurrScale() if necessary and report the compensated full charge capacity.
- **Ubiquitous – pack voltage:**  The driver shall read Voltage() (0x08/0x09), multiply by VoltScale() (0x20) if the scale is greater than one and report the pack voltage in millivolts.
- **Ubiquitous – instantaneous current:**  The driver shall read Current() (0x10/0x11) to obtain the instantaneous current through the sense resistor; if CurrScale() is greater than one, the value shall be multiplied accordingly.
- **Ubiquitous – average current:**  The driver shall read AverageCurrent() (0x0A/0x0B) to obtain the average current updated every second and scale it using CurrScale().
- **Optional – discharged capacity:**  Where discharged capacity since reset is required, the driver shall read PassedCharge() (0x1C/0x1D) and convert the value to milliampere‑hours.
- **Ubiquitous – time to empty:**  The driver shall read AverageTimeToEmpty() (0x18/0x19) to provide the predicted remaining discharge time in minutes.
- **Ubiquitous – time to full:**  The driver shall read AverageTimeToFull() (0x1A/0x1B) to provide the predicted time until the battery reaches full charge.
- **Ubiquitous – state of health:**  The driver shall read StateOfHealth() (0x2E/0x2F) to report the battery’s health as a percentage of the ratio of the predicted full charge capacity at 25 °C to the design capacity.
- **Ubiquitous – maximum error:**  The driver shall read MaxError() (0x03) and report the expected margin of error in the state‑of‑charge estimation.
- **Ubiquitous – cycle count:**  The driver shall read CycleCount() (0x2C/0x2D) to provide the number of battery cycles experienced.
- **Ubiquitous – design capacity:**  The driver shall read DesignCapacity() (0x3C/0x3D) to obtain the nominal design capacity in milliampere‑hours.
- **Ubiquitous – average power:**  The driver shall read AveragePower() (0x26/0x27), convert the centi‑Watt reading to milliwatts by multiplying by 10, and report the average power consumption.
- **Ubiquitous – available energy:**  The driver shall read AvailableEnergy() (0x24/0x25) to determine the remaining energy in centi‑watt‑hours, convert it to kilowatt‑hours and report it.  The driver shall compute the design energy by multiplying the design capacity and nominal voltage and convert the result to kilowatt‑hours.
- **Event‑driven – flags reporting:**  When Flags() (0x0E/0x0F) or FlagsB() (0x12/0x13) report overtemperature, battery‑high or battery‑low conditions or other status bits, the driver shall assemble a fault bitmask and publish it.
- **Optional – identity:**  Where manufacturer name, serial number, pack name or chemistry are stored in data flash or extended commands, the driver shall read and publish these identifiers for logging and traceability.
- **State‑driven – stale data:**  If polling fails or data remains stale beyond the configured timeout, the BQ34Z100 driver shall mark the data invalid and refrain from publishing it until fresh data is obtained.
## **Upper PDB Manager Requirements**
- **Ubiquitous – configuration propagation:**  The Upper PDB Manager shall be initialized using a configuration file that specifies driver settings, polling intervals and messaging endpoints.  During initialization it shall propagate the relevant configuration to the HDC2010, BQ76942 and BQ34Z100 drivers.
- **State‑driven – scheduled polling:**  While running, the module shall schedule polling of each driver at the configured intervals and assemble the resulting measurements into fast, detailed, temperature and configuration message types.  It shall publish these messages over MQTT, ZMQ and/or Chirp according to the configuration.
- **Ubiquitous – shared I²C access:**  The module shall use a shared I²C handler for all drivers and coordinate access to prevent concurrent transactions, implementing mutual exclusion to avoid bus contention.
- **Event‑driven – configuration publication:**  After initialization and configuration of each sensor, the module shall poll the configuration registers once, package the configuration into a message and publish it.
- **Event‑driven – fault escalation:**  When any fault is reported by the BQ76942 or BQ34Z100 drivers, the module shall poll additional diagnostic registers, determine the fault cause and publish warning and error messages, escalating to higher‑level systems as required.
- **State‑driven – timestamping and stale detection:**  The module shall associate a timestamp with every measurement.  If a measurement is not updated within a configurable timeout (default two seconds), the module shall mark the measurement as invalid and avoid using stale data.
- **State‑driven – bounds checking:**  For each battery instance, the module shall validate incoming measurements against configurable physical bounds (voltage, current and temperature).  If a measurement violates a bound, the module shall reject the sample, mark it invalid and increment an error counter for that instance.
- **State‑driven – health state:**  The module shall maintain a health state per battery instance (e.g., OK, degraded, failed) derived from measurement validity and driver communication status.  The health state updates shall be deterministic for identical input streams and parameter sets.
- **Event‑driven – connection events:**  When communication with a battery data source is established or restored, the module shall mark the battery instance as connected and resume publishing valid status.  When communication is lost for longer than the stale timeout, the module shall mark the instance as failed and publish status indicating loss of data.  After a configurable number of consecutive valid updates, the module shall clear the failed state.
- **Event‑driven – threshold warnings:**  When remaining capacity or pack voltage crosses configurable low, critical or emergency thresholds, the module shall set and publish the corresponding warning level for that instance.
- **Event‑driven – over‑current detection:**  When the instantaneous or average current exceeds a configured maximum for longer than a configured duration, the module shall set an over‑current warning or fault for that instance.
- **Event‑driven – temperature limits:**  When internal, cell or MOSFET temperature measurements exceed configured high limits or fall below low limits, the module shall set the corresponding temperature warning or fault.
- **Event‑driven – per‑cell voltage limits:**  When any cell voltage exceeds configured per‑cell minimum or maximum limits, the module shall set a cell voltage warning or fault and identify the affected cell index (as reported by the BQ76942 driver).
- **Ubiquitous – state of health and cycle count:**  If the BMS provides state‑of‑health and cycle count, the module shall publish these values for each battery instance.
- **Ubiquitous – identity information:**  If the BMS provides manufacturer name, serial number, pack name or chemistry, the module shall publish and log these identifiers.
- **Unwanted – no invalid validity:**  The module shall not mark a battery instance as valid when the underlying measurement stream is stale, uninitialized or failing validation.
- **Unwanted – unit consistency:**  The module shall not publish values with inconsistent units or scaling relative to the configured source.
- **Unwanted – warning oscillation:**  The module shall not oscillate warning states due to measurement noise; it shall apply hysteresis or time filtering when evaluating thresholds.
- **Unwanted – silent failure:**  The module shall not fail silently; persistent faults shall be surfaced through status flags and logged events.
- **Ubiquitous – logging:**  The module shall log battery status, warnings and faults at rates compatible with flight log analysis.
- **Ubiquitous – telemetry support:**  Where telemetry is enabled, the module shall provide battery data needed for telemetry reporting to a ground station, including voltage, current, remaining capacity and warning levels.
- **Ubiquitous – safe initialization:**  The module shall initialize into a safe state where missing or invalid data results in conservative warnings rather than an optimistic “OK” state.
- **Ubiquitous – error rate limiting:**  The module shall rate‑limit error reporting to avoid log flooding during repeated communication failures.
- **Ubiquitous – resource bounds:**  The module shall bound its CPU usage and I²C transaction rate to avoid starving higher‑priority real‑time control tasks.
- **Ubiquitous – thread safety:**  The module shall ensure thread‑safe access to shared state when multiple drivers or tasks update concurrently.
- **Ubiquitous – determinism:**  The module shall behave deterministically for identical input streams and parameter sets.