Document esp8266 & esp32 new platform components (#1540)
Co-authored-by: Oxan van Leeuwen <oxan@oxanvanleeuwen.nl> Co-authored-by: Guillermo Ruffino <glm.net@gmail.com> Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
This commit is contained in:
Otto Winter
Jesse Hills
parent
06d245b3fa
commit
2d1ca74d4f
|
|
@ -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 <https://platformio.org/boards?count=1000&filter%5Bplatform%5D=espressif32>`__.
|
||||
*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 <https://github.com/espressif/arduino-esp32/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 <https://github.com/platformio/platform-espressif32/releases/>`__ 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 <https://github.com/espressif/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 <https://github.com/platformio/platform-espressif32/releases/>`__ package to use.
|
||||
- **sdkconfig_options** (*Optional*, mapping): Custom sdkconfig options to set in the ESP-IDF project.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :doc:`esphome`
|
||||
- :ghedit:`Edit`
|
||||
|
|
@ -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 <https://platformio.org/boards?count=1000&filter%5Bplatform%5D=espressif8266>`__.
|
||||
*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 <https://github.com/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 <https://github.com/platformio/platform-espressif8266/releases/>`__ 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`
|
||||
|
|
@ -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 <https://platformio.org/boards?count=1000&filter%5Bplatform%5D=espressif8266>`__ for the ESP8266, and
|
||||
`this list <https://platformio.org/boards?count=1000&filter%5Bplatform%5D=espressif32>`__ 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 ``<NODE_NAME>/``,
|
||||
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 </components/esp32>` and :doc:`esp8266 </components/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 </components/esp32>` and :doc:`esp8266 </components/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 <https://platformio.org/boards?count=1000&filter%5Bplatform%5D=espressif8266>`__ for the ESP8266, and
|
||||
`this list <https://platformio.org/boards?count=1000&filter%5Bplatform%5D=espressif32>`__ 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 <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 <https://github.com/esp8266/Arduino/releases>`__):
|
||||
|
||||
* `3.0.1 <https://github.com/esp8266/Arduino/releases/tag/3.0.1>`__ (not recommended yet)
|
||||
* `3.0.0 <https://github.com/esp8266/Arduino/releases/tag/3.0.0>`__ (not recommended yet)
|
||||
* `2.7.4 <https://github.com/esp8266/Arduino/releases/tag/2.7.4>`__ (default)
|
||||
* `2.7.3 <https://github.com/esp8266/Arduino/releases/tag/2.7.3>`__
|
||||
* `2.7.2 <https://github.com/esp8266/Arduino/releases/tag/2.7.2>`__
|
||||
* `2.7.1 <https://github.com/esp8266/Arduino/releases/tag/2.7.1>`__
|
||||
* `2.7.0 <https://github.com/esp8266/Arduino/releases/tag/2.7.0>`__
|
||||
* `2.6.3 <https://github.com/esp8266/Arduino/releases/tag/2.6.3>`__
|
||||
* `2.6.2 <https://github.com/esp8266/Arduino/releases/tag/2.6.2>`__
|
||||
* `2.6.1 <https://github.com/esp8266/Arduino/releases/tag/2.6.1>`__
|
||||
* `2.5.2 <https://github.com/esp8266/Arduino/releases/tag/2.5.2>`__
|
||||
* `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>`__
|
||||
* `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>`__
|
||||
|
||||
For the ESP32, there are these Arduino `framework versions <https://github.com/espressif/arduino-esp32/releases>`__:
|
||||
|
||||
- `1.0.6 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.6>`__ (default)
|
||||
- `1.0.5 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.5>`__
|
||||
- `1.0.4 <https://github.com/espressif/arduino-esp32/releases/tag/1.0.4>`__
|
||||
- `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>`__
|
||||
- `1.0.0 <https://github.com/espressif/arduino-esp32/releases/tag/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 </components/esp8266>`, ``restore_from_flash`` must also be set to ``true`` for states to be written to flash.
|
||||
|
||||
.. _esphome-changing_node_name:
|
||||
|
||||
|
|
|
|||
|
|
@ -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 <esphome-arduino_version>` 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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue