From 2d1ca74d4f2f060378d53aea89ae58c71f0ebb9e Mon Sep 17 00:00:00 2001 From: Otto Winter Date: Tue, 19 Oct 2021 23:08:37 +0200 Subject: [PATCH] Document esp8266 & esp32 new platform components (#1540) Co-authored-by: Oxan van Leeuwen Co-authored-by: Guillermo Ruffino Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com> --- components/esp32.rst | 90 ++++++++++++++++++++++++++++++ components/esp8266.rst | 44 +++++++++++++++ components/esphome.rst | 108 +++++------------------------------- components/http_request.rst | 8 +-- index.rst | 3 + 5 files changed, 152 insertions(+), 101 deletions(-) create mode 100644 components/esp32.rst create mode 100644 components/esp8266.rst 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/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