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

Command	Description	Parameters
FD	Disable EVSE	—
FE	Enable EVSE	—
FS	Sleep EVSE	—
FR	Restart EVSE	—
F0	Enable/disable display updates	1=enable, 0=disable
F1	Simulate front-panel button press	—
FB	Set LCD backlight color	0=OFF 1=RED 2=GREEN 3=YELLOW 4=BLUE 5=VIOLET 6=TEAL 7=WHITE
FP	Print text on LCD	x, y, text
FF	Enable/disable feature flag	feature_id (B/D/E/F/G/R/T/V), 0/1

Set Commands

Command	Description	Parameters
SC	Set current capacity	amps, [V|M]
SL	Set service level	1=L1, 2=L2, A=Auto
ST	Set timer	starthr, startmin, endhr, endmin
S3	Set charge time limit	cnt × 15 min
SH	Set charge limit	kWh
SK	Set accumulated Wh	value
SV	Set voltage for power calc	millivolts
SA	Set ammeter calibration	currentscalefactor, currentoffset
SM	Set voltmeter calibration	voltscalefactor, voltoffset
S1	Set RTC clock	yr, mo, day, hr, min, sec
S2	Enable/disable ammeter cal mode	0/1
S4	Set auth lock	0=unlocked, 1=locked
S5	Mennekes lock setting	A=auto, M=manual, 0=unlock, 1=lock
SB	Clear boot lock	—
SY	Set heartbeat supervision	interval, currentlimit
S0	Set LCD type	0=monochrome, 1=RGB

Get Commands

Command	Description	Response
GS	Get EVSE state	evsestate, elapsed, pilotstate, vflags
GG	Get charging current & voltage	milliamps, millivolts
GU	Get energy usage	Wattseconds, Whacc
GC	Get current capacity info	minamps, hmaxamps, pilotamps, cmaxamps
GE	Get settings	amps, flags
GV	Get firmware & protocol version	firmware_version, protocol_version
GT	Get RTC time	yr, mo, day, hr, min, sec
GP	Get temperature sensors	ds3231temp, mcp9808temp, tmp007temp
GO	Get overtemperature thresholds	ambientthresh, irthresh
GH	Get charge limit	kWh
G3	Get charge time limit	cnt
GD	Get delay timer	starthr, startmin, endhr, endmin
GF	Get fault counters	gfitripcnt, nogndtripcnt, stuckrelaytripcnt
GA	Get ammeter settings	currentscalefactor, currentoffset
GM	Get voltmeter settings	voltscalefactor, voltoffset
G0	Get EV connect state	connectstate (0/1/2)
G4	Get auth lock state	lockstate
G5	Get Mennekes settings	state, mode
GI	Get MCU ID	mcuid
GY	Get heartbeat supervision status	interval, currentlimit, trigger

---

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

Feature	Status
Web UI control (start/pause, current, schedules, limits)	Stable
MQTT status & control	Stable
Emoncms logging (data.openevse.com or self-hosted)	Stable
Eco / Solar divert mode	Stable
Power shaper (grid capacity management)	Stable
OTA firmware updates	Stable
OCPP v1.6J	Stable
Home Assistant integration	Stable
Tesla vehicle API	Available

REST API

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

Status

Method	Endpoint	Description
GET	/status	Current EVSE operational state
POST	/status	Push external data (voltage, power, solar, grid, battery)
GET	/ws	WebSocket — real-time state stream

Configuration

Method	Endpoint	Description
GET	/config	Read WiFi/EVSE settings
POST	/config	Write config (EmonCMS, solar divert, charging mode, Tesla credentials)

Manual Override

Method	Endpoint	Description
GET	/override	Read current override
POST	/override	Set override with custom parameters
PATCH	/override	Toggle override state
DELETE	/override	Clear override

Claims (multi-client current arbitration)

Method	Endpoint	Description
GET	/claims	List all client claims
GET	/claims/{client}	Get specific client claim
POST	/claims/{client}	Create/update claim
DELETE	/claims/{client}	Release claim

Scheduling

Method	Endpoint	Description
GET	/schedule	List all schedule events
POST	/schedule	Batch update events
GET	/schedule/{id}	Get event by ID
POST	/schedule/{id}	Update event
DELETE	/schedule/{id}	Remove event
GET	/schedule/plan	Planned events by day

Limits

Method	Endpoint	Description
GET	/limit	Get active charge limit
POST	/limit	Set charge limit
DELETE	/limit	Clear charge limit

System

Method	Endpoint	Description
POST	/restart	Restart gateway or EVSE (device param)
GET	/time	Get current time and timezone offset
POST	/time	Set time and timezone
DELETE	/emeter	Reset energy meter
GET	/logs	Log block index
GET	/logs/{index}	Fetch log events for block

Tesla

Method	Endpoint	Description
GET	/tesla/vehicles	List vehicles linked to Tesla account

Certificates

Method	Endpoint	Description
GET	/certificates	List uploaded TLS certificates
POST	/certificates	Upload certificate
GET	/certificates/{id}	Get certificate by ID
DELETE	/certificates/{id}	Delete certificate

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

Component	Link
OpenEVSE Plus v5 Controller	https://github.com/OpenEVSE/OpenEVSE_PLUS
ESP32 WiFi Kit	https://www.openevse.com
OpenEVSE Hardware Repo	https://github.com/OpenEVSE/OpenEVSE_PLUS

---

7. Useful Links

Resource	URL
Main firmware repo	https://github.com/OpenEVSE/open_evse
ESP32 gateway firmware	https://github.com/OpenEVSE/openevse_esp32_firmware
Web interface	https://github.com/OpenEVSE/openevse-gui-v2
Interactive API docs	https://openevse.stoplight.io/docs/openevse-wifi
OpenEnergyMonitor	https://openenergymonitor.org

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.