Smart Electric Vehicle Charge Controller
This repository is a fork of dingo35/SmartEVSE-3.5 maintained as a testbed for IT/OT software engineering with AI-assisted development (multi-agent software engineering using Claude Code).
The upstream SmartEVSE firmware is a monolithic embedded C++/Arduino codebase where the
state machine, load balancing, MQTT, HTTP, and hardware control all live in a single
~3,000-line main.cpp. This fork restructures the architecture to enable native host
testing of the core logic — pure C modules, context structs, a bridge layer, and HAL
callbacks — resulting in 1,200+ automated tests (1,096 native C tests across 50 suites,
50 OCPP protocol tests, and 146 Modbus compatibility tests).
See Quality Engineering for the full architecture, testing methodology, CI/CD pipeline, and hardening approach. See Upstream Differences for a complete list of changes compared to the upstream repository.
An open source EVSE (Electric Vehicle Supply Equipment). It supports 1-3 phase charging, fixed charging cable or charging socket, locking actuator support (5 types), and it can directly drive a mains contactor for supplying power to the EV. It features a display for parameter configuration. Up to 8 modules can be connected together to charge up to eight EVs from one mains connection without overloading it.
| Feature | Highlights |
|---|---|
| Charging | 1-3 phase, auto cable detection (13/16/32A), dual contactor outputs, thermal protection |
| Solar & Smart Mode | Solar surplus charging, auto 1P/3P switching, EMA smoothing, dead band regulation |
| Load Balancing | Up to 8 nodes, priority scheduling, oscillation dampening, convergence testing |
| OCPP & Authorization | OCPP 1.6j, RFID (100 cards), pure C logic extraction (85 tests), 50 protocol tests, FreeVend solar safety |
| MQTT & Home Assistant | Change-only publishing (70-97% reduction), fixed HA discovery, per-phase power/energy |
| Metering | 18 Modbus meter types, 146 compatibility tests, HomeWizard P1, Sensorbox, API/MQTT feed, staleness detection |
| EVCC Integration | IEC 61851 state mapping, HTTP phase switching, ready-to-use template |
| Diagnostics | Ring buffer events, LittleFS persistence, WebSocket live stream, test replay |
| ERE Session Logging | Dutch ERE certificate output, MQTT publish, REST endpoint, zero flash wear |
| Capacity Tariff | 15-min peak tracking, monthly peak persistence, automatic current limiting, LCD/Web/MQTT/REST config |
| CircuitMeter | Subpanel metering, breaker protection, ERE circuit verification, all 19 meter types supported |
| SoC Injection | MQTT topics for InitialSoC/FullSoC/EnergyCapacity/EnergyRequest/EVCCID, WiCAN OBD-II integration |
| Web UI | Offline-first, WebSocket updates, dark mode, load balancing dashboard, diagnostic viewer |
| Privacy | No cloud, no tracking, open source |
For detailed feature descriptions and fork improvements, see Features.
Follow the instructions on the Configuration page, WiFi section.
Connect to your WiFi network, then browse to http://smartevse-xxxx.local/update
(replace xxxx with your serial number, shown on the display). Select the
firmware.bin and press Update.
| Document | Description |
|---|---|
| Hardware installation | Wiring, mounting, contactor setup |
| Power Input Methods | Metering options — reliability ranking, setup, troubleshooting |
| Configuration | LCD menu settings reference |
| Settings Reference | All settings by access channel with safety flags |
| Operation | Day-to-day usage guide |
| Document | Description |
|---|---|
| Features & USPs | All features with fork improvements |
| Upstream Differences | Complete diff with upstream repo |
| Solar & Smart Mode Stability | EMA smoothing, dead bands, phase switch timers |
| Load Balancing Stability | Oscillation dampening, diagnostics |
| MQTT & Home Assistant | Topic reference, HA auto-discovery |
| EVCC Integration | EVCC charger template, phase switching API |
| REST API reference | HTTP endpoints for external integration |
| ERE Session Logging | Dutch ERE certificates, HA automation |
| OCPP setup | Provider guides (Tap Electric, Tibber, SteVe) |
| Priority scheduling | Load balancing priority configuration |
| Document | Description |
|---|---|
| Quality Engineering | Architecture, testing, CI/CD, hardening, interoperability |
| Building & Flashing | Compiling firmware from source |
| Coding standards | Code conventions for contributors |
| Contributing | How to contribute to this project |
| AI agent instructions | Multi-agent workflow for Claude Code |
Completed improvement plans, tracked via GitHub Projects:
| Status | Project | PRs | Upstream issues |
|---|---|---|---|
| Done | Plan 01: Solar & Smart Mode Stability | #65, #83 | #327, #335, #316 |
| Done | Plan 02: Multi-Node Load Balancing | #69 | #316 |
| Done | Plan 03: OCPP Robustness | #77, #79, #80 | — |
| Done | Plan 04: EVCC Integration | #70 | EVCC #13852 |
| Done | Plan 05: Meter Compatibility & Modbus | #76 | — |
| Done | Plan 06: Diagnostic Telemetry | #84 | — |
| Done | Plan 07: Web UI Modernization | #85 | — |
| Done | Plan 08: HA MQTT Integration | #64, #68, #82 | #320, #294, PR #338 |
| Done | Plan 09: Power Input Methods | #86 | — |
| Done | Plan 10: ERE Session Logging | #89 | — |
| Done | Plan 11: OCPP Compatibility Testing | #96 | — |
| Done | Plan 12: Modbus Compatibility Testing | #97 | — |
| Done | Plan 13: Capacity Tariff Peak Tracking | #116 | — |
| Done | Plan 14: CircuitMeter — Subpanel Metering | #117 | — |
| Done | Plan 15: SoC Injection via MQTT | #115, #116 | — |
All 15 improvement plans are complete. The CI/CD pipeline runs a 10-job quality gate on every PR, including OCPP interoperability tests (mock CSMS via mobilityhouse/ocpp) and Modbus compatibility tests (C decode functions called from Python via ctypes). See Quality Engineering for details.
The SmartEVSE-app can be found here or on Google Play