@esp-vision/device-core 0.5.1 → 0.6.1

package/src/node_serial.py

@@ -4,12 +4,64 @@
 import json
 import os
 import signal
+import struct
 import sys
 import threading
 
 import serial
 
 
+def _report_serial_error(stage, error):
+    """Emit bounded OS diagnostics, never exception text or transferred bytes."""
+    number = getattr(error, 'errno', None)
+    winerror = getattr(error, 'winerror', None)
+    cause = error.__cause__ or error.__context__
+    if not isinstance(number, int) and cause is not None:
+        number = getattr(cause, 'errno', None)
+    if not isinstance(winerror, int) and cause is not None:
+        winerror = getattr(cause, 'winerror', None)
+    def bounded_number(value):
+        if isinstance(value, int) and not isinstance(value, bool) and -0x80000000 <= value <= 0xffffffff:
+            return value
+        return None
+    number = bounded_number(number)
+    winerror = bounded_number(winerror)
+    # Pyserial sometimes wraps a Windows API failure without preserving errno.
+    # Only recognize fixed API names/messages; arbitrary exception text may
+    # contain application bytes and must not cross this diagnostic channel.
+    text = str(error)[:512]
+    message = 'Serial ' + stage + ' failed'
+    if number is not None and 0 < number < 4096:
+        message = os.strerror(number)
+    else:
+        for needle, safe in (
+            ('ClearCommError', 'ClearCommError failed'),
+            ('GetOverlappedResult', 'GetOverlappedResult failed'),
+            ('ReadFile', 'ReadFile failed'),
+            ('WriteFile', 'WriteFile failed'),
+            ('readiness to read but returned no data', 'Device reports readiness to read but returned no data'),
+            ('write timeout', 'Serial write timed out'),
+            ('Zero-byte serial write', 'Serial write returned zero bytes'),
+        ):
+            if needle.lower() in text.lower():
+                message = safe
+                break
+    record = {'kind': 'serial.error', 'stage': stage, 'type': type(error).__name__[:64],
+              'errno': number, 'winerror': winerror, 'message': message[:160]}
+    # One small line keeps READY/control records intact when the reader thread
+    # fails concurrently with the main thread. stderr failure is terminal too.
+    line = (json.dumps(record, ensure_ascii=True) + '\n').encode()
+    try:
+        offset = 0
+        while offset < len(line):
+            count = os.write(2, line[offset:])
+            if count <= 0:
+                break
+            offset += count
+    except OSError:
+        pass
+
+
 def _configure_serial_exclusive(port, platform=os.name):
     # pyserial implements this as a non-blocking advisory lock on POSIX. The
     # Windows backend does not support this option, so leave its behavior alone.
@@ -17,6 +69,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
@@ -37,16 +101,24 @@ def main():
         raise SystemExit(0)
 
     def receive():
-        try:
-            while not stopped.is_set():
+        while not stopped.is_set():
+            try:
                 data = port.read(8192)
-                if data:
+            except (OSError, serial.SerialException) as error:
+                if not stopped.is_set():
+                    _report_serial_error('read', error)
+                    os._exit(2)
+                return
+            if data:
+                try:
                     offset = 0
                     while offset < len(data):
                         offset += os.write(1, data[offset:])
-        except (OSError, serial.SerialException):
-            if not stopped.is_set():
-                os._exit(2)
+                except OSError as error:
+                    if not stopped.is_set():
+                        _report_serial_error('stdout', error)
+                        os._exit(2)
+                    return
 
     signal.signal(signal.SIGTERM, terminate)
     signal.signal(signal.SIGINT, terminate)
@@ -55,13 +127,50 @@ 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):
-            offset = 0
-            while offset < len(data):
-                written = port.write(data[offset:])
-                if not written:
-                    raise OSError('Zero-byte serial write')
-                offset += written
+        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
+            try:
+                offset = 0
+                while offset < len(data):
+                    written = port.write(data[offset:])
+                    if not written:
+                        raise OSError('Zero-byte serial write')
+                    offset += written
+            except (OSError, serial.SerialException) as error:
+                _report_serial_error('write', error)
+                raise SystemExit(2) from None
     finally:
         stopped.set()
         port.close()

package/src/node_transport.js

@@ -39,62 +39,177 @@ export function tcpTransport(options) {
 
 export function serialTransport(options) {
   const events = subscribers()
-  let child
+  let child, connection, lastError = null, 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 = ''
+        const bridge = child = spawn(options.python, ['-u', adapter, options.serial], { stdio: ['pipe', 'pipe', 'pipe'] })
+        const current = connection = { intentional: false }
+        lastError = null
+        let adapterCause = null, processCause = null
+        const safeCause = value => {
+          if (value?.kind !== 'serial.error' || !['read', 'write', 'stdout'].includes(value.stage)
+              || typeof value.type !== 'string' || typeof value.message !== 'string') return null
+          const integer = n => Number.isSafeInteger(n) && n >= -0x80000000 && n <= 0xffffffff ? n : null
+          return { stage: value.stage, type: value.type.slice(0, 64), errno: integer(value.errno),
+            winerror: integer(value.winerror), message: value.message.replace(/[\r\n\x00-\x1f\x7f]/g, ' ').slice(0, 160) }
+        }
+        const errorDetails = (exitCode = null, signal = null) => ({
+          ...(adapterCause ?? processCause ?? { stage: 'process', type: 'ProcessExit', errno: null, winerror: null,
+            message: 'Serial adapter exited unexpectedly' }),
+          exitCode: Number.isInteger(exitCode) ? exitCode : null,
+          signal: typeof signal === 'string' ? signal.slice(0, 32) : null,
+        })
+        let ready = false, settled = false, runtimeErrorReported = false, stderr = '', lines = ''
         const abort = () => {
-          child.kill('SIGTERM')
+          current.intentional = true
+          bridge.kill('SIGTERM')
           if (!settled) {
             settled = true
             reject(fail('CANCELLED', 'Serial connection cancelled'))
           }
         }
         const cleanup = () => signal.removeEventListener('abort', abort)
-        const serialError = () => {
-          const code = ['SERIAL_ACCESS_DENIED', 'SERIAL_BUSY'].find(code => stderr.includes(code)) ?? 'SERIAL_ERROR'
-          return fail(code, 'Serial adapter failed; ensure Python, pyserial and port access are available')
+        const serialError = details => {
+          const code = ready ? 'SERIAL_ERROR' : ['SERIAL_ACCESS_DENIED', 'SERIAL_BUSY'].find(code => stderr.includes(code)) ?? 'SERIAL_ERROR'
+          const message = ready && details?.stage !== 'process'
+            ? `Serial adapter ${details.stage} failed: ${details.message}`
+            : 'Serial adapter failed; ensure Python, pyserial and port access are available'
+          const error = fail(code, message)
+          error.details = details ?? errorDetails()
+          error.cause = Object.assign(new Error(error.details.message), { ...error.details, name: error.details.type })
+          return error
         }
-        const failBeforeReady = () => {
+        const failBeforeReady = details => {
           if (settled) return
           settled = true
           cleanup()
-          const error = serialError()
+          const error = serialError(details)
           reject(error)
           events.emit('error', error)
         }
-        const reportRuntimeError = () => {
+        const reportRuntimeError = details => {
           if (runtimeErrorReported) return
           runtimeErrorReported = true
-          events.emit('error', serialError())
+          const error = serialError(details)
+          lastError = { ...error.details }
+          events.emit('error', error)
         }
-        child.on('error', () => { if (ready) reportRuntimeError() })
-        child.stdin.on('error', () => { if (ready) reportRuntimeError() })
+        const recordProcessError = (stage, error) => {
+          processCause = { stage, type: 'ProcessError', errno: null, winerror: null,
+            message: typeof error?.code === 'string' && /^[A-Z0-9_]{1,32}$/.test(error.code)
+              ? `Serial adapter ${stage} failed (${error.code})` : `Serial adapter ${stage} failed` }
+        }
+        child.on('error', error => recordProcessError('process', error))
+        child.stdin.on('error', error => recordProcessError('stdin', error))
         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 diagnostic = safeCause(response)
+            if (diagnostic) { adapterCause = diagnostic; 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', (code, signal) => {
+          cleanup()
+          if (connection !== current) return
+          const details = errorDetails(code, signal)
+          if (current.intentional) {
+            const error = fail('SERIAL_CLOSED', 'Serial adapter closed')
+            rejectControls(error)
+            if (!settled) { settled = true; reject(error) }
+          } else {
+            lastError = { ...details }
+            const error = serialError(details)
+            rejectControls(error)
+            if (!ready) failBeforeReady(details)
+            else reportRuntimeError(details)
+          }
+          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, ...(lastError ? { lastError: { ...lastError } } : {}) } },
     async disconnect() {
+      if (connection) connection.intentional = true
+      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
+}