644 lines
18 KiB
YAML
644 lines
18 KiB
YAML
openapi: 3.0.2
|
|
info:
|
|
title: OpenEVSE WiFi API
|
|
description: |
|
|
The API for the OpenEVSE WiFi module
|
|
version: "1.0"
|
|
contact:
|
|
email: jeremy@bigjungle.net
|
|
name: Jeremy Poulter
|
|
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
|
|
ohm_hour: NotConnected
|
|
free_heap: 203268
|
|
comm_sent: 335139
|
|
comm_success: 335139
|
|
rapi_connected: 1
|
|
amp: 0
|
|
pilot: 32
|
|
temp1: 282
|
|
temp2: -2560
|
|
temp3: -2560
|
|
state: 254
|
|
elapsed: 3473
|
|
wattsec: 22493407
|
|
watthour: 51536
|
|
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
|
|
/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
|
|
tags:
|
|
- Status
|
|
/config:
|
|
get:
|
|
operationId: getConfig
|
|
summary: Get the EVSE configuration
|
|
description: ""
|
|
tags:
|
|
- Config
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./models/Config.yaml
|
|
examples: {}
|
|
post:
|
|
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_enabled: true
|
|
divert_attack_smoothing_factor: 0.4
|
|
divert_decay_smoothing_factor: 0.05
|
|
divert_min_charge_time: 60
|
|
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:
|
|
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
|
|
energy_limit: 0
|
|
time_limit: 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:
|
|
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:
|
|
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/ESP32_WiFi_V4.x/blob/master/src/evse_man.h#L25)"
|
|
/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
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: ./models/EvseState.yaml
|
|
operationId: getScheduleEvent
|
|
tags:
|
|
- Schedule
|
|
post:
|
|
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:
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Message"
|
|
examples: {}
|
|
operationId: removeScheduleEvent
|
|
tags:
|
|
- Schedule
|
|
summary: Remove event
|
|
/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: ""
|
|
parameters:
|
|
- schema:
|
|
type: integer
|
|
name: index
|
|
in: path
|
|
required: true
|
|
/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.
|
|
components:
|
|
schemas:
|
|
Message:
|
|
title: Informational message
|
|
type: object
|
|
properties:
|
|
msg:
|
|
type: string
|
|
description: The message
|
|
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:
|
|
type: string
|
|
enum:
|
|
- monday
|
|
- tuesday
|
|
- wednesday
|
|
- thursday
|
|
- friday
|
|
- saturday
|
|
- sunday
|
|
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
|