mirror of
https://github.com/esphome/esphome.git
synced 2026-08-27 08:28:30 +00:00
67 lines
2.4 KiB
Python
67 lines
2.4 KiB
Python
"""Stable classification of ``--device`` / port strings.
|
|
|
|
External tooling (the device-builder dashboard at
|
|
esphome/device-builder, and other consumers) needs to decide whether
|
|
a user-supplied port string names a local serial device, an OTA
|
|
network target, an MQTT magic string, or an RP2040 BOOTSEL upload.
|
|
|
|
This module is the single stable home for that classification. The
|
|
upstream CLI (``esphome.__main__``) re-exports ``PortType`` and
|
|
``get_port_type`` from here for its own use; external callers should
|
|
import directly from ``esphome.upload_targets`` so the surface stays
|
|
stable across releases (``esphome/__main__`` is a CLI entrypoint and
|
|
not a stable import path).
|
|
|
|
Please keep ``PortType`` member names / values and the
|
|
``get_port_type`` signature stable — see the docstrings on each for
|
|
the contract.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from esphome.enum import StrEnum
|
|
|
|
|
|
class PortType(StrEnum):
|
|
"""Port classification returned by :func:`get_port_type`.
|
|
|
|
Used by device-builder (esphome/device-builder) and other
|
|
external tooling to route a user-supplied ``--device`` value to
|
|
the right upload / log path. Member names and string values are
|
|
part of the stable surface — adding new members is fine, but
|
|
existing names / values must not be renamed or changed.
|
|
"""
|
|
|
|
SERIAL = "SERIAL"
|
|
NETWORK = "NETWORK"
|
|
MQTT = "MQTT"
|
|
MQTTIP = "MQTTIP"
|
|
BOOTSEL = "BOOTSEL"
|
|
|
|
|
|
def get_port_type(port: str) -> PortType:
|
|
"""Determine the type of port/device identifier.
|
|
|
|
Used by device-builder (esphome/device-builder)'s dashboard to
|
|
decide whether a user-supplied ``--device`` value names a local
|
|
serial port (must build / flash locally), an OTA network target
|
|
(eligible for remote builds), an MQTT magic string, or an RP2040
|
|
BOOTSEL upload. Please keep the signature stable.
|
|
|
|
Returns:
|
|
PortType.SERIAL for serial ports (/dev/ttyUSB0, COM1, etc.)
|
|
PortType.BOOTSEL for RP2040 BOOTSEL upload via picotool
|
|
PortType.MQTT for MQTT logging
|
|
PortType.MQTTIP for MQTT IP lookup
|
|
PortType.NETWORK for IP addresses, hostnames, or mDNS names
|
|
"""
|
|
if port == "BOOTSEL":
|
|
return PortType.BOOTSEL
|
|
if port.startswith(("/", "COM")):
|
|
return PortType.SERIAL
|
|
if port == "MQTT":
|
|
return PortType.MQTT
|
|
if port == "MQTTIP":
|
|
return PortType.MQTTIP
|
|
return PortType.NETWORK
|