# pekaway/esp32-ble-wifi-shunt architecture

> Architecture diagram of the GitHub repository pekaway/esp32-ble-wifi-shunt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pekaway/esp32-ble-wifi-shunt
- Repository: https://github.com/pekaway/esp32-ble-wifi-shunt

## Overview

This repository is an ESP32-C3 battery-shunt monitor: it measures current and voltage, tracks battery state of charge (SOC), and exposes readings and settings over BLE. The main workflow is sensor measurement, SOC/state handling, persistence, then BLE access by a phone or Python clients. The INA library and Python scripts are sampled; the firmware sketch is present in the tree but was not excerpted, so firmware relationships below rely on the README rather than inspected calls. Node-RED and other peripheral files are not mapped because their runtime roles are not documented in the supplied evidence.

Main entry points: [`Esp32c3_Shunt_BLE_0.2/Esp32c3_Shunt_BLE_0.2.ino`](https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/Esp32c3_Shunt_BLE_0.2/Esp32c3_Shunt_BLE_0.2.ino) (ESP32-C3 firmware), [`INA-master_lib/src/INA.cpp`](https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/INA-master_lib/src/INA.cpp) (INA sensor library), [`python read out/READesp32shunt.py`](https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/python%20read%20out/READesp32shunt.py) (Python readings client), [`python read out/SETesp32shunt.py`](https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/python%20read%20out/SETesp32shunt.py) (Python settings client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_measurement["Measurement"]
  node_ina["INA sensor library<br/>[INA.cpp]"]
end

subgraph group_firmware["Device firmware"]
  node_firmware_app["ESP32-C3 firmware"]
  node_soc["SOC and capacity"]
  node_ble["BLE services"]
  node_spiffs[("SOC persistence")]
end

subgraph group_clients["BLE clients"]
  node_python_reader["Python readings client<br/>[READesp32shunt.py]"]
  node_python_setter["Python settings client<br/>[SETesp32shunt.py]"]
end

node_shunt["Battery shunt"]
node_operator(("Device operator"))

node_shunt -->|"senses current"| node_ina
node_ina -.->|"provides measurements"| node_firmware_app
node_firmware_app -->|"tracks SOC"| node_soc
node_firmware_app -->|"exposes readings"| node_ble
node_firmware_app -->|"stores SOC"| node_spiffs
node_python_reader -->|"reads values"| node_ble
node_python_setter -->|"writes settings"| node_ble
node_operator -->|"requests readings"| node_python_reader
node_operator -->|"sets capacity"| node_python_setter

click node_ina "https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/INA-master_lib/src/INA.cpp"
click node_firmware_app "https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/Esp32c3_Shunt_BLE_0.2/Esp32c3_Shunt_BLE_0.2.ino"
click node_soc "https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/Esp32c3_Shunt_BLE_0.2/Esp32c3_Shunt_BLE_0.2.ino"
click node_ble "https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/Esp32c3_Shunt_BLE_0.2/Esp32c3_Shunt_BLE_0.2.ino"
click node_spiffs "https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/Esp32c3_Shunt_BLE_0.2/Esp32c3_Shunt_BLE_0.2.ino"
click node_python_reader "https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/python%20read%20out/READesp32shunt.py"
click node_python_setter "https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/python%20read%20out/SETesp32shunt.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ina toneBlue
class node_firmware_app,node_soc,node_ble,node_spiffs toneAmber
class node_python_reader,node_python_setter toneMint
class node_shunt,node_operator toneIndigo
```

## Components

### Measurement

- [INA sensor library](https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/INA-master_lib/src/INA.cpp): `INA-master_lib/src/INA.cpp`

### Device firmware

- [ESP32-C3 firmware](https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/Esp32c3_Shunt_BLE_0.2/Esp32c3_Shunt_BLE_0.2.ino): `Esp32c3_Shunt_BLE_0.2/Esp32c3_Shunt_BLE_0.2.ino`
- [SOC and capacity](https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/Esp32c3_Shunt_BLE_0.2/Esp32c3_Shunt_BLE_0.2.ino): `Esp32c3_Shunt_BLE_0.2/Esp32c3_Shunt_BLE_0.2.ino`
- [BLE services](https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/Esp32c3_Shunt_BLE_0.2/Esp32c3_Shunt_BLE_0.2.ino): `Esp32c3_Shunt_BLE_0.2/Esp32c3_Shunt_BLE_0.2.ino`
- [SOC persistence](https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/Esp32c3_Shunt_BLE_0.2/Esp32c3_Shunt_BLE_0.2.ino): `Esp32c3_Shunt_BLE_0.2/Esp32c3_Shunt_BLE_0.2.ino`

### BLE clients

- [Python readings client](https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/python%20read%20out/READesp32shunt.py): `python read out/READesp32shunt.py`
- [Python settings client](https://github.com/pekaway/esp32-ble-wifi-shunt/blob/main/python%20read%20out/SETesp32shunt.py): `python read out/SETesp32shunt.py`

### Other components

- **Battery shunt**
- **Device operator**

## Connections

- Battery shunt → INA sensor library: senses current (evidence: `readme.md`)
- INA sensor library → ESP32-C3 firmware: provides measurements
- ESP32-C3 firmware → SOC and capacity: tracks SOC (evidence: `readme.md`)
- ESP32-C3 firmware → BLE services: exposes readings (evidence: `readme.md`)
- ESP32-C3 firmware → SOC persistence: stores SOC (evidence: `readme.md`)
- Python readings client → BLE services: reads values (evidence: `python read out/READesp32shunt.py`)
- Python settings client → BLE services: writes settings (evidence: `python read out/SETesp32shunt.py`)
- Device operator → Python readings client: requests readings (evidence: `readme.md`)
- Device operator → Python settings client: sets capacity (evidence: `readme.md`)