Skip to content

Add serialType field to auto-select CDC vs UART firmware variants#685

Open
DTTerastar wants to merge 2 commits intoesphome:mainfrom
ESPresense:serial-type
Open

Add serialType field to auto-select CDC vs UART firmware variants#685
DTTerastar wants to merge 2 commits intoesphome:mainfrom
ESPresense:serial-type

Conversation

@DTTerastar
Copy link

Summary

  • Adds an optional serialType: "cdc" | "uart" field to the Build interface in the manifest schema
  • Detects whether the connected device uses native USB CDC (Espressif VID 0x303a) or an external USB-to-UART bridge via port.getInfo()
  • Automatically selects the matching firmware variant when multiple builds share the same chipFamily

Motivation

Chips like ESP32-S3 and ESP32-C3 can be connected either via their built-in USB CDC port or via an external USB-to-UART bridge. These two connection methods require different firmware builds (different compile flags). Previously, users had to manually choose the correct variant — or the wrong firmware could be flashed silently.

This was originally requested in #383, which was closed with the conclusion that detecting the connection type was not possible. However, port.getInfo() from the Web Serial API does expose the USB vendor and product IDs before any communication begins, making detection straightforward. Espressif's native USB CDC devices are identifiable by VID 0x303a and known CDC product IDs, as noted in the discussion on #383 itself.

The Tasmota approach (single firmware that detects CDC at runtime) is a valid alternative, but is not always available — particularly for projects that need separate binaries for each transport type. This feature is purely additive and requires no changes for projects that don't need it.

Behavior

Build selection priority:

  1. Exact match: build with chipFamily + serialType matching the detected connection
  2. Generic fallback: build with chipFamily and no serialType specified
  3. Not supported: if neither is found, installation is refused — avoiding silently flashing the wrong transport variant

Manifests without serialType are completely unaffected — existing single-variant manifests continue to work as before.

Example manifest

{
  "chipFamily": "ESP32-S3",
  "serialType": "uart",
  "parts": [...]
},
{
  "chipFamily": "ESP32-S3",
  "serialType": "cdc",
  "parts": [...]
}

Closes #383
Related: #331

DTTerastar and others added 2 commits February 20, 2026 19:38
Adds an optional `serialType: "cdc" | "uart"` field to the Build
interface. When multiple builds share the same chipFamily, the one
matching the detected connection type is selected automatically.

Connection type is detected via port.getInfo(): Espressif native USB
CDC devices are identified by VID 0x303a and known CDC product IDs.
Builds without serialType serve as a generic fallback for any connection.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] Detect cdc/USB_SERIAL_JTAG devices so users can just get the cdc firmware flavor automatically

1 participant