From 49840ed4fa630bec9b9dfb6c956e97daac80e7fe Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@home-assistant.io>
Date: Thu, 29 Jan 2026 17:18:42 -0600
Subject: [PATCH] [logger] Fix USB Serial JTAG VFS linker errors when using
 UART on IDF

---
 esphome/components/esp32/__init__.py  | 26 +++++++++++++++++++++-----
 esphome/components/logger/__init__.py |  8 ++++++++
 2 files changed, 29 insertions(+), 5 deletions(-)

diff --git a/esphome/components/esp32/__init__.py b/esphome/components/esp32/__init__.py
index 1d7ea5395fb..c2c694d9513 100644
--- a/esphome/components/esp32/__init__.py
+++ b/esphome/components/esp32/__init__.py
@@ -739,9 +739,10 @@ CONF_DISABLE_REGI2C_IN_IRAM = "disable_regi2c_in_iram"
 CONF_DISABLE_FATFS = "disable_fatfs"
 
 # VFS requirement tracking
-# Components that need VFS features can call require_vfs_select() or require_vfs_dir()
+# Components that need VFS features can call require_vfs_*() functions
 KEY_VFS_SELECT_REQUIRED = "vfs_select_required"
 KEY_VFS_DIR_REQUIRED = "vfs_dir_required"
+KEY_VFS_TERMIOS_REQUIRED = "vfs_termios_required"
 # Feature requirement tracking - components can call require_* functions to re-enable
 # These are stored in CORE.data[KEY_ESP32] dict
 KEY_USB_SERIAL_JTAG_SECONDARY_REQUIRED = "usb_serial_jtag_secondary_required"
@@ -768,6 +769,15 @@ def require_vfs_dir() -> None:
     CORE.data[KEY_VFS_DIR_REQUIRED] = True
 
 
+def require_vfs_termios() -> None:
+    """Mark that VFS termios support is required by a component.
+
+    Call this from components that use terminal I/O functions (usb_serial_jtag_vfs_*, etc.).
+    This prevents CONFIG_VFS_SUPPORT_TERMIOS from being disabled.
+    """
+    CORE.data[KEY_VFS_TERMIOS_REQUIRED] = True
+
+
 def require_full_certificate_bundle() -> None:
     """Request the full certificate bundle instead of the common-CAs-only bundle.
 
@@ -1372,11 +1382,17 @@ async def to_code(config):
         add_idf_sdkconfig_option("CONFIG_LIBC_LOCKS_PLACE_IN_IRAM", False)
 
     # Disable VFS support for termios (terminal I/O functions)
-    # ESPHome doesn't use termios functions on ESP32 (only used in host UART driver).
+    # USB Serial JTAG VFS functions require termios support.
+    # Components that need it (e.g., logger with USB_SERIAL_JTAG) call require_vfs_termios().
     # Saves approximately 1.8KB of flash when disabled (default).
-    add_idf_sdkconfig_option(
-        "CONFIG_VFS_SUPPORT_TERMIOS", not advanced[CONF_DISABLE_VFS_SUPPORT_TERMIOS]
-    )
+    if CORE.data.get(KEY_VFS_TERMIOS_REQUIRED, False):
+        # Component requires VFS termios - force enable regardless of user setting
+        add_idf_sdkconfig_option("CONFIG_VFS_SUPPORT_TERMIOS", True)
+    else:
+        # No component needs it - allow user to control (default: disabled)
+        add_idf_sdkconfig_option(
+            "CONFIG_VFS_SUPPORT_TERMIOS", not advanced[CONF_DISABLE_VFS_SUPPORT_TERMIOS]
+        )
 
     # Disable VFS support for select() with file descriptors
     # ESPHome only uses select() with sockets via lwip_select(), which still works.
diff --git a/esphome/components/logger/__init__.py b/esphome/components/logger/__init__.py
index cadd0a14ae9..40ceaec7dc6 100644
--- a/esphome/components/logger/__init__.py
+++ b/esphome/components/logger/__init__.py
@@ -16,6 +16,8 @@ from esphome.components.esp32 import (
     VARIANT_ESP32S3,
     add_idf_sdkconfig_option,
     get_esp32_variant,
+    require_usb_serial_jtag_secondary,
+    require_vfs_termios,
 )
 from esphome.components.libretiny import get_libretiny_component, get_libretiny_family
 from esphome.components.libretiny.const import (
@@ -397,9 +399,15 @@ async def to_code(config):
         elif config[CONF_HARDWARE_UART] == USB_SERIAL_JTAG:
             add_idf_sdkconfig_option("CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG", True)
             cg.add_define("USE_LOGGER_UART_SELECTION_USB_SERIAL_JTAG")
+    # Define platform support flags for components that need auto-detection
     try:
         uart_selection(USB_SERIAL_JTAG)
         cg.add_define("USE_LOGGER_USB_SERIAL_JTAG")
+        # USB Serial JTAG code is compiled when platform supports it.
+        # Enable secondary USB serial JTAG console so the VFS functions are available.
+        if CORE.is_esp32 and config[CONF_HARDWARE_UART] != USB_SERIAL_JTAG:
+            require_usb_serial_jtag_secondary()
+            require_vfs_termios()
     except cv.Invalid:
         pass
     try: