From 9ea7645b345077565b19e433200f3dd45b235232 Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Mon, 21 Oct 2024 17:56:37 -0500 Subject: [PATCH] Update documentation for custom MAC support on Arduino (#4358) --- components/esp32.rst | 170 +++++++++++++++++++++---------------------- 1 file changed, 84 insertions(+), 86 deletions(-) diff --git a/components/esp32.rst b/components/esp32.rst index 5e6b4e8a0..5bdeba264 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,6 +29,89 @@ 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. +- **framework** (*Optional*): Options for the underlying framework used by ESPHome. See :ref:`esp32-arduino_framework` + and :ref:`esp32-espidf_framework`. + +.. _esp32-arduino_framework: + +Arduino framework +----------------- + +This is the default framework for ESP32 chips at the moment. + +.. code-block:: yaml + + # Example configuration entry + esp32: + board: ... + framework: + type: arduino + +Configuration variables: +************************ + +- **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. +- **advanced** (*Optional*, mapping): See :ref:`esp32-advanced_configuration` below. + +.. _esp32-espidf_framework: + +ESP-IDF framework +----------------- + +This is an alternative base framework for ESP32 chips; it is recommended for variants of the ESP32 like ESP32S2, +ESP32S3, ESP32C3 and single-core ESP32 chips. + +.. code-block:: yaml + + # Example configuration entry + esp32: + 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``. + 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 + `compiler options `__ + to set in the ESP-IDF project. +- **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 ------------------ @@ -57,89 +138,6 @@ Some notes about the pins on the original ESP32: name: "Pin GPIO23" pin: GPIO23 -.. _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 - -Configuration variables: ------------------------- - -- **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; it is 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: - COMPILER_OPTIMIZATION_SIZE: y - # Advanced tweaking options - advanced: - ignore_efuse_mac_crc: false - -Configuration variables: ------------------------- - -- **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 - `compiler options `__ - to set in the ESP-IDF project. -- **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. - - **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``. - See Also --------