diff --git a/README.md b/README.md index 53592c1..f044eda 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,10 @@ Ziel des Projekts ist es, eine WLAN-Schnittstelle zu entwickeln um zusätzliche ![GitHub all releases](https://img.shields.io/github/downloads/steff393/wbec/total?color=blue&style=flat-square) +## API +Die Vollständige API Dokumentation befindet sich in der Datei [api.swagger.yaml](./api.swagger.yaml). +Eine Formatierte Version ist unter [petstore.swagger.io](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/steff393/wbec/master/api.swagger.yaml) verfügbar. + ## Funktionen - Anbindung an openWB, EVCC, Solaranzeige - MQTT-Kommunikation mit openWB und EVCC (ideal für mehrere Ladestationen) diff --git a/api.swagger.yaml b/api.swagger.yaml new file mode 100644 index 0000000..086874e --- /dev/null +++ b/api.swagger.yaml @@ -0,0 +1,801 @@ +openapi: 3.0.3 +info: + title: WBEC API + description: API for controlling WBEC. + version: 1.0.0 + contact: + name: steff393 + url: https://github.com/steff393/wbec +servers: + - url: http://{hostname} + variables: + hostname: + default: wbec.local + description: IP address or hostname of the WBEC device +paths: + /: + get: + tags: + - HTML + summary: Simple web interface + description: Provides a simple web interface to read values and set the load current. + responses: + '200': + description: HTML page displaying internal values and a form to set load current. + content: + text/html: + schema: + type: string + /heap: + get: + tags: + - System + summary: Get free heap memory + description: Returns the current free heap memory of the ESP8266. + responses: + '200': + description: Free heap memory in bytes. + content: + text/plain: + schema: + type: string + /json: + get: + tags: + - API + summary: Get all internal values + description: >- + Retrieves all internal system values in JSON format. Supports query + parameters to filter the data. + parameters: + - name: id + in: query + description: Zero-based index to get the values of a specific box (0-15). + required: false + schema: + type: integer + example: 2 + - name: wdTmOut + in: query + description: Timeout value for the watchdog timer. + required: false + schema: + type: integer + example: 60000 + - name: standby + in: query + description: Standby Function Control (0 or 4). + required: false + schema: + type: integer + enum: [0, 4] + example: 4 + - name: remLock + in: query + description: Value to set/remove remote lock. + required: false + schema: + type: integer + enum: [0, 1] + example: 1 + - name: currLim + in: query + description: Current limit in 1/10 Amperes. + required: false + schema: + type: integer + example: 160 + - name: currFs + in: query + description: Current frequency setting. + required: false + schema: + type: integer + example: 0 + - name: pvMode + in: query + description: PV charging mode (0-3). + required: false + schema: + type: integer + example: 2 + - name: pvWbId + in: query + description: PV system ID (0-15). + required: false + schema: + type: integer + example: 1 + - name: pvWatt + in: query + description: Power generated by the PV system in watts. + required: false + schema: + type: integer + example: 4386 + responses: + '200': + description: JSON object containing internal values. + content: + application/json: + schema: + $ref: '#/components/schemas/JsonResponse' + /edit: + get: + tags: + - HTML + summary: List files in LittleFS + description: Displays the list of files stored in the LittleFS. + responses: + '200': + description: List of files. + content: + application/json: + schema: + type: array + items: + type: string + /cfg: + get: + tags: + - API + summary: Get cfg.json content + description: Returns the content of the `cfg.json` file for testing purposes. + responses: + '200': + description: Configuration content in JSON format. + content: + application/json: + schema: + type: object + additionalProperties: true + /reset: + get: + tags: + - System + summary: Trigger system reset + description: Triggers a system reset. + responses: + '200': + description: System resetting, no response content. + content: + text/plain: + schema: + type: string + example: "Resetting the ESP8266..." + /resetwifi: + get: + tags: + - System + summary: Reset WiFi credentials + description: Resets all WiFi credentials (used mainly for testing). + responses: + '200': + description: WiFi credentials reset, no response content. + content: + text/plain: + schema: + type: string + example: "WiFi credentials deleted!" + /status: + get: + tags: + - API + summary: Get system status + description: >- + Provides a subset of values needed for openWB/EVCC integration. Supports + query parameter to access a specific box. + parameters: + - name: box + in: query + description: Zero-based index to directly access a specific box (0-15). + required: false + schema: + type: integer + example: 0 + responses: + '200': + description: Status information in JSON format. + content: + application/json: + schema: + $ref: '#/components/schemas/StatusResponse' + /mqtt: + get: + tags: + - API + summary: Send MQTT command + description: Sends a command via MQTT to control the system or wallbox. + parameters: + - name: payload + in: query + description: Command payload (e.g., `alw=1` to allow charging). + required: false + schema: + type: string + example: alw=1 + - name: box + in: query + description: Zero-based index to access a specific box (0-15). + required: false + schema: + type: integer + example: 0 + responses: + '200': + description: MQTT command executed successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/StatusResponse' + /update: + get: + tags: + - System + summary: Trigger firmware update + description: >- + Starts the firmware update process. In some test versions, available as + `/ota`. + responses: + '200': + description: Firmware update started. + /bootlog: + get: + tags: + - System + summary: Get debug log + description: Returns the current debug buffer. + responses: + '200': + description: Debug log data. + content: + text/plain: + schema: + type: string + /bootlog_reset: + get: + tags: + - System + summary: Clear debug log + description: Clears the current debug buffer. + responses: + '200': + description: Debug buffer cleared. + content: + text/plain: + schema: + type: string + example: "Cleared" + /gpio: + get: + tags: + - API + summary: Get or set GPIO pin D3 + description: Retrieves the status of GPIO pin D3 or allows changing its state. + parameters: + - name: 'on' + in: query + description: Turns on GPIO pin D3. + required: false + schema: + type: boolean + - name: 'off' + in: query + description: Turns off GPIO pin D3. + required: false + schema: + type: boolean + responses: + '200': + description: Status or confirmation of GPIO pin state. + content: + application/json: + schema: + type: object + properties: + D3: + type: integer + description: State of GPIO pin D3 (0 or 1) + example: 1 + D7: + type: integer + description: State of GPIO pin D7 (0 or 1) + example: 0 + text/plain: + schema: + type: string + example: "Not possible, RFID active!" + /pv: + get: + tags: + - API + summary: Get or set PV system data + description: >- + Retrieves or sets current data from the PV system. Supports query + parameters to filter the data. + parameters: + - name: pvMode + in: query + description: PV charging mode (0-3). + required: false + schema: + type: integer + example: 2 + - name: pvWbId + in: query + description: PV system ID (0-15). + required: false + schema: + type: integer + example: 1 + - name: pvWatt + in: query + description: Power generated by the PV system in watts. + required: false + schema: + type: integer + example: 4386 + responses: + '200': + description: PV system data in JSON format. + content: + application/json: + schema: + $ref: '#/components/schemas/PvResponse' + /phaseCtrl: + get: + tags: + - API + summary: Control phases + description: >- + Allows controlling the phases of the system based on the provided + parameter. + parameters: + - name: ph + in: query + description: Phase control value. + required: false + schema: + type: integer + example: 1 + responses: + '200': + description: Confirmation of phase control action. + content: + text/plain: + schema: + type: string + /inverter: + get: + tags: + - API + summary: Get inverter status + description: Retrieves the status of the inverter. + responses: + '200': + description: Inverter status information in JSON format. + content: + application/json: + schema: + type: object + additionalProperties: true + /log.html: + get: + tags: + - HTML + summary: Get logs in HTML + description: Retrieves the load logs in HTML format. + responses: + '200': + description: HTML page displaying the load logs. + content: + text/html: + schema: + type: string + /time.html: + get: + tags: + - HTML + summary: Time control options + description: Displays the time control options for the wallbox. + responses: + '200': + description: HTML page displaying the time control options logs. + content: + text/html: + schema: + type: string + /cfg.html: + get: + tags: + - HTML + summary: Configuration options + description: Displays the configuration options for the wallbox. + responses: + '200': + description: HTML page displaying the configuration options. + content: + text/html: + schema: + type: string + /chargelog: + get: + tags: + - API + summary: Get load logs + description: >- + Retrieves load logs in JSON format. Supports query parameters to filter + the logs. + parameters: + - name: id + in: query + description: Log ID to start retrieving logs from. + required: false + schema: + type: integer + example: 0 + - name: len + in: query + description: Number of logs to retrieve. + required: false + schema: + type: integer + example: 10 + responses: + '200': + description: JSON object containing load logs. + content: + application/json: + schema: + $ref: '#/components/schemas/ChargeLogResponse' +components: + schemas: + StatusResponse: + type: object + properties: + car: + type: string + description: > + Charging state of the vehicle. - "0" means no car is connected. - + "1" means car is connected. + example: '0' + err: + type: string + description: Error code indicating the current error state. + example: '0' + alw: + type: string + description: Allow charging status. + example: '0' + amp: + type: string + description: Current amperage. + example: '0' + stp: + type: string + description: Stop status. + example: '0' + tmp: + type: string + description: Temperature reading. + example: '0' + dws: + type: string + description: Day/night switch status. + example: '0' + ubi: + type: string + description: Ubiquity status. + example: '0' + eto: + type: string + description: Estimated time remaining. + example: '0' + nrg: + type: array + items: + type: integer + description: Array of energy readings. + example: + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + - 0 + fwv: + type: string + description: Firmware version. + example: '40' + JsonResponse: + type: object + properties: + wbec: + $ref: '#/components/schemas/WbecDetails' + box: + type: array + items: + $ref: '#/components/schemas/BoxDetails' + modbus: + $ref: '#/components/schemas/ModbusDetails' + rfid: + $ref: '#/components/schemas/RfidDetails' + pv: + $ref: '#/components/schemas/PvDetails' + wifi: + $ref: '#/components/schemas/WifiDetails' + PvResponse: + type: object + properties: + box: + $ref: '#/components/schemas/BoxDetails' + modbus: + $ref: '#/components/schemas/ModbusDetails' + pv: + $ref: '#/components/schemas/PvDetails' + WbecDetails: + type: object + properties: + version: + type: string + description: wbec version. + example: v0.3.0 + bldDate: + type: string + description: wbec build date. + example: 2021-06-10 + timeNow: + type: string + description: Current time in the system. + example: '20:03:19' + enwg14a: + type: integer + description: Status of §14a EnWG throttling. + example: 0 + enwgErr: + type: integer + description: Error with §14a EnWG functionality. + example: 0 + BoxDetails: + type: object + properties: + busId: + type: integer + description: Modbus bus id (as configured by DIP switches). + example: 1 + version: + type: string + description: | + Modbus Register-Layouts Version, e.g. 1.0.8. + - https://www.amperfied.de/wp-content/uploads/2022/06/ModBus-Register-Tabelle.pdf + - https://www.amperfied.de/wp-content/uploads/2023/03/20220809_AMP-Erweiterte-ModBus-Registerbeschreibung.pdf + example: '108' + chgStat: + type: integer + description: | + Charging State. + - 2: State A1, No Vehicle plugged, Wallbox doesn't allow charging + - 3: State A2, No Vehicle plugged, Wallbox allows charging + - 4: State B1, Vehicle plugged without charging request, Wallbox doesn't allow charging + - 5: State B2, Vehicle plugged without charging request, Wallbox allows charging + - 6: State C1, Vehicle plugged with charging request, Wallbox doesn't allow charging + - 7: State C2, Vehicle plugged with charging request, Wallbox allows charging + - 8 --- Derating + - 9: State E, Error + - 10: State F, Wallbox locked or not ready + - 11 --- Error + example: 2 + currL1: + type: number + description: L1 - Current RMS (in 0.1A). + example: 0 + currL2: + type: number + description: L2 - Current RMS (in 0.1A). + example: 0 + currL3: + type: number + description: L3 - Current RMS (in 0.1A). + example: 0 + pcbTemp: + type: integer + description: PCB temperature (in 0.1°C). + example: 333 + voltL1: + type: integer + description: Voltage L1 - N rms in Volt. + example: 232 + voltL2: + type: integer + description: Voltage L2 - N rms in Volt. + example: 9 + voltL3: + type: integer + description: Voltage L3 - N rms in Volt. + example: 9 + extLock: + type: integer + description: | + Extern lock state. + - 0: System locked + - 1: System unlocked + example: 1 + power: + type: number + description: Power (L1+L2+L3) in VA. + example: 0 + energyP: + type: number + description: Energy since PowerOn (in kWh). + example: 0 + energyI: + type: number + description: Energy since Installation (in kWh). + example: 0.003 + energyC: + type: number + description: Energy since Car is plugged (in kWh). + example: 0 + currMax: + type: number + description: Hardware configuration maximal current (in 0.1A). + example: 16 + currMin: + type: number + description: Hardware configuration minimal current (in 0.1A). + example: 6 + logStr: + type: string + description: Log string in format " ". + example: "00.000.0000/00 0000 000000" + wdTmOut: + type: integer + description: ModBus-Master WatchDog Timeout (in ms). + example: 15000 + standby: + type: integer + description: | + Standby Function Control. + - 0: active + - 4: inactive (recommended) + example: 4 + remLock: + type: integer + description: Remote lock (only if extern lock unlocked). + example: 1 + currLim: + type: number + description: Maximal current command. + example: 130 + currFs: + type: number + description: FailSafe Current configuration. + example: 0 + lmReq: + type: number + description: Load management request. + example: 0 + lmLim: + type: number + description: Load management limit. + example: 0 + load: + type: number + description: wbec load management. + example: 0 + resCode: + type: string + description: Result code of last Modbus message (0 = ok). + example: '0' + failCnt: + type: integer + description: Failure count. + example: 0 + ModbusDetails: + type: object + properties: + state: + type: object + properties: + lastTm: + type: integer + description: Timestamp of last Modbus message (in ms). + example: 2852819 + millis: + type: integer + description: Time since start of wbec (in ms). + example: 2855489 + RfidDetails: + type: object + properties: + enabled: + type: boolean + description: RFID enabled status. + example: false + release: + type: boolean + description: RFID release status. + example: false + lastId: + type: string + description: Last RFID ID. + example: '' + PvDetails: + type: object + properties: + mode: + type: integer + description: PV system mode (0-3). + example: 2 + watt: + type: integer + description: Power generated by the PV system in watts. + example: 4386 + wbId: + type: integer + description: Id of wallbox that is controlled by pv. + example: 1 + batt: + type: number + description: Battery status or charge level. + example: 0 + WifiDetails: + type: object + properties: + mac: + type: string + description: MAC address of the WiFi module. + example: '00:1F:3F:15:29:7E' + rssi: + type: integer + description: WLAN signal strength (in dBm). + example: -76 + signal: + type: integer + description: WiFi signal quality (in %). + example: 48 + channel: + type: integer + description: WiFi channel. + example: 11 + ChargeLogEntry: + type: object + properties: + timestamp: + type: integer + description: Timestamp of the log entry. + example: 1719135780 + duration: + type: integer + description: Duration of the charging session in milliseconds. + example: 22358 + energy: + type: integer + description: Energy consumed in watt-hours. + example: 0 + user: + type: integer + description: User ID or identifier. + example: 0 + box: + type: integer + description: Box identifier. + example: 0 + + ChargeLogResponse: + type: object + properties: + line: + type: array + items: + $ref: '#/components/schemas/ChargeLogEntry'