# Modular BMS

A composable Battery Management System built from Adom molecules. Uses the TI BQ76952 battery monitor/protector IC with an MSP430 host MCU, supporting both 18650 cylindrical and EVE LF105 prismatic LiFePO4 cell carriers.

## System Architecture

The Modular BMS is composed of the following molecules:

| Molecule | Purpose |
|----------|---------|
| [molecule-bq76952-v2](https://wiki.adom.inc/adom/molecule-bq76952-v2) | BMS brain — BQ76952 monitor, FET control, cell balancing, protection |
| [molecule-18650-battery](https://wiki.adom.inc/adom/molecule-18650-battery) | Dual 18650 cylindrical cell carrier (Keystone 54 holders) |
| [molecule-18650-jumper](https://wiki.adom.inc/adom/molecule-18650-jumper) | Series interconnect between 18650 carriers |
| [molecule-eve-lf105-prismatic](https://wiki.adom.inc/adom/molecule-eve-lf105-prismatic) | EVE LF105 105Ah prismatic LiFePO4 cell carrier |

## Requirements

- Minimum 3 cells in series
- MSP430F5529LP eval board (for SBW programming)
- BQ76952EVM or the BQ76952 BMS Molecule v2

## Firmware

The MSP430 firmware lives in `PlatformIO/MSP430_BQ76952/` and provides:

- I2C communication with the BQ76952 (UCB1: P4.4=SCL, P4.5=SDA)
- UART telemetry output (UCA1: P4.2=RX, P4.3=TX) in human-readable or JSON format
- Periodic cell voltage, current, and temperature readings
- CHG/DSG FET control via GPIO buttons (P3.3=DSG, P3.4=CHG)
- Full protection monitoring (OV, UV, OCD, SCD, PF)
- Configurable n-cell mode via `VCellMode`

### Build & Flash

```sh
# Install PlatformIO, conda with Python 2.7 for MSP430 toolchain
conda create -n py27 python=2.7
conda activate py27
export LD_LIBRARY_PATH="/root/miniconda3/pkgs/python-2.7.18-h42bf7aa_3/lib:$LD_LIBRARY_PATH"

# Build and upload
pio run -t upload
```

### Cell Count Configuration

Default is 3S. To change, edit in `main_MSP430FR2355_I2C.cpp`:

```c
#define NUM_CELLS 3
#define NUM_CELLS_BITS 0x0007   // enable Cell1..Cell3
```

### Output Modes

```c
set_output_mode(OUTPUT_HUMAN);  // readable console logs
set_output_mode(OUTPUT_JSON);   // Hydrogen-style JSON notifications
```

## Notes

- To reset the system, power cycle the MSP EZ-FET Lite molecule
- If the BQ76952 is stuck, pull RST_SHUT high (or to REG1)
- PACK pin voltage reads ~0V when FETs are open (normal)
- Current is signed — cast CC2Current to int16_t

## Source

- GitHub: [adom-inc/Modular_BMS](https://github.com/adom-inc/Modular_BMS)