OpenEVSE — System Overview & Developer Reference

OpenEVSE is an open-source electric vehicle supply equipment (EVSE) platform consisting of three tightly integrated components: an AVR-based charging controller, an ESP32 WiFi gateway, and a Svelte web interface. Together they deliver a fully featured, locally hosted EV charging station with cloud integration, energy management, and smart-home connectivity.

Architecture Overview

┌─────────────────────────────────────────────────────┐
│                   Web Browser / App                 │
│            openevse-gui-v2  (Svelte / Vite)         │
└────────────────────┬────────────────────────────────┘
                     │  HTTP REST / WebSocket
┌────────────────────▼────────────────────────────────┐
│          ESP32 WiFi Gateway Firmware                │
│    openevse_esp32_firmware  (C / C++ / ESP-IDF)     │
│  WiFi · Ethernet · MQTT · OCPP · Home Assistant     │
└────────────────────┬────────────────────────────────┘
                     │  Serial RAPI API (UART) 115200
┌────────────────────▼────────────────────────────────┐
│      OpenEVSE EV Safety Controller Firmware         │
│      open_evse  (C++, ATmega328P/ARM SAMD21)        │
│   J1772 · GMI/GFI · Relay · Pilot · Proximity       │
└─────────────────────────────────────────────────────┘

1. OpenEVSE Controller Firmware

Repository: https://github.com/OpenEVSE/open_evse
MCU: ATmega328P / ATSAMD21G18
Language: C++ (83.8%), Roff
Standard: SAE J1772 (Level 1 & Level 2)

Key Capabilities

• GFI (Ground Fault Interrupter) protection
• Pilot signal generation and state machine (A/B/C/D/E/F)
• Relay control with stuck-relay and no-ground fault detection
• Time-based scheduled charging
• Display with 3.5" TFT or Text RGB backlight
• Temperature monitoring (MCP9808)
• Ammeter with calibration
• Charge time and energy limits
• Heartbeat supervision for gateway watchdog
• Mennekes lock control (EU Type 2)

Build & Programming

• Pre-compiled binaries available on GitHub Releases
• Compile with VSCode / PlatformIO using bundled library versions
• Flash via avrdude with USBASP or compatible ISP programmer
• Hardware definitions in /boards/, firmware source in /firmware/open_evse/

2. RAPI Protocol

The Remote API (RAPI) is a serial ASCII protocol used by the ESP32 gateway (and any host) to control and query the OpenEVSE controller over UART.

Format: $<cmd> [args...]*<checksum>\r\n
Response: $OK [values...] or $NK (not OK)

Function Commands

Set Commands

Get Commands

3. ESP32 WiFi Gateway Firmware

Repository: https://github.com/OpenEVSE/openevse_esp32_firmware
MCU: ESP32
Language: C (73%), C++ (24.7%)
License: GPL v3
Latest Release: v5.1.5 (October 2025)
Minimum OpenEVSE firmware: v7.1.3

Connectivity

• 802.11 b/g/n WiFi (AP + STA modes)
• Wired Ethernet via ESP32 Gateway board
• UART to OpenEVSE controller (RAPI)

Features

REST API

Base URL: http://<device-ip> (default hostname: openevse.local)

Status

Configuration

Manual Override

Claims (multi-client current arbitration)

Scheduling

Limits

System

Tesla

Certificates

Full API Spec

OpenAPI / Swagger specification: api.yml in the firmware repository root.
Interactive docs: https://openevse.stoplight.io/docs/openevse-wifi

4. Web Interface (openevse-gui-v2)

Repository: https://github.com/OpenEVSE/openevse-gui-v2
License: BSD-2-Clause
Stack: Svelte, Vite, Bulma CSS
Language: Svelte (54.9%), JavaScript (44.2%)

Features

• Dashboard: live state, current draw, energy session
• Start / pause charging
• Current capacity slider
• Scheduler: create, edit, and delete timed charging events
• Eco/Solar divert mode controls
• System configuration (WiFi, MQTT, EmonCMS, limits)
• Internationalization (i18n)

Development

# Clone with submodules
git clone --recurse-submodules https://github.com/OpenEVSE/openevse-gui-v2.git
cd openevse-gui-v2

npm install

# Set target device (defaults to openevse.local)
export VITE_OPENEVSEHOST=192.168.x.x

npm run dev        # Dev server on :5173 — proxies API to VITE_OPENEVSEHOST
npm run build      # Production build → dist/

5. Integration Notes

MQTT

The ESP32 gateway publishes EVSE state and subscribes to control topics. Configure broker, username, password, and base topic via /config or the web UI. Commonly used with Home Assistant MQTT discovery.

Emoncms

Data can be logged to enoncms.org or a self-hosted Emoncms instance. Set emoncms_apikey, emoncms_server, and emoncms_node in /config.

Eco / Solar Divert Mode

The gateway accepts real-time solar generation and grid import data via POST /status (fields: solar, grid_ie, voltage) and adjusts the pilot current to charge only from surplus renewable energy.

Home Assistant

Beta native integration. Alternatively, use MQTT with HA's MQTT integration. The gateway's auto-discovery payloads populate entities automatically.

OCPP v1.6

Beta support for communicating with a central management system (CMS/CSMS). Configure OCPP server URL and identity via /config.

6. Hardware References

7. Useful Links

Tip Jar: Lincomatic developed/maintains this firmware on a volunteer basis. Any donation, no matter how small, is greatly appreciated.

Open EVSE is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3, or (at your option)
any later version.

Open EVSE is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with Open EVSE; see the file COPYING.  If not, write to the
Free Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA 02111-1307, USA.

* Open EVSE is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.