openapi: 3.0.3
info:
title: OpenEVSE WiFi API
description: |
The API for the OpenEVSE WiFi module
version: '1.0'
contact:
email: jeremy@bigjungle.net
name: Jeremy Poulter
url: 'https://github.com/jeremypoulter/'
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
- url: '{server}'
variables:
server:
default: 'http://openevse.local'
- url: 'http://localhost:8080'
paths:
/status:
get:
operationId: getStatus
summary: Get the EVSE status
description: |
The status endpoint can be called to get the status of the EVSE.
While it is posible to poll this endpoint, the recomendatoin is to retrieve the initial
state then use the [/ws](#statusUpdates)
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: ./models/Status.yaml
examples:
EVSE Status:
value:
mode: STA
wifi_client_connected: 1
eth_connected: 0
net_connected: 1
srssi: -73
ipaddress: 192.168.1.43
emoncms_connected: 1
packets_sent: 22307
packets_success: 22290
mqtt_connected: 1
free_heap: 203268
comm_sent: 335139
comm_success: 335139
rapi_connected: 1
amp: 0
pilot: 32
max_current: 32
temp1: 282
temp2: -2560
temp3: -2560
state: 254
elapsed: 3473
session_energy: 25034
total_energy: 998
total_day: 23
total_week: 68
total_month: 126
total_year: 998
gfcicount: 0
nogndcount: 0
stuckcount: 0
divertmode: 1
solar: 390
grid_ie: 0
charge_rate: 7
divert_update: 0
ota_update: 0
time: '2020-05-12T17:53:48Z'
offset: '+0000'
tags:
- Status
post:
operationId: postStatus
summary: Update external data to EVSE status
description: |
The status endpoint can be called to post external data that should be updated by MQTT
If MQTT is not an option, all external data needed can be updated from an HTTP POST request to /status endpoint.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
voltage:
type: integer
description: live voltage in V
shaper_live_pwr:
type: integer
description: total household live power in W
solar:
type: integer
description: divert solar production in W
grid_ie:
type: integer
description: divert grid -import/+export in W
battery_level:
type: integer
description: vehicle soc in %
battery_range:
type: integer
description: vehicle range
time_to_full_charge:
type: integer
description: vehicle charge ETA
x-examples:
EVSE Status:
voltage: 220
shaper_live_pwr: 3400
solar: 3000
grid_ie: 3000
battery_level: 85
battery_range: 230
time_to_full_charge: 1590
examples:
EVSE Status:
value:
voltage: 220
shaper_live_pwr: 3400
solar: 3000
grid_ie: 3000
battery_level: 85
battery_range: 230
time_to_full_charge: 1590
tags:
- Status
/ws:
get:
operationId: statusUpdates
summary: EVSE status updates
description: |
As the state changes on the EVSE a websocket frame will be sent over the socket.
The frame will contain a JSON document conntaining only the updated state.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: ./models/Status.yaml
'400':
description: Error
tags:
- Status
/config:
get:
operationId: getConfig
summary: Get the EVSE configuration
description: |
Retrieve the current WiFi and EVSE module configuration
tags:
- Config
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: ./models/Config.yaml
examples: {}
post:
description: |
Update the EVSE configuration
operationId: updateConfig
responses:
'200':
$ref: '#/components/responses/UpdateSuccessful'
'400':
$ref: '#/components/responses/BadRequest'
requestBody:
content:
application/json:
schema:
$ref: ./models/Config.yaml
examples:
Update EmonCMS setting:
value:
emoncms_enabled: true
emoncms_server: 'http://emoncms.org'
emoncms_node: openevse-a7d4
emoncms_apikey: emoncmskey
emoncms_fingerprint: ''
Configure Solar divert:
value:
divert_type: 0
divert_enabled: true
divert_attack_smoothing_time: 8
divert_decay_smoothing_time: 300
divert_min_charge_time: 20
Set normal charging mode:
value:
charge_mode: fast
Set Eco mode:
value:
charge_mode: eco
Configure Tesla credentials:
value:
tesla_enabled: true
tesla_access_token: qts-1234.......
tesla_refresh_token: abcd.......
tesla_created_at: 1623358948
tesla_expires_in: 3888000
Select Tesla vehicle:
value:
tesla_vehicle_id: '2238974987235987'
summary: Update the EVSE configuration
tags:
- Config
/override:
description: Manual override can be used to override a charging timer or to immediately start a charge if the EVSE is in sleeping state.
get:
responses:
'200':
description: Manual overide is active
content:
application/json:
schema:
$ref: ./models/Properties.yaml
'404':
$ref: '#/components/responses/NotFound'
operationId: getManualOverride
tags:
- Manual Override
summary: Get the Manual Override status
description: Returns the current state of the manual override.
post:
description: |
Set the manual override
requestBody:
content:
application/json:
schema:
$ref: ./models/Properties.yaml
examples:
Force stop of charging:
value:
state: disabled
example-1:
value:
state: active
charge_current: 0
max_current: 0
auto_release: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
operationId: setManualOverride
tags:
- Manual Override
summary: Set the manual override
patch:
description: Toggle the manual override
responses:
'200':
description: OK
operationId: toggleManualOverride
tags:
- Manual Override
summary: Toggle the manual Override
delete:
description: Clears the manual override
responses:
'200':
description: OK
operationId: clearManualOverride
tags:
- Manual Override
summary: Clear the manual override
/claims:
get:
description: |
List all claims made by EVSE clients.
The response will be an array of EVSE claims.
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: ./models/Claim.yaml
operationId: listClaims
tags:
- Claims
summary: List EVSE claims
'/claims/{client}':
get:
description: |
Get the claim information for a specific client.
The response will be an EVSE claim.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: ./models/Properties.yaml
'404':
$ref: '#/components/responses/NotFound'
parameters: []
operationId: getClaim
tags:
- Claims
summary: Get EVSE claim information
post:
description: Make/Update a claim
requestBody:
content:
application/json:
schema:
$ref: ./models/Properties.yaml
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
'400':
$ref: '#/components/responses/BadRequest'
operationId: setClaim
summary: Make/Update an EVSE claim
tags:
- Claims
delete:
description: Release a claim
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
'404':
$ref: '#/components/responses/NotFound'
operationId: releaseClaim
summary: Release an EVSE claim
tags:
- Claims
parameters:
- schema:
type: integer
name: client
in: path
required: true
description: 'The client ID, defined by [OpenEVSE](https://github.com/OpenEVSE/openevse_esp32_firmware/blob/master/src/evse_man.h#L28)'
/schedule:
get:
summary: List schedule events
description: This will get a complete list of events in the schedule
responses:
'200':
description: List of the schedule events
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ScheduleEvent'
'400':
$ref: '#/components/responses/BadRequest'
operationId: listSchedule
tags:
- Schedule
post:
operationId: updateSchedule
description: Perform multiple event updates
responses:
'201':
description: item created
'400':
description: 'invalid input, object invalid'
'409':
description: an existing item already exists
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ScheduleEvent'
examples:
Single event:
value:
- id: 1
state: active
time: '14:15:22Z'
days:
- monday
Daily Timer:
value:
- id: 1
state: active
days:
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
time: '07:00:00'
- id: 2
state: disabled
days:
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
time: '10:00:00'
description: Inventory item to add
tags:
- Schedule
summary: Batch update schedule
'/schedule/{id}':
parameters:
- in: path
name: id
required: true
schema:
type: integer
description: Numeric ID of the event
get:
summary: Get event details
description: |
This will get the details of a specific event in the schedule.
The response will be the EVSE state to set for that event.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: ./models/EvseState.yaml
operationId: getScheduleEvent
tags:
- Schedule
post:
description: |
Update the details of a specific event in the schedule.
responses:
'200':
$ref: '#/components/responses/UpdateSuccessful'
requestBody:
content:
application/json:
schema:
$ref: ./models/EvseState.yaml
description: ''
operationId: setScheduleEvent
tags:
- Schedule
summary: Update event details
delete:
description: |
Remove a specific event from the schedule.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
examples: {}
operationId: removeScheduleEvent
tags:
- Schedule
summary: Remove event
/schedule/plan:
get:
summary: Get planned events and state
description: This will return the planned events by day and also the current state of the scheduler
responses:
'200':
description: List of planed events
content:
application/json:
schema:
type: object
properties:
current_day:
$ref: '#/components/schemas/Day'
operationId: getSchedulePlan
tags:
- Schedule
/logs:
get:
summary: Get event block information
tags:
- Event Log
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
min:
type: integer
max:
type: integer
operationId: getEventBlockInfo
description: 'Retrieve the start and end indexes of the log event blocks. Each log event block contains '
parameters: []
parameters: []
'/logs/{index}':
get:
summary: Get log block events
tags:
- Event Log
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/LogEvent'
'404':
$ref: '#/components/responses/NotFound'
operationId: getEventBlock
description: |
Retrieve the log events for a specific block.
The block index range is returned by the /logs endpoint.
parameters:
- schema:
type: integer
name: index
in: path
required: true
/restart:
post:
summary: restart gateway or evse modules
description: restart wifi gateway or openevse module
operationId: restart
tags:
- Restart
requestBody:
content:
application/json:
schema:
type: object
properties:
device:
type: string
description: gateway|evse
responses:
'200':
description: Restart successfull
content:
application/json:
schema:
type: object
properties:
msg:
type: string
description: restart gateway|evse
/limit:
get:
summary: Get charge limit
description: 'This will return the limit type, value and auto_release (true|false) defined if there''s one'
responses:
'200':
description: Limit properties
content:
application/json:
schema:
$ref: ./models/Limit.yaml
'404':
description: No limit
content:
application/json:
schema:
type: object
properties:
msg:
type: string
description: No limit
operationId: limit_get
tags:
- Limit
post:
summary: Set charge limit
description: 'This will set the limit type, value and auto_release (true|false)'
responses:
'200':
description: Limit set
content:
application/json:
schema:
type: object
properties:
msg:
type: string
description: created
'500':
description: Failed to parse data
content:
application/json:
schema:
type: object
properties:
msg:
type: string
description: Failed to parse JSON
requestBody:
content:
application/json:
schema:
$ref: ./models/Limit.yaml
operationId: limit_set
tags:
- Limit
delete:
summary: Get charge limit
description: This will clear current limit
responses:
'200':
description: Clear Limit ok
content:
application/json:
schema:
type: object
properties:
msg:
type: string
description: Deleted
'404':
description: No limit
content:
application/json:
schema:
type: object
properties:
msg:
type: string
description: No limit to clear
'500':
description: Failed to clear limit
content:
application/json:
schema:
type: object
properties:
msg:
type: string
description: Failed to clear limit
operationId: limit_clear
tags:
- Limit
/boost:
get:
summary: Get the active boost
description: >
Returns the active boost (type, value, remaining, started), or an
empty object when no boost is active. The idle 200+{} response
doubles as the capability probe: older firmware has no clean 404 for
this path, so clients should treat any non-200-JSON response as
unsupported rather than relying on a 404.
responses:
'200':
description: Active boost, or {} when idle
content:
application/json:
schema:
type: object
properties:
type:
type: string
enum: [time, energy, soc, range]
value:
type: integer
description: >
time: seconds (NOT minutes, unlike /limit); energy: Wh
added since activation; soc: absolute percent; range:
absolute distance
remaining:
type: integer
description: Remaining amount in the dimension's unit (ceil)
started:
type: string
format: date-time
operationId: boost_get
tags:
- Boost
post:
summary: Arm (or replace) a boost
description: >
Boost charges NOW - an Active claim at priority 200 (above Divert and
the Scheduler, below Manual and Limit) - until the target is reached,
then releases so the previous controller resumes. Re-POSTing while a
boost is active replaces it with a fresh activation snapshot. Time
values clamp to 604800 seconds (7 days). Energy value is a Wh delta
from the moment of activation; soc/range values are absolute targets
and require a vehicle data source (422 otherwise). A soc/range target
that is ALREADY met arms as a no-op: 201, no claim is taken, and GET
/boost still returns {}. The MQTT /boost event topic publishes
the boolean boost + boost_version on every change; boost_reason
("reached", "cancelled" or "replaced") appears only on end events
(boost false) and never on an active one, so a replace emits the end
event first and then the fresh arm event. The retained /boost
state topic carries this same serialized object ({} when idle) - the
retained remaining is a snapshot at arm/end, not a live countdown.
responses:
'201':
description: Boost armed
content:
application/json:
schema:
type: object
properties:
msg:
type: string
description: created
'400':
description: Malformed body, unknown type, or zero value
content:
application/json:
schema:
type: object
properties:
msg:
type: string
description: Failed to parse JSON
'422':
description: soc/range boost without a vehicle data source
content:
application/json:
schema:
type: object
properties:
msg:
type: string
description: No vehicle data available
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [type, value]
properties:
type:
type: string
enum: [time, energy, soc, range]
value:
type: integer
minimum: 1
operationId: boost_set
tags:
- Boost
delete:
summary: Cancel the active boost
description: This will clear the active boost, if any
responses:
'200':
description: Boost cancelled
content:
application/json:
schema:
type: object
properties:
msg:
type: string
description: Deleted
'404':
description: No boost active
content:
application/json:
schema:
type: object
properties:
msg:
type: string
description: No boost to clear
operationId: boost_clear
tags:
- Boost
/emeter:
delete:
summary: Reset Energy Meter
description: This will clear the Energy Meter
requestBody:
content:
application/json:
schema:
type: object
properties:
hard:
type: integer
description: 0|1 Enable hard reset ( reset total_counter & total_switches)
import:
type: integer
description: 0|1 Import OpenEvse module total kwh.
responses:
'200':
description: Reset counter ok
content:
application/json:
schema:
type: object
properties:
msg:
type: string
description: Reset done
'500':
description: Failed to reset counter
content:
application/json:
schema:
type: object
properties:
msg:
type: string
description: Reset failed
operationId: energymeter-reset
tags:
- Energy Meter
/tesla/vehicles:
get:
summary: Get Tesla vehicle list
tags:
- Tesla
responses:
'200':
description: OK
content:
application/json:
schema:
description: ''
type: object
x-examples:
example-1:
count: 3
vehicles:
- id: '1492932278133304'
name: AwesomeSAUCE
- id: '1492931610165415'
name: Herbie
- id: '1492930973960452'
name: 'Life, the Universe, and Everything'
properties:
count:
type: number
vehicles:
type: array
uniqueItems: true
items:
type: object
additionalProperties: false
properties:
id:
type: string
minLength: 1
name:
type: string
minLength: 1
required:
- id
- name
required:
- count
- vehicles
examples:
example-1:
value:
count: 1
vehicles:
- id: '2238974987235987'
name: My Tesla
operationId: get-tesla-vehicles
description: Once the Tesla account credentials have been configured via the `/config` API this endpoint will return a list of vehicles associated with the account. The ID of the vehicle to use for SoC/Range can then be set using `tesla_vehicle_id` on the `/config` endpoint.
/time:
get:
summary: Get the time
tags:
- Time
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
time:
type: string
x-stoplight:
id: 6q0laeyxt5u85
description: The time in UTC according to the OpenEVSE.
format: date-time
offset:
type: string
x-stoplight:
id: u5zngl88caktf
pattern: '^[+-][0-9]{4}$'
local_time:
type: string
x-stoplight:
id: 7h1cpgfjj5j9j
format: date-time
uptime:
type: integer
description: EVSE gateway uptime, in seconds
required:
- time
- offset
- local_time
- uptime
operationId: get-time
description: Gets the time set on the OpenEVSE
post:
summary: Set the time
tags:
- Time
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
x-examples:
Example 1:
sntp_enabled: false
time_zone: 'GMT0BST,M3.5.0/1,M10.5.0'
time: '2018-08-10T14:30:00Z'
properties:
sntp_enabled:
type: boolean
description: |
Set to `true` to enable receiving time updates via NTP, `false` will disable NTP updates.
default: false
time_zone:
type: string
description: The time zone to use on the OpenEVSE. This has the format `|`. The `location name` is not used by the EVSE and is largely to for the UI to provide a human readable version of the timezone and differentiate between locations that use the same time zone.
default: UTC0
time:
type: string
description: If `sntp_enabled` is false this is the time to set. Must be in UTC.
format: date-time
'400':
$ref: '#/components/responses/BadRequest'
operationId: post-time
description: Set the time and associated config options. If not setting the time the `/config` endpoint can be used.
/certificates:
get:
summary: Get a list of certificates
description: |
Returns a list of certificates that have been uploaded to the OpenEVSE. The certificates are used to
authenticate the OpenEVSE to the MQTT broker, provide a secure web interface or as additional root CA
certificates.
operationId: listCertificates
tags:
- Certificates
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
certificates:
type: array
items:
$ref: './models/Certificate.yaml'
post:
summary: Upload a certificate
description: |
Upload a certificate to the OpenEVSE. The certificate can be used to authenticate the OpenEVSE to the MQTT
broker, provide a secure web interface or as additional root CA certificates.
operationId: uploadCertificate
tags:
- Certificates
requestBody:
content:
application/json:
schema:
$ref: './models/Certificate.yaml'
responses:
'200':
$ref: '#/components/responses/UpdateSuccessful'
'400':
$ref: '#/components/responses/BadRequest'
'/certificates/{id}':
get:
summary: Get a certificate
description: |
Returns a certificate that has been uploaded to the OpenEVSE. The certificate is used to
authenticate the OpenEVSE to the MQTT broker, provide a secure web interface or as additional root CA
certificates.
operationId: getCertificate
tags:
- Certificates
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: './models/Certificate.yaml'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
delete:
summary: Delete a certificate
description: |
Delete a certificate that has been uploaded to the OpenEVSE. The certificate is used to
authenticate the OpenEVSE to the MQTT broker, provide a secure web interface or as additional root CA
certificates.
operationId: deleteCertificate
tags:
- Certificates
parameters:
- in: path
name: id
required: true
schema:
type: string
responses:
'200':
$ref: '#/components/responses/UpdateSuccessful'
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
Message:
title: Informational message
type: object
properties:
msg:
type: string
description: The message
Day:
type: string
enum:
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
x-examples: {}
ScheduleEvent:
type: object
properties:
id:
type: integer
example: 1
state:
$ref: ./models/EvseState.yaml
time:
type: string
format: time
days:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/Day'
required:
- state
- time
- days
title: ''
LogEvent:
title: LogEvent
type: object
x-examples:
example-1:
value:
time: '2021-08-24T14:15:22Z'
type: information
managerState: active
evseState: 1
evseFlags: 123
pilot: 32
energy: 1234.5
elapsed: 123456
temperature: 35.4
tempuratureMax: 50.4
divertMode: 1
properties:
time:
type: string
format: date-time
readOnly: true
type:
type: string
enum:
- information
- notification
- warning
managerState:
$ref: ./models/EvseState.yaml
evseState:
type: integer
minimum: 0
maximum: 255
evseFlags:
type: integer
format: int32
pilot:
type: integer
format: int32
minimum: 0
energy:
type: number
format: double
minimum: 0
elapsed:
type: integer
format: int32
minimum: 0
temperature:
type: number
format: double
tempuratureMax:
type: number
format: double
divertMode:
type: integer
format: int32
minimum: 1
maximum: 2
exclusiveMaximum: false
responses:
UpdateSuccessful:
description: Update successful
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
examples:
Success message:
value:
msg: done
NotFound:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
examples:
Not found:
value:
msg: Not found
BadRequest:
description: Example response
content:
application/json:
schema:
$ref: '#/components/schemas/Message'
examples:
Bad JSON:
value:
msg: Could not parse JSON
parameters: {}
tags:
- name: Claims
- name: Config
- name: Event Log
- name: Manual Override
- name: Schedule
- name: Status
- name: Tesla
- name: Limit
- name: Boost
- name: Energy Meter
- name: Time
- name: Restart
- name: Certificates