diff --git a/Doxygen b/Doxygen index d0c2d0c72..bd12c6690 100644 --- a/Doxygen +++ b/Doxygen @@ -38,7 +38,7 @@ PROJECT_NAME = "ESPHome" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 2021.10.0b7 +PROJECT_NUMBER = 2021.10.0b8 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/Makefile b/Makefile index 4411bda1b..6cc855e5f 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2021.10.0b7 +ESPHOME_REF = 2021.10.0b8 .PHONY: html html-strict cleanhtml deploy help webserver Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify diff --git a/_static/version b/_static/version index d3a4267ae..e56d4fc4d 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2021.10.0b7 \ No newline at end of file +2021.10.0b8 \ No newline at end of file diff --git a/changelog/2021.10.0.rst b/changelog/2021.10.0.rst index 20e982be8..3c96c5130 100644 --- a/changelog/2021.10.0.rst +++ b/changelog/2021.10.0.rst @@ -178,6 +178,8 @@ Beta Fixes - Fix Bluetooth setup_priorities :esphomepr:`2458` by :ghuser:`jesserockz` - Autodetect ESP32 variant :esphomepr:`2530` by :ghuser:`oxan` - OTA firmware MD5 check + password support for esp-idf :esphomepr:`2507` by :ghuser:`mmakaay` (new-integration) +- Fix ADC pin validation on ESP32-C3 :esphomepr:`2551` by :ghuser:`oxan` +- ignore exception when not waiting for a response :esphomepr:`2552` by :ghuser:`martgras` All changes ^^^^^^^^^^^ @@ -375,6 +377,8 @@ All changes - Fix Bluetooth setup_priorities :esphomepr:`2458` by :ghuser:`jesserockz` - Autodetect ESP32 variant :esphomepr:`2530` by :ghuser:`oxan` - OTA firmware MD5 check + password support for esp-idf :esphomepr:`2507` by :ghuser:`mmakaay` (new-integration) +- Fix ADC pin validation on ESP32-C3 :esphomepr:`2551` by :ghuser:`oxan` +- ignore exception when not waiting for a response :esphomepr:`2552` by :ghuser:`martgras` Past Changelogs --------------- diff --git a/components/esp32.rst b/components/esp32.rst new file mode 100644 index 000000000..9d70e2b05 --- /dev/null +++ b/components/esp32.rst @@ -0,0 +1,90 @@ +ESP32 Platform +============== + +.. seo:: + :description: Configuration for the ESP32 platform for ESPHome. + :image: esp32.png + +This component contains platform-specific options for the ESP32 platform. + +.. code-block:: yaml + + # Example configuration entry + esp32: + board: nodemcu-32s + +Configuration variables: +------------------------ + +- **board** (**Required**, string): The PlatformIO board ID that should + be used. Choose the appropriate board from + `this list `__. + *This only affects pin aliases, flash size and some internal settings*, if unsure choose a generic board. +- **framework** (*Optional*): Options for the underlying framework used by ESPHome. + See :ref:`esp32-arduino_framework` and :ref:`esp32-espidf_framework`. + +- **variant** (*Optional*, boolean): Defaults to the variant detected from the board. If the board is not known this option becomes mandatory. + One of ``esp32``, ``esp32s2``, ``esp32s3``, ``esp32c3`` and ``esp32h2``. + +.. _esp32-arduino_framework: + +Arduino framework +----------------- + +This is the default framework for ESP32 chips at the moment. + +.. code-block:: yaml + + # Example configuration entry + esp32: + board: nodemcu-32s + framework: + type: arduino + version: 2.0.0 + +- **version** (*Optional*, string): The base framework version number to use, from + `ESP32 arduino releases `__. Defaults to ``recommended``. Additional values are: + + - ``dev``: Use the latest commit from https://github.com/espressif/arduino-esp32, note this may break at any time + - ``latest``: Use the latest *release* from https://github.com/espressif/arduino-esp32/releases, even if it hasn't been recommended yet. + - ``recommended``: Use the recommended framework version. + +- **source** (*Optional*, string): The PlatformIO package or repository to use for framework. This can be used to use a custom or patched version of the framework. +- **platform_version** (*Optional*, string): The version of the `platformio/espressif32 `__ package to use. + +.. _esp32-espidf_framework: + +ESP-IDF framework +----------------- + +This is an alternative base framework for ESP32 chips, and recommended for variants +of the ESP32 like ESP32S2, ESP32S3, ESP32C3 and single-core ESP32 chips. + +.. code-block:: yaml + + # Example configuration entry + esp32: + board: esp32-c3-devkitm-1 + framework: + type: esp-idf + version: recommended + # Custom sdkconfig options + sdkconfig_options: + CONFIG_COMPILER_OPTIMIZATION_SIZE: y + +- **version** (*Optional*, string): The base framework version number to use, from + `ESP32 ESP-IDF releases `__. Defaults to ``recommended``. Additional values are: + + - ``dev``: Use the latest commit from https://github.com/espressif/esp-idf, note this may break at any time + - ``latest``: Use the latest *release* from https://github.com/espressif/esp-idf/releases, even if it hasn't been recommended yet. + - ``recommended``: Use the recommended framework version. + +- **source** (*Optional*, string): The PlatformIO package or repository to use for the framework. This can be used to use a custom or patched version of the framework. +- **platform_version** (*Optional*, string): The version of the `platformio/espressif32 `__ package to use. +- **sdkconfig_options** (*Optional*, mapping): Custom sdkconfig options to set in the ESP-IDF project. + +See Also +-------- + +- :doc:`esphome` +- :ghedit:`Edit` diff --git a/components/esp8266.rst b/components/esp8266.rst new file mode 100644 index 000000000..be11a4b5d --- /dev/null +++ b/components/esp8266.rst @@ -0,0 +1,44 @@ +ESP8266 Platform +================ + +.. seo:: + :description: Configuration for the ESP8266 platform for ESPHome. + :image: esp8266.png + +This component contains platform-specific options for the ESP8266 platform. + +.. code-block:: yaml + + # Example configuration entry + esp8266: + board: nodemcuv2 + framework: + version: recommended + +Configuration variables: +------------------------ + +- **board** (**Required**, string): The PlatformIO board ID that should + be used. Choose the appropriate board from + `this list `__. + *This only affects pin aliases, flash size and some internal settings*, if unsure choose a generic board. +- **framework** (*Optional*): Options for the underlying framework used by ESPHome. + + - **version** (*Optional*, string): The base framework version number to use, from + `esp8266 arduino releases `__. Defaults to ``recommended``. Additional values + + - ``dev``: Use the latest commit from https://github.com/esp8266/Arduino, note this may break at any time + - ``latest``: Use the latest *release* from https://github.com/esp8266/Arduino/releases, even if it hasn't been recommended yet. + - ``recommended``: Use the recommended framework version. + + - **source** (*Optional*, string): The PlatformIO package or repository to use for the framework. This can be used to use a custom or patched version of the framework. + - **platform_version** (*Optional*, string): The version of the `platformio/espressif8266 `__ package to use. + +- **restore_from_flash** (*Optional*, boolean): Whether to store some persistent preferences in flash memory. Defaults to ``false``. +- **board_flash_mode** (*Optional*, string): The SPI mode of the flash chip. One of ``qio``, ``qout``, ``dio`` and ``dout``. Defaults to ``dout`` for compatibility with all chips. Note: on the next OTA update the actual flash mode is automatically detected and changed to the appropriate one. + +See Also +-------- + +- :doc:`esphome` +- :ghedit:`Edit` diff --git a/components/esphome.rst b/components/esphome.rst index 0217da043..5a413afa5 100644 --- a/components/esphome.rst +++ b/components/esphome.rst @@ -27,19 +27,9 @@ Configuration variables: - **name** (**Required**, string): This is the name of the node. It should always be unique in your ESPHome network. May only contain lowercase characters, digits and hyphens. See :ref:`esphome-changing_node_name`. -- **platform** (**Required**, string): The platform your board is using, - either ``ESP32`` or ``ESP8266``. -- **board** (**Required**, string): The PlatformIO board ID that should - be used. Choose the appropriate board from - `this list `__ for the ESP8266, and - `this list `__ for the ESP32 (the icon - next to the name can be used to copy the board ID). *This only affects pin aliases and some internal settings*, - if unsure choose a generic board from Espressif. Advanced options: -- **arduino_version** (*Optional*): The version of the Arduino framework to link the project against. - See :ref:`esphome-arduino_version`. - **build_path** (*Optional*, string): Customize where ESPHome will store the build files for your node. By default, ESPHome puts all PlatformIO project files under a folder ``/``, but you can customize this behavior using this option. @@ -61,10 +51,20 @@ Advanced options: - **name** (**Required**, string): Name of the project - **version** (**Required**, string): Version of the project -ESP8266 Options: +Platform options that have been moved (now in platform-specific sections :doc:`esp32 ` and :doc:`esp8266 `): -- **esp8266_restore_from_flash** (*Optional*, boolean): Whether to save & restore data from flash on ESP8266s. - Defaults to ``no``. See :ref:`esphome-esp8266_restore_from_flash` for more info +- **platform** (**Required**, string): The type of platform. One of ``esp8266`` or ``esp32``. +- **board** (**Required**, string): The board that should be used. See + :doc:`esp32 ` and :doc:`esp8266 ` for more information. +- **arduino_version** (*Optional*): The version of the Arduino framework to compile the project against. +- **esp8266_restore_from_flash** (*Optional*, boolean): For ESP8266s, whether to store some persistent preferences in flash + memory. + +Choose the appropriate board from + `this list `__ for the ESP8266, and + `this list `__ for the ESP32 (the icon + next to the name can be used to copy the board ID). *This only affects pin aliases and some internal settings*, + if unsure choose a generic board from Espressif. Automations: @@ -75,86 +75,6 @@ Automations: - **on_loop** (*Optional*, :ref:`Automation `): An automation to perform on each ``loop()`` iteration. See :ref:`esphome-on_loop`. -.. _esphome-arduino_version: - -``arduino_version`` -------------------- - -ESPHome uses the Arduino framework internally to handle all low-level interactions like -initializing the WiFi driver and so on. Unfortunately, every Arduino framework version often -has its own quirks and bugs, especially concerning WiFi performance. With the ``arduino_version`` -option you can tell ESPHome which Arduino framework to use for compiling. - -.. code-block:: yaml - - # Example configuration entry - esphome: - # ... - # Default: use the recommended version, usually this equals - # the latest version. - arduino_version: recommended - - # Use the latest stable version - arduino_version: latest - - # Use the latest staged version from GitHub, try this if you have WiFi problems - arduino_version: dev - - # Use a specific version - arduino_version: 2.3.0 - -For the ESP8266, you currently can manually pin the Arduino version to these values (see the full -list of Arduino frameworks `here `__): - -* `3.0.1 `__ (not recommended yet) -* `3.0.0 `__ (not recommended yet) -* `2.7.4 `__ (default) -* `2.7.3 `__ -* `2.7.2 `__ -* `2.7.1 `__ -* `2.7.0 `__ -* `2.6.3 `__ -* `2.6.2 `__ -* `2.6.1 `__ -* `2.5.2 `__ -* `2.5.1 `__ -* `2.5.0 `__ -* `2.4.2 `__ -* `2.4.1 `__ -* `2.4.0 `__ -* `2.3.0 `__ - -For the ESP32, there are these Arduino `framework versions `__: - -- `1.0.6 `__ (default) -- `1.0.5 `__ -- `1.0.4 `__ -- `1.0.3 `__ -- `1.0.2 `__ -- `1.0.1 `__ -- `1.0.0 `__ - -.. _esphome-esp8266_restore_from_flash: - -``esp8266_restore_from_flash`` ------------------------------- - -With this option you can control where the state of certain components is kept on the ESP. -Components like ``light``, ``switch``, ``fan`` and ``globals`` can restore their state upon -boot. - -However, by default this data is stored in the "RTC memory" section of the ESP8266s. This memory -is cleared when the ESP8266 is disconnected from power. So by default the state cannot be recovered -after power loss. - -To still have these components restore their state upon power loss the state can additionally be -saved in *flash* memory by setting this option to ``true``. - -Beware: The flash has a limited number of write cycles (usually around 100 000), after that -the flash section will fail. So do not use this option when you have components that update rapidly. -These include GPIO switches that are used internally (disable restoring with the ``restore_mode`` option), -certain light effects like ``random`` and the ``on_value_range`` trigger. - .. _esphome-on_boot: ``on_boot`` @@ -304,7 +224,7 @@ results in fewer flash writes, preserving the flash health. This behavior can be disabled by setting ``flash_write_interval`` to ``0s`` to immediately commit the state to flash, however, be aware that this may lead to increased flash wearing and a shortened device lifespan! -For ESP8266, :ref:`esphome-esp8266_restore_from_flash` must also be set to true for states to be written to flash. +For :doc:`ESP8266 `, ``restore_from_flash`` must also be set to ``true`` for states to be written to flash. .. _esphome-changing_node_name: diff --git a/components/http_request.rst b/components/http_request.rst index 5a81090b9..107580cdb 100644 --- a/components/http_request.rst +++ b/components/http_request.rst @@ -7,13 +7,7 @@ HTTP Request :keywords: http, request -The ``http_request`` component lets you make HTTP/HTTPS requests. - -.. note:: - - This component works only with :ref:`arduino framework ` 2.5.0 or newer. - -First, you need to setup a component: +The ``http_request`` component lets you make HTTP/HTTPS requests. First, you need to setup a component: .. code-block:: yaml diff --git a/components/sensor/uptime.rst b/components/sensor/uptime.rst index 04dc86209..58fbff2d0 100644 --- a/components/sensor/uptime.rst +++ b/components/sensor/uptime.rst @@ -56,10 +56,10 @@ with human readable output. int minutes = seconds / 60; seconds = seconds % 60; return ( - (days ? String(days) + "d " : "") + - (hours ? String(hours) + "h " : "") + - (minutes ? String(minutes) + "m " : "") + - (String(seconds) + "s") + (days ? to_string(days) + "d " : "") + + (hours ? to_string(hours) + "h " : "") + + (minutes ? to_string(minutes) + "m " : "") + + (to_string(seconds) + "s") ).c_str(); See Also diff --git a/conf.py b/conf.py index 29ebc0848..1835713fe 100644 --- a/conf.py +++ b/conf.py @@ -69,7 +69,7 @@ author = "Otto Winter" # The short X.Y version. version = "2021.10" # The full version, including alpha/beta/rc tags. -release = "2021.10.0b7" +release = "2021.10.0b8" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/guides/configuration-types.rst b/guides/configuration-types.rst index 402e4e4f1..c75032db6 100644 --- a/guides/configuration-types.rst +++ b/guides/configuration-types.rst @@ -75,39 +75,41 @@ In some places, ESPHome also supports a more advanced “pin schema”. pin: number: D0 inverted: true - mode: INPUT_PULLUP + mode: + input: true + pullup: true Configuration variables: - **number** (**Required**, pin): The pin number. - **inverted** (*Optional*, boolean): If all read and written values should be treated as inverted. Defaults to ``false``. -- **mode** (*Optional*, string): A pin mode to set for the pin at - startup, corresponds to Arduino’s ``pinMode`` call. +- **mode** (*Optional*, string or mapping): Configures the pin to behave in different + modes like input or output. The default value depends on the context. + Accepts either a shorthand string or a mapping where each feature can be individually + enabled/disabled: -Available Pin Modes: + - **input** (*Optional*, boolean): If true, configure the pin as an input. + - **output** (*Optional*, boolean): If true, configure the pin as an output. + - **pullup** (*Optional*, boolean): Activate internal pullup resistors on the pin. + - **pulldown** (*Optional*, boolean): Activate internal pulldown resistors on the pin. + - **open_drain** (*Optional*, boolean): Set the pin to open-drain (as opposed to push-pull). + The active pin state will then result in a high-impedance state. -- ``INPUT`` -- ``OUTPUT`` -- ``OUTPUT_OPEN_DRAIN`` -- ``ANALOG`` (only on ESP32) -- ``INPUT_PULLUP`` -- ``INPUT_PULLDOWN`` (only on ESP32) -- ``INPUT_PULLDOWN_16`` (only on ESP8266 and only on GPIO16) + For compatibility some shorthand modes can also be used. -More exotic Pin Modes are also supported, but rarely used: + - ``INPUT`` + - ``OUTPUT`` + - ``OUTPUT_OPEN_DRAIN`` + - ``ANALOG`` + - ``INPUT_PULLUP`` + - ``INPUT_PULLDOWN`` -- ``WAKEUP_PULLUP`` (only on ESP8266) -- ``WAKEUP_PULLDOWN`` (only on ESP8266) -- ``SPECIAL`` -- ``FUNCTION_0`` (only on ESP8266) -- ``FUNCTION_1`` -- ``FUNCTION_2`` -- ``FUNCTION_3`` -- ``FUNCTION_4`` -- ``FUNCTION_5`` (only on ESP32) -- ``FUNCTION_6`` (only on ESP32) +Advanced options: +- **drive_strength** (*Optional*, string): On ESP32s with esp-idf framework the pad drive strength, + i.e. the maximum amount of current can additionally be set. Defaults to ``20mA``. + Options are ``5mA``, ``10mA``, ``20mA``, ``40mA``. .. _config-time: diff --git a/guides/supporters.rst b/guides/supporters.rst index df448131d..4100fbae2 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -742,4 +742,4 @@ Contributors - `ZTX18 (@ZTX18) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated October 19, 2021.* +*This page was last updated October 20, 2021.* diff --git a/index.rst b/index.rst index 381b5ab8d..330bff03b 100644 --- a/index.rst +++ b/index.rst @@ -559,6 +559,9 @@ Misc Components .. imgtable:: + ESP8266, components/esp8266, esp8266.svg + ESP32, components/esp32, esp32.svg + Remote Receiver, components/remote_receiver, remote.svg Remote Transmitter, components/remote_transmitter, remote.svg Status LED, components/status_led, led-on.svg