KXKM Batterie Parallelator

Battery Management Unit for parallel 24-30V packs
Up to 32 batteries · ESP32-S3 · BLE + MQTT + InfluxDB · iOS companion app

Overview

The KXKM Batterie Parallelator is an embedded Battery Management Unit (BMU) that safely parallels multiple battery packs (24-30V) for off-grid stage installations. Each battery is individually monitored (voltage, current, temperature) and can be disconnected in microseconds via MOSFET switches.

Built by L'Electron Rare for KompleX KapharnaüM (Villeurbanne, France) — a live arts company deploying digital scenography in public spaces without grid power.

Key Features

Feature	Description
Per-battery protection	Under/over-voltage, over-current, imbalance detection
Auto-reconnection	Exponential backoff with permanent lock after 5 faults
Soft-balancing	Duty-cycling with opportunistic R_int measurement
Victron integration	BLE Instant Readout + GATT SmartShunt emulation + device scanner
Touchscreen UI	320x240 LVGL display with battery grid, SOH, charts
iOS companion app	BLE real-time monitoring, offline cache, role-based access
Cloud telemetry	MQTT + InfluxDB + Grafana with offline persistence
OTA updates	Dual-partition with automatic rollback

Quick Start

# ESP-IDF firmware (production)
cd firmware-idf
source ~/esp/esp-idf/export.sh
idf.py build
idf.py -p /dev/cu.usbmodem* flash monitor

# PlatformIO (legacy Arduino)
pio run -e kxkm-s3-16MB --target upload

# Run all tests (no hardware needed)
pio test -e sim-host          # 13 PlatformIO tests
cd firmware-idf && idf.py build  # 13 ESP-IDF host tests

# Cloud stack (kxkm-ai server)
cd kxkm-api && cp .env.example .env && docker compose up -d

Architecture

                          ┌──────────────────────────┐
                          │    ESP32-S3-BOX-3         │
                          │    320x240 LVGL display   │
                          │    NimBLE + WiFi          │
                          └─────────┬────────────────┘
                                    │ I2C 50kHz
                    ┌───────────────┼───────────────┐
                    │               │               │
              ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
              │ TCA9535    │  │ TCA9535   │  │  ...×8    │
              │ 4× MOSFET  │  │ 4× LED   │  │           │
              └─────┬─────┘  └───────────┘  └───────────┘
                    │
              ┌─────▼─────┐
              │ INA237 ×4  │  ← per TCA (voltage + current)
              └───────────┘

    ┌──────────────────────────────────────────────────────┐
    │                    Cloud Stack                        │
    │  BMU ──MQTT──► Mosquitto ──► Telegraf ──► InfluxDB   │
    │                                              │       │
    │  iPhone ◄──BLE──► BMU    Grafana ◄───────────┘       │
    │  iPhone ◄──REST──► FastAPI ◄─────────────────┘       │
    └──────────────────────────────────────────────────────┘

Firmware Components (ESP-IDF, 25 modules)

Component	Role
`bmu_protection`	State machine: 5 states, 5 criteria, permanent lock
`bmu_balancer`	Soft-balancing duty-cycling + R_int measurement
`bmu_ina237`	16× INA237 power monitors (2mΩ shunt)
`bmu_tca9535`	8× GPIO expanders (switches + LEDs)
`bmu_ble`	NimBLE 4 GATT services + Victron SmartShunt
`bmu_ble_victron`	Victron Instant Readout (AES-CTR encrypted ads)
`bmu_ble_victron_scan`	BLE central scanner for Victron devices
`bmu_display`	LVGL: battery grid, pack info, SOH, charts, swipe
`bmu_influx` + `_store`	InfluxDB client + offline FAT/SD persistence
`bmu_mqtt`	ESP-MQTT with auth credentials
`bmu_vedirect`	Victron VE.Direct UART parser (solar charger)
`bmu_rint`	Internal resistance pulse measurement
`bmu_web`	HTTP + WebSocket with token auth + rate limiting
`bmu_config`	NVS runtime config + Victron device keys
`bmu_storage`	NVS, FAT, SPIFFS, SD card, USB MSC
`bmu_ota`	OTA firmware update with rollback

Protection Logic

Nb_switch < 5   →  Reconnect immediately when condition clears
Nb_switch == 5  →  10-second delay before reconnection
Nb_switch > 5   →  Permanent lock (blinking red LED) until reboot

Threshold	Default	Configurable
Min voltage	24,000 mV	via Kconfig + NVS
Max voltage	30,000 mV	via Kconfig + NVS
Max current	10,000 mA	via Kconfig + NVS
Imbalance	1,000 mV	via Kconfig + NVS
Reconnect delay	10,000 ms	via Kconfig
Switch limit	5	via Kconfig

LED Behavior

State	LED
Connected	Solid green
Disconnected	Solid red
Error	Blinking red (~1 Hz)
Locked	Solid red

iOS Companion App

KXKM BMU — SwiftUI + CoreBluetooth

Feature	Transport
Real-time battery dashboard	BLE (2s poll)
Battery detail + voltage chart	BLE
Switch ON/OFF + reset	BLE (role-gated)
Protection config (0.025V/A step)	BLE
WiFi config for BMU	BLE
Audit trail + filtering	Local SQLDelight
Offline mode with cache indicator	Auto-fallback
SOH dashboard + R_int	BLE + REST
Victron device scanning	BLE passive

3 roles: Admin (full), Technician (control), Viewer (read-only) — PIN + Face ID.

Code: iosApp/ (Xcode, CoreBluetooth) + kxkm-bmu-app/ (KMP Shared Kotlin)

Victron BLE Integration

The BMU interacts with the Victron ecosystem via three mechanisms:

Mechanism	Direction	Protocol
Instant Readout	BMU → VictronConnect	AES-CTR encrypted advertising (PID 0xA389)
GATT SmartShunt	BMU → any BLE client	9 read-only characteristics (V, I, SOC, Ah, TTG, T, alarm)
Device Scanner	Victron devices → BMU	Passive BLE scan, AES decrypt, 8 device cache

Supported Victron record types: Solar (0x01), Battery (0x02), Inverter (0x03), DC-DC (0x04).

Cloud Infrastructure

Docker stack on kxkm-ai server:

Service	Port	Role
Mosquitto	1883, 9001	MQTT broker (authenticated)
InfluxDB 2.7	8086	Time-series storage (org=kxkm, bucket=bmu)
Telegraf	-	MQTT → InfluxDB bridge
FastAPI	8400	REST API (sync, history, audit)
Grafana 11	3001	3 dashboards (live, fleet, solar)

Setup: cp .env.example .env — fill all secrets (API key, InfluxDB token, MQTT credentials, Grafana password, CORS origins). All secrets via ${...} env vars, chmod 600 .env.

Offline resilience: when WiFi/InfluxDB is unreachable, telemetry is persisted to internal FAT flash (/fatfs/influx/) with 2-file rotation (512KB each). Automatic replay on reconnection.

Testing

26 tests total — no hardware required.

PlatformIO sim-host (13 tests)

pio test -e sim-host

Suite	Tests	Covers
`test_protection`	10	V/I/imbalance/lock state machine
`test_battery_route_validation`	-	Index bounds + state checks
`test_influx_buffer_codec`	-	InfluxDB line-protocol encoding
`test_web_mutation_rate_limit`	3	Sliding window + multi-IP
`test_web_route_security`	9	Constant-time token + Bearer
`test_ws_auth_flow`	7	Combined auth + rate limit
`test_mqtt_influx_codec`	3	JSON MQTT + topic parsing
`test_emulation_bench`	-	Emulation benchmark

ESP-IDF Host Tests (13 tests)

cd firmware-idf && idf.py build

Suite	Tests	Covers
`test_protection`	13	Full state machine (ESP-IDF)
`test_victron_gatt`	8	GATT encoding (V, SOC, alarm, TTG, T)
`test_victron_scan`	5	Payload parsing, expiry, MAC, CID
`test_ble_victron`	-	Battery/solar payload encoding
`test_vedirect_parser`	-	VE.Direct frame parsing
`test_rint`	-	R_int calculation
`test_config_labels`	-	Battery label management
`test_vrm_topics`	-	VRM topic generation

CI/CD Pipelines

Pipeline	Trigger	Gate
`ci.yml`	push/PR	sim-host 13 tests pass
`sim-host-tests.yml`	push/PR	+ S3 build + RAM ≤75% + Flash ≤85%
`esp-idf-ci.yml`	push/PR	+ ESP-IDF host tests + flash ≤85% of 2MB OTA

Current flash usage: 81% (1.69 MB / 2 MB OTA partition) — 19% headroom.

Security Audit

All findings resolved as of 2026-04-07.

Phase 1 — Migration (March 2026): 7/7 resolved

ID	Finding	Status
CRIT-001	Obsolete function calls	✅
CRIT-002	Unreliable global Nb_INA	✅
CRIT-003	I2C access without mutex	✅
CRIT-004	Missing mutex init	✅
HIGH-005	WebSocket V/I race	✅
HIGH-006	reconnect_time race	✅
HIGH-007	Uninitialized globals	✅

Phase 2 — Deep audit (March-April 2026): 13/13 resolved

ID	Severity	Finding	Fix
CRIT-A	Critical	mV/V unit mismatch	ESP-IDF: mV everywhere
CRIT-B	Critical	Imbalance vs config instead of fleet max	bmu_protection
CRIT-C	Critical	Deadlock in web switch	bmu_web
CRIT-D	Critical	Unauthenticated routes	bmu_web_security
HIGH-1	High	Negative overcurrent ignored	Bidirectional factor
HIGH-2	High	Unauthenticated WebSocket	Token on first frame
HIGH-3	High	XSS in /log	cJSON null check
HIGH-4	High	MQTT plaintext	Mosquitto auth + .env
HIGH-5	High	I2C speed change unguarded	I2CLockGuard
HIGH-7	High	Public battery_voltages[]	state_mutex
HIGH-8	High	Influx task crash on SD fail	influx_store fallback
MED-1	Medium	No permanent lock (F08)	BMU_STATE_LOCKED
MED-010	Medium	mV/V harmonization	mV throughout

Infrastructure audit (April 2026): 5/5 resolved

Finding	Fix
Mosquitto anonymous access	Auth + password file
Hardcoded secrets in docker-compose	All via .env (chmod 600)
Default InfluxDB token	Rotated (44-char random)
CORS allow_origins=["*"]	Restricted via env var
Offline data loss	FAT/SD persistence + replay

Hardware

PCB Revisions

Version	Status	Files
BMU v1	Manufactured	`hardware/PCB/`
BMU v2	Production-ready (ERC 0, BOM 107)	`hardware/pcb-bmu-v2/`

Key ICs

IC	Package	Role	I2C Address
INA237	VSSOP-10	Power monitor (V/I/P)	0x40-0x4F (16 max)
TCA9535	TSSOP-24	GPIO expander (switches + LEDs)	0x20-0x27 (8 max)
ISO1540	SOIC-8	Galvanic I2C isolator	-
IRF4905	D2PAK	P-channel MOSFET (55V, 74A)	-

I2C Mapping

TCA_0 (0x20) → INA 0x40-0x43 → Batteries 1-4
TCA_1 (0x21) → INA 0x44-0x47 → Batteries 5-8
TCA_2 (0x22) → INA 0x48-0x4B → Batteries 9-12
TCA_3 (0x23) → INA 0x4C-0x4F → Batteries 13-16

Topology constraint: Nb_TCA × 4 == Nb_INA — mismatch triggers fail-safe (all OFF).

Project Structure

KXKM_Batterie_Parallelator/
├── firmware-idf/          # ESP-IDF 5.4 firmware (25 components)
│   ├── components/        # Modular ESP-IDF components
│   ├── main/              # app_main entry point
│   └── test/              # Unity host tests (13 suites)
├── firmware/              # Legacy PlatformIO/Arduino firmware
│   ├── src/               # Source modules
│   ├── test/              # sim-host tests (8 suites, 13 tests)
│   └── lib/INA237/        # Local INA237 driver fork
├── iosApp/                # iOS SwiftUI app (CoreBluetooth)
├── kxkm-bmu-app/          # KMP shared Kotlin module
│   └── shared/            # Cross-platform domain logic
├── kxkm-api/              # Docker stack (Mosquitto, InfluxDB, FastAPI, Grafana)
├── hardware/              # KiCad schematics + Gerbers (v1 + v2)
├── specs/                 # Kill_LIFE gates (S0-S3)
├── docs/                  # Specs, plans, governance, research
├── grafana/dashboards/    # 3 Grafana dashboard JSONs
└── scripts/               # CI, QA, ML pipeline

About KompleX KapharnaüM

KompleX KapharnaüM is a live arts company based in Villeurbanne (Lyon, France), active for 20+ years in street arts, live performance, and digital creation. The company develops its own embedded hardware platform (K32, ESP32-based) and maintains open-source tools on GitHub.

License

GNU General Public License v3.0

_{Built with ESP-IDF, LVGL, NimBLE, SwiftUI, FastAPI, InfluxDB, and Grafana.}
_{Developed by L'Electron Rare for KompleX KapharnaüM}

Name		Name	Last commit message	Last commit date
Latest commit History 430 Commits
.claude		.claude
.github		.github
.remember		.remember
.superpowers/brainstorm/41015-1775076599		.superpowers/brainstorm/41015-1775076599
ArduinoJson		ArduinoJson
docs		docs
firmware-idf		firmware-idf
firmware-rs		firmware-rs
firmware		firmware
grafana/dashboards		grafana/dashboards
hardware		hardware
iosApp		iosApp
kxkm-api		kxkm-api
kxkm-bmu-app		kxkm-bmu-app
models		models
plan		plan
scripts		scripts
services		services
specs		specs
tests/llm		tests/llm
.gitattributes		.gitattributes
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
AGENTS.md		AGENTS.md
BMU.jpeg		BMU.jpeg
CLAUDE.md		CLAUDE.md
CLAUDE.md.backup		CLAUDE.md.backup
KXKM_Batterie_Parallelator.code-workspace		KXKM_Batterie_Parallelator.code-workspace
LICENSE		LICENSE
README.md		README.md
adresse TCA_INA.xlsx		adresse TCA_INA.xlsx
phase2_fpnn_train.log		phase2_fpnn_train.log
phase2_fpnn_train_v2.log		phase2_fpnn_train_v2.log
platformio.ini		platformio.ini

Navigation Menu

Uh oh!

Repository files navigation

KXKM Batterie Parallelator

Overview

Key Features

Quick Start

Architecture

Firmware Components (ESP-IDF, 25 modules)

Protection Logic

LED Behavior

iOS Companion App

Victron BLE Integration

Cloud Infrastructure

Testing

PlatformIO sim-host (13 tests)

ESP-IDF Host Tests (13 tests)

CI/CD Pipelines

Security Audit

Hardware

PCB Revisions

Key ICs

I2C Mapping

Project Structure

About KompleX KapharnaüM

License

About

Releases

Packages

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

KXKM Batterie Parallelator

Overview

Key Features

Quick Start

Architecture

Firmware Components (ESP-IDF, 25 modules)

Protection Logic

LED Behavior

iOS Companion App

Victron BLE Integration

Cloud Infrastructure

Testing

PlatformIO sim-host (13 tests)

ESP-IDF Host Tests (13 tests)

CI/CD Pipelines

Security Audit

Hardware

PCB Revisions

Key ICs

I2C Mapping

Project Structure

About KompleX KapharnaüM

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages