From 55db2d535c9ebcabaf589652c9952edbce9a7734 Mon Sep 17 00:00:00 2001 From: Andrew Zaborowski Date: Mon, 19 Jul 2021 19:49:52 +0200 Subject: [PATCH] Document the cover REST calls (#1195) Co-authored-by: Franck Nijhof --- web-api/index.rst | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/web-api/index.rst b/web-api/index.rst index 5ffe618af..e09e4d538 100644 --- a/web-api/index.rst +++ b/web-api/index.rst @@ -6,7 +6,7 @@ Web Server API :image: espeasy.png Since version 1.3, ESPHome includes a built-in web server that can be used to view states -and send commands. In addition to visible the web-frontend available under the root index of the +and send commands. In addition to the web-frontend available under the root index of the web server, there's also two other features the web server currently offers: A real time event source and REST API. @@ -213,3 +213,39 @@ and ``/fan//toggle``. Turn on additionally supports these optional parameter - **speed_level**: The new speed level of the fan. Values as above. - **oscillation**: The new oscillation setting of the fan. Values as above. + +Cover +***** + +Covers are again similar to switches whose two possible states are ``OPEN`` and ``CLOSED``. They +can however be in an intermediate position, anywhere between **0.0** (fully closed) to **1.0** +(fully open). They usually take some time to move from one position to another and can also be +stopped midway. An example GET request for ``/cover/front_window_blinds`` might return: + +.. code-block:: json + + { + "id": "cover-front_window_blinds", + "state": "OPEN", + "value": 0.8, + "current_operation": "IDLE", + "tilt": 0.5 + } + +- **id**: The ID of the cover, prefixed with ``cover-``. +- **state**: ``OPEN`` or ``CLOSED``. Any position other than 0.0 is considered open. +- **value**: Current cover position as a float number. +- **current_operation**: ``OPENING``, ``CLOSING`` or ``IDLE``. +- **tilt**: (only if supported by this cover component) tilt angle from 0.0 to 1.0. + +POST requests on the other hand allow performing actions on the cover, the available +methods being ``open``, ``close``, ``stop`` and ``set``. The following parameters +can be used: + +- **position**: The target position for a ``set`` call. The ``open`` method implies + a target position of 1.0, ``close`` implies a target position of 0.0. +- **tilt**: The tilt angle to set, if supported. + +Creating a POST request to ``/cover/front_window_blinds/set?position=0.1&tilt=0.3`` will +start moving the blinds towards an almost completely closed position and a new tilt +angle.