REST: Add batterymode-endpoint (#750)

Co-authored-by: Michael Geers <[email protected]>

Author: Maschga

package.json

@@ -13,7 +13,8 @@
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
     "serve": "docusaurus serve",
-    "format": "prettier --write . && node src/sortOpenAPI.js",
+    "format": "prettier --write . && npm run sort",
+    "sort": "node src/sortOpenAPI.js",
     "write-translations": "docusaurus write-translations",
     "write-heading-ids": "docusaurus write-heading-ids"
   },

static/rest-api.yaml

@@ -147,6 +147,26 @@ paths:
       responses:
         "200":
           $ref: "#/components/responses/NumberResult"
+  /batterymode:
+    delete:
+      summary: Disable external battery control
+      description: Default evcc control behavior is restored
+      tags:
+        - Home Battery
+      responses:
+        "200":
+          $ref: "#/components/responses/BatteryModeResult"
+  /batterymode/{batteryMode}:
+    post:
+      summary: Set external battery mode
+      description: Directly controls the mode of all controllable batteries. evcc behavior like "price limit" or "prevent discharge while fast charging" is overruled. External mode resets after 60s. The external system has to call this endpoint regularly.
+      tags:
+        - Home Battery
+      parameters:
+        - $ref: "#/components/parameters/batteryMode"
+      responses:
+        "200":
+          $ref: "#/components/responses/BatteryModeResult"
   /buffersoc/{soc}:
     post:
       summary: Set battery buffer SoC
@@ -966,6 +986,15 @@ paths:
                     $ref: "#/components/schemas/StaticSocPlan"
 components:
   schemas:
+    BatteryMode:
+      description: TODO
+      type: string
+      example: normal
+      enum:
+        - unknown
+        - normal
+        - hold
+        - charge
     ChangePassword:
       type: object
       properties:
@@ -1335,6 +1364,12 @@ components:
       required: true
       schema:
         $ref: "#/components/schemas/Power"
+    batteryMode:
+      name: batteryMode
+      in: path
+      required: true
+      schema:
+        $ref: "#/components/schemas/BatteryMode"
     costLimit:
       name: cost
       description: Cost limit in configured currency (default EUR) or CO2 limit in g/kWh
@@ -1445,6 +1480,18 @@ components:
             type: string
             enum:
               - Unauthorized
+    BatteryModeResult:
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              result:
+                type: integer
+                description: |
+                  Battery mode. 0: unknown, 1: normal, 2: hold, 3: charge
+                minimum: 0
+                maximum: 3
   securitySchemes:
     cookieAuth:
       type: apiKey