@esp-vision/device-core 0.5.0 → 0.6.0

package/src/browser_rom_compat.js

@@ -1,73 +1,100 @@
 // SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
 // SPDX-License-Identifier: Apache-2.0
-// Compatibility for pinned tasmota-webserial-esptool 9.4.2. Keep changes per
-// instance: consumers need neither package-manager patches nor global prototypes.
-export function browserRomCompatibility(loader) {
-  const readPacket = loader.readPacket
-  loader.readPacket = async function (timeout) {
+import { romMd5 } from './rom_md5.js'
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+export const romError = (code, message, cause) => Object.assign(new Error(message, { cause }), { code })
+export function romWords(...values) {
+  const bytes = new Uint8Array(values.length * 4), view = new DataView(bytes.buffer)
+  values.forEach((value, index) => view.setUint32(index * 4, value, true))
+  return bytes
+}
+
+// Per-instance fixes for esptool-js 0.7.1, not patches to global prototypes.
+// Its parser loses a whole buffered chunk (including a valid packet) when a
+// boot-log prefix precedes SLIP. Keep the upstream buffer/readLoop and framing,
+// while bounding a complete packet by one deadline, including slow partial data.
+export function browserTransportCompatibility(transport) {
+  transport.read = async function (timeout) {
     const deadline = Date.now() + timeout
+    let started = false, escaping = false
+    const packet = []
     for (;;) {
-      try { return await readPacket.call(this, Math.max(1, deadline - Date.now())) }
-      catch (error) {
-        // Only a byte before the SLIP header is safe to discard. Preserve invalid
-        // escapes, mid-packet errors, I/O failures and the overall timeout.
-        if (!/^Invalid head of packet \(/.test(error.message) || Date.now() >= deadline) throw error
+      if (Date.now() >= deadline) throw romError('ROM_READ_TIMEOUT', 'Timed out receiving a complete ROM packet')
+      if (!this.buffer.length) {
+        if (!this.device.readable) throw romError('ROM_PORT_LOST', 'Serial device disconnected; select its current download port again')
+        await sleep(Math.min(2, Math.max(1, deadline - Date.now())))
+        continue
       }
-    }
-  }
-  // runStub returns a separate loader. Its command replies use two status bytes;
-  // the ROM loader still expects four and cannot issue reset register writes.
-  let activeStub
-  const hardReset = loader.hardReset
-  loader.hardReset = function (...args) {
-    return activeStub ? activeStub.hardReset(...args) : hardReset.apply(this, args)
-  }
-  const runStub = loader.runStub
-  loader.runStub = async function (skipFlashDetection = false) {
-    const memFinish = this.memFinish, packet = this.readPacket
-    const nativeUsb = this.isUsbJtagOrOtg === true
-    if (nativeUsb) {
-      // USB can reset before ROM sends MEM_END's reply. Do not claim success:
-      // upstream must still receive and validate OHAI from the running stub.
-      this.memFinish = async (...args) => {
-        try { return await memFinish.apply(this, args) }
-        catch (error) {
-          if (!/timed?\s*out|timeout/i.test(error.message)) throw error
-        }
+      const bytes = this.buffer
+      this.buffer = new Uint8Array(0)
+      if (!started && bytes[0] !== 0xc0) this.detectPanicHandler?.(bytes)
+      for (let i = 0; i < bytes.length; i++) {
+        const byte = bytes[i]
+        if (!started) {
+          if (byte === 0xc0) started = true
+        } else if (escaping) {
+          escaping = false
+          if (byte !== 0xdc && byte !== 0xdd) throw romError('ROM_SLIP_ESCAPE', `Invalid SLIP escape (0xdb, 0x${byte.toString(16)})`)
+          packet.push(byte === 0xdc ? 0xc0 : 0xdb)
+        } else if (byte === 0xdb) escaping = true
+        else if (byte === 0xc0) {
+          this.buffer = this.appendArray(bytes.slice(i + 1), this.buffer)
+          if (packet.length) return new Uint8Array(packet)
+          started = true
+        } else packet.push(byte)
+        if (packet.length > 65536) throw romError('ROM_PACKET_SIZE', 'ROM packet exceeds the bounded receive size')
       }
-      this.readPacket = timeout => packet.call(this, Math.max(timeout, 5000))
     }
-    try {
-      const stub = await runStub.call(this, skipFlashDetection)
-      if (!stub.IS_STUB) throw new Error('This device has no supported browser flash stub')
-      browserStubCompatibility(stub)
-      activeStub = stub
-      return stub
-    } finally { this.memFinish = memFinish; this.readPacket = packet }
   }
-  return loader
+  const write = transport.write
+  transport.write = async function (bytes) {
+    if (!this.device.writable) throw romError('ROM_PORT_LOST', 'Serial device disconnected; select its current download port again')
+    if (typeof this.slipWriter !== 'function') return write.call(this, bytes)
+    const writer = this.device.writable.getWriter()
+    try { await writer.write(this.slipWriter(bytes)) }
+    finally { writer.releaseLock() }
+  }
+  return transport
 }
 
-function browserStubCompatibility(stub) {
-  // Official esp-flasher-stub erases the entire region in FLASH_BEGIN. Its erase
-  // duration must scale with image size rather than the short command timeout.
-  const command = stub.checkCommand
-  stub.checkCommand = function (opcode, buffer, checksum, timeout) {
-    if (opcode === 0x02 && buffer?.length >= 4) {
-      const size = (buffer[0] | buffer[1] << 8 | buffer[2] << 16 | buffer[3] << 24) >>> 0
-      timeout = Math.max(timeout ?? 0, 3000, 30000 * size / 1000000)
-    }
-    return command.call(this, opcode, buffer, checksum, timeout)
+// #273 remains an open timing investigation. This deliberately bounded read
+// uses 1 KiB blocks and one outstanding packet, then consumes AND verifies the
+// protocol's final MD5 packet. Replace this shim when a pinned upstream release
+// implements these semantics and passes read -> write -> full readback coverage.
+export async function readBrowserFlash(loader, address, size, progress, { timeout = 5000 } = {}) {
+  if (!loader.IS_STUB) throw romError('ROM_STUB_REQUIRED', 'Readback requires an initialized flasher stub')
+  if (!Number.isSafeInteger(address) || address < 0 || !Number.isSafeInteger(size) || size <= 0 || size > 65536 || address + size > 0x100000000) throw new RangeError('ROM read requires a positive range of at most 64 KiB')
+  const status = await loader.checkCommand('read flash', loader.ESP_READ_FLASH, romWords(address, size, 1024, 1), 0, 0, timeout)
+  if (status !== 0) throw romError('ROM_READ_STATUS', `Flash read command failed: ${status}`)
+  const output = new Uint8Array(size)
+  let received = 0
+  const deadline = Date.now() + Math.max(timeout, Math.ceil(size * 10 * 1000 / (loader.transport.baudrate || 115200)) + timeout)
+  const read = () => loader.transport.read(Math.max(1, Math.min(timeout, deadline - Date.now())))
+  while (received < size) {
+    if (Date.now() >= deadline) throw romError('ROM_READ_TIMEOUT', 'Flash readback exceeded its deadline')
+    const packet = await read()
+    if (!(packet instanceof Uint8Array) || !packet.length || packet.length > 1024 || received + packet.length > size) throw romError('ROM_READ_PACKET', 'Invalid or oversized flash readback packet')
+    output.set(packet, received); received += packet.length
+    await loader.transport.write(romWords(received))
+    progress?.(packet, received, size)
   }
-  // Stub commands use their own loader instance and inherit the same SLIP issue.
-  const readPacket = stub.readPacket
-  stub.readPacket = async function (timeout) {
-    const deadline = Date.now() + timeout
-    for (;;) {
-      try { return await readPacket.call(this, Math.max(1, deadline - Date.now())) }
-      catch (error) {
-        if (!/^Invalid head of packet \(/.test(error.message) || Date.now() >= deadline) throw error
-      }
+  const digest = await read()
+  if (!(digest instanceof Uint8Array) || digest.length !== 16) throw romError('ROM_READ_DIGEST', 'Missing or malformed flash readback MD5 digest')
+  const expected = romMd5(output)
+  if (digest.some((byte, index) => byte !== expected[index])) throw romError('ROM_READ_DIGEST', 'Flash readback MD5 digest mismatch')
+  return output
+}
+
+export function browserRomCompatibility(loader, { nativeUsb = false } = {}) {
+  const finish = loader.memFinish
+  if (nativeUsb) loader.memFinish = async function (...args) {
+    try { return await finish.apply(this, args) }
+    catch (error) {
+      // Some native-USB ROMs omit MEM_END acknowledgement. runStub must still
+      // consume and validate the exact OHAI greeting before setting IS_STUB.
+      if (!/timed?\s*out|timeout|serial data stream stopped|no serial data received/i.test(error.message)) throw error
     }
   }
+  return loader
 }

package/src/browser_serial.js

@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+
+const failure = (code, message) => Object.assign(new Error(message), { code })
+const cancelled = signal => signal?.reason instanceof Error ? signal.reason
+  : Object.assign(new Error('Serial operation cancelled'), { name: 'AbortError' })
+
+/** Passive Web Serial byte adapter. The UI supplies its already authorized port. */
+export function serialTransport({ port, signals = { dataTerminalReady: true, requestToSend: false }, bufferSize = 256 * 1024 } = {}) {
+  if (!port || typeof port.open !== 'function' || typeof port.close !== 'function') throw new TypeError('A browser SerialPort is required')
+  if (!Number.isSafeInteger(bufferSize) || bufferSize <= 0 || bufferSize > 16 * 1024 * 1024) throw new RangeError('bufferSize must be between 1 byte and 16 MiB')
+  let listener = null, reader = null, writer = null, reading = null
+  let stopped = true, reopening = false, opened = false, opening = false, generation = 0, baudRate = 115200
+  let queue = Promise.resolve()
+  const ordered = operation => {
+    const result = queue.then(operation)
+    queue = result.catch(() => {})
+    return result
+  }
+  const emit = (event, value) => listener?.[event]?.(value)
+  const check = signal => {
+    if (signal?.aborted) throw cancelled(signal)
+    if (stopped) throw failure('SERIAL_CLOSED', 'Browser serial adapter is closed')
+  }
+  const disconnected = () => { if (!stopped) emit('close') }
+  const stopStreams = async () => {
+    generation += 1
+    try { await reader?.cancel() } catch { /* Unplugged streams may already be errored. */ }
+    await reading?.catch(() => {})
+    reading = null
+    reader = null
+    if (writer) { writer.releaseLock(); writer = null }
+  }
+  const closePort = async () => {
+    await stopStreams()
+    if (opened) {
+      await port.close()
+      opened = false
+    }
+  }
+  const startStreams = () => {
+    if (!port.readable || !port.writable) throw failure('SERIAL_CLOSED', 'Browser serial streams are unavailable')
+    const active = ++generation
+    const input = reader = port.readable.getReader()
+    writer = port.writable.getWriter()
+    reading = (async () => {
+      try {
+        while (!stopped && active === generation) {
+          const { value, done } = await input.read()
+          if (done) {
+            if (!stopped && !reopening && active === generation) emit('close')
+            break
+          }
+          if (value?.byteLength && active === generation) emit('data', value)
+        }
+      } catch {
+        if (!stopped && !reopening && active === generation) emit('error', failure('SERIAL_READ', 'Browser serial read failed'))
+      } finally {
+        input.releaseLock()
+        if (reader === input) reader = null
+      }
+    })()
+  }
+  const open = async (speed, signal) => {
+    check(signal)
+    opening = true
+    try {
+      await port.open({ baudRate: speed, bufferSize })
+      opened = true
+      check(signal)
+      try { await port.setSignals?.(signals) } catch { /* Native USB interfaces may not expose modem control lines. */ }
+      check(signal)
+      baudRate = speed
+      startStreams()
+    } catch (error) { await closePort().catch(() => {}); throw error }
+    finally { opening = false }
+  }
+  return {
+    subscribe(value) {
+      if (listener) throw failure('TRANSPORT_BUSY', 'Already subscribed')
+      listener = value
+      return () => { if (listener === value) listener = null }
+    },
+    connect({ signal } = {}) {
+      if (!stopped) return Promise.reject(failure('TRANSPORT_BUSY', 'Browser serial adapter is already connected'))
+      stopped = false
+      port.addEventListener?.('disconnect', disconnected)
+      const connecting = ordered(async () => {
+        try { await open(115200, signal) }
+        catch (error) {
+          stopped = true
+          port.removeEventListener?.('disconnect', disconnected)
+          throw error
+        }
+      })
+      if (!signal) return connecting
+      return new Promise((resolve, reject) => {
+        const abort = () => { stopped = true; port.removeEventListener?.('disconnect', disconnected); cleanup(); reject(cancelled(signal)) }
+        const cleanup = () => signal.removeEventListener('abort', abort)
+        signal.addEventListener('abort', abort, { once: true })
+        connecting.then(value => { cleanup(); resolve(value) }, error => { cleanup(); reject(error) })
+        if (signal.aborted) abort()
+      })
+    },
+    writeBytes(bytes) {
+      return ordered(async () => { check(); if (!writer) throw failure('SERIAL_CLOSED', 'Browser serial writer is unavailable'); await writer.write(bytes) })
+    },
+    setBaudRate(speed, { signal } = {}) {
+      if (!Number.isSafeInteger(speed) || speed <= 0) return Promise.reject(new RangeError('baudRate must be a positive integer'))
+      return ordered(async () => {
+        check(signal)
+        if (opened && baudRate === speed) return
+        // Releasing both locks is required by Web Serial before close. Keep
+        // subscribers attached; this internal reopen is not a device removal.
+        reopening = true
+        try { await closePort(); await open(speed, signal) }
+        finally { reopening = false }
+      })
+    },
+    disconnect() {
+      stopped = true
+      port.removeEventListener?.('disconnect', disconnected)
+      // Web Serial cannot cancel open(). Do not block cancellation on it; the
+      // late completion checks stopped and closes its newly acquired port.
+      if (opening && !opened) return Promise.resolve()
+      return ordered(closePort)
+    },
+    getDiagnostics() { return { baudRate, connected: opened, reopening } },
+  }
+}

package/src/device.js

@@ -135,11 +135,12 @@ class Device {
   }
 
   async connect(options = {}) {
-    object(options, ['transport', 'role', 'expectedDevice', 'timeout', 'signal', 'probeRepl'], 'connect')
-    const { role = 'unknown', expectedDevice = null, timeout = 30000, signal, probeRepl = true } = options
+    object(options, ['transport', 'role', 'expectedDevice', 'timeout', 'signal', 'probeRepl', 'autoBaud'], 'connect')
+    const { role = 'unknown', expectedDevice = null, timeout = 60000, signal, probeRepl = true, autoBaud = true } = options
     if (!['unknown', 'usj', 'usb', 'uart', 'tcp'].includes(role)) throw new TypeError('role must be usj, usb, uart or tcp')
     if (!Number.isFinite(timeout) || timeout <= 0) throw new RangeError('timeout must be positive')
     if (typeof probeRepl !== 'boolean') throw new TypeError('probeRepl must be a boolean')
+    if (typeof autoBaud !== 'boolean') throw new TypeError('autoBaud must be a boolean')
     if (signal !== undefined && (!signal || typeof signal.addEventListener !== 'function' || typeof signal.aborted !== 'boolean')) throw new TypeError('signal must be an AbortSignal')
     if (signal?.aborted) throw cancellation(signal)
     if (this.#updating || this.#connecting || this.#disconnecting || this.#session) throw failure('DEVICE_BUSY', 'Disconnect before opening another connection')
@@ -184,7 +185,7 @@ class Device {
       this.#unsubscribe = transport.subscribe({ data: bytes => { if (this.#session === session) session.feedBytes(bytes) }, error: lost, close: () => lost() })
       if (typeof this.#unsubscribe !== 'function') throw new TypeError('Transport subscribe must synchronously return an unsubscribe function')
       if (transport.connect) await abortable(transport.connect({ signal: lifecycle.signal }), lifecycle.signal)
-      await abortable(session.negotiate({ role, expectedDevice, probeRepl, signal: lifecycle.signal }), lifecycle.signal)
+      await abortable(session.negotiate({ role, expectedDevice, probeRepl, autoBaud, signal: lifecycle.signal }), lifecycle.signal)
       if (lifecycle.signal.aborted || this.#session !== session) throw cancellation(lifecycle.signal)
       this.#api = {
         python: createPythonApi({ session, state: this.#state }),
@@ -210,7 +211,7 @@ class Device {
     ++this.#generation
     this.#lifecycle?.abort(reason)
     let error
-    try { if (session?.sessionId) await session.release() } catch (caught) { error = caught }
+    try { if (session && (session.sessionId || session.resetPromise)) await session.release() } catch (caught) { error = caught }
     finally {
       session?.close(reason)
       this.#session = null

package/src/device_bindings.js

@@ -3,6 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { requireObservedCameraCapture } from './device_capture.js'
 
 export const EPHEMERAL_PYTHON_PATH = '/.espvision_agent_run.py'
 
@@ -326,14 +327,14 @@ export function bindSessionDeviceActions(registry, {
     { timeout: input.timeoutMs, channel: input.channel, signal },
   ))
   registry.bind('frame.capture', async (input, { session, signal }) => {
-    session.lastDebugImage = null
-    await session.rpc('debug.capture_frame', {}, {
+    requireObservedCameraCapture(session)
+    const image = await session.rpc('debug.capture_frame', {}, {
       timeout: input.timeoutMs,
       channel: 'debug.rpc',
       signal,
+      binaryResponse: true,
     })
-    if (!session.lastDebugImage) throw new Error('Firmware returned no JPEG frame')
-    return session.lastDebugImage
+    return { base64: bytesToBase64(image.data), metadata: image.metadata }
   })
 
   return { evidence, controllerFor }

package/src/device_capture.js

@@ -0,0 +1,11 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+
+export const OBSERVED_CAMERA_FEATURE = 'debug.capture_frame.observed.v1'
+
+/** Older capture_frame implementations can overwrite an application's Image. */
+export function requireObservedCameraCapture(session) {
+  if (!session.hasFeature?.('debug.capture_frame') || !session.hasFeature?.(OBSERVED_CAMERA_FEATURE)) {
+    throw Object.assign(new Error(`Safe camera observation requires firmware feature ${OBSERVED_CAMERA_FEATURE}; update ESP-VISION firmware before capturing camera frames`), { code: 'UNSUPPORTED_OPERATION' })
+  }
+}

package/src/device_operations.js

@@ -2,6 +2,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { withDeviceOperation } from './device_python.js'
+import { requireObservedCameraCapture } from './device_capture.js'
 
 function failure(code, message) { return Object.assign(new Error(message), { code }) }
 function record(value, keys, label) {
@@ -163,7 +164,8 @@ export function createDeviceOperations({ session, state = {} }) {
       if (request.format !== undefined && request.format !== 'jpeg') throw new TypeError('Only jpeg capture is supported')
       if (request.quality !== undefined && (!Number.isInteger(request.quality) || request.quality < 1 || request.quality > 100)) throw new RangeError('quality must be an integer from 1 to 100')
       const method = request.source === 'camera' ? 'debug.capture_frame' : 'debug.capture_screen'
-      supported(session, method)
+      if (request.source === 'camera') requireObservedCameraCapture(session)
+      else supported(session, method)
       return withDeviceOperation(state, 'capture', () => session.captureImage(method, request.quality === undefined ? {} : { quality: request.quality }, opts))
     },
   }