2026.9.4
Home ▸ Integrations

USB Discovery

The USB Discovery integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] detects supported USB devices that can be discovered by Home Assistant integrations. Devices that match a supported integration appear in the Discovered section on Settings > Devices & services.

This integration does not manage USB storage devices. To use a USB-attached drive, such as an SSD or HDD, as storage with Home Assistant Operating SystemHome Assistant OS, the Home Assistant Operating System, is an embedded, minimalistic, operating system designed to run the Home Assistant ecosystem on single board computers (like the Raspberry Pi) or Virtual Machines. It includes Home Assistant Core, the Home Assistant Supervisor, and supports apps. Home Assistant Supervisor keeps it up to date, removing the need for you to manage an operating system. Home Assistant Operating System is the recommended installation type for most users., see using an external data disk.

  • On all supported systems, devices are detected during startup.
  • On Linux systems that have functional udev support, including Home Assistant Operating System, devices are detected as soon as they are plugged in.
  • On non-Linux systems or systems without udev support, devices are detected when visiting the integrations page and during onboarding.

The USB Discovery integration also provides the Serial panel under Settings > Connectivity. This panel lists serial ports that Home Assistant detects or tracks through an integration or appApps are additional standalone third-party software packages that can be installed on Home Assistant OS. [Learn more]. This includes USB devices, but also serial ports that are built into your system or shared over your network.

Viewing your serial ports

You can see the serial ports that Home Assistant detects in one place from the Serial configuration panel. This is also where you look up the device path of a port, for example, when an integration asks for it during setup.

  1. Go to Settings > Connectivity > Serial.

    • At the top, a status summary shows how many of your connected ports are in use, and whether any ports are disconnected.
    • The ports are grouped into three lists:
      • Connected: ports that are used by at least one integration or appApps are additional standalone third-party software packages that can be installed on Home Assistant OS. [Learn more].
      • Available: ports that are connected, but not used by any integration or appApps are additional standalone third-party software packages that can be installed on Home Assistant OS. [Learn more].
      • Disconnected: ports that an integration or appApps are additional standalone third-party software packages that can be installed on Home Assistant OS. [Learn more] uses, but that are currently not connected.
    • If Home Assistant did not find any serial ports, the panel shows No serial ports found instead.
    • To look for ports again, for example after plugging in a USB-to-serial adapter, select Refresh in the top right corner.

    Tip

    Serial ports used only by YAML-only integrations, such as the Serial sensor, are not tracked as having a consumer. If Home Assistant detects such a local port, it appears in the Available section rather than the Connected section. A network port that Home Assistant cannot discover, such as a socket:// port, used only by such an integration does not appear in the panel at all.

    1. Under each port, you see what it is used for:
      • Every appApps are additional standalone third-party software packages that can be installed on Home Assistant OS. [Learn more] and every integration set up in the UI that uses the port is listed below it. Select one to go to its settings. An integration or app that is not running at the moment is marked as not running.
      • Discovered by: names the integration that recognized the device on this port and is ready to set it up. Select this line to start the setup.
      • Can be used with: lists the integrations that support the device on this port. This appears only for a port that is not in use yet.
    2. To view more details about a port, select Port information next to it. The Port information dialog shows the device path, together with details such as the description, manufacturer, and serial number of the device. This option is available for ports that are currently connected.
      • To use the port with an integration that asks for a device path, such as Zigbee Home Automation or the Serial sensor, copy the value of the Device field. For example, /dev/ttyAMA0.

    About the serial ports panel

    The Serial panel under Settings > Connectivity can list the following types of serial ports:

    • USB: a device that is connected to a USB port, such as a USB-to-serial adapter.
    • Built-in: a serial port that is part of your system’s hardware. For example, the Zigbee radio on Home Assistant Yellow.
    • Serial proxies: a serial port that an ESPHome device shares over your network. These ports are listed alongside the ports that are connected to your system, so you can use them the same way. For more information, refer to serial proxy.
    • Integration-provided: a serial port that is addressed with a URL instead of a device path, such as a port on a remote system that you expose with ser2net or socat.
    • Other: a serial port that Home Assistant cannot identify any further.

    Configuration

    This integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] is part of default_config:. If you have opted not to use default_config:, you can add this integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] by adding the following lines to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]:

    # Example configuration.yaml entry
usb: