# green-bms/smartbms architecture

> Architecture diagram of the GitHub repository green-bms/smartbms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/green-bms/smartbms
- Repository: https://github.com/green-bms/smartbms

## Overview

##### Project type and purpose
- This is an open-source, hardware-software Battery Management System (BMS) for Li-ion/LiFePO4 packs.
- It combines multiple PCB modules (Cell Module, Interface Board, Limiter), embedded firmware (Attiny, Arduino Mega) and a mobile UI (Android app).

##### File structure
- Top‐level directories:
– 01_Documentation: datasheets, KiCad libraries
– 02_Cell Module: KiCad hardware + Attiny Arduino code
– 03_Control Unit: Arduino Mega firmware
– 04_Interface board: KiCad hardware for bus connection to Mega
– 05_Control Unit case: mechanical CAD
– 06_Android app: MIT App Inventor project
– 07_Limiter: QElectroTech schematic for power-relay circuit
- Pattern:
– Multiple small embedded-sensor modules (02_Cell Module)
– A central “brain” (03_Control Unit)
– A power-relay stage (07_Limiter)
– A physical connection board (04_Interface board)
– A user-interface mobile app (06_Android app)

##### Extract architectural insights from README
- The Cell Modules measure voltage & temperature and speak I2C to the Control Unit.
- The Control Unit (Arduino Mega) aggregates cell data, drives the Limiter (charging/discharging relays), and speaks Bluetooth to the Android app.
- Limiter contains the main charging relay plus current-limit circuitry.
- Interface board PCB hosts sockets/headers to plug all Cell Modules and the Mega together on the same I2C bus.

##### Main components & their interactions
a. Components
- Cell Modules (Attiny-based PCBs, one per cell)
- I2C Bus (shared serial data line)
- Interface Board (PCB backplane with sockets for Cell Mods + headers to Mega)
- Control Unit (Arduino Mega + Bluetooth module)
- Limiter Board (power relay + current-limit circuit)
- Android App (MIT App Inventor)
- Battery pack (Li-ion/LiFePO4 cells)
b. Relationships / Data Flows
- Each Cell Module → measures cell voltage/temperature → sends readings over I2C → to Control Unit.
- Control Unit → sends balance commands (via I2C) back to Cell Modules.
- Control Unit → drives Limiter relay/coils via digital I/O → to open/close charging/discharging paths.
- Control Unit → current-limit command to Limiter when balancing.
- Control Unit ←→ Bluetooth serial link ←→ Android App (status & settings).
- All Cell Modules and Control Unit share Vcc/GND on the Interface Board.
c. Architectural patterns
- Master/slave multi-drop I2C network
- Distributed sensing/actuation (one Attiny per cell)
- Central orchestration (Arduino Mega)
- Event-driven control loops (charging, discharging, balancing)
- Mobile UI over Bluetooth serial
d. Key technologies
- KiCad (PCB design for Cell Module & Interface Board)
- QElectroTech (Limiter schematic)
- Arduino IDE (C/C++ firmware for Attiny & Mega)
- MIT App Inventor (Android .aia project)
- Bluetooth module (e.g., HC-05)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Sensing Modules"
        CellMod["n × Cell Module (Attiny85, KiCad PCB)"]:::sensing
    end
    I2CBus["I2C Bus: SDA/SCL, Vcc, GND"]:::bus
    InterfaceBoard["Interface Board (KiCad PCB Backplane)"]:::interconnect
    ControlUnit["Control Unit (Arduino Mega, Bluetooth HC-05)"]:::control
    Limiter["Limiter Board (Power Relay & Current-Limit)"]:::power
    Battery["Battery Pack (Li-ion/LiFePO4 cells)"]:::power
    AndroidApp["Android App (MIT App Inventor)"]:::ui
    Doc["Documentation & Libraries"]:::docs

    CellMod -->|"I2C readings"| I2CBus
    ControlUnit -->|"balance cmd (I2C)"| I2CBus
    I2CBus -->|"pass-through"| InterfaceBoard
    InterfaceBoard -->|"connects"| ControlUnit
    ControlUnit -.->|"Bluetooth serial"| AndroidApp
    ControlUnit -.->|"drive relay (DIO)"| Limiter
    Limiter -->|"switched power"| Battery

    click CellMod "https://github.com/green-bms/smartbms/tree/master/02_Cell Module/Hardware/Kikad_mod_cell_0_02"
    click CellMod "https://github.com/green-bms/smartbms/blob/master/02_Cell Module/Software/Attiny_Cell_mod_1_6/Cell_mod_1_6.ino"
    click CellMod "https://github.com/green-bms/smartbms/blob/master/02_Cell Module/Software/Attiny_Cell_mod_1_6/functions_4.h"
    click I2CBus "https://github.com/green-bms/smartbms/blob/master/02_Cell Module/Software/Attiny_Cell_mod_1_6/TinyWireS.zip"
    click InterfaceBoard "https://github.com/green-bms/smartbms/blob/master/04_Interface board/Hardware/Kikad_Interface_board_1/Interface_board_1.kicad_pcb"
    click InterfaceBoard "https://github.com/green-bms/smartbms/tree/master/04_Interface board/Hardware/Kikad_Interface_board_1/gerber"
    click InterfaceBoard "https://github.com/green-bms/smartbms/blob/master/04_Interface board/Hardware/Kikad_Interface_board_1/Socket_Arduino_Mega.3dshapes"
    click InterfaceBoard "https://github.com/green-bms/smartbms/blob/master/04_Interface board/Hardware/Kikad_Interface_board_1/Green_bms_library.pretty"
    click ControlUnit "https://github.com/green-bms/smartbms/blob/master/03_Control Unit/Software/Mega_Control_Unit_2_1/Control_Unit_2_1.ino"
    click ControlUnit "https://github.com/green-bms/smartbms/blob/master/03_Control Unit/Software/Mega_Control_Unit_2_1/functions_4.h"
    click ControlUnit "https://github.com/green-bms/smartbms/blob/master/05_Control Unit case/Librecad_box_lcu_0_0/box_lcu_0_0.dxf"
    click Limiter "https://github.com/green-bms/smartbms/blob/master/07_Limiter/QElectroTech_Limiter_0/limiter_0.qet"
    click Limiter "https://github.com/green-bms/smartbms/blob/master/07_Limiter/QElectroTech_Limiter_0/pdf/limiter_0.pdf"
    click AndroidApp "https://github.com/green-bms/smartbms/blob/master/06_Android app/App_inventor_Green_bms_0_0/Green_bms_0_0.aia"
    click Doc "https://github.com/green-bms/smartbms/tree/master/01_Documentation/Drawings"
    click Doc "https://github.com/green-bms/smartbms/tree/master/01_Documentation/Kikad additional libreries"

    classDef sensing fill:#E0F7FA,stroke:#006064,color:#006064
    classDef bus fill:#CFD8DC,stroke:#455A64,color:#455A64
    classDef interconnect fill:#ECEFF1,stroke:#90A4AE,color:#90A4AE
    classDef control fill:#E8F5E9,stroke:#388E3C,color:#388E3C
    classDef power fill:#FFF3E0,stroke:#F57C00,color:#E65100
    classDef ui fill:#FFF9C4,stroke:#F9A825,color:#F57F17
    classDef docs fill:#ECEFF1,stroke:#757575,color:#424242
```
