[core] fix upload to device via MQTT IP lookup (e.g. when mDNS is disable) (#10632)

Co-authored-by: J. Nick Koston <nick@koston.org> Co-authored-by: J. Nick Koston <nick@home-assistant.io> Co-authored-by: J. Nick Koston <nick+github@koston.org>
2025-09-27 07:32:22 +01:00 · 2025-09-12 23:31:53 +02:00
parent 24eb33a1c0
commit d3592c451b
3 changed files with 547 additions and 187 deletions
--- a/esphome/main.py
+++ b/esphome/main.py
@@ -15,9 +15,11 @@ import argcomplete

 from esphome import const, writer, yaml_util
 import esphome.codegen as cg
+from esphome.components.mqtt import CONF_DISCOVER_IP
 from esphome.config import iter_component_configs, read_config, strip_default_ids
 from esphome.const import (
    ALLOWED_NAME_CHARS,
+    CONF_API,
    CONF_BAUD_RATE,
    CONF_BROKER,
    CONF_DEASSERT_RTS_DTR,
@@ -43,6 +45,7 @@ from esphome.const import (
    SECRETS_FILES,
 )
 from esphome.core import CORE, EsphomeError, coroutine
+from esphome.enum import StrEnum
 from esphome.helpers import get_bool_env, indent, is_ip_address
 from esphome.log import AnsiFore, color, setup_log
 from esphome.types import ConfigType
@@ -106,13 +109,15 @@ def choose_prompt(options, purpose: str = None):
    return options[opt - 1][1]


+class Purpose(StrEnum):
+    UPLOADING = "uploading"
+    LOGGING = "logging"
+
+
 def choose_upload_log_host(
    default: list[str] | str | None,
    check_default: str | None,
-    show_ota: bool,
-    show_mqtt: bool,
-    show_api: bool,
-    purpose: str | None = None,
+    purpose: Purpose,
 ) -> list[str]:
    # Convert to list for uniform handling
    defaults = [default] if isinstance(default, str) else default or []
@@ -132,13 +137,30 @@ def choose_upload_log_host(
                ]
                resolved.append(choose_prompt(options, purpose=purpose))
            elif device == "OTA":
-                if CORE.address and (
-                    (show_ota and "ota" in CORE.config)
-                    or (show_api and "api" in CORE.config)
+                # ensure IP adresses are used first
+                if is_ip_address(CORE.address) and (
+                    (purpose == Purpose.LOGGING and has_api())
+                    or (purpose == Purpose.UPLOADING and has_ota())
                ):
                    resolved.append(CORE.address)
-                elif show_mqtt and has_mqtt_logging():
-                    resolved.append("MQTT")
+
+                if purpose == Purpose.LOGGING:
+                    if has_api() and has_mqtt_ip_lookup():
+                        resolved.append("MQTTIP")
+
+                    if has_mqtt_logging():
+                        resolved.append("MQTT")
+
+                    if has_api() and has_non_ip_address():
+                        resolved.append(CORE.address)
+
+                elif purpose == Purpose.UPLOADING:
+                    if has_ota() and has_mqtt_ip_lookup():
+                        resolved.append("MQTTIP")
+
+                    if has_ota() and has_non_ip_address():
+                        resolved.append(CORE.address)
+
            else:
                resolved.append(device)
        if not resolved:
@@ -149,39 +171,111 @@ def choose_upload_log_host(
    options = [
        (f"{port.path} ({port.description})", port.path) for port in get_serial_ports()
    ]
-    if (show_ota and "ota" in CORE.config) or (show_api and "api" in CORE.config):
-        options.append((f"Over The Air ({CORE.address})", CORE.address))
-    if show_mqtt and has_mqtt_logging():
-        mqtt_config = CORE.config[CONF_MQTT]
-        options.append((f"MQTT ({mqtt_config[CONF_BROKER]})", "MQTT"))
+
+    if purpose == Purpose.LOGGING:
+        if has_mqtt_logging():
+            mqtt_config = CORE.config[CONF_MQTT]
+            options.append((f"MQTT ({mqtt_config[CONF_BROKER]})", "MQTT"))
+
+        if has_api():
+            if has_resolvable_address():
+                options.append((f"Over The Air ({CORE.address})", CORE.address))
+            if has_mqtt_ip_lookup():
+                options.append(("Over The Air (MQTT IP lookup)", "MQTTIP"))
+
+    elif purpose == Purpose.UPLOADING and has_ota():
+        if has_resolvable_address():
+            options.append((f"Over The Air ({CORE.address})", CORE.address))
+        if has_mqtt_ip_lookup():
+            options.append(("Over The Air (MQTT IP lookup)", "MQTTIP"))

    if check_default is not None and check_default in [opt[1] for opt in options]:
        return [check_default]
    return [choose_prompt(options, purpose=purpose)]


-def mqtt_logging_enabled(mqtt_config):
+def has_mqtt_logging() -> bool:
+    """Check if MQTT logging is available."""
+    if CONF_MQTT not in CORE.config:
+        return False
+
+    mqtt_config = CORE.config[CONF_MQTT]
+
+    # enabled by default
+    if CONF_LOG_TOPIC not in mqtt_config:
+        return True
+
    log_topic = mqtt_config[CONF_LOG_TOPIC]
    if log_topic is None:
        return False
+
    if CONF_TOPIC not in log_topic:
        return False
-    return log_topic.get(CONF_LEVEL, None) != "NONE"
+
+    return log_topic[CONF_LEVEL] != "NONE"


-def has_mqtt_logging() -> bool:
-    """Check if MQTT logging is available."""
-    return (mqtt_config := CORE.config.get(CONF_MQTT)) and mqtt_logging_enabled(
-        mqtt_config
-    )
+def has_mqtt() -> bool:
+    """Check if MQTT is available."""
+    return CONF_MQTT in CORE.config
+
+
+def has_api() -> bool:
+    """Check if API is available."""
+    return CONF_API in CORE.config
+
+
+def has_ota() -> bool:
+    """Check if OTA is available."""
+    return CONF_OTA in CORE.config
+
+
+def has_mqtt_ip_lookup() -> bool:
+    """Check if MQTT is available and IP lookup is supported."""
+    if CONF_MQTT not in CORE.config:
+        return False
+    # Default Enabled
+    if CONF_DISCOVER_IP not in CORE.config[CONF_MQTT]:
+        return True
+    return CORE.config[CONF_MQTT][CONF_DISCOVER_IP]
+
+
+def has_mdns() -> bool:
+    """Check if MDNS is available."""
+    return CONF_MDNS not in CORE.config or not CORE.config[CONF_MDNS][CONF_DISABLED]
+
+
+def has_non_ip_address() -> bool:
+    """Check if CORE.address is set and is not an IP address."""
+    return CORE.address is not None and not is_ip_address(CORE.address)
+
+
+def has_ip_address() -> bool:
+    """Check if CORE.address is a valid IP address."""
+    return CORE.address is not None and is_ip_address(CORE.address)
+
+
+def has_resolvable_address() -> bool:
+    """Check if CORE.address is resolvable (via mDNS or is an IP address)."""
+    return has_mdns() or has_ip_address()
+
+
+def mqtt_get_ip(config: ConfigType, username: str, password: str, client_id: str):
+    from esphome import mqtt
+
+    return mqtt.get_esphome_device_ip(config, username, password, client_id)
+
+
+_PORT_TO_PORT_TYPE = {
+    "MQTT": "MQTT",
+    "MQTTIP": "MQTTIP",
+}


 def get_port_type(port: str) -> str:
    if port.startswith("/") or port.startswith("COM"):
        return "SERIAL"
-    if port == "MQTT":
-        return "MQTT"
-    return "NETWORK"
+    return _PORT_TO_PORT_TYPE.get(port, "NETWORK")


 def run_miniterm(config: ConfigType, port: str, args) -> int:
@@ -439,23 +533,9 @@ def upload_program(
    password = ota_conf.get(CONF_PASSWORD, "")
    binary = args.file if getattr(args, "file", None) is not None else CORE.firmware_bin

-    # Check if we should use MQTT for address resolution
-    # This happens when no device was specified, or the current host is "MQTT"/"OTA"
-    if (
-        CONF_MQTT in config  # pylint: disable=too-many-boolean-expressions
-        and (not devices or host in ("MQTT", "OTA"))
-        and (
-            ((config[CONF_MDNS][CONF_DISABLED]) and not is_ip_address(CORE.address))
-            or get_port_type(host) == "MQTT"
-        )
-    ):
-        from esphome import mqtt
-
-        devices = [
-            mqtt.get_esphome_device_ip(
-                config, args.username, args.password, args.client_id
-            )
-        ]
+    # MQTT address resolution
+    if get_port_type(host) in ("MQTT", "MQTTIP"):
+        devices = mqtt_get_ip(config, args.username, args.password, args.client_id)

    return espota2.run_ota(devices, remote_port, password, binary)

@@ -476,20 +556,28 @@ def show_logs(config: ConfigType, args: ArgsProtocol, devices: list[str]) -> int
    if get_port_type(port) == "SERIAL":
        check_permissions(port)
        return run_miniterm(config, port, args)
-    if get_port_type(port) == "NETWORK" and "api" in config:
-        addresses_to_use = devices
-        if config[CONF_MDNS][CONF_DISABLED] and CONF_MQTT in config:
-            from esphome import mqtt

-            mqtt_address = mqtt.get_esphome_device_ip(
+    port_type = get_port_type(port)
+
+    # Check if we should use API for logging
+    if has_api():
+        addresses_to_use: list[str] | None = None
+
+        if port_type == "NETWORK" and (has_mdns() or is_ip_address(port)):
+            addresses_to_use = devices
+        elif port_type in ("NETWORK", "MQTT", "MQTTIP") and has_mqtt_ip_lookup():
+            # Only use MQTT IP lookup if the first condition didn't match
+            # (for MQTT/MQTTIP types, or for NETWORK when mdns/ip check fails)
+            addresses_to_use = mqtt_get_ip(
                config, args.username, args.password, args.client_id
-            )[0]
-            addresses_to_use = [mqtt_address]
+            )

-        from esphome.components.api.client import run_logs
+        if addresses_to_use is not None:
+            from esphome.components.api.client import run_logs

-        return run_logs(config, addresses_to_use)
-    if get_port_type(port) in ("NETWORK", "MQTT") and "mqtt" in config:
+            return run_logs(config, addresses_to_use)
+
+    if port_type in ("NETWORK", "MQTT") and has_mqtt_logging():
        from esphome import mqtt

        return mqtt.show_logs(
@@ -555,10 +643,7 @@ def command_upload(args: ArgsProtocol, config: ConfigType) -> int | None:
    devices = choose_upload_log_host(
        default=args.device,
        check_default=None,
-        show_ota=True,
-        show_mqtt=False,
-        show_api=False,
-        purpose="uploading",
+        purpose=Purpose.UPLOADING,
    )

    exit_code, _ = upload_program(config, args, devices)
@@ -583,10 +668,7 @@ def command_logs(args: ArgsProtocol, config: ConfigType) -> int | None:
    devices = choose_upload_log_host(
        default=args.device,
        check_default=None,
-        show_ota=False,
-        show_mqtt=True,
-        show_api=True,
-        purpose="logging",
+        purpose=Purpose.LOGGING,
    )
    return show_logs(config, args, devices)

@@ -612,10 +694,7 @@ def command_run(args: ArgsProtocol, config: ConfigType) -> int | None:
    devices = choose_upload_log_host(
        default=args.device,
        check_default=None,
-        show_ota=True,
-        show_mqtt=False,
-        show_api=True,
-        purpose="uploading",
+        purpose=Purpose.UPLOADING,
    )

    exit_code, successful_device = upload_program(config, args, devices)
@@ -632,10 +711,7 @@ def command_run(args: ArgsProtocol, config: ConfigType) -> int | None:
    devices = choose_upload_log_host(
        default=successful_device,
        check_default=successful_device,
-        show_ota=False,
-        show_mqtt=True,
-        show_api=True,
-        purpose="logging",
+        purpose=Purpose.LOGGING,
    )
    return show_logs(config, args, devices)