Updates

Author: OttoWinter

changelog/v1.10.0.rst

@@ -55,7 +55,7 @@ of time to find+fix some final bugs.
 
 First, make sure you run at least Home Assistant 0.85.0 (currently a
 `beta release <https://www.home-assistant.io/docs/installation/updating/#run-the-beta-version>`__).
-Then, go through the :ref:`migration guide here <api-mqtt_to_native>`.
+Then, go through the migration guide here (removed).
 
 Python 3 Compatibility
 ----------------------

components/api.rst

@@ -34,91 +34,9 @@ Configuration variables:
 - **reboot_timeout** (*Optional*, :ref:`time <config-time>`): The amount of time to wait before rebooting when no
   client connects to the API. This is needed because sometimes the low level ESP functions report that
   the ESP is connected to the network, when in fact it is not - only a full reboot fixes it.
-  Can be disabled by setting this to ``0s``. Defaults to ``5min``.
+  Can be disabled by setting this to ``0s``. Defaults to ``15min``.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 
-.. _api-mqtt_to_native:
-
-Migrating from MQTT to Native API Setup in Home Assistant
----------------------------------------------------------
-
-The native API is the best way to use ESPHome together with Home Assistant - it's fast,
-highly efficient and requires almost zero setup (whereas MQTT requires you to set up an MQTT broker first).
-
-If you've previously used ESPHome with Home Assistant via MQTT and have enabled MQTT discovery,
-the upgrade process is unfortunately not just swapping out the ``mqtt`` for ``api`` in your configuration:
-Home Assistant's `entity registry <https://developers.home-assistant.io/docs/en/entity_registry_index.html>`__ complicates
-things a bit. If you don't follow these steps, all your new native API entities will have a trailing
-``_2`` at the end of the entity ID.
-
-You can repeat these steps for all your nodes, or convert them over to the new native API one by one.
-
-1. Disable MQTT discovery on ESP side. In your ESPHome configuration, set a special "clean" discovery flag:
-
-  .. code-block:: yaml
-
-      # In your ESPHome configuration! Not HA config!
-      mqtt:
-        # Other settings ...
-        discovery: clean
-
-2. Compile and upload this new firmware. All entities should now be gone from Home Assistant.
-
-3. Go to your Home Assistant configuration folder and go to the ``.storage`` folder (might be hidden
-   depending on your operating system). In there you will find a file called ``core.entity_registry`` - open
-   the file with a text editor and paste the contents below
-
-
-   .. raw:: html
-
-       <textarea rows="10" cols="50" id="entity-reg-converter"></textarea>
-       <button type="button" id="entity-reg-button">Convert Entity Registry</button>
-       <script>
-         var elem = document.getElementById("entity-reg-converter");
-         elem.addEventListener("click", function() {
-           elem.focus();
-           elem.select();
-         });
-         document.getElementById("entity-reg-button").addEventListener("click", function() {
-           try {
-             data = JSON.parse(elem.value);
-           } catch(e) {
-             alert(e);
-           }
-           var entities = data.data.entities;
-           var newEntities = [];
-           for (var i = 0; i < entities.length; i++) {
-             var entity = entities[i];
-             if (entity.platform != "mqtt") {
-               newEntities.push(entity);
-             }
-           }
-           data.data.entities = newEntities;
-           elem.value = JSON.stringify(data, null, 4);
-         });
-       </script>
-
-4. Stop Home Assistant - this is necessary for the entity registry changes not to become overriden.
-
-5. Convert the Entity Registry file above using the "Convert Entity Registry Button", and
-   override the ``.storage/core.entity_registry`` file with the new contents.
-
-6. Start Home Assistant.
-
-7. Now you can enable the ESPHome native API (and upload the new firmware)
-
-  .. code-block:: yaml
-
-      # Example configuration entry
-      api:
-
-8. In Home Assistant, go to "Configuration" -> "Integrations" - if you've set up the ``discovery:`` component,
-   you'll already see the ESP as a suggestion to be configured. But if you're having issues with that, you can
-   always manually set up an ESPHome device using "Set up a new integration" -> "ESPHome".
-
-9. Now you can remove ``mqtt:`` from your ESPHome configuration. You don't have to, but doing so will
-   free up resources (of which these ESPs don't have too much).
-
 .. _api-homeassistant_service_action:
 
 ``homeassistant.service`` Action
@@ -220,6 +138,11 @@ There are currently 4 types of variables:
 - float: A floating point number. C++ type: ``float``
 - string: A string. C++ type: ``std::string``
 
+Each of these also exist in array form:
+
+- bool[]: An array of boolean values. C++ type: ``std::vector<bool>``
+- ... - Same for other types.
+
 .. _api-connected_condition:
 
 ``api.connected`` Condition
@@ -257,6 +180,34 @@ never be removed. Features of native API (vs. MQTT):
 - **Low Latency:** The native API is optimized for very low latency, usually this is only
   a couple of milliseconds and far less than can be noticed by the eye.
 
+
+.. _api-homeassistant_event_action:
+
+``homeassistant.event`` Action
+------------------------------
+
+When using the native API with Home Assistant, you can create events in the Home Assistant event bus
+straight from ESPHome :ref:`Automations <automation>`.
+
+.. code-block:: yaml
+
+    # In some trigger
+    on_...:
+      # Simple
+      - homeassistant.event:
+          event: esphome.button_pressed
+          data:
+            title: Button was pressed
+
+Configuration options:
+
+- **event** (**Required**, string): The event to create - must begin with ``esphome.``
+- **data** (*Optional*, mapping): Optional *static* data to pass along with the event.
+- **data_template** (*Optional*, mapping): Optional template data to pass along with the event.
+  This is evaluated on the Home Assistant side with Home Assistant's templating engine.
+- **variables** (*Optional*, mapping): Optional variables that can be used in the ``data_template``.
+  Values are :ref:`lambdas <config-lambda>` and will be evaluated before sending the request.
+
 See Also
 --------
 

components/captive_portal.rst

@@ -0,0 +1,46 @@
+Captive Portal
+==============
+
+.. seo::
+    :description: Instructions for setting up the Captive Portal fallback mechanism in ESPHome.
+    :image: wifi-strength-alert-outline.png
+
+The captive portal component in ESPHome is a fallback mechanism for when connecting to the
+configured :doc:`WiFi <wifi>` fails.
+
+After 1 minute of unsuccesful wifi connection attempts, the ESP will start a WiFi hotspot
+(with the credentials from your configuration)
+
+.. figure:: images/captive_portal-ui.png
+    :align: center
+    :width: 70.0%
+
+In this web interface, you can manually override the WiFi settings of the device (please note
+this will be overwritten by any subsequent upload, so make sure to also update your YAML configuration).
+
+Additionally, you can upload a new firmware file.
+
+When you connect to the fallback network, the web interface should open automatically (see also
+login to network notifications). If that does not work, you can also navigate to http://192.168.4.1/
+manually in your browser.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    wifi:
+      # ...
+      ap:
+        ssid: "Livingroom Fallback Hotspot"
+        password: "W1PBGyrokfLz"
+
+    captive_portal:
+
+
+No configuration variables.
+
+See Also
+--------
+
+- :doc:`wifi`
+- :apiref:`captive_portal/captive_portal.h`
+- :ghedit:`Edit`

components/images/captive_portal-ui.png

@@ -60,7 +60,7 @@ Configuration variables:
   for verifying SSL connections. See :ref:`mqtt-ssl_fingerprints`
   for more information.
 - **reboot_timeout** (*Optional*, :ref:`time <config-time>`): The amount of time to wait before rebooting when no
-  MQTT connection exists. Can be disabled by setting this to ``0s``. Defaults to ``5min``.
+  MQTT connection exists. Can be disabled by setting this to ``0s``. Defaults to ``15min``.
 - **keepalive** (*Optional*, :ref:`config-time`): The time
   to keep the MQTT socket alive, decreasing this can help with overall stability due to more
   WiFi traffic with more pings. Defaults to 15 seconds.

components/mqtt.rst

@@ -33,6 +33,9 @@ Configuration variables:
 
 - **address** (**Required**, int): The i²c address of the sensor.
   See :ref:`I²C Addresses <ads1115_i2c_addresses>` for more information.
+- **continuous_mode** (*Optional*, boolean): Set if the ADS1115 should continuously measure voltages or
+  only measure them when an update is called. Please enable this for the :doc:`ct_clamp` integration.
+  Defaults to ``off``.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID for this ADS1115 Hub. Use this if you
   want to use multiple ADS1115 hubs at once.
 

components/sensor/ads1115.rst

@@ -360,12 +360,6 @@ Configuration variables:
 
   - All options from :ref:`Sensor <config-sensor>`.
 
-.. note::
-
-    The ``id()`` wrapper for ESPHome-lambdas is not available in custom code. However, in most
-    cases you can drop the ``id()`` wrapper and use the ID directly: ``id(my_var).state`` ->
-    ``my_var->state``
-
 Logging in Custom Components
 ----------------------------
 

components/sensor/custom.rst

@@ -152,6 +152,7 @@ the value the sensor shows.
     - platform: dht
       # ...
       temperature:
+        name: "DHT22 Temperature"
         filters:
           - calibrate_linear:
               # Map 0.0 (from sensor) to 0.0 (true value)
@@ -162,6 +163,30 @@ The arguments are a list of data points, each in the form ``MEASURED -> TRUTH``.
 then fit a linear equation to the values (using least squares). So you need to supply at least
 two values.
 
+``calibrate_polynomial``
+************************
+
+Calibrate your sensor values by fitting them to a polynomial functions. This is similar to
+the ``calibrate_linear`` filter, but also allows for higher-order functions like quadratic polynomials.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    - platform: adc
+      # ...
+      filters:
+        - calibrate_polynomial:
+           degree: 2
+           datapoints:
+            # Map 0.0 (from sensor) to 0.0 (true value)
+            - 0.0 -> 0.0
+            - 10.0 -> 12.1
+            - 13.0 -> 14.0
+
+The arguments are a list of data points, each in the form ``MEASURED -> TRUTH``. Additionally, you need
+to specify the degree of the resulting polynomial, the datapoints will then be fitted to the given
+degree with a least squares solver.
+
 ``filter_out``
 **************
 

components/sensor/index.rst

@@ -56,14 +56,16 @@ Configuration variables:
     Defaults to 1.
   - **manual_ip** (*Optional*): Manually set the IP options for the AP. Same options as
     manual_ip for station mode.
+  - **ap_timeout** (*Optional*, :ref:`time <config-time>`): The time after which to enable the
+    configured fallback hotspot. Defaults to ``1min``.
 
 - **domain** (*Optional*, string): Set the domain of the node hostname used for uploading.
   For example, if it's set to ``.local``, all uploads will be sent to ``<HOSTNAME>.local``.
   Defaults to ``.local``.
 - **reboot_timeout** (*Optional*, :ref:`time <config-time>`): The amount of time to wait before rebooting when no
   WiFi connection exists. Can be disabled by setting this to ``0s``, but note that the low level IP stack currently
-  seems to have issues with WiFi where a full reboot is required to get the interface back working. Defaults to ``5min``.
-- **power_save_mode** (*Optional*, string): The power save mode for the WiFi interface. Defaults to no power saving.
+  seems to have issues with WiFi where a full reboot is required to get the interface back working. Defaults to ``15min``.
+- **power_save_mode** (*Optional*, string): The power save mode for the WiFi interface.
   See :ref:`wifi-power_save_mode`
 
 - **fast_connect** (*Optional*, boolean): If enabled, directly connects to WiFi network without doing a full scan
@@ -126,11 +128,8 @@ WiFi. While some options *can* reduce the power usage of the ESP, they generally
 reliability of the WiFi connection, with frequent disconnections from the router in the highest
 power saving mode.
 
-The default is ``none`` (a bit of power saving). If you experience frequent WiFi disconnection problems,
-please also try ``light``.
-
-- ``NONE`` (least power saving, Default)
-- ``LIGHT``
+- ``NONE`` (least power saving, Default for ESP8266)
+- ``LIGHT`` (Default for ESP32)
 - ``HIGH`` (most power saving)
 
 .. code-block:: yaml
@@ -192,5 +191,6 @@ This :ref:`Condition <config-condition>` checks if the WiFi client is currently
 See Also
 --------
 
+- :doc:`captive_portal`
 - :apiref:`wifi/wifi_component.h`
 - :ghedit:`Edit`

components/wifi.rst

@@ -307,6 +307,8 @@ There is one caveat though: ESPHome automatically reboots if no connection to th
 made. This is because the ESPs typically have issues in their network stacks that require a reboot to fix.
 You can adjust this behavior (or even disable automatic rebooting) using the ``reboot_timeout`` option
 in the :doc:`wifi component </components/wifi>` and :doc:`mqtt component </components/mqtt>`.
+(Beware that effectively disables the reboot watchdog, so you will need to power cycle the device
+if it fails to connect to the network without a reboot)
 
 All Triggers
 ------------

guides/automations.rst

@@ -11,7 +11,16 @@ ESPHome's command line interface always has the following format
 
 .. code-block:: console
 
-    esphome <CONFIGURATION> <COMMAND> [ARGUMENTS]
+    esphome <CONFIGURATION...> <COMMAND> [ARGUMENTS]
+
+.. note::
+
+    You can specify multiple configuration files in the command line interface,
+    just list all files in front of the <COMMAND> like so:
+
+    .. code-block:: console
+
+        esphome livingroom.yaml kitchen.yaml run
 
 
 ``run`` Command

guides/cli.rst

@@ -300,6 +300,8 @@ Misc Components
     PCF8574 I/O Expander, components/pcf8574, pcf8574.jpg
     MCP23017 I/O Expander, components/mcp23017, mcp23017.svg
     SIM800L, components/sim800l, sim800l.jpg
+
+    Captive Portal, components/captive_portal, wifi-strength-alert-outline.svg
     Debug Component, components/debug, bug-report.svg
 
 Additional Custom Components

images/wifi-strength-alert-outline.svg

@@ -7,9 +7,12 @@ def setup(app):
     app.connect('html-page-context', add_html_link)
     app.connect('build-finished', create_sitemap)
     app.sitemap_links = []
+
+    is_production = os.getenv('PRODUCTION') == 'YES'
+
     return {"version": "1.0.0",
             "parallel_read_safe": True,
-            "parallel_write_safe": True}
+            "parallel_write_safe": not is_production}
 
 
 def add_html_link(app, pagename, templatename, context, doctree):