diff --git a/changelog/v1.10.0.rst b/changelog/v1.10.0.rst index d12d28d91..fec041d1b 100644 --- a/changelog/v1.10.0.rst +++ b/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 `__). -Then, go through the :ref:`migration guide here `. +Then, go through the migration guide here (removed). Python 3 Compatibility ---------------------- diff --git a/components/api.rst b/components/api.rst index 834950401..6f45b8d24 100644 --- a/components/api.rst +++ b/components/api.rst @@ -34,91 +34,9 @@ Configuration variables: - **reboot_timeout** (*Optional*, :ref:`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 `__ 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 - - - - - -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`` +- ... - 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 `. + +.. 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 ` and will be evaluated before sending the request. + See Also -------- diff --git a/components/captive_portal.rst b/components/captive_portal.rst new file mode 100644 index 000000000..29caa5aa7 --- /dev/null +++ b/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 ` 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` diff --git a/components/images/captive_portal-ui.png b/components/images/captive_portal-ui.png new file mode 100644 index 000000000..f77d0e0c1 Binary files /dev/null and b/components/images/captive_portal-ui.png differ diff --git a/components/mqtt.rst b/components/mqtt.rst index 186f43397..01c781b9b 100644 --- a/components/mqtt.rst +++ b/components/mqtt.rst @@ -60,7 +60,7 @@ Configuration variables: for verifying SSL connections. See :ref:`mqtt-ssl_fingerprints` for more information. - **reboot_timeout** (*Optional*, :ref:`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. diff --git a/components/sensor/ads1115.rst b/components/sensor/ads1115.rst index f7bb323af..24dc20702 100644 --- a/components/sensor/ads1115.rst +++ b/components/sensor/ads1115.rst @@ -33,6 +33,9 @@ Configuration variables: - **address** (**Required**, int): The i²c address of the sensor. See :ref:`I²C 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. diff --git a/components/sensor/custom.rst b/components/sensor/custom.rst index 2cefca6bd..6ae96ac74 100644 --- a/components/sensor/custom.rst +++ b/components/sensor/custom.rst @@ -360,12 +360,6 @@ Configuration variables: - All options from :ref:`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 ---------------------------- diff --git a/components/sensor/index.rst b/components/sensor/index.rst index 6efdfa873..d82095cd5 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.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`` ************** diff --git a/components/wifi.rst b/components/wifi.rst index 7d85e782e..fafb4e1f6 100644 --- a/components/wifi.rst +++ b/components/wifi.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 `): 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 ``.local``. Defaults to ``.local``. - **reboot_timeout** (*Optional*, :ref:`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 ` checks if the WiFi client is currently See Also -------- +- :doc:`captive_portal` - :apiref:`wifi/wifi_component.h` - :ghedit:`Edit` diff --git a/guides/automations.rst b/guides/automations.rst index 9ac3e87f4..92f83f971 100644 --- a/guides/automations.rst +++ b/guides/automations.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 ` and :doc:`mqtt component `. +(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 ------------ diff --git a/guides/cli.rst b/guides/cli.rst index 3d3c5034e..31462c6c0 100644 --- a/guides/cli.rst +++ b/guides/cli.rst @@ -11,7 +11,16 @@ ESPHome's command line interface always has the following format .. code-block:: console - esphome [ARGUMENTS] + esphome [ARGUMENTS] + +.. note:: + + You can specify multiple configuration files in the command line interface, + just list all files in front of the like so: + + .. code-block:: console + + esphome livingroom.yaml kitchen.yaml run ``run`` Command diff --git a/images/wifi-strength-alert-outline.svg b/images/wifi-strength-alert-outline.svg new file mode 100644 index 000000000..303d91b3c --- /dev/null +++ b/images/wifi-strength-alert-outline.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/index.rst b/index.rst index acc11755a..ca70dde00 100644 --- a/index.rst +++ b/index.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 diff --git a/sitemap.py b/sitemap.py index ba8738bba..6878b12b5 100644 --- a/sitemap.py +++ b/sitemap.py @@ -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):