From 66045c3ad821f4194a1d8b66f78597f1bdbeff25 Mon Sep 17 00:00:00 2001 From: clydebarrow <2366188+clydebarrow@users.noreply.github.com> Date: Thu, 10 Jul 2025 22:10:21 +1000 Subject: [PATCH 1/4] [esp32] Document automatic board config --- components/esp32.rst | 22 ++++++++++++++-------- 1 file changed, 14 insertions(+), 8 deletions(-) diff --git a/components/esp32.rst b/components/esp32.rst index ea7b0e04be..bb779d7ac5 100644 --- a/components/esp32.rst +++ b/components/esp32.rst @@ -11,16 +11,25 @@ This component contains platform-specific options for the ESP32 platform. # Example configuration entry esp32: - board: esp32dev + variant: esp32s3 Configuration variables: ------------------------ -- **board** (**Required**, string): The PlatformIO board ID that should be used. Choose the appropriate board from +- **board** (*Optional*, string): The PlatformIO board ID that should be used. Choose the appropriate board from `this list `__ (the icon next - 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. + to the name can be used to copy the board ID). *This only affects pin aliases and some internal settings*; + if unsure or you cannot find your exact board, use ``variant`` instead. +- **variant** (*Optional*, string): The variant of the ESP32 that is used on this board. One of ``esp32``, + ``esp32s2``, ``esp32s3``, ``esp32c2``, ``esp32c3``, ``esp32c5``, ``esp32c6``, ``esp32h2`` or ``esp32p4``. Defaults + to the variant that is detected from the board; if a board that's unknown to ESPHome is used, this option is mandatory. + + .. note:: + + At least one of ``board`` or ``variant`` must be specified. If ``variant`` alone is specified (the recommended practice), + the board configuration will be automatically filled using a standard Espressif devkit board + suitable for that variant. + - **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.** @@ -28,9 +37,6 @@ Configuration variables: ``360MHz`` or ``400MHz``. Defaults to ``160MHz``. Not all values are available for all chips. - **partitions** (*Optional*, filename): The name of (optionally including the path to) the file containing the partitioning scheme to be used. When not specified, partitions are automatically generated based on ``flash_size``. -- **variant** (*Optional*, string): The variant of the ESP32 that is used on this board. One of ``esp32``, - ``esp32s2``, ``esp32s3``, ``esp32c2``, ``esp32c3``, ``esp32c5``, ``esp32c6``, ``esp32h2`` and ``esp32p4``. 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`. From 5efb9defa576045feccca5db1ddb8df4cf46bb35 Mon Sep 17 00:00:00 2001 From: clydebarrow <2366188+clydebarrow@users.noreply.github.com> Date: Sat, 12 Jul 2025 17:15:03 +1000 Subject: [PATCH 2/4] Make variant the more prominent option. --- components/esp32.rst | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/components/esp32.rst b/components/esp32.rst index bb779d7ac5..2d748e71fe 100644 --- a/components/esp32.rst +++ b/components/esp32.rst @@ -16,19 +16,18 @@ This component contains platform-specific options for the ESP32 platform. Configuration variables: ------------------------ +- **variant** (*Optional*, string): The variant of the ESP32 that is used on this board. One of ``esp32``, + ``esp32s2``, ``esp32s3``, ``esp32c2``, ``esp32c3``, ``esp32c5``, ``esp32c6``, ``esp32h2`` or ``esp32p4``. - **board** (*Optional*, string): The PlatformIO board ID that should be used. Choose the appropriate board from `this list `__ (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 or you cannot find your exact board, use ``variant`` instead. -- **variant** (*Optional*, string): The variant of the ESP32 that is used on this board. One of ``esp32``, - ``esp32s2``, ``esp32s3``, ``esp32c2``, ``esp32c3``, ``esp32c5``, ``esp32c6``, ``esp32h2`` or ``esp32p4``. Defaults - to the variant that is detected from the board; if a board that's unknown to ESPHome is used, this option is mandatory. + This setting is no longer recommended, ``variant`` should be used instead. .. note:: At least one of ``board`` or ``variant`` must be specified. If ``variant`` alone is specified (the recommended practice), the board configuration will be automatically filled using a standard Espressif devkit board - suitable for that variant. + suitable for that variant. Both may be specified (for backwards compatibility) but they must define the same variant. - **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 From e0d004fdd618398e0a43411709717e21ed96c097 Mon Sep 17 00:00:00 2001 From: clydebarrow <2366188+clydebarrow@users.noreply.github.com> Date: Sat, 12 Jul 2025 17:18:37 +1000 Subject: [PATCH 3/4] lint, clarify chip --- components/esp32.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/components/esp32.rst b/components/esp32.rst index 2d748e71fe..6fcfc1da9f 100644 --- a/components/esp32.rst +++ b/components/esp32.rst @@ -16,14 +16,15 @@ This component contains platform-specific options for the ESP32 platform. Configuration variables: ------------------------ -- **variant** (*Optional*, string): The variant of the ESP32 that is used on this board. One of ``esp32``, +- **variant** (*Optional*, string): The ESP32 mcu/chip to use for this device configuration. One of ``esp32``, ``esp32s2``, ``esp32s3``, ``esp32c2``, ``esp32c3``, ``esp32c5``, ``esp32c6``, ``esp32h2`` or ``esp32p4``. + This must match the hardware in use, or it will fail to flash. - **board** (*Optional*, string): The PlatformIO board ID that should be used. Choose the appropriate board from `this list `__ (the icon next to the name can be used to copy the board ID). *This only affects pin aliases and some internal settings*; This setting is no longer recommended, ``variant`` should be used instead. - .. note:: + .. note:: At least one of ``board`` or ``variant`` must be specified. If ``variant`` alone is specified (the recommended practice), the board configuration will be automatically filled using a standard Espressif devkit board From cb558177b8fb0562230da7567d99b0392433a97a Mon Sep 17 00:00:00 2001 From: clydebarrow <2366188+clydebarrow@users.noreply.github.com> Date: Sat, 12 Jul 2025 17:20:26 +1000 Subject: [PATCH 4/4] fix indentation --- components/esp32.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/esp32.rst b/components/esp32.rst index 6fcfc1da9f..7c9e708bf1 100644 --- a/components/esp32.rst +++ b/components/esp32.rst @@ -24,7 +24,7 @@ Configuration variables: to the name can be used to copy the board ID). *This only affects pin aliases and some internal settings*; This setting is no longer recommended, ``variant`` should be used instead. - .. note:: +.. note:: At least one of ``board`` or ``variant`` must be specified. If ``variant`` alone is specified (the recommended practice), the board configuration will be automatically filled using a standard Espressif devkit board