http_request component Docs (#392)

components/esphome.rst

@@ -97,18 +97,20 @@ option you can tell ESPHome which arduino framework to use for compiling.
 For the ESP8266, you currently can manually pin the arduino version to these values (see the full
 list of arduino frameworks `here <https://github.com/esp8266/Arduino/releases>`__):
 
-* `2.5.2 <https://github.com/esp8266/Arduino/releases/tag/2.5.2>`__
+* `2.5.2 <https://github.com/esp8266/Arduino/releases/tag/2.5.2>`__ (default)
 * `2.5.1 <https://github.com/esp8266/Arduino/releases/tag/2.5.1>`__
 * `2.5.0 <https://github.com/esp8266/Arduino/releases/tag/2.5.0>`__
-* `2.4.2 <https://github.com/esp8266/Arduino/releases/tag/2.4.2>`__ (default)
+* `2.4.2 <https://github.com/esp8266/Arduino/releases/tag/2.4.2>`__
 * `2.4.1 <https://github.com/esp8266/Arduino/releases/tag/2.4.1>`__
 * `2.4.0 <https://github.com/esp8266/Arduino/releases/tag/2.4.0>`__
 * `2.3.0 <https://github.com/esp8266/Arduino/releases/tag/2.3.0>`__ (used by Tasmota etc)
 
 For the ESP32, there are these arduino `framework versions <https://github.com/espressif/arduino-esp32/releases>`__:
 
+- `1.0.4 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.4>`__ (default)
+- `1.0.3 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.3>`__
 - `1.0.2 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.2>`__
-- `1.0.1 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.1>`__ (default)
+- `1.0.1 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.1>`__
 - `1.0.0 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.0>`__
 
 .. _esphome-esp8266_restore_from_flash:

components/http_request.rst

@@ -0,0 +1,184 @@
+HTTP Request
+============
+
+.. seo::
+    :description: Instructions for setting up HTTP Requests in ESPHome
+    :image: connection.png
+    :keywords: http, request
+
+
+The ``http_request`` component lets you make HTTP/HTTPS requests.
+
+.. note::
+
+    This component works only with :ref:`arduino framework <esphome-arduino_version>` 2.5.0 or newer.
+
+First, you need to setup a component:
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    http_request:
+      useragent: esphome/device
+      timeout: 10s
+
+Configuration variables:
+------------------------
+
+- **useragent** (*Optional*, string): User-Agent header for requests. Defaults to ``ESPHome``.
+- **timeout** (*Optional*, :ref:`time <config-time>`): Timeout for request. Defaults to ``5s``.
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+
+HTTP Request Actions
+--------------------
+
+Component support a number of :ref:`actions <config-action>` that can be used to send requests.
+
+.. _http_request-get_action:
+
+``http_request.get`` Action
+***************************
+
+This :ref:`action <config-action>` sends a GET request.
+
+.. code-block:: yaml
+
+    on_...:
+      - http_request.get:
+          url: https://esphome.io
+          headers:
+            Content-Type: application/json
+          verify_ssl: false
+      # Short form
+      - http_request.get: https://esphome.io
+
+Configuration variables:
+
+- **url** (**Required**, string, :ref:`templatable <config-templatable>`): URL to send request.
+- **headers** (*Optional*, mapping): Map of HTTP headers. Values are :ref:`templatable <config-templatable>`.
+- **verify_ssl** (*Optional*, boolean): Verify the SSL certificate of the endpoint. Defaults to ``true``.
+
+.. note::
+
+    Currently ESPHome **can't verify the SSL certificate** of the endpoint.
+    Set ``verify_ssl: false`` to make HTTPS request.
+
+.. _http_request-post_action:
+
+``http_request.post`` Action
+****************************
+
+This :ref:`action <config-action>` sends a POST request.
+
+.. code-block:: yaml
+
+    on_...:
+      - http_request.post:
+          url: https://esphome.io
+          headers:
+            Content-Type: application/json
+          json:
+            key: value
+          verify_ssl: false
+      # Short form
+      - http_request.post: https://esphome.io
+
+Configuration variables:
+
+- **body** (*Optional*, string, :ref:`templatable <config-templatable>`): A HTTP body string to send with request.
+- **json** (*Optional*, mapping): A HTTP body in JSON format. Values are :ref:`templatable <config-templatable>`. See :ref:`http_request-examples`.
+- All other options from :ref:`http_request-get_action`.
+
+.. _http_request-send_action:
+
+``http_request.send`` Action
+****************************
+
+This :ref:`action <config-action>` sends a request.
+
+.. code-block:: yaml
+
+    on_...:
+      - http_request.send:
+          method: PUT
+          url: https://esphome.io
+          headers:
+            Content-Type: application/json
+          body: "Some data"
+          verify_ssl: false
+
+Configuration variables:
+
+- **method** (**Required**, string): HTTP method to use (``GET``, ``POST``, ``PUT``, ``DELETE``, ``PATCH``).
+- All other options from :ref:`http_request-post_action`.
+
+.. _http_request-examples:
+
+Examples
+--------
+
+Templatable values
+******************
+
+.. code-block:: yaml
+
+    on_...:
+      - http_request.post:
+          url: !lambda |-
+            return ((std::string) "https://esphome.io?state=" + id(my_sensor).state).c_str();
+          headers:
+            X-Custom-Header: !lambda |-
+              return ((std::string) "Value-" + id(my_sensor).state).c_str();
+          body: !lambda |-
+            return id(my_sensor).state;
+
+
+Body in JSON format (syntax 1)
+******************************
+
+**Note:** all values of the map should be a strings.
+It's impossible to send ``boolean`` or ``numbers`` with this syntax.
+
+.. code-block:: yaml
+
+    on_...:
+      - http_request.post:
+          url: https://esphome.io
+          verify_ssl: false
+          json:
+            key: !lambda |-
+              return id(my_sensor).state;
+            greeting: "Hello World"
+
+        # Will send:
+        # {"key": "42.0", "greeting": "Hello World"}
+
+Body in JSON format (syntax 2)
+******************************
+
+**Note:** use this syntax to send ``boolean`` or ``numbers`` in JSON.
+
+The JSON message will be constructed using the `ArduinoJson <https://github.com/bblanchon/ArduinoJson>`__ library.
+In the ``json`` option you have access to a ``root`` object which will represents the base object
+of the JSON message. You can assign values to keys by using the ``root["KEY_NAME"] = VALUE;`` syntax
+as seen below.
+
+.. code-block:: yaml
+
+    on_...:
+      - http_request.post:
+          url: https://esphome.io
+          verify_ssl: false
+          json: |-
+            root["key"] = id(my_sensor).state;
+            root["greeting"] = "Hello World";
+
+        # Will send:
+        # {"key": 42.0, "greeting": "Hello World"}
+
+See Also
+--------
+
+- :doc:`index`
+- :apiref:`http_request/http_request.h`
+- :ghedit:`Edit`

guides/automations.rst

@@ -367,6 +367,7 @@ All Actions
 - :ref:`uart.write <uart-write_action>`
 - :ref:`sim800l.send_sms <sim800l-send_sms_action>`
 - :ref:`mhz19.calibrate_zero <mhz19-calibrate_zero_action>` / :ref:`mhz19.abc_enable <mhz19-abc_enable_action>` / :ref:`mhz19.abc_disable <mhz19-abc_disable_action>`
+- :ref:`http_request.get <http_request-get_action>` / :ref:`http_request.post <http_request-post_action>` / :ref:`http_request.send <http_request-send_action>`
 
 .. _config-condition:
 

images/connection.svg

@@ -0,0 +1 @@
+<?xml version="1.0" ?><svg height="48" viewBox="0 0 48 48" width="48" xmlns="http://www.w3.org/2000/svg"><path d="M0 0h48v48H0z" fill="none"/><path d="M15.54 13.52l-3.08-2.55L1.64 24l10.82 13.04 3.08-2.55L6.84 24l8.7-10.48zM14 26h4v-4h-4v4zm20-4h-4v4h4v-4zm-12 4h4v-4h-4v4zm13.54-15.04l-3.08 2.55L41.16 24l-8.7 10.48 3.08 2.55L46.36 24 35.54 10.96z"/></svg>

index.rst

@@ -304,6 +304,7 @@ Misc Components
     Remote Receiver, components/remote_receiver, remote.svg
     Remote Transmitter, components/remote_transmitter, remote.svg
     Status LED, components/status_led, led-on.svg
+    HTTP Request, components/http_request, connection.svg
 
     Time, components/time, clock-outline.svg
     Sun, components/sun, weather-sunny.svg