Update documentation for custom MAC support on Arduino (#4358)

esphome · Oct 21, 2024 · 8a6a7bb · 8a6a7bb
1 parent 0da104b
commit 8a6a7bb
Showing 1 changed file with 44 additions and 46 deletions.
diff --git 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 </components/binary_sensor/esp32_touch>` (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,13 +43,12 @@ This is the default framework for ESP32 chips at the moment.
 
     # Example configuration entry
     esp32:
-      board: nodemcu-32s
+      board: ...
       framework:
         type: arduino
-        version: 2.0.0
 
 Configuration variables:
-------------------------
+************************
 
 - **version** (*Optional*, string): The base framework version number to use, from
   `ESP32 arduino releases <https://github.com/espressif/arduino-esp32/releases>`__. Defaults to ``recommended``.
@@ -89,6 +63,7 @@ Configuration variables:
   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.
+- **advanced** (*Optional*, mapping): See :ref:`esp32-advanced_configuration` below.
 
 .. _esp32-espidf_framework:
 
@@ -102,19 +77,12 @@ ESP32S3, ESP32C3 and single-core ESP32 chips.
 
     # Example configuration entry
     esp32:
-      board: esp32-c3-devkitm-1
+      board: ...
       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 <https://github.com/espressif/esp-idf/releases>`__. Defaults to ``recommended``.
@@ -132,13 +100,43 @@ Configuration variables:
 - **sdkconfig_options** (*Optional*, mapping): Custom sdkconfig
   `compiler options <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/kconfig.html#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
+------------------
 
-  - **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``.
+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 </components/binary_sensor/esp32_touch>` (in addition to a few other pins).
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    binary_sensor:
+      - platform: gpio
+        name: "Pin GPIO23"
+        pin: GPIO23
 
 See Also
 --------