esp32tool 1.1.9 → 1.3.0

package/dist/esp_loader.d.ts

@@ -3,10 +3,10 @@ export declare class ESPLoader extends EventTarget {
     port: SerialPort;
     logger: Logger;
     private _parent?;
-    chipFamily: ChipFamily;
-    chipName: string | null;
-    chipRevision: number | null;
-    chipVariant: string | null;
+    __chipFamily?: ChipFamily;
+    __chipName: string | null;
+    __chipRevision: number | null;
+    __chipVariant: string | null;
     _efuses: any[];
     _flashsize: number;
     debug: boolean;
@@ -14,22 +14,66 @@ export declare class ESPLoader extends EventTarget {
     connected: boolean;
     flashSize: string | null;
     __inputBuffer?: number[];
+    __inputBufferReadIndex?: number;
     __totalBytesRead?: number;
-    private _currentBaudRate;
+    currentBaudRate: number;
     private _maxUSBSerialBaudrate?;
     private _reader?;
     private _isESP32S2NativeUSB;
     private _initializationSucceeded;
     private __commandLock;
     private __isReconfiguring;
+    private __abandonCurrentOperation;
+    private _suppressDisconnect;
+    private __consoleMode;
+    _isUsbJtagOrOtg: boolean | undefined;
+    /**
+     * Check if device is using USB-JTAG or USB-OTG (not external serial chip)
+     * Returns undefined if not yet determined
+     */
+    get isUsbJtagOrOtg(): boolean | undefined;
+    private __adaptiveBlockMultiplier;
+    private __adaptiveMaxInFlightMultiplier;
+    private __consecutiveSuccessfulChunks;
+    private __lastAdaptiveAdjustment;
+    private __isCDCDevice;
     constructor(port: SerialPort, logger: Logger, _parent?: ESPLoader | undefined);
+    get chipFamily(): ChipFamily;
+    set chipFamily(value: ChipFamily);
+    get chipName(): string | null;
+    set chipName(value: string | null);
+    get chipRevision(): number | null;
+    set chipRevision(value: number | null);
+    get chipVariant(): string | null;
+    set chipVariant(value: string | null);
+    private get _consoleMode();
+    private set _consoleMode(value);
+    setConsoleMode(value: boolean): void;
     private get _inputBuffer();
+    private get _inputBufferReadIndex();
+    private set _inputBufferReadIndex(value);
+    private get _inputBufferAvailable();
+    private _readByte;
+    private _clearInputBuffer;
+    private _compactInputBuffer;
     private get _totalBytesRead();
     private set _totalBytesRead(value);
     private get _commandLock();
     private set _commandLock(value);
     private get _isReconfiguring();
     private set _isReconfiguring(value);
+    private get _abandonCurrentOperation();
+    private set _abandonCurrentOperation(value);
+    private get _adaptiveBlockMultiplier();
+    private set _adaptiveBlockMultiplier(value);
+    private get _adaptiveMaxInFlightMultiplier();
+    private set _adaptiveMaxInFlightMultiplier(value);
+    private get _consecutiveSuccessfulChunks();
+    private set _consecutiveSuccessfulChunks(value);
+    private get _lastAdaptiveAdjustment();
+    private set _lastAdaptiveAdjustment(value);
+    private get _isCDCDevice();
+    private set _isCDCDevice(value);
     private detectUSBSerialChip;
     initialize(): Promise<void>;
     /**
@@ -50,6 +94,10 @@ export declare class ESPLoader extends EventTarget {
         chipId: number;
         apiVersion: number;
     }>;
+    /**
+     * Get MAC address from efuses
+     */
+    getMacAddress(): Promise<string>;
     /**
      * @name readLoop
      * Reads data from the input stream and places it in the inputBuffer
@@ -57,8 +105,142 @@ export declare class ESPLoader extends EventTarget {
     readLoop(): Promise<void>;
     sleep(ms?: number): Promise<unknown>;
     state_DTR: boolean;
+    state_RTS: boolean;
     setRTS(state: boolean): Promise<void>;
     setDTR(state: boolean): Promise<void>;
+    setDTRandRTS(dtr: boolean, rts: boolean): Promise<void>;
+    /**
+     * @name hardResetUSBJTAGSerial
+     * USB-JTAG/Serial reset for Web Serial (Desktop)
+     */
+    hardResetUSBJTAGSerial(): Promise<void>;
+    /**
+     * @name hardResetClassic
+     * Classic reset for Web Serial (Desktop) DTR = IO0, RTS = EN
+     */
+    hardResetClassic(): Promise<void>;
+    /**
+     * Reset to firmware mode (not bootloader) for Web Serial
+     * Keeps IO0=HIGH during reset so chip boots into firmware
+     */
+    hardResetToFirmware(): Promise<void>;
+    /**
+     * Reset to firmware mode (not bootloader) for WebUSB
+     * Keeps IO0=HIGH during reset so chip boots into firmware
+     */
+    hardResetToFirmwareWebUSB(): Promise<void>;
+    /**
+     * @name hardResetUnixTight
+     * Unix Tight reset for Web Serial (Desktop) - sets DTR and RTS simultaneously
+     */
+    hardResetUnixTight(): Promise<void>;
+    setRTSWebUSB(state: boolean): Promise<void>;
+    setDTRWebUSB(state: boolean): Promise<void>;
+    setDTRandRTSWebUSB(dtr: boolean, rts: boolean): Promise<void>;
+    /**
+     * @name hardResetUSBJTAGSerialWebUSB
+     * USB-JTAG/Serial reset for WebUSB (Android)
+     */
+    hardResetUSBJTAGSerialWebUSB(): Promise<void>;
+    /**
+     * @name hardResetUSBJTAGSerialInvertedDTRWebUSB
+     * USB-JTAG/Serial reset with inverted DTR for WebUSB (Android)
+     */
+    hardResetUSBJTAGSerialInvertedDTRWebUSB(): Promise<void>;
+    /**
+     * @name hardResetClassicWebUSB
+     * Classic reset for WebUSB (Android)
+     */
+    hardResetClassicWebUSB(): Promise<void>;
+    /**
+     * @name hardResetUnixTightWebUSB
+     * Unix Tight reset for WebUSB (Android) - sets DTR and RTS simultaneously
+     */
+    hardResetUnixTightWebUSB(): Promise<void>;
+    /**
+     * @name hardResetClassicLongDelayWebUSB
+     * Classic reset with longer delays for WebUSB (Android)
+     * Specifically for CP2102/CH340 which may need more time
+     */
+    hardResetClassicLongDelayWebUSB(): Promise<void>;
+    /**
+     * @name hardResetClassicShortDelayWebUSB
+     * Classic reset with shorter delays for WebUSB (Android)
+     */
+    hardResetClassicShortDelayWebUSB(): Promise<void>;
+    /**
+     * @name hardResetInvertedWebUSB
+     * Inverted reset sequence for WebUSB (Android) - both signals inverted
+     */
+    hardResetInvertedWebUSB(): Promise<void>;
+    /**
+     * @name hardResetInvertedDTRWebUSB
+     * Only DTR inverted for WebUSB (Android)
+     */
+    hardResetInvertedDTRWebUSB(): Promise<void>;
+    /**
+     * @name hardResetInvertedRTSWebUSB
+     * Only RTS inverted for WebUSB (Android)
+     */
+    hardResetInvertedRTSWebUSB(): Promise<void>;
+    /**
+     * Check if we're using WebUSB (Android) or Web Serial (Desktop)
+     */
+    private isWebUSB;
+    /**
+     * @name connectWithResetStrategies
+     * Try different reset strategies to enter bootloader mode
+     * Similar to esptool.py's connect() method with multiple reset strategies
+     */
+    connectWithResetStrategies(): Promise<void>;
+    /**
+     * @name watchdogReset
+     * Watchdog reset for ESP32-S2/S3/C3 with USB-OTG or USB-JTAG/Serial
+     * Uses RTC watchdog timer to reset the chip - works when DTR/RTS signals are not available
+     * This is an alias for rtcWdtResetChipSpecific() for backwards compatibility
+     */
+    watchdogReset(): Promise<void>;
+    /**
+     * Check if current chip is using USB-OTG
+     * Supports ESP32-S2 and ESP32-S3
+     */
+    usingUsbOtg(): Promise<boolean>;
+    /**
+     * Check if current chip is using USB-JTAG/Serial
+     * Supports ESP32-S3 and ESP32-C3
+     */
+    usingUsbJtagSerial(): Promise<boolean>;
+    /**
+     * Get chip revision for ESP32-C3
+     * Reads from EFUSE registers and calculates revision
+     */
+    getChipRevisionC3(): Promise<number>;
+    /**
+     * RTC watchdog timer reset for ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C5, ESP32-C6, and ESP32-P4
+     * Uses specific registers for each chip family
+     * Note: ESP32-H2 does NOT support WDT reset
+     */
+    rtcWdtResetChipSpecific(): Promise<void>;
+    /**
+     * Helper: Check if USB-based WDT reset should be used for S2/S3
+     * Returns true if WDT reset was performed, false otherwise
+     */
+    private tryUsbWdtReset;
+    /**
+     * Chip-specific hard reset for ESP32-S2
+     * Checks if using USB-JTAG/Serial and uses watchdog reset if necessary
+     */
+    hardResetS2(): Promise<void>;
+    /**
+     * Chip-specific hard reset for ESP32-S3
+     * Checks if using USB-JTAG/Serial and uses watchdog reset if necessary
+     */
+    hardResetS3(): Promise<void>;
+    /**
+     * Chip-specific hard reset for ESP32-C3
+     * Checks if using USB-JTAG/Serial and uses watchdog reset if necessary
+     */
+    hardResetC3(): Promise<void>;
     hardReset(bootloader?: boolean): Promise<void>;
     /**
      * @name macAddr
@@ -86,6 +268,10 @@ export declare class ESPLoader extends EventTarget {
      * @name readPacket
      * Generator to read SLIP packets from a serial port.
      * Yields one full SLIP packet at a time, raises exception on timeout or invalid data.
+     *
+     * Two implementations:
+     * - Burst: CDC devices (Native USB) and CH343 - very fast processing
+     * - Byte-by-byte: CH340, CP2102, and other USB-Serial adapters - stable fast processing
      */
     readPacket(timeout: number): Promise<number[]>;
     /**
@@ -103,21 +289,11 @@ export declare class ESPLoader extends EventTarget {
     setBaudrate(baud: number): Promise<void>;
     reconfigurePort(baud: number): Promise<void>;
     /**
-     * @name connectWithResetStrategies
-     * Try different reset strategies to enter bootloader mode
-     * Similar to esptool.py's connect() method with multiple reset strategies
-     */
-    connectWithResetStrategies(): Promise<void>;
-    /**
-     * @name hardResetUSBJTAGSerial
-     * USB-JTAG/Serial reset sequence for ESP32-C3, ESP32-S3, ESP32-C6, etc.
+     * @name syncWithTimeout
+     * Sync with timeout that can be abandoned (for reset strategy loop)
+     * This is internally time-bounded and checks the abandon flag
      */
-    hardResetUSBJTAGSerial(): Promise<void>;
-    /**
-     * @name hardResetClassic
-     * Classic reset sequence for USB-to-Serial bridge chips (CH340, CP2102, etc.)
-     */
-    hardResetClassic(): Promise<void>;
+    syncWithTimeout(timeoutMs: number): Promise<boolean>;
     /**
      * @name sync
      * Put into ROM bootload mode & attempt to synchronize with the
@@ -205,11 +381,44 @@ export declare class ESPLoader extends EventTarget {
     private set _writeChain(value);
     writeToStream(data: number[]): Promise<void>;
     disconnect(): Promise<void>;
+    /**
+     * @name releaseReaderWriter
+     * Release reader and writer locks without closing the port
+     * Used when switching to console mode
+     */
+    releaseReaderWriter(): Promise<void>;
+    /**
+     * @name resetToFirmware
+     * Public method to reset device from bootloader to firmware for console mode
+     * Automatically detects USB-JTAG/Serial and USB-OTG devices and performs appropriate reset
+     * @returns true if reset was performed, false if not needed
+     */
+    resetToFirmware(): Promise<boolean>;
+    /**
+     * @name enterConsoleMode
+     * Prepare device for console mode by resetting to firmware
+     * Handles both USB-JTAG/OTG devices (closes port) and external serial chips (keeps port open)
+     * @returns true if port was closed (USB-JTAG), false if port stays open (serial chip)
+     */
+    enterConsoleMode(): Promise<boolean>;
+    /**
+     * @name _resetToFirmwareIfNeeded
+     * Reset device from bootloader to firmware when switching to console mode
+     * Detects USB-JTAG/Serial and USB-OTG devices and performs appropriate reset
+     * @returns true if reconnect was performed, false otherwise
+     */
+    private _resetToFirmwareIfNeeded;
     /**
      * @name reconnectAndResume
      * Reconnect the serial port to flush browser buffers and reload stub
      */
     reconnect(): Promise<void>;
+    /**
+     * @name reconnectToBootloader
+     * Close and reopen the port, then reset ESP to bootloader mode
+     * This is needed after Improv or other operations that leave ESP in firmware mode
+     */
+    reconnectToBootloader(): Promise<void>;
     /**
      * @name drainInputBuffer
      * Actively drain the input buffer by reading data for a specified time.
@@ -233,9 +442,17 @@ export declare class ESPLoader extends EventTarget {
      * @param addr - Address to read from
      * @param size - Number of bytes to read
      * @param onPacketReceived - Optional callback function called when packet is received
+     * @param options - Optional parameters for advanced control
+     *   - chunkSize: Amount of data to request from ESP in one command (bytes)
+     *   - blockSize: Size of each data block sent by ESP (bytes)
+     *   - maxInFlight: Maximum unacknowledged bytes (bytes)
      * @returns Uint8Array containing the flash data
      */
-    readFlash(addr: number, size: number, onPacketReceived?: (packet: Uint8Array, progress: number, totalSize: number) => void): Promise<Uint8Array>;
+    readFlash(addr: number, size: number, onPacketReceived?: (packet: Uint8Array, progress: number, totalSize: number) => void, options?: {
+        chunkSize?: number;
+        blockSize?: number;
+        maxInFlight?: number;
+    }): Promise<Uint8Array>;
 }
 declare class EspStubLoader extends ESPLoader {
     IS_STUB: boolean;
@@ -245,9 +462,14 @@ declare class EspStubLoader extends ESPLoader {
      */
     memBegin(size: number, _blocks: number, _blocksize: number, offset: number): Promise<[number, number[]]>;
     /**
-     * @name getEraseSize
-     * depending on flash chip model the erase may take this long (maybe longer!)
+     * @name eraseFlash
+     * Erase entire flash chip
      */
     eraseFlash(): Promise<void>;
+    /**
+     * @name eraseRegion
+     * Erase a specific region of flash
+     */
+    eraseRegion(offset: number, size: number): Promise<void>;
 }
 export {};