From 3fe87688d92d7272ecd969aa24b9ac7c42e2d841 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Wed, 16 Sep 2026 18:31:27 -0500
Subject: [PATCH] [esp32] Enable octal flash when the flash mode is opi
 (#19218)

---
 esphome/components/esp32/__init__.py          |  9 ++++++++
 .../esp32/config/flash_mode_opi_s3.yaml       |  8 +++++++
 tests/component_tests/esp32/test_esp32.py     | 22 +++++++++++++++++++
 3 files changed, 39 insertions(+)
 create mode 100644 tests/component_tests/esp32/config/flash_mode_opi_s3.yaml

diff --git a/esphome/components/esp32/__init__.py b/esphome/components/esp32/__init__.py
index de25afa23be..0c5b9c5df6a 100644
--- a/esphome/components/esp32/__init__.py
+++ b/esphome/components/esp32/__init__.py
@@ -1519,6 +1519,13 @@ def final_validate(config) -> None:
                 path=[CONF_FRAMEWORK, CONF_ADVANCED, CONF_MINIMUM_CHIP_REVISION],
             )
         )
+    if config[CONF_VARIANT] != VARIANT_ESP32S3 and config.get(CONF_FLASH_MODE) == "opi":
+        errs.append(
+            cv.Invalid(
+                f"'{CONF_FLASH_MODE}: opi' is only supported on {VARIANT_ESP32S3}",
+                path=[CONF_FLASH_MODE],
+            )
+        )
     if config[CONF_VARIANT] != VARIANT_ESP32 and advanced[CONF_SRAM1_AS_IRAM]:
         errs.append(
             cv.Invalid(
@@ -2732,6 +2739,8 @@ async def to_code(config):
         add_idf_sdkconfig_option(
             f"CONFIG_ESPTOOLPY_FLASHMODE_{flash_mode.upper()}", True
         )
+        # the opi mode choice only exists once octal flash is enabled
+        add_idf_sdkconfig_option("CONFIG_ESPTOOLPY_OCT_FLASH", flash_mode == "opi")
     if flash_frequency := config.get(CONF_FLASH_FREQUENCY):
         add_idf_sdkconfig_option(
             f"CONFIG_ESPTOOLPY_FLASHFREQ_{flash_frequency[:-3]}M", True
diff --git a/tests/component_tests/esp32/config/flash_mode_opi_s3.yaml b/tests/component_tests/esp32/config/flash_mode_opi_s3.yaml
new file mode 100644
index 00000000000..82262f63493
--- /dev/null
+++ b/tests/component_tests/esp32/config/flash_mode_opi_s3.yaml
@@ -0,0 +1,8 @@
+esphome:
+  name: test
+
+esp32:
+  variant: esp32s3
+  flash_mode: opi
+  framework:
+    type: esp-idf
diff --git a/tests/component_tests/esp32/test_esp32.py b/tests/component_tests/esp32/test_esp32.py
index 777759e8afc..d5d0acfb2ad 100644
--- a/tests/component_tests/esp32/test_esp32.py
+++ b/tests/component_tests/esp32/test_esp32.py
@@ -252,6 +252,16 @@ def test_esp32_rejects_unsupported_cli_toolchain(
             r"value must be at most 5 .* @ data\['framework'\]\['advanced'\]\['nvs_encryption'\]\['key_id'\]",
             id="nvs_encryption_key_id_out_of_range",
         ),
+        pytest.param(
+            {
+                "variant": "esp32",
+                "board": "esp32dev",
+                "flash_mode": "opi",
+                "framework": {"type": "esp-idf"},
+            },
+            r"'flash_mode: opi' is only supported on ESP32S3 @ data\['flash_mode'\]",
+            id="flash_mode_opi_only_on_s3",
+        ),
     ],
 )
 def test_esp32_configuration_errors(
@@ -704,10 +714,22 @@ def test_flash_mode_sets_sdkconfig_and_pio_option(
     sdkconfig = CORE.data[KEY_ESP32][KEY_SDKCONFIG_OPTIONS]
     assert sdkconfig.get("CONFIG_ESPTOOLPY_FLASHMODE_QIO") is True
     assert sdkconfig.get("CONFIG_ESPTOOLPY_FLASHFREQ_80M") is True
+    assert sdkconfig.get("CONFIG_ESPTOOLPY_OCT_FLASH") is False
     assert CORE.platformio_options.get("board_build.flash_mode") == "qio"
     assert CORE.platformio_options.get("board_build.f_flash") == "80000000L"
 
 
+def test_flash_mode_opi_enables_octal_flash(
+    generate_main: Callable[[str | Path], str],
+    component_config_path: Callable[[str], Path],
+) -> None:
+    """flash_mode: opi needs the octal flash switch or ESP-IDF ignores the mode."""
+    generate_main(component_config_path("flash_mode_opi_s3.yaml"))
+    sdkconfig = CORE.data[KEY_ESP32][KEY_SDKCONFIG_OPTIONS]
+    assert sdkconfig.get("CONFIG_ESPTOOLPY_FLASHMODE_OPI") is True
+    assert sdkconfig.get("CONFIG_ESPTOOLPY_OCT_FLASH") is True
+
+
 def test_flash_mode_unset_leaves_defaults(
     generate_main: Callable[[str | Path], str],
     component_config_path: Callable[[str], Path],