# dalathegreat/battery-emulator architecture

> Architecture diagram of the GitHub repository dalathegreat/battery-emulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dalathegreat/battery-emulator
- Repository: https://github.com/dalathegreat/battery-emulator

## Overview

##### Project Type and Purpose
- This is an embedded IoT/firmware project running on an ESP32‐based devboard (LilyGo T-CAN485).
- Its purpose is to read CAN-bus signals from a large EV battery pack, translate them into a solar-inverter-compatible protocol (Modbus over RS485), and manage associated hardware (contactors, pre-charge circuits), plus provide local web/UI, logging, safety and OTA.

##### High-Level File-Structure Analysis
- Top-level: PlatformIO/CMake build files, .ino entry point, global settings (`USER_SETTINGS.h`, `system_settings.h`).
- `Software/src/…` is subdivided into:
- battery (per-battery-type implementations inheriting a common interface)
- charger (charger abstractions)
- inverter (per-inverter protocol modules)
- communication (drivers/interfaces for CAN, RS485/Modbus, contactor control, NVM, pre-charge control, stop button)
- datalayer (unified in-memory model bridging vehicle data to emulator logic)
- devboard (HAL and board-specific services: GPIO, SD card, Wi-Fi, MQTT, webserver, safety, timers, logging)
- `Software/src/lib` holds third-party libraries (ArduinoJson, AsyncTCP/WebServer, eModbus, CAN drivers, etc.).
- `test/…` contains unit tests.

##### Key Architectural Insights from README
- EV‐battery CAN ↔ ESP32 (CommCAN) → DataLayer → ProtocolTranslator (Inverter emulator) → RS485 Modbus (CommRS485) ↔ Solar inverter.
- HAL abstracts hardware (GPIO, timers, interrupts, SD card).
- Webserver + Wi-Fi + MQTT provide configuration & telemetry.
- Safety & contactor control modules manage high‐voltage circuitry.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "External Systems"
        direction TB
        Battery["EV Battery Pack\n(CAN bus)"]:::external
        Inverter["Solar Inverter\n(Modbus RTU)"]:::external
    end

    %% Firmware Entry & Config
    EntryPoint["Application Core\n(Software.ino)"]:::core
    click EntryPoint "https://github.com/dalathegreat/battery-emulator/blob/main/Software/Software.ino"
    Settings["Global Settings\n(USER_SETTINGS.h, USER_SECRETS.TEMPLATE.h,\nsystem_settings.h)"]:::core
    click Settings "https://github.com/dalathegreat/battery-emulator/blob/main/Software/USER_SETTINGS.h"
    click Settings "https://github.com/dalathegreat/battery-emulator/blob/main/Software/USER_SECRETS.TEMPLATE.h"
    click Settings "https://github.com/dalathegreat/battery-emulator/blob/main/system_settings.h"

    %% HAL & Drivers Layer
    subgraph "HAL & Drivers" 
        direction TB
        HAL["HAL Interfaces\n(hal.h)"]:::hardware
        click HAL "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/devboard/hal/hal.h"
        HW1["Board HAL\n(hw_lilygo.h, hw_devkit.h,\nhw_3LB.h, hw_stark.h)"]:::hardware
        click HW1 "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/devboard/hal/hw_lilygo.h"
        CommCAN["Comm_CAN Driver"]:::hardware
        click CommCAN "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/communication/can/comm_can.h"
        CommRS485["Comm_RS485 Driver"]:::hardware
        click CommRS485 "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/communication/rs485/comm_rs485.h"
        Contactor["Contactor Control"]:::hardware
        click Contactor "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/communication/contactorcontrol/comm_contactorcontrol.h"
        Precharge["Pre-charge Control"]:::hardware
        click Precharge "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/communication/precharge_control/precharge_control.h"
        StopBtn["Stop Button Input"]:::hardware
        click StopBtn "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/communication/equipmentstopbutton/comm_equipmentstopbutton.h"
        NVM["NVM Storage"]:::storage
        click NVM "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/communication/nvm/comm_nvm.h"
        Timers["Timers & Interrupts"]:::hardware
        click Timers "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/devboard/utils/timer.h"
    end

    %% Data Layer
    subgraph "Data Model & Domain" 
        direction TB
        DataLayer["DataLayer Core"]:::data
        click DataLayer "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/datalayer/datalayer.h"
        DataExt["DataLayer Extended"]:::data
        click DataExt "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/datalayer/datalayer_extended.h"
        BatteryAdapters["Battery Adapters\n(factory)"]:::data
        click BatteryAdapters "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/battery/BATTERIES.h"
        ChargerAdapters["Charger Adapters"]:::data
        click ChargerAdapters "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/charger/CHARGERS.h"
        InverterAdapters["Inverter Adapters"]:::data
        click InverterAdapters "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/inverter/INVERTERS.h"
    end

    %% Services & UI
    subgraph "Services & UI" 
        direction TB
        Safety["Safety Monitor"]:::service
        click Safety "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/devboard/safety/safety.h"
        SDCard["SD Card Logging"]:::service
        click SDCard "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/devboard/sdcard/sdcard.h"
        MQTT["MQTT Client"]:::service
        click MQTT "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/devboard/mqtt/mqtt.h"
        Webserver["Webserver & HTTP UI"]:::service
        click Webserver "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/devboard/webserver/webserver.h"
        WiFi["Wi-Fi Connectivity"]:::service
        click WiFi "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/devboard/wifi/wifi.h"
        OTA["OTA Update"]:::service
        click OTA "https://github.com/dalathegreat/battery-emulator/blob/main/Software/src/lib/ayushsharma82-ElegantOTA/src/ElegantOTA.h"
    end

    %% Connections
    Battery -->|CAN 500 kbps| CommCAN
    CommCAN -->|"parsed frames"| DataLayer
    DataLayer --> DataExt
    DataExt -->|standard state| BatteryAdapters
    DataExt -->|standard state| ChargerAdapters
    DataExt -->|standard state| InverterAdapters
    InverterAdapters -->|Modbus frames| CommRS485
    CommRS485 -->|RS485| Inverter

    Timers -->|periodic triggers| EntryPoint
    HAL --> EntryPoint
    HW1 --> EntryPoint
    NVM --> EntryPoint

    EntryPoint --> DataLayer
    EntryPoint --> BatteryAdapters
    EntryPoint --> ChargerAdapters
    EntryPoint --> InverterAdapters

    EntryPoint --> Safety
    EntryPoint --> SDCard
    EntryPoint --> MQTT
    EntryPoint --> Webserver
    EntryPoint --> WiFi
    EntryPoint --> OTA

    Webserver -->|HTTP/JSON| EntryPoint
    MQTT -->|MQTT msgs| EntryPoint

    %% Styles
    classDef external fill:#ddd,stroke:#888,stroke-width:1px
    classDef hardware fill:#cce5ff,stroke:#6593f5,stroke-width:1px
    classDef data fill:#d4edda,stroke:#28a745,stroke-width:1px
    classDef service fill:#ffe5b4,stroke:#ff9800,stroke-width:1px
    classDef storage fill:#e2d8f9,stroke:#8e44ad,stroke-width:1px
    classDef core fill:#f0f0f0,stroke:#666,stroke-width:1px
```
