tasmota-esp-web-tools 12.2.0 → 12.2.1

package/README.md

@@ -138,6 +138,38 @@ A device with ESP32-S3 and 16MB flash gets the first build, 4MB gets the second,
 
 The `flashSizeMB` field is **optional**. If omitted, the build will match any flash size. Builds with matching `flashSizeMB` are preferred over builds without it (most-specific-matching algorithm).
 
+## USB Interface Support (UART vs CDC)
+
+For chips that can be connected either through a native USB interface (USB-JTAG/USB-OTG, e.g. ESP32-S2/S3/C3/C6/...) or through an external USB-to-Serial bridge (CP210x, FTDI, CH340, ...), you can ship dedicated firmware variants by specifying `usbInterface`:
+
+- `"CDC"` – firmware built for native USB (CDC) console / programming
+- `"UART"` – firmware built for the regular UART console via an external USB-to-Serial chip
+
+```json
+{
+  "name": "My Firmware",
+  "builds": [
+    {
+      "chipFamily": "ESP32-S3",
+      "usbInterface": "CDC",
+      "parts": [{ "path": "s3-cdc.bin", "offset": 0 }]
+    },
+    {
+      "chipFamily": "ESP32-S3",
+      "usbInterface": "UART",
+      "parts": [{ "path": "s3-uart.bin", "offset": 0 }]
+    }
+  ]
+}
+```
+
+ESP Web Tools automatically detects how the device is connected:
+
+- If the device is reached via native USB (USB-JTAG/USB-OTG) the build with `usbInterface: "CDC"` is selected.
+- Otherwise (external USB-to-Serial bridge) the build with `usbInterface: "UART"` is selected.
+
+The `usbInterface` field is **optional**. If omitted, the build will match any USB interface and is used as a fallback. It can also be combined freely with `chipVariant` and `flashSizeMB`.
+
 ## Performance
 
 ESP Web Tools supports configurable baud rates for flashing. By default, it uses 115200 baud for maximum compatibility. You can increase the baud rate for significantly faster flashing speeds.

package/dist/const.d.ts

@@ -7,6 +7,13 @@ export interface Build {
     chipFamily: "ESP32" | "ESP8266" | "ESP32-S2" | "ESP32-S3" | "ESP32-C2" | "ESP32-C3" | "ESP32-C5" | "ESP32-C6" | "ESP32-C61" | "ESP32-H2" | "ESP32-P4";
     chipVariant?: string;
     flashSizeMB?: number;
+    /**
+     * Optional USB interface qualifier.
+     * - "CDC": native USB CDC (USB-JTAG/USB-OTG, e.g. direct USB on S2/S3/C3/C6/...)
+     * - "UART": external USB-to-Serial bridge (CP210x, FTDI, CH340, ...)
+     * If omitted, the build will match any USB interface.
+     */
+    usbInterface?: "UART" | "CDC";
     parts: {
         path: string;
         offset: number;

package/dist/flash.js

@@ -18,11 +18,12 @@ function parseFlashSizeToMB(flashSize) {
 }
 /**
  * Select the best build using most-specific-matching algorithm
+ * - Builds with matching usbInterface are strongly preferred
  * - Builds with matching flashSizeMB are preferred
  * - Among builds with same specificity, first one wins
- * - Builds without flashSizeMB are fallback options
+ * - Builds without these qualifiers are fallback options
  */
-function selectBestBuild(builds, detectedFlashSizeMB) {
+function selectBestBuild(builds, detectedFlashSizeMB, detectedUsbInterface) {
     if (builds.length === 0)
         return undefined;
     // Score builds: higher score = more specific match
@@ -30,7 +31,19 @@ function selectBestBuild(builds, detectedFlashSizeMB) {
     let bestScore = -Infinity;
     for (const build of builds) {
         let score = 0;
-        // Flash size match gives highest priority
+        // USB interface match - if specified, must match
+        if (build.usbInterface !== undefined) {
+            if (detectedUsbInterface !== undefined &&
+                build.usbInterface === detectedUsbInterface) {
+                score += 1000; // Strong preference for explicit usbInterface match
+            }
+            else {
+                // Mismatched usbInterface - disqualify this build
+                continue;
+            }
+        }
+        // Builds without usbInterface stay neutral (compatible with any)
+        // Flash size match gives second priority
         if (build.flashSizeMB !== undefined && detectedFlashSizeMB !== undefined) {
             if (build.flashSizeMB === detectedFlashSizeMB) {
                 score += 100; // Exact flash size match
@@ -118,6 +131,20 @@ logger, manifestPath, eraseFirst, firmwareBuffer, _baudRate) => {
     }
     flashSize = esploader.flashSize; // e.g., "4MB", "8MB"
     const flashSizeMB = flashSize ? parseFlashSizeToMB(flashSize) : undefined;
+    // Detect USB connection type to pick CDC vs UART firmware variants
+    // - true: native USB (USB-JTAG/USB-OTG) -> CDC
+    // - false: external USB-to-Serial bridge -> UART
+    let detectedUsbInterface;
+    if (typeof esploader.detectUsbConnectionType === "function") {
+        try {
+            const isUsbJtagOrOtg = await esploader.detectUsbConnectionType();
+            detectedUsbInterface = isUsbJtagOrOtg ? "CDC" : "UART";
+            logger.debug(`Detected USB interface: ${detectedUsbInterface}`);
+        }
+        catch (err) {
+            logger.debug("Failed to detect USB connection type:", err);
+        }
+    }
     fireStateEvent({
         state: "initializing" /* FlashStateType.INITIALIZING */,
         message: `Initialized. Found ${chipFamily}${chipVariant ? ` (${chipVariant})` : ""}${flashSize ? `, ${flashSize}` : ""}`,
@@ -154,9 +181,9 @@ logger, manifestPath, eraseFirst, firmwareBuffer, _baudRate) => {
     // Prefer builds with more matching qualifiers (flashSizeMB)
     const exactVariantBuilds = compatibleBuilds.filter((b) => b.chipVariant !== undefined && b.chipVariant === chipVariant);
     const variantAgnosticBuilds = compatibleBuilds.filter((b) => b.chipVariant === undefined);
-    build = selectBestBuild(exactVariantBuilds, flashSizeMB);
+    build = selectBestBuild(exactVariantBuilds, flashSizeMB, detectedUsbInterface);
     if (!build) {
-        build = selectBestBuild(variantAgnosticBuilds, flashSizeMB);
+        build = selectBestBuild(variantAgnosticBuilds, flashSizeMB, detectedUsbInterface);
     }
     if (!build) {
         fireStateEvent({