From 5006877514d164a96013b7523002bc248d8374be Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Mon, 21 Oct 2024 07:03:28 +0000 Subject: [PATCH] Add advanced section, organize better --- components/esp32.rst | 86 ++++++++++++++++++++++---------------------- 1 file changed, 44 insertions(+), 42 deletions(-) diff --git a/components/esp32.rst b/components/esp32.rst index f9241421ac..5bdeba2645 100644 --- a/components/esp32.rst +++ b/components/esp32.rst @@ -11,7 +11,7 @@ This component contains platform-specific options for the ESP32 platform. # Example configuration entry esp32: - board: nodemcu-32s + board: esp32dev Configuration variables: ------------------------ @@ -21,8 +21,6 @@ Configuration variables: to the name can be used to copy the board ID). *This only affects pin aliases, flash size and some internal settings*; if unsure or you cannot find your exact board, using a generic board (from Espressif) such as ``esp32dev`` almost always works just fine. -- **framework** (*Optional*): Options for the underlying framework used by ESPHome. See :ref:`esp32-arduino_framework` - and :ref:`esp32-espidf_framework`. - **flash_size** (*Optional*, string): The amount of flash memory available on the ESP32 board/module. One of ``2MB``, ``4MB``, ``8MB``, ``16MB`` or ``32MB``. Defaults to ``4MB``. **Warning: specifying a size larger than that available on your board will cause the ESP32 to fail to boot.** @@ -31,31 +29,8 @@ Configuration variables: - **variant** (*Optional*, string): The variant of the ESP32 that is used on this board. One of ``esp32``, ``esp32s2``, ``esp32s3``, ``esp32c3`` and ``esp32h2``. Defaults to the variant that is detected from the board; if a board that's unknown to ESPHome is used, this option is mandatory. - -GPIO Pin Numbering ------------------- - -The ESP32 boards often use the internal GPIO pin numbering based on the microcontroller, so you likely don't have to -worry about pin alias names or numbering...yay! - -Some notes about the pins on the original ESP32: - -- ``GPIO0`` is used to determine the boot mode on startup; note that **ESP32 variants use differnt pins to determine - the boot mode.** Bootstrapping pin(s) should **not** be pulled LOW on startup to avoid booting into flash mode when - it's not desired. You can, however, still use the strapping pins as output pins. -- ``GPIO34`` to ``GPIO39``: These pins **cannot** be used as outputs (yes, even though GPIO stands for "general purpose - input/**output**"...). -- ``GPIO32`` to ``GPIO39``: These pins can be used with the :doc:`/components/sensor/adc` to measure voltages. -- ``GPIO2``: On the ``esp32dev`` board, this pin is connected to the blue LED. It also supports the - :doc:`touch pad binary sensor ` (in addition to a few other pins). - -.. code-block:: yaml - - # Example configuration entry - binary_sensor: - - platform: gpio - name: "Pin GPIO23" - pin: GPIO23 +- **framework** (*Optional*): Options for the underlying framework used by ESPHome. See :ref:`esp32-arduino_framework` + and :ref:`esp32-espidf_framework`. .. _esp32-arduino_framework: @@ -68,12 +43,12 @@ This is the default framework for ESP32 chips at the moment. # Example configuration entry esp32: - board: esp32dev + board: ... framework: type: arduino Configuration variables: ------------------------- +************************ - **version** (*Optional*, string): The base framework version number to use, from `ESP32 arduino releases `__. Defaults to ``recommended``. @@ -88,10 +63,7 @@ Configuration variables: custom or patched version of the framework. - **platform_version** (*Optional*, string): The version of the `platformio/espressif32 `__ package to use. -- **advanced** (*Optional*, mapping): Advanced options for highly specific tweaks. - - - **ignore_efuse_custom_mac** (*Optional*, boolean): Can be set to ``true`` for devices on which the burned-in custom - MAC address is not valid. +- **advanced** (*Optional*, mapping): See :ref:`esp32-advanced_configuration` below. .. _esp32-espidf_framework: @@ -105,12 +77,12 @@ ESP32S3, ESP32C3 and single-core ESP32 chips. # Example configuration entry esp32: - board: esp32-c3-devkitm-1 + board: ... framework: type: esp-idf Configuration variables: ------------------------- +************************ - **version** (*Optional*, string): The base framework version number to use, from `ESP32 ESP-IDF releases `__. Defaults to ``recommended``. @@ -128,13 +100,43 @@ Configuration variables: - **sdkconfig_options** (*Optional*, mapping): Custom sdkconfig `compiler options `__ to set in the ESP-IDF project. -- **advanced** (*Optional*, mapping): Advanced options for highly specific tweaks. +- **advanced** (*Optional*, mapping): See :ref:`esp32-advanced_configuration` below. + +.. _esp32-advanced_configuration: + +Advanced Configuration +---------------------- + +- **ignore_efuse_custom_mac** (*Optional*, boolean): Can be set to ``true`` for devices on which the burned-in custom + MAC address is not valid. +- **ignore_efuse_mac_crc** (*Optional*, boolean): Can be set to ``true`` for devices on which the burned-in MAC + address is not consistent with the burned-in CRC for that MAC address, resulting in an error like + ``Base MAC address from BLK0 of EFUSE CRC error``. **Valid only on original ESP32 with** ``esp-idf`` **framework.** + +GPIO Pin Numbering +------------------ + +The ESP32 boards often use the internal GPIO pin numbering based on the microcontroller, so you likely don't have to +worry about pin alias names or numbering...yay! + +Some notes about the pins on the original ESP32: + +- ``GPIO0`` is used to determine the boot mode on startup; note that **ESP32 variants use differnt pins to determine + the boot mode.** Bootstrapping pin(s) should **not** be pulled LOW on startup to avoid booting into flash mode when + it's not desired. You can, however, still use the strapping pins as output pins. +- ``GPIO34`` to ``GPIO39``: These pins **cannot** be used as outputs (yes, even though GPIO stands for "general purpose + input/**output**"...). +- ``GPIO32`` to ``GPIO39``: These pins can be used with the :doc:`/components/sensor/adc` to measure voltages. +- ``GPIO2``: On the ``esp32dev`` board, this pin is connected to the blue LED. It also supports the + :doc:`touch pad binary sensor ` (in addition to a few other pins). - - **ignore_efuse_custom_mac** (*Optional*, boolean): Can be set to ``true`` for devices on which the burned-in custom - MAC address is not valid. - - **ignore_efuse_mac_crc** (*Optional*, boolean): Can be set to ``true`` for devices on which the burned-in MAC - address is not consistent with the burned-in CRC for that MAC address, resulting in an error like - ``Base MAC address from BLK0 of EFUSE CRC error``. +.. code-block:: yaml + + # Example configuration entry + binary_sensor: + - platform: gpio + name: "Pin GPIO23" + pin: GPIO23 See Also --------