@esp-vision/device-core 0.5.0 → 0.6.0

package/src/node_rom.js

@@ -4,14 +4,18 @@ import { spawn } from 'node:child_process'
 import { createInterface } from 'node:readline'
 import { fileURLToPath } from 'node:url'
 import { defaultPython } from './node_inventory.js'
+import { prepareNodeRomPort, recoverNodeRomPort } from './node_rom_port.js'
 
-export function openNodeRom({ port, python = defaultPython, signal } = {}) {
+export function openNodeRom({ port, python = defaultPython, signal } = {}, dependencies = {}) {
   if (!port) throw new TypeError('Firmware update requires a local --port')
-  let child, input, pending, sequence = 0, closed = false
+  const lifecycle = new AbortController()
+  signal = signal ? AbortSignal.any([signal, lifecycle.signal]) : lifecycle.signal
+  let child, input, pending, sequence = 0, closed = false, initializing = false, romReady = false
   const fail = code => Object.assign(new Error(code === 'ESPTOOL_UNAVAILABLE' ? 'Install Python esptool>=5.3,<6 for the built-in flasher' : 'ROM operation failed'), { code })
   const reject = code => { if (pending) { clearTimeout(pending.timer); pending.reject(fail(code)); pending = null } }
   function rpc(method, args = []) {
     if (closed) return Promise.reject(fail('ROM_CLOSED'))
+    if (!child || (method !== 'initialize' && !romReady)) return Promise.reject(fail('ROM_NOT_INITIALIZED'))
     if (pending) return Promise.reject(fail('ROM_BUSY'))
     return new Promise((resolve, rejectPromise) => {
       const id = ++sequence
@@ -19,27 +23,77 @@ export function openNodeRom({ port, python = defaultPython, signal } = {}) {
       child.stdin.write(JSON.stringify({ id, method, args }) + '\n', error => { if (error) reject('ROM_IO_FAILED') })
     })
   }
+  async function closeProcess() {
+    const process = child
+    child = null; romReady = false; reject('ROM_CLOSED'); input?.close(); input = null
+    if (!process || process.exitCode !== null) return
+    await new Promise(resolve => {
+      const timer = setTimeout(() => { process.kill(); resolve() }, 2000)
+      process.once('exit', () => { clearTimeout(timer); resolve() })
+      process.stdin.end()
+    })
+  }
+  function startProcess(selected) {
+    signal.throwIfAborted()
+    const process = (dependencies.spawn ?? spawn)(python, ['-u', fileURLToPath(new URL('./node_rom.py', import.meta.url)), selected.port], { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true })
+    child = process
+    const active = action => { if (child === process) action() }
+    process.on('error', () => active(() => reject('ESPTOOL_UNAVAILABLE')))
+    process.on('exit', () => active(() => reject('ROM_CLOSED')))
+    process.stdin.on('error', () => active(() => reject('ROM_IO_FAILED')))
+    input = createInterface({ input: process.stdout })
+    input.on('line', line => {
+      if (child !== process) return
+      try {
+        const message = JSON.parse(line)
+        if (message.error && !message.id) return reject(message.error)
+        if (!pending || message.id !== pending.id) return
+        const operation = pending; pending = null; clearTimeout(operation.timer)
+        if (message.error) operation.reject(Object.assign(fail(message.error), { operation: message.method, cause: message.detail })); else operation.resolve(message.result)
+      } catch { reject('ROM_RESPONSE_INVALID') }
+    })
+    return rpc('initialize')
+  }
   const loader = {
     async initialize() {
-      signal?.throwIfAborted()
-      child = spawn(python, ['-u', fileURLToPath(new URL('./node_rom.py', import.meta.url)), port], { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true })
-      child.on('error', () => reject('ESPTOOL_UNAVAILABLE'))
-      child.on('exit', () => reject('ROM_CLOSED'))
-      child.stdin.on('error', () => reject('ROM_IO_FAILED'))
-      input = createInterface({ input: child.stdout })
-      input.on('line', line => {
-        try {
-          const message = JSON.parse(line)
-          if (message.error && !message.id) return reject(message.error)
-          if (!pending || message.id !== pending.id) return
-          const operation = pending; pending = null; clearTimeout(operation.timer)
-          if (message.error) operation.reject(Object.assign(fail(message.error), { operation: message.method, cause: message.detail })); else operation.resolve(message.result)
-        } catch { reject('ROM_RESPONSE_INVALID') }
-      })
+      signal.throwIfAborted()
+      if (closed) throw fail('ROM_CLOSED')
+      if (initializing || child) throw fail('ROM_ALREADY_INITIALIZED')
+      initializing = true
+      let selected
       const cancelled = () => { reject('CANCELLED'); void loader.disconnect() }
-      signal?.addEventListener('abort', cancelled, { once: true })
-      try { Object.assign(loader, await rpc('initialize')) }
-      finally { signal?.removeEventListener('abort', cancelled) }
+      signal.addEventListener('abort', cancelled, { once: true })
+      try {
+        selected = await (dependencies.preparePort ?? prepareNodeRomPort)({ port, python, signal })
+        signal.throwIfAborted()
+        let identity
+        try { identity = await startProcess(selected) }
+        catch (error) {
+          await closeProcess()
+          signal.throwIfAborted()
+          // No writes have been accepted. A ROM/stub can return to its app
+          // between enumeration and SYNC. Recover only after observing that
+          // same physical device's runtime; never repeat a previous handoff.
+          if (error.code !== 'ROM_OPERATION_FAILED' || error.operation !== 'initialize'
+              || !selected.expectedMac || selected.transition?.observed !== 'rom'
+              || selected.transition.requested !== false) throw error
+          const recovered = await (dependencies.recoverPort ?? recoverNodeRomPort)(selected, { python, signal })
+          if (!recovered) throw error
+          selected = recovered
+          selected.transition.previousInitialization = { code: error.code, operation: error.operation, detail: String(error.cause ?? '').slice(0, 1024) }
+          signal.throwIfAborted()
+          identity = await startProcess(selected)
+        }
+        if (selected.expectedMac && identity.chipMac !== selected.expectedMac) {
+          throw Object.assign(new Error('ROM MAC differs from the selected USB device'), { code: 'ROM_IDENTITY_CHANGED' })
+        }
+        Object.assign(loader, identity, { port: selected.port, usbTransition: selected.transition })
+        romReady = true
+      } catch (error) {
+        if (error && typeof error === 'object' && selected?.transition) error.transition ??= selected.transition
+        await loader.disconnect()
+        throw error
+      } finally { initializing = false; signal.removeEventListener('abort', cancelled) }
     },
     flashId: () => rpc('flashId'),
     getSecurityInfo: () => rpc('security'),
@@ -51,13 +105,8 @@ export function openNodeRom({ port, python = defaultPython, signal } = {}) {
     hardReset: () => rpc('reset'),
     async disconnect() {
       if (closed) return
-      closed = true; reject('ROM_CLOSED'); input?.close()
-      if (!child || child.exitCode !== null) return
-      await new Promise(resolve => {
-        const timer = setTimeout(() => { child.kill(); resolve() }, 2000)
-        child.once('exit', () => { clearTimeout(timer); resolve() })
-        child.stdin.end()
-      })
+      closed = true; lifecycle.abort(fail('ROM_CLOSED'))
+      await closeProcess()
     },
   }
   return loader

package/src/node_rom.py

@@ -4,9 +4,61 @@
 import base64
 import contextlib
 import json
+import os
 import sys
 
 
+def _port_key(port):
+    name = str(port)
+    if name.startswith('\\\\.\\'):
+        name = name[4:]
+    if name.upper().startswith('COM') and name[3:].isdigit():
+        return name.upper()
+    return os.path.realpath(name)
+
+
+def _reset_supported(port):
+    # Descriptors permit a reset policy, never establish firmware/board identity.
+    # Unknown/native USB ports must not receive the UART DTR/RTS sequence.
+    try:
+        from serial.tools.list_ports import comports
+        matches = {(item.vid, item.pid) for item in comports()
+                   if _port_key(item.device) == _port_key(port)}
+    except (ImportError, OSError, ValueError):
+        return False
+    if len(matches) != 1:
+        return False
+    vid, pid = next(iter(matches))
+    return vid in {0x10c4, 0x1a86, 0x0403, 0x067b} or (vid, pid) == (0x303a, 0x1001)
+
+
+def _open_rom(esptool, port):
+    import serial
+    modes = ['no-reset', 'default-reset'] if _reset_supported(port) else ['no-reset']
+    first_error = None
+    for mode in modes:
+        if mode == 'default-reset' and not _reset_supported(port):
+            raise RuntimeError(f'Port no longer permits reset after synchronization failed: {first_error}') from first_error
+        connection = serial.serial_for_url(port, baudrate=115200, exclusive=True, do_not_open=True)
+        try:
+            # Set before open on every OS, as esptool does on Windows. Opening
+            # with asserted RTS can otherwise perturb an already-running stub.
+            connection.rts = False
+            connection.dtr = False
+            connection.open()
+            loader = esptool.detect_chip(port=connection, connect_mode=mode,
+                                         connect_attempts=1 if mode == 'no-reset' else 7)
+            return loader, mode
+        except Exception as error:
+            if connection.is_open:
+                connection.close()
+            if mode == modes[-1]:
+                if first_error is not None:
+                    raise RuntimeError(f'No-reset synchronization failed: {first_error}; reset connection failed: {error}') from error
+                raise
+            first_error = error
+
+
 def main():
     with contextlib.redirect_stdout(sys.stderr):
         import esptool
@@ -22,9 +74,23 @@ def main():
                 with contextlib.redirect_stdout(sys.stderr):
                     method, args = request['method'], request.get('args', [])
                     result = None
+                    if method != 'initialize' and esp is None:
+                        raise RuntimeError('Initialize the ROM adapter before issuing operations')
                     if method == 'initialize':
-                        esp = esptool.detect_chip(port=sys.argv[1])
-                        result = {'chipFamily': families.get(esp.CHIP_NAME), 'chipRevision': esp.get_chip_revision()}
+                        if esp is not None:
+                            raise RuntimeError('ROM adapter is already initialized')
+                        candidate, mode = _open_rom(esptool, sys.argv[1])
+                        try:
+                            mac = bytes(candidate.read_mac())
+                            if len(mac) != 6:
+                                raise RuntimeError('ROM did not return a six-byte factory MAC')
+                            result = {'chipFamily': families.get(candidate.CHIP_NAME), 'chipRevision': candidate.get_chip_revision(),
+                                      'connectionMode': mode, 'stubRunning': bool(candidate.IS_STUB), 'chipMac': mac.hex()}
+                        except Exception:
+                            if candidate._port.is_open:
+                                candidate._port.close()
+                            raise
+                        esp = candidate
                     elif method == 'security':
                         security = esp.get_security_info()
                         result = {'flags': security['flags'], 'flashCryptCnt': security['flash_crypt_cnt']}

package/src/node_rom_port.js

@@ -0,0 +1,211 @@
+// SPDX-FileCopyrightText: 2026 ESP-VISION-IDE
+// SPDX-License-Identifier: Apache-2.0
+import { realpath } from 'node:fs/promises'
+import { setTimeout as delay } from 'node:timers/promises'
+import { createDevice } from './index.js'
+import { defaultPython, listSerial } from './node_inventory.js'
+import { serialTransport } from './node_transport.js'
+
+const ROM_PIDS = new Set([2, 9, 18, 32])
+// Confirmed ESP-VISION runtime composites: CDC+MSC and CDC+MSC+UVC.
+const RUNTIME_PIDS = new Set([0x4003, 0x4023])
+const UNIQUE_ID_SOURCE = "import machine,ubinascii\nprint('__EV_ROM_ID__'+ubinascii.hexlify(machine.unique_id()).decode())"
+function fail(code, message, cause) { return Object.assign(new Error(message), { code, ...(cause ? { cause } : {}) }) }
+function checkAbort(signal) {
+  if (!signal?.aborted) return
+  throw signal.reason instanceof Error ? signal.reason : Object.assign(new Error('ROM port preparation cancelled'), { name: 'AbortError' })
+}
+function errorInfo(error) { return { code: error?.code ?? error?.name ?? 'ERROR', message: String(error?.message ?? error).slice(0, 512) } }
+function mac(value) {
+  if (typeof value !== 'string') return null
+  const result = value.replace(/[:-]/g, '').toLowerCase()
+  return /^[0-9a-f]{12}$/.test(result) ? result : null
+}
+function comKey(value) {
+  return typeof value === 'string' && /^(?:\\\\\.\\)?COM[1-9]\d*$/i.test(value)
+    ? value.replace(/^\\\\\.\\/, '').toUpperCase() : null
+}
+function physicalLocation(value) {
+  // pyserial adds :configuration.interface (Windows uses :x.interface).
+  return typeof value === 'string' && value.trim() ? value.trim().replace(/:(?:\d+|x)\.\d+$/i, '') : null
+}
+function nativeRom(port) { return port.vendorId === 0x303a && ROM_PIDS.has(port.productId) }
+function nativeRuntime(port) { return port.vendorId === 0x303a && RUNTIME_PIDS.has(port.productId) }
+
+/** Resolve only the selected port. Descriptors authorize a handoff, never a flash. */
+export async function prepareNodeRomPort({ port, python = defaultPython, signal, timeout = 5000, expectedIdentity } = {}, dependencies = {}) {
+  if (typeof port !== 'string' || !port || /[\x00-\x1f\x7f]/.test(port)) throw new TypeError('ROM preparation requires a local port')
+  if (!Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 5000) throw new RangeError('ROM preparation timeout must be positive and at most 5000 ms')
+  const required = expectedIdentity == null ? null : { mac: mac(expectedIdentity.mac), location: physicalLocation(expectedIdentity.location) }
+  if (required && (!required.mac || !required.location)) throw new TypeError('Bound ROM preparation requires a MAC and physical USB location')
+  const enumerate = dependencies.listSerial ?? listSerial
+  const resolvePath = dependencies.realpath ?? realpath
+  const now = dependencies.now ?? (() => performance.now())
+  const sleep = dependencies.sleep ?? ((ms, abortSignal) => delay(ms, undefined, { signal: abortSignal }))
+  const makeDevice = dependencies.createDevice ?? createDevice
+  const makeTransport = dependencies.serialTransport ?? serialTransport
+  checkAbort(signal)
+  const settleDeadline = now() + timeout
+  let canonical = comKey(port)
+  while (!canonical) {
+    checkAbort(signal)
+    try {
+      canonical = await resolvePath(port)
+      if (typeof canonical !== 'string' || !canonical) throw fail('ROM_PORT_LOST', 'The selected path has no canonical serial address')
+    }
+    catch (error) {
+      checkAbort(signal)
+      if (error.code !== 'ENOENT' || now() >= settleDeadline) throw fail('ROM_PORT_LOST', 'The selected serial path is unavailable; select its current port', error)
+      await sleep(Math.min(50, settleDeadline - now()), signal)
+    }
+  }
+  checkAbort(signal)
+  let ports
+  try { ports = await enumerate({ python, signal, timeout }) }
+  catch (error) {
+    checkAbort(signal)
+    if (required) throw fail('ROM_PORT_IDENTITY_REQUIRED', 'Cannot confirm the bound runtime descriptors', error)
+    // A known OS path may still be used without descriptors, but never probed
+    // as an EV-MUX runtime or rebound to a different port.
+    return { port: canonical, expectedMac: null, transition: null }
+  }
+  checkAbort(signal)
+  if (!Array.isArray(ports)) throw fail('ROM_PORT_ENUMERATION_FAILED', 'Serial enumeration returned invalid descriptors')
+  const selected = ports.filter(item => item.path === port || item.path === canonical || (comKey(item.path) && comKey(item.path) === canonical))
+  if (selected.length > 1) throw fail('ROM_PORT_AMBIGUOUS', 'The selected port has ambiguous descriptors')
+  if (!selected.length) {
+    if (required) throw fail('ROM_PORT_LOST', 'The bound runtime port is no longer enumerated')
+    return { port: canonical, expectedMac: null, transition: null }
+  }
+  const current = selected[0]
+  const expectedMac = mac(current.serialNumber)
+  const location = physicalLocation(current.location)
+  if (required && (expectedMac !== required.mac || location !== required.location)) throw fail('ROM_RUNTIME_IDENTITY_MISMATCH', 'The selected runtime descriptors changed before recovery')
+  if (nativeRom(current)) return {
+    port: current.path, expectedMac,
+    transition: { requested: false, observed: 'rom', selectedPort: port, port: current.path, serial: expectedMac, location },
+  }
+  if (!nativeRuntime(current)) return { port: canonical, expectedMac: null, transition: null }
+  if (!expectedMac || !location) throw fail('ROM_PORT_IDENTITY_REQUIRED', 'Native USB runtime requires a MAC serial and physical USB location')
+
+  const transition = { requested: false, selectedPort: port, runtimePort: current.path, expectedMac, location,
+    command: { attempted: false, acknowledged: false, outcome: 'not_attempted' }, cleanup: null, observed: null }
+  let device, primary
+  try {
+    device = makeDevice({ transport: makeTransport({ serial: current.path, role: 'usb', python }) })
+    const connected = await device.connect({ role: 'usb', probeRepl: false, autoBaud: false, timeout, signal })
+    checkAbort(signal)
+    const owners = connected?.capabilities?.sinks?.filter(sink => sink.owner === true) ?? []
+    if (owners.length !== 1 || owners[0].id !== 'usb' || owners[0].kind !== 'usb_otg_cdc' || owners[0].state !== 'active' || owners[0].ready !== true) {
+      throw fail('ROM_RUNTIME_INTERFACE_MISMATCH', 'The selected runtime did not establish the active USB owner')
+    }
+    let runtimeMac = connected?.identity?.deviceId
+    let identitySource = 'runtime.deviceId'
+    if (runtimeMac == null) {
+      const result = await device.python.execute({ source: UNIQUE_ID_SOURCE, completion: 'wait', timeout, maxOutputChars: 512, signal })
+      checkAbort(signal)
+      const matches = typeof result?.output === 'string' ? [...result.output.matchAll(/^__EV_ROM_ID__([0-9a-f]{12})\r?$/gim)] : []
+      if (result?.ok !== true || result.outputTruncated !== false || matches.length !== 1 || /Traceback/.test(result.output)) {
+        throw fail('ROM_RUNTIME_IDENTITY_UNAVAILABLE', 'The legacy runtime did not return one complete unique_id')
+      }
+      runtimeMac = matches[0][1]
+      identitySource = 'machine.unique_id'
+    }
+    if (mac(runtimeMac) !== expectedMac) throw fail('ROM_RUNTIME_IDENTITY_MISMATCH', 'Runtime identity does not match the selected USB serial')
+    transition.identitySource = identitySource
+    checkAbort(signal)
+    transition.requested = true
+    transition.command = { attempted: true, acknowledged: false, outcome: 'unknown' }
+    try {
+      const result = await device.control({ action: 'bootloader', timeout, signal })
+      checkAbort(signal)
+      if (result?.ok !== true || result.operation !== 'bootloader') throw fail('ROM_BOOTLOADER_REJECTED', 'Runtime did not accept the bootloader command')
+      transition.command = { attempted: true, acknowledged: result.acknowledged === true, outcome: result.outcome ?? 'unknown' }
+    } catch (error) {
+      checkAbort(signal)
+      if (error.reset?.outcome !== 'unknown' && error.outcome !== 'unknown') throw error
+      transition.command = { attempted: true, acknowledged: false, outcome: 'unknown', error: errorInfo(error) }
+    }
+  } catch (error) { primary = error }
+  finally {
+    if (device) {
+      try { await device.disconnect(); transition.cleanup = { ok: true } }
+      catch (error) { transition.cleanup = { ok: false, error: errorInfo(error) } }
+    }
+  }
+  try { checkAbort(signal) } catch (error) { primary ??= error }
+  if (primary) {
+    primary.transition = transition
+    if (transition.cleanup?.ok === false) primary.cleanupError = transition.cleanup.error
+    throw primary
+  }
+
+  // No reset replay: only the selected physical device's ROM may finish the
+  // handoff. A successful match does not turn an unknown command into an ACK.
+  const deadline = now() + timeout
+  while (now() < deadline) {
+    checkAbort(signal)
+    const remaining = Math.max(1, Math.ceil(deadline - now()))
+    let candidates
+    try { candidates = await enumerate({ python, signal, timeout: remaining }) }
+    catch (error) {
+      checkAbort(signal)
+      throw Object.assign(fail('ROM_PORT_REBIND_FAILED', 'Cannot enumerate the selected device after bootloader submission', error), { transition })
+    }
+    checkAbort(signal)
+    if (now() >= deadline) break
+    if (!Array.isArray(candidates)) throw Object.assign(fail('ROM_PORT_ENUMERATION_FAILED', 'Serial enumeration returned invalid descriptors'), { transition })
+    const matches = candidates.filter(item => nativeRom(item) && mac(item.serialNumber) === expectedMac && physicalLocation(item.location) === location)
+    if (matches.length > 1) throw Object.assign(fail('ROM_PORT_AMBIGUOUS', 'Multiple ROM ports match the selected device'), { transition })
+    if (matches.length === 1) {
+      const selectedRom = matches[0]
+      transition.observed = 'rom'
+      transition.port = selectedRom.path
+      return { port: selectedRom.path, expectedMac, transition }
+    }
+    await sleep(Math.min(50, Math.max(1, deadline - now())), signal)
+  }
+  throw Object.assign(fail('ROM_PORT_REBIND_TIMEOUT', 'The selected device did not expose one matching ROM port within the deadline'), { transition })
+}
+
+
+/** Only for the caller's first read-only initialize failure, never read/write. */
+export async function recoverNodeRomPort(previous, { python = defaultPython, signal, timeout = 5000 } = {}, dependencies = {}) {
+  checkAbort(signal)
+  if (!Number.isSafeInteger(timeout) || timeout <= 0 || timeout > 5000) throw new RangeError('ROM recovery timeout must be positive and at most 5000 ms')
+  const expectedMac = mac(previous?.expectedMac)
+  const location = physicalLocation(previous?.transition?.location)
+  if (!expectedMac || !location || previous?.transition?.observed !== 'rom' || previous.transition.requested !== false) return null
+  if (mac(previous.transition.serial) !== expectedMac) return null
+  const enumerate = dependencies.listSerial ?? listSerial
+  const now = dependencies.now ?? (() => performance.now())
+  const deadline = now() + timeout
+  let ports
+  try { ports = await enumerate({ python, signal, timeout }) }
+  catch (error) {
+    checkAbort(signal)
+    throw fail('ROM_PORT_ENUMERATION_FAILED', 'Cannot verify the selected device for read-only initialization recovery', error)
+  }
+  checkAbort(signal)
+  if (now() >= deadline) throw fail('ROM_PORT_REBIND_TIMEOUT', 'Read-only initialization recovery enumeration exceeded its deadline')
+  if (!Array.isArray(ports)) throw fail('ROM_PORT_ENUMERATION_FAILED', 'Serial enumeration returned invalid descriptors')
+  const sameDevice = item => mac(item.serialNumber) === expectedMac && physicalLocation(item.location) === location
+  const existingRom = ports.filter(item => nativeRom(item) && sameDevice(item))
+  if (existingRom.length > 1) throw fail('ROM_PORT_AMBIGUOUS', 'Multiple ROM ports match the selected device')
+  if (existingRom.length) return null
+  const runtimes = ports.filter(nativeRuntime)
+  const conflicting = runtimes.filter(item => (mac(item.serialNumber) === expectedMac || physicalLocation(item.location) === location) && !sameDevice(item))
+  if (conflicting.length) throw fail('ROM_RUNTIME_IDENTITY_MISMATCH', 'Runtime descriptors do not match the previously selected ROM device')
+  const matches = runtimes.filter(sameDevice)
+  if (matches.length > 1) throw fail('ROM_PORT_AMBIGUOUS', 'Multiple runtime ports match the selected device')
+  if (!matches.length) return null
+  // Revalidate at prepare's fresh enumeration, before opening EV-MUX. An OS port
+  // may have been reused for a different board since the recovery snapshot.
+  const result = await prepareNodeRomPort({ port: matches[0].path, python, signal, timeout,
+    expectedIdentity: { mac: expectedMac, location } }, dependencies)
+  if (result.expectedMac !== expectedMac || result.transition?.observed !== 'rom' || physicalLocation(result.transition.location) !== location) {
+    throw fail('ROM_RUNTIME_IDENTITY_MISMATCH', 'Recovery did not preserve the selected physical device identity')
+  }
+  result.transition.recovery = { previousPort: previous.port, runtimePid: matches[0].productId }
+  return result
+}

package/src/node_serial.py

@@ -4,6 +4,7 @@
 import json
 import os
 import signal
+import struct
 import sys
 import threading
 
@@ -17,6 +18,18 @@ def _configure_serial_exclusive(port, platform=os.name):
         port.exclusive = True
 
 
+def _read_exact(stream, size):
+    data = bytearray()
+    while len(data) < size:
+        chunk = stream.read(size - len(data))
+        if not chunk:
+            if data:
+                raise OSError('Truncated serial bridge record')
+            return None
+        data.extend(chunk)
+    return bytes(data)
+
+
 def main():
     if sys.argv[1] == '--list':
         from serial.tools.list_ports import comports
@@ -55,7 +68,40 @@ def main():
         thread = threading.Thread(target=receive, daemon=True)
         thread.start()
         print('READY', file=sys.stderr, flush=True)
-        while data := sys.stdin.buffer.read1(8192):
+        while header := _read_exact(sys.stdin.buffer, 5):
+            kind, size = struct.unpack('>BI', header)
+            if kind not in (0, 1, 2) or size > 1048576:
+                raise OSError('Invalid serial bridge record')
+            data = _read_exact(sys.stdin.buffer, size)
+            if data is None:
+                raise OSError('Truncated serial bridge record')
+            if kind == 1:
+                request = json.loads(data)
+                try:
+                    baud = request['baudRate']
+                    if not isinstance(baud, int) or isinstance(baud, bool) or baud <= 0:
+                        raise ValueError('Invalid baudrate')
+                    port.flush()
+                    port.baudrate = baud
+                    response = {'id': request['id'], 'ok': True, 'baudRate': baud}
+                except (KeyError, ValueError, OSError, serial.SerialException):
+                    response = {'id': request.get('id'), 'ok': False}
+                print(json.dumps(response), file=sys.stderr, flush=True)
+                continue
+            if kind == 2:
+                request = json.loads(data)
+                try:
+                    request_id = request['id']
+                    if not isinstance(request_id, int) or isinstance(request_id, bool) or request_id <= 0:
+                        raise ValueError('Invalid drain request ID')
+                    # stdin records are processed in order. All preceding byte
+                    # records have completed port.write before this drain ACK.
+                    port.flush()
+                    response = {'id': request_id, 'ok': True, 'drained': True}
+                except (KeyError, ValueError, OSError, serial.SerialException):
+                    response = {'id': request.get('id'), 'ok': False}
+                print(json.dumps(response), file=sys.stderr, flush=True)
+                continue
             offset = 0
             while offset < len(data):
                 written = port.write(data[offset:])

package/src/node_transport.js

@@ -39,14 +39,27 @@ export function tcpTransport(options) {
 
 export function serialTransport(options) {
   const events = subscribers()
-  let child
+  let child, controlId = 0, baudRate = 115200
+  const pending = new Map()
+  const rejectControls = error => {
+    for (const request of pending.values()) request.reject(error)
+    pending.clear()
+  }
+  const send = (kind, bytes) => new Promise((resolveWrite, reject) => {
+    if (!child?.stdin.writable) return reject(fail('SERIAL_CLOSED', 'Serial adapter closed'))
+    const record = Buffer.allocUnsafe(5 + bytes.byteLength)
+    record.writeUInt8(kind, 0)
+    record.writeUInt32BE(bytes.byteLength, 1)
+    record.set(bytes, 5)
+    child.stdin.write(record, error => error ? reject(fail('SERIAL_WRITE', 'Serial write failed')) : resolveWrite())
+  })
   return {
     subscribe: events.subscribe,
     connect({ signal }) {
       return new Promise((resolveConnect, reject) => {
         const adapter = fileURLToPath(new URL('./node_serial.py', import.meta.url))
         child = spawn(options.python, ['-u', adapter, options.serial], { stdio: ['pipe', 'pipe', 'pipe'] })
-        let ready = false, settled = false, runtimeErrorReported = false, stderr = ''
+        let ready = false, settled = false, runtimeErrorReported = false, stderr = '', lines = ''
         const abort = () => {
           child.kill('SIGTERM')
           if (!settled) {
@@ -76,25 +89,78 @@ export function serialTransport(options) {
         child.stdin.on('error', () => { if (ready) reportRuntimeError() })
         child.stdout.on('data', bytes => events.emit('data', bytes))
         child.stderr.on('data', bytes => {
-          if (ready) return
           // Do not print Python errors: they can contain host paths or device data.
           stderr = (stderr + bytes.toString()).slice(-128)
-          if (stderr.split(/\r?\n/).includes('READY')) {
-            ready = true
-            settled = true
-            cleanup()
-            resolveConnect()
+          lines = (lines + bytes.toString()).slice(-8192)
+          for (let newline; (newline = lines.indexOf('\n')) !== -1;) {
+            const line = lines.slice(0, newline).trim()
+            lines = lines.slice(newline + 1)
+            if (line === 'READY' && !ready) {
+              ready = true
+              settled = true
+              baudRate = 115200
+              cleanup()
+              resolveConnect()
+              continue
+            }
+            let response
+            try { response = JSON.parse(line) } catch { continue }
+            const request = pending.get(response.id)
+            if (!request) continue
+            pending.delete(response.id)
+            if (request.kind === 'drain') {
+              if (response.ok === true && response.drained === true) request.resolve()
+              else request.reject(fail('SERIAL_DRAIN_FAILED', 'Serial adapter could not drain pending output'))
+            } else if (response.ok && response.baudRate === request.baudRate) {
+              baudRate = response.baudRate
+              request.resolve()
+            } else request.reject(fail('SERIAL_BAUD_UNSUPPORTED', 'Serial adapter rejected the requested baudrate'))
           }
         })
         // Wait for close rather than exit: stdout/stderr may still have buffered
         // data after exit, including the adapter's stable SERIAL_BUSY marker.
-        child.on('close', () => { cleanup(); if (!ready) failBeforeReady(); events.emit('close') })
+        child.on('close', () => { cleanup(); rejectControls(fail('SERIAL_CLOSED', 'Serial adapter closed')); if (!ready) failBeforeReady(); events.emit('close') })
         signal.addEventListener('abort', abort, { once: true })
         if (signal.aborted) abort()
       })
     },
-    writeBytes(bytes) { return new Promise((resolveWrite, reject) => child?.stdin.writable ? child.stdin.write(bytes, error => error ? reject(fail('SERIAL_WRITE', 'Serial write failed')) : resolveWrite()) : reject(fail('SERIAL_CLOSED', 'Serial adapter closed'))) },
+    writeBytes(bytes) { return send(0, bytes) },
+    drain({ signal } = {}) {
+      if (signal?.aborted) return Promise.reject(signal.reason ?? fail('CANCELLED', 'Serial drain cancelled'))
+      const id = ++controlId
+      return new Promise((resolve, reject) => {
+        const cleanup = () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); pending.delete(id) }
+        const abort = () => { cleanup(); reject(signal.reason ?? fail('CANCELLED', 'Serial drain cancelled')) }
+        const timer = setTimeout(() => { cleanup(); reject(fail('SERIAL_DRAIN_TIMEOUT', 'Serial drain timed out')) }, 2000)
+        pending.set(id, {
+          kind: 'drain',
+          resolve() { cleanup(); resolve() },
+          reject(error) { cleanup(); reject(error) },
+        })
+        signal?.addEventListener('abort', abort, { once: true })
+        send(2, Buffer.from(JSON.stringify({ id }))).catch(error => pending.get(id)?.reject(error))
+      })
+    },
+    setBaudRate(speed, { signal } = {}) {
+      if (!Number.isSafeInteger(speed) || speed <= 0) return Promise.reject(new RangeError('baudRate must be a positive integer'))
+      if (signal?.aborted) return Promise.reject(signal.reason ?? fail('CANCELLED', 'Serial speed change cancelled'))
+      const id = ++controlId
+      return new Promise((resolve, reject) => {
+        const cleanup = () => { clearTimeout(timer); signal?.removeEventListener('abort', abort); pending.delete(id) }
+        const abort = () => { cleanup(); reject(signal.reason ?? fail('CANCELLED', 'Serial speed change cancelled')) }
+        const timer = setTimeout(() => { cleanup(); reject(fail('SERIAL_BAUD_TIMEOUT', 'Serial speed change timed out')) }, 2000)
+        pending.set(id, {
+          baudRate: speed,
+          resolve() { cleanup(); resolve() },
+          reject(error) { cleanup(); reject(error) },
+        })
+        signal?.addEventListener('abort', abort, { once: true })
+        send(1, Buffer.from(JSON.stringify({ id, baudRate: speed }))).catch(error => pending.get(id)?.reject(error))
+      })
+    },
+    getDiagnostics() { return { baudRate } },
     async disconnect() {
+      rejectControls(fail('SERIAL_CLOSED', 'Serial adapter closed'))
       if (!child?.pid || child.exitCode !== null || child.signalCode !== null) return
       await new Promise(resolveExit => {
         const timer = setTimeout(() => { child.kill('SIGKILL') }, 2000)

package/src/rom_md5.js

@@ -0,0 +1,30 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+// MD5 verifies the flasher stub's transport digest; approved firmware still uses
+// full SHA-256. Web Crypto intentionally does not offer the legacy MD5 algorithm.
+export function romMd5(bytes) {
+  const input = new Uint8Array(Math.ceil((bytes.length + 9) / 64) * 64)
+  input.set(bytes); input[bytes.length] = 0x80
+  const view = new DataView(input.buffer)
+  view.setUint32(input.length - 8, (bytes.length * 8) >>> 0, true)
+  view.setUint32(input.length - 4, Math.floor(bytes.length / 0x20000000), true)
+  const rotations = [[7, 12, 17, 22], [5, 9, 14, 20], [4, 11, 16, 23], [6, 10, 15, 21]]
+  const state = [0x67452301, 0xefcdab89, 0x98badcfe, 0x10325476]
+  for (let offset = 0; offset < input.length; offset += 64) {
+    let [a, b, c, d] = state
+    for (let i = 0; i < 64; i++) {
+      const round = i >>> 4
+      const f = round === 0 ? (b & c) | (~b & d) : round === 1 ? (d & b) | (~d & c) : round === 2 ? b ^ c ^ d : c ^ (b | ~d)
+      const index = round === 0 ? i : round === 1 ? (5 * i + 1) % 16 : round === 2 ? (3 * i + 5) % 16 : (7 * i) % 16
+      const value = (a + f + Math.floor(Math.abs(Math.sin(i + 1)) * 0x100000000) + view.getUint32(offset + index * 4, true)) | 0
+      const shift = rotations[round][i % 4]
+      const next = (b + ((value << shift) | (value >>> (32 - shift)))) | 0
+      a = d; d = c; c = b; b = next
+    }
+    state[0] = (state[0] + a) >>> 0; state[1] = (state[1] + b) >>> 0
+    state[2] = (state[2] + c) >>> 0; state[3] = (state[3] + d) >>> 0
+  }
+  const output = new Uint8Array(16), result = new DataView(output.buffer)
+  state.forEach((value, index) => result.setUint32(index * 4, value, true))
+  return output
+}