Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2024-12-24 17:08:15 +01:00
Code Issues Projects Releases Wiki Activity

Document esp8266 & esp32 new platform components (#1540)

Browse Source 
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 2021-10-19 23:08:37 +02:00 committed by Jesse Hills
parent 06d245b3fa
commit 2d1ca74d4f
No known key found for this signature in database
GPG Key ID: BEAAE804EFD8E83A
5 changed files with 152 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

90
components/esp32.rst Normal file
View File

@ -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`

44
components/esp8266.rst Normal file
View File

@ -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`

108
components/esphome.rst
View File

@ -27,19 +27,9 @@ Configuration variables:
- **name** (**Required**, string): This is the name of the node. It - **name** (**Required**, string): This is the name of the node. It
should always be unique in your ESPHome network. May only contain lowercase should always be unique in your ESPHome network. May only contain lowercase
characters, digits and hyphens. See :ref:`esphome-changing_node_name`. 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: 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 - **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>/``, 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. but you can customize this behavior using this option.
@ -61,10 +51,20 @@ Advanced options:
- **name** (**Required**, string): Name of the project - **name** (**Required**, string): Name of the project
- **version** (**Required**, string): Version 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. - **platform** (**Required**, string): The type of platform. One of ``esp8266`` or ``esp32``.
Defaults to ``no``. See :ref:`esphome-esp8266_restore_from_flash` for more info - **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: Automations:
@ -75,86 +75,6 @@ Automations:
- **on_loop** (*Optional*, :ref:`Automation <automation>`): An automation to perform - **on_loop** (*Optional*, :ref:`Automation <automation>`): An automation to perform
on each ``loop()`` iteration. See :ref:`esphome-on_loop`. 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: .. _esphome-on_boot:
``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, 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! 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: .. _esphome-changing_node_name:

8
components/http_request.rst
View File

@ -7,13 +7,7 @@ HTTP Request
:keywords: http, request :keywords: http, request
The ``http_request`` component lets you make HTTP/HTTPS requests. The ``http_request`` component lets you make HTTP/HTTPS requests. First, you need to setup a component:
.. note::
This component works only with :ref:`arduino framework <esphome-arduino_version>` 2.5.0 or newer.
First, you need to setup a component:
.. code-block:: yaml .. code-block:: yaml

3
index.rst
View File

@ -559,6 +559,9 @@ Misc Components
.. imgtable:: .. imgtable::
ESP8266, components/esp8266, esp8266.svg
ESP32, components/esp32, esp32.svg
Remote Receiver, components/remote_receiver, remote.svg Remote Receiver, components/remote_receiver, remote.svg
Remote Transmitter, components/remote_transmitter, remote.svg Remote Transmitter, components/remote_transmitter, remote.svg
Status LED, components/status_led, led-on.svg Status LED, components/status_led, led-on.svg