@esp-vision/device-core 0.6.0 → 0.7.0

package/src/node_serial.py

@@ -11,6 +11,57 @@ 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.
@@ -50,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)
@@ -102,12 +161,16 @@ def main():
                     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:])
-                if not written:
-                    raise OSError('Zero-byte serial write')
-                offset += written
+            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,7 +39,7 @@ export function tcpTransport(options) {
 
 export function serialTransport(options) {
   const events = subscribers()
-  let child, controlId = 0, baudRate = 115200
+  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)
@@ -58,35 +58,65 @@ export function serialTransport(options) {
     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'] })
+        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)
+        }
+        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', () => { if (ready) reportRuntimeError() })
-        child.stdin.on('error', () => { if (ready) reportRuntimeError() })
+        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 => {
           // Do not print Python errors: they can contain host paths or device data.
@@ -105,6 +135,8 @@ export function serialTransport(options) {
             }
             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)
@@ -119,7 +151,23 @@ export function serialTransport(options) {
         })
         // 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(); rejectControls(fail('SERIAL_CLOSED', 'Serial adapter closed')); 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()
       })
@@ -158,8 +206,9 @@ export function serialTransport(options) {
         send(1, Buffer.from(JSON.stringify({ id, baudRate: speed }))).catch(error => pending.get(id)?.reject(error))
       })
     },
-    getDiagnostics() { return { baudRate } },
+    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 => {

package/src/rom_identity.js

@@ -0,0 +1,9 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+
+// This option is validated before opening a port or loading a ROM backend.
+export function normalizeExpectedMac(value) {
+  if (value === undefined) return undefined
+  if (typeof value !== 'string' || value.length !== 12 || !/^[0-9a-f]{12}$/i.test(value)) throw new TypeError('expectedMac must contain exactly 12 hexadecimal characters')
+  return value.toLowerCase()
+}

package/tests/check-browser.mjs

@@ -50,12 +50,13 @@ try {
     async setSignals() { throw new Error('OTG must not require UART control signals') },
   })
   try {
-    prototype.detectChip = async function () { detects++; await this.transport.connect(115200); this.chip = { CHIP_NAME: 'ESP32-S31', getChipRevision: async () => 0 } }
+    prototype.detectChip = async function () { detects++; await this.transport.connect(115200); this.chip = { CHIP_NAME: 'ESP32-S31', getChipRevision: async () => 0, readMac: async () => '30:ed:a0:ed:a1:b0' } }
     prototype.getSecurityInfo = async () => ({ flags: 0, flashCryptCnt: 0 })
-    const controller = new AbortController(), loader = context.DeviceCore.openBrowserRom({ port: fakePort(), signal: controller.signal })
+    const controller = new AbortController(), loader = context.DeviceCore.openBrowserRom({ port: fakePort(), signal: controller.signal, expectedMac: '30EDA0EDA1B0' })
+    assert.equal(loader.chipMac, null)
     const first = loader.initialize()
     assert.equal(loader.initialize(), first)
-    await first; controller.abort()
+    await first; assert.equal(loader.chipMac, '30eda0eda1b0'); controller.abort()
     assert.equal(closes, 0, 'abort after initialization preserves ongoing flash')
     await loader.disconnect(); await loader.disconnect()
     assert.equal(closes, 1); assert.equal(detects, 1)
@@ -73,6 +74,18 @@ try {
     cancelled.abort(); await assert.rejects(starting, { name: 'AbortError' })
     finishOpen(); await new Promise(resolve => setTimeout(resolve, 5))
     assert.equal(closes, 3); assert.equal(waitingPort.readable, null)
+    prototype.runStub = async function () { this.IS_STUB = true }
+    let finishErase
+    prototype.checkCommand = () => new Promise(resolve => { finishErase = resolve })
+    const eraseCancel = new AbortController(), erasePort = fakePort()
+    const eraseLoader = context.DeviceCore.openBrowserRom({ port: erasePort, signal: eraseCancel.signal })
+    await eraseLoader.initialize(); const eraseStub = await eraseLoader.runStub()
+    const erasing = eraseStub.eraseRegion(0x710000, 4096)
+    const failedErase = assert.rejects(erasing, { name: 'AbortError' })
+    eraseCancel.abort(); await failedErase
+    finishErase(0)
+    assert.equal(closes, 4); assert.equal(erasePort.readable, null)
+    await assert.rejects(eraseStub.eraseRegion(0x710000, 4096))
     const data = new Uint8Array([0xe9, 1, 2, 3]), table = new Uint8Array([4, 5])
     const hash = async bytes => Array.from(new Uint8Array(await webcrypto.subtle.digest('SHA-256', bytes)), byte => byte.toString(16).padStart(2, '0')).join('')
     const release = { board: 'BOARD', version: 'browser-test', image: {
@@ -102,10 +115,16 @@ try {
       this.transport.buffer = new Uint8Array([...frame(bytes), ...frame(digest)])
       return 0
     }
+    const wrongPort = fakePort(), wrong = context.DeviceCore.openBrowserRom({ port: wrongPort, expectedMac: '30eda0eda1b1' })
+    const beforeStubs = stubs, beforeWrites = writes
+    await assert.rejects(wrong.initialize(), { code: 'ROM_IDENTITY_CHANGED' })
+    assert.equal(wrong.chipMac, null); assert.equal(wrongPort.readable, null)
+    await assert.rejects(async () => wrong.runStub(), { code: 'ROM_CLOSED' })
+    assert.equal(stubs, beforeStubs); assert.equal(writes, beforeWrites)
     const updatePort = fakePort(), openUpdate = updatePort.open
     updatePort.open = async function (...args) { await openUpdate.apply(this, args); this.writable = { getWriter: () => ({ async write() {}, releaseLock() {} }) } }
     const beforeCloses = closes
-    const updated = await device.firmware.update({ ...request, signal: writing.signal, openLoader: ({ signal }) => context.DeviceCore.openBrowserRom({ port: updatePort, signal }) })
+    const updated = await device.firmware.update({ ...request, signal: writing.signal, openLoader: ({ signal }) => context.DeviceCore.openBrowserRom({ port: updatePort, signal, expectedMac: '30eda0eda1b0' }) })
     assert.equal(updated.verified, true); assert.equal(updated.needsReset, false)
     assert.equal(stubs, 1); assert.equal(writes, 1); assert.equal(resets, 4)
     assert.equal(closes, beforeCloses + 1)

package/tests/check-package.mjs

@@ -7,6 +7,7 @@ import { tmpdir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import process from 'node:process'
+import { npmCommand } from '../scripts/npm-command.mjs'
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
 const manifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'))
@@ -14,7 +15,7 @@ assert.equal(manifest.license, 'Apache-2.0')
 assert.match(await readFile(join(root, 'LICENSE'), 'utf8'), /Apache License[\s\S]*Version 2\.0/)
 const temporary = await mkdtemp(join(tmpdir(), 'esp-vision-device-core-package-'))
 try {
-  const [packed] = JSON.parse(execFileSync('npm', ['pack', '--json', '--ignore-scripts', '--pack-destination', temporary], { cwd: root, encoding: 'utf8' }))
+  const [packed] = JSON.parse(execFileSync(...npmCommand(['pack', '--json', '--ignore-scripts', '--pack-destination', temporary]), { cwd: root, encoding: 'utf8' }))
   assert.ok(packed.files.some(({ path }) => path === 'LICENSE'))
   assert.ok(packed.files.some(({ path }) => path === 'NOTICE'))
   assert.ok(packed.files.some(({ path }) => path === 'schemas/device-actions-v1.json'))
@@ -25,7 +26,7 @@ try {
   assert.ok(!packed.files.some(({ path }) => path.includes('__pycache__') || path.endsWith('.pyc')), 'Never ship host Python bytecode')
   const consumer = join(temporary, 'consumer')
   await mkdir(consumer)
-  execFileSync('npm', ['install', '--offline', '--ignore-scripts', '--no-audit', '--no-fund', '--package-lock=false', join(temporary, packed.filename)], { cwd: consumer, stdio: 'pipe' })
+  execFileSync(...npmCommand(['install', '--offline', '--ignore-scripts', '--no-audit', '--no-fund', '--package-lock=false', join(temporary, packed.filename)]), { cwd: consumer, stdio: 'pipe' })
   const installed = join(consumer, 'node_modules/@esp-vision/device-core')
   assert.equal(await readFile(join(installed, 'LICENSE'), 'utf8'), await readFile(join(root, 'LICENSE'), 'utf8'))
   const notice = await readFile(join(installed, 'NOTICE'), 'utf8')
@@ -44,6 +45,13 @@ try {
   const { defaultPython, filterSerialPorts, inventory, listSerial, serialEntry, tcpTransport, serialTransport, transportFor, openNodeRom } = await import('@esp-vision/device-core/node');
   const { openBrowserRom } = await import('@esp-vision/device-core/browser');
   if (typeof openBrowserRom !== 'function' || typeof openBrowserRom({ port: { open() { throw new Error('Not opened'); }, close() {} } }).initialize !== 'function') throw new Error('Missing passive browser ROM adapter');
+  const romPort = { open() { throw new Error('Not opened'); }, close() {} };
+  const browserRom = openBrowserRom({ port: romPort, expectedMac: '30EDA0EDA1B0' });
+  if (!Object.hasOwn(browserRom, 'chipMac') || browserRom.chipMac !== null) throw new Error('Missing passive browser ROM MAC contract');
+  let rejectedExpectedMac = false;
+  try { openBrowserRom({ port: romPort, expectedMac: '30:ed:a0:ed:a1:b0' }); } catch (error) { rejectedExpectedMac = error instanceof TypeError; }
+  if (!rejectedExpectedMac) throw new Error('Installed browser ROM must validate expectedMac before opening');
+  await browserRom.disconnect();
   if (typeof tcpTransport !== 'function' || typeof serialTransport !== 'function') throw new Error('Missing public Node transports');
   if (typeof inventory !== 'function' || typeof listSerial !== 'function' || typeof filterSerialPorts !== 'function'
       || typeof serialEntry !== 'function' || typeof transportFor !== 'function' || typeof defaultPython !== 'string') throw new Error('Missing public Node inventory APIs');
@@ -62,22 +70,22 @@ try {
   api.createDevice({ transport: serialTransport({ python: 'python3', serial: 'not-opened' }) });
   if (typeof DeviceSession !== 'function' || typeof FirmwareFlashSession !== 'function') throw new Error('Missing host adapter APIs');`
   execFileSync(process.execPath, ['--input-type=module', '-e', script], { cwd: consumer, stdio: 'pipe' })
-  for (const required of ['src/node_serial.py', 'src/jpeg_validate.js', 'scripts/run-tests.mjs', 'tests/hardware-check.mjs', 'tests/device-checks.mjs', 'tests/jpeg-fixtures.mjs', 'tests/test-jpeg-validation.mjs', 'tests/fixtures/device-checks.py']) {
+  for (const required of ['src/node_serial.py', 'src/jpeg_validate.js', 'src/rom_identity.js', 'scripts/run-tests.mjs', 'tests/hardware-check.mjs', 'tests/device-checks.mjs', 'tests/jpeg-fixtures.mjs', 'tests/test-jpeg-validation.mjs', 'tests/fixtures/device-checks.py']) {
     assert.ok(packed.files.some(({ path }) => path === required), `Missing installed check asset: ${required}`)
   }
-  const unitOutput = execFileSync('npm', ['test'], { cwd: installed, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 })
+  const unitOutput = execFileSync(...npmCommand(['test']), { cwd: installed, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 })
   const unitCount = Number(/^(?:# tests|ℹ tests) (\d+)$/m.exec(unitOutput)?.[1] ?? 0)
   assert.ok(unitCount > 0, 'Installed npm test must execute a nonempty suite')
-  const hardwareHelp = execFileSync('npm', ['run', 'test:hardware', '--', '--help'], { cwd: installed, encoding: 'utf8' })
+  const hardwareHelp = execFileSync(...npmCommand(['run', 'test:hardware', '--', '--help']), { cwd: installed, encoding: 'utf8' })
   assert.ok(hardwareHelp.includes('--serial PATH'), 'Installed hardware runner must load and show its help')
   // A damaged tarball must fail instead of reporting a successful zero-test run.
   await rm(join(installed, 'tests'), { recursive: true })
   await mkdir(join(installed, 'tests'))
-  const empty = spawnSync('npm', ['test'], { cwd: installed, encoding: 'utf8' })
+  const empty = spawnSync(...npmCommand(['test']), { cwd: installed, encoding: 'utf8' })
   assert.equal(empty.status, 1, 'An empty suite must fail closed')
   assert.match(empty.stderr, /No Device Core unit tests found/)
   await rm(join(installed, 'tests'), { recursive: true })
-  const missing = spawnSync('npm', ['test'], { cwd: installed, encoding: 'utf8' })
+  const missing = spawnSync(...npmCommand(['test']), { cwd: installed, encoding: 'utf8' })
   assert.equal(missing.status, 1, 'Missing tests must fail closed')
   console.log(JSON.stringify({ package: packed.name, version: packed.version, entryPoints, unitCount, standalone: true }))
 } finally {

package/tests/device-checks.mjs

@@ -2,10 +2,15 @@
 // Application-level HIL checks. All device I/O goes through createDevice's API.
 import { readFile, mkdir, writeFile } from 'node:fs/promises'
 import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createHash } from 'node:crypto'
 import { EV_REPL_INPUT_MAX_BYTES, evReplExecInputBytes } from '../src/evrepl.js'
 import { validateJpegImage } from '../src/jpeg_validate.js'
 
-export const DEVICE_CHECKS = Object.freeze(['identity', 'memory', 'camera', 'framesizes', 'pixformats', 'orientation', 'ipa_stats', 'snapshot_rate', 'preview', 'image_ops', 'display', 'display_stream', 'camera_display_lifecycle', 'image_copy_to_fb', 'image_transform_argument', 'sensor_snapshot_buffer', 'memory_policy'])
+export const DEVICE_CHECKS = Object.freeze(['identity', 'memory', 'camera', 'framesizes', 'pixformats', 'orientation', 'ipa_stats', 'snapshot_rate', 'preview', 'image_ops', 'display', 'display_stream', 'camera_display_lifecycle', 'image_copy_to_fb', 'image_transform_argument', 'sensor_snapshot_buffer', 'memory_policy', 'espdl_inference', 'isp_ccm_frames', 'isp_lsc_display'])
+// The npm package ships tests without models; repository checkouts use the bundled face detector.
+export const DEFAULT_ESPDL_SHA256 = '04eec2220adbf642a843c953817fb219a06c094aedb76c181ba2a958c65201dc'
+export const DEFAULT_ESPDL_MODEL = fileURLToPath(new URL('../../../models/espdet/pico/face/espdet_pico_224_224_face.espdl', import.meta.url))
 const MARKER = '__EVDEVICECHECK__'
 const failure = (code, message) => Object.assign(new Error(message), { code })
 const unsupported = error => error?.code === 'UNSUPPORTED_OPERATION' || /ESP_ERR_NOT_SUPPORTED|ESP_ERR_NOT_FOUND|no module named|ENODEV/i.test(error?.message ?? '')
@@ -44,7 +49,7 @@ export async function runDeviceChecks(device, options, { signal, nonce, report =
   const results = [], namespace = `_evhil_${nonce}`
   let loaded = false, namespaceStarted = false, loadError = null, inputLimit = EV_REPL_INPUT_MAX_BYTES
   const parameters = { frames: options.frames, framesize: options.framesize, pixformat: options.pixformat, displayHold: options.displayHold, screenCapture: Boolean(options.screenOutput) }
-  const timeoutFor = name => 1000 * (name === 'display' ? 30 + options.displayHold * 3 : name === 'camera_display_lifecycle' ? options.frameTimeout + 80 : name === 'memory_policy' ? options.frameTimeout + 60 : name === 'sensor_snapshot_buffer' ? options.frameTimeout + 40 : name === 'image_copy_to_fb' ? 30 : name === 'ipa_stats' ? options.frameTimeout + 40 : options.frameTimeout + Math.max(30, options.frames * (name === 'display_stream' ? 2 : 1)))
+  const timeoutFor = name => 1000 * (name === 'display' ? 30 + options.displayHold * 3 : name === 'camera_display_lifecycle' ? options.frameTimeout + 80 : name === 'memory_policy' ? options.frameTimeout + 60 : name === 'sensor_snapshot_buffer' ? options.frameTimeout + 40 : name === 'image_copy_to_fb' ? 30 : name === 'espdl_inference' ? options.frameTimeout + 60 + options.frames * 2 : name === 'ipa_stats' ? options.frameTimeout + 40 : options.frameTimeout + Math.max(30, options.frames * (name === 'display_stream' ? 2 : 1)))
   const execute = async (source, timeout = 10000, operationSignal = signal) => {
     // Larger python.execute() requests use temporary files in Device Core.
     // Keep fixtures in RAM by respecting the actual encoded REPL-line budget.
@@ -53,6 +58,34 @@ export async function runDeviceChecks(device, options, { signal, nonce, report =
     if (result.ok === false || result.outputTruncated) throw failure('PYTHON_CHECK', 'Device Python check did not complete')
     return result.output
   }
+  const acknowledged = (output, operation, expected) => {
+    let reply
+    try {
+      const line = output.trim()
+      if (!line.startsWith('__EVHILACK__')) throw new Error()
+      reply = JSON.parse(line.slice('__EVHILACK__'.length))
+    } catch { throw failure('MODEL_ACK_INVALID', 'Missing or malformed hardware fixture acknowledgement') }
+    // Python dictionaries need not preserve the host's insertion order.
+    if (!Array.isArray(reply) || reply.length !== 3 || reply[0] !== nonce || reply[1] !== operation || !reply[2] || typeof reply[2] !== 'object' || Array.isArray(reply[2]) ||
+        Object.keys(reply[2]).length !== Object.keys(expected).length || Object.entries(expected).some(([key, value]) => reply[2][key] !== value)) {
+      throw failure('MODEL_ACK_INVALID', 'Hardware fixture acknowledgement does not match the operation')
+    }
+  }
+  const modelSource = (operation, args) => `${namespace}['model_command'](${JSON.stringify(operation)}${args.length ? ',' + args.map(value => JSON.stringify(value)).join(',') : ''})`
+  const modelCall = async (operation, args, expected, { retry = false, timeout = 10000, operationSignal = signal } = {}) => {
+    for (let attempt = 1; ; attempt++) {
+      cancelled(operationSignal)
+      try {
+        // Re-enter the public API for a fresh source variable and its existing
+        // Ctrl-C + exec('1') synchronization. Never replay an SDK += line.
+        acknowledged(await execute(modelSource(operation, args), timeout, operationSignal), operation, expected)
+        return attempt - 1
+      } catch (error) {
+        cancelled(operationSignal)
+        if (!retry || error.code !== 'TIMEOUT' || attempt === 3) throw error
+      }
+    }
+  }
   const load = async () => {
     if (loaded) return
     if (loadError) throw loadError
@@ -62,7 +95,7 @@ export async function runDeviceChecks(device, options, { signal, nonce, report =
       if (Number.isSafeInteger(advertised) && advertised > 0) inputLimit = Math.min(inputLimit, advertised)
       const source = await readFile(new URL('./fixtures/device-checks.py', import.meta.url), 'utf8')
       namespaceStarted = true
-      await execute(`${namespace}={'_source':[]}`)
+      await execute(`${namespace}={'_source':[],'_fixture_nonce':${JSON.stringify(nonce)}}`)
       const append = chunk => `${namespace}['_source'].append(${JSON.stringify(chunk)})`
       let chunk = ''
       for (const character of source) {
@@ -78,15 +111,58 @@ export async function runDeviceChecks(device, options, { signal, nonce, report =
       loaded = true
     } catch (error) { loadError = error; throw error }
   }
-  const invoke = async name => {
+  const invoke = async (name, extra = {}) => {
     await load()
-    const output = await execute(`${namespace}['run_check'](${JSON.stringify(name)},${JSON.stringify(JSON.stringify(parameters))})`, timeoutFor(name))
+    const selected = name === 'espdl_inference' ? { frames: parameters.frames, framesize: parameters.framesize, ...extra } : { ...parameters, ...extra }
+    const output = await execute(`${namespace}['run_check'](${JSON.stringify(name)},${JSON.stringify(JSON.stringify(selected))})`, timeoutFor(name))
     return parseCheckResult(output, name)
   }
   const requirePass = result => {
     if (result.status !== 'PASS') throw Object.assign(failure(result.status === 'SKIP' ? 'UNSUPPORTED_OPERATION' : 'DEVICE_CHECK_FAILED', result.error.message), { checkResult: result })
     return result.data
   }
+  // ESPDet accepts VFS streams, including a read-only BytesIO-backed mount.
+  // Keep inference acceptance independent of persistent storage provisioning.
+  const espdlInference = async () => {
+    let model
+    try { model = new Uint8Array(await readFile(options.model ?? DEFAULT_ESPDL_MODEL)) }
+    catch (error) { throw failure('MODEL_UNAVAILABLE', `Cannot read ESP-DL model: ${error.code ?? 'read failed'}`) }
+    if (!model.length || model.length > 2 * 1024 * 1024) throw failure('MODEL_INVALID', 'ESP-DL acceptance model must be 1 byte to 2 MiB')
+    const sha256 = createHash('sha256').update(model).digest('hex')
+    const expected = options.modelSha256 ?? (options.model ? null : DEFAULT_ESPDL_SHA256)
+    if (expected && expected !== sha256) throw failure('MODEL_HASH_MISMATCH', 'ESP-DL model differs from the expected SHA-256')
+    await load()
+    const path = `/evhil_${nonce}`
+    let started = false, chunks = 0, retries = 0
+    const retryOffsets = []
+    const transferStarted = Date.now()
+    try {
+      started = true
+      await modelCall('begin', [nonce, model.length, path], { size: model.length, offset: 0, path })
+      const append = (chunk, offset) => modelSource('append', [offset, Buffer.from(chunk).toString('base64')])
+      // Base64 carries binary model bytes without the temporary-file execution
+      // path or a second host protocol implementation. Honor the live limit.
+      const chunkBytes = Math.floor((inputLimit - evReplExecInputBytes(append([], model.length))) / 4) * 3
+      if (chunkBytes < 3) throw failure('REPL_INPUT_LIMIT', 'Device REPL input limit cannot load the inference model')
+      for (let offset = 0; offset < model.length; offset += chunkBytes) {
+        cancelled(signal)
+        const chunk = model.subarray(offset, offset + chunkBytes), end = offset + chunk.length
+        const recovered = await modelCall('append', [offset, Buffer.from(chunk).toString('base64')], { offset, end, bytes: chunk.length, current: end }, { retry: true })
+        retries += recovered
+        if (recovered) retryOffsets.push({ offset, retries: recovered })
+        chunks++
+      }
+      await modelCall('mount', [sha256], { path, bytes: model.length, sha256 })
+      const modelTransferMs = Date.now() - transferStarted
+      const data = requirePass(await invoke('espdl_inference', { modelPath: `${path}/model.espdl` }))
+      return { ...data, modelBytes: model.length, modelSha256: sha256, modelStorage: 'ram-vfs', modelChunks: chunks, modelTransferMs, modelRetries: retries, modelRetryOffsets: retryOffsets }
+    } finally {
+      if (started) {
+        try { await modelCall('close', [], { bytes: 0, offset: 0, mounted: false }, { timeout: 5000, operationSignal: AbortSignal.timeout(6000) }) }
+        catch { throw failure('MODEL_CLEANUP_FAILED', 'Could not release the temporary RAM model mount') }
+      }
+    }
+  }
   const record = result => { results.push(result); report({ check: result.name, ...result, name: undefined }) }
   try {
     for (const name of options.checks) {
@@ -119,6 +195,8 @@ export async function runDeviceChecks(device, options, { signal, nonce, report =
             if (!count) throw failure('PREVIEW_EMPTY', 'No preview frame arrived')
             data.received = count
           } finally { unsubscribe() }
+        } else if (name === 'espdl_inference') {
+          data = await espdlInference()
         } else {
           const response = await invoke(name)
           if (name === 'ipa_stats' && response.status === 'SKIP') {
@@ -137,7 +215,7 @@ export async function runDeviceChecks(device, options, { signal, nonce, report =
         result = { name, status: 'PASS', data }
       } catch (error) {
         cancelled(signal)
-        const skip = unsupported(error) && !options.requireAll && !(name === 'display' && options.screenOutput)
+        const skip = (unsupported(error) || error.code === 'MODEL_UNAVAILABLE') && !options.requireAll && !(name === 'display' && options.screenOutput)
         result = { name, status: skip ? 'SKIP' : 'FAIL', error: { code: error.code ?? 'DEVICE_CHECK_FAILED', message: String(error.message ?? 'Device check failed').slice(0, 240) } }
       } finally {
         if (name === 'display' && loaded) {
@@ -152,7 +230,11 @@ export async function runDeviceChecks(device, options, { signal, nonce, report =
     const cleanupSignal = AbortSignal.timeout(10000)
     let cleanupError
     if (namespaceStarted) {
-      try { await execute(`if ${JSON.stringify(namespace)} in globals():\n ${namespace}.get('close_display',lambda:None)()\n del ${namespace}`, 5000, cleanupSignal) }
+      try {
+        await execute(`if ${JSON.stringify(namespace)} in globals():\n ${namespace}.get('close_display',lambda:None)()\n ${namespace}.get('close_model',lambda:None)()\n del ${namespace}`, 5000, cleanupSignal)
+        const marker = '__EVHILACK__' + JSON.stringify([nonce, 'cleanup', { absent: true }])
+        acknowledged(await execute(`assert ${JSON.stringify(namespace)} not in globals();print(${JSON.stringify(marker)})`, 5000, cleanupSignal), 'cleanup', { absent: true })
+      }
       catch (error) { cleanupError = error }
     }
     if (cleanupError) record({ name: 'fixture-cleanup', status: 'FAIL', error: { code: 'FIXTURE_CLEANUP_FAILED', message: 'Could not release the hardware fixture namespace' } })

package/tests/firmware-fixtures.mjs

@@ -0,0 +1,60 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import { createHash } from 'node:crypto'
+import { createDevice } from '../src/index.js'
+import { firmwareSha256 } from '../src/firmware_flash.js'
+
+export function partitionTable(entries = [
+  { label: 'nvs', type: 1, subtype: 2, offset: 0x9000, size: 0x6000 },
+  { label: 'phy_init', type: 1, subtype: 1, offset: 0xf000, size: 0x1000 },
+  { label: 'factory', type: 0, subtype: 0, offset: 0x10000, size: 0x10000 },
+  { label: 'ffat', type: 1, subtype: 0x81, offset: 0x20000, size: 0x21000 },
+], { md5 = true, size = 0xc00 } = {}) {
+  const bytes = new Uint8Array(size).fill(0xff), view = new DataView(bytes.buffer)
+  entries.forEach((entry, index) => {
+    const offset = index * 32
+    bytes.fill(0, offset, offset + 32)
+    view.setUint16(offset, 0x50aa, true)
+    bytes[offset + 2] = entry.type
+    bytes[offset + 3] = entry.subtype
+    view.setUint32(offset + 4, entry.offset, true)
+    view.setUint32(offset + 8, entry.size, true)
+    bytes.set(new TextEncoder().encode(entry.label), offset + 12)
+    view.setUint32(offset + 28, entry.flags ?? 0, true)
+  })
+  if (md5) {
+    const offset = entries.length * 32
+    bytes.set([0xeb, 0xeb], offset)
+    bytes.set(createHash('md5').update(bytes.subarray(0, offset)).digest(), offset + 16)
+  }
+  return bytes
+}
+
+export async function installFixture() {
+  const data = new Uint8Array(0x11000).fill(0xff), calls = []
+  data.set([0xe9, 1, 2, 3], 0x2000)
+  data.set(partitionTable(), 0x8000)
+  data.set([0xe9, 6, 7, 8], 0x10000)
+  const part = async (offset, size = 4) => ({ offset, bytes: size, sha256: await firmwareSha256(data.subarray(offset, offset + size)) })
+  const release = { board: 'BOARD', version: 'new', image: {
+    evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302, ...(await part(0x10000)),
+    partitionSize: 0x10000, partitionTable: await part(0x8000, 0xc00), url: 'https://example.test/app.bin',
+  }, install: { offset: 0, bytes: data.length, flashSize: 0x1000000, chipRevisionMin: 302, chipRevisionMax: 302,
+    sha256: await firmwareSha256(data), bootloader: await part(0x2000), url: 'https://example.test/full.bin' } }
+  const flash = new Uint8Array(0x41000).fill(0x5a)
+  const loader = {
+    chipFamily: 0x3280, chipRevision: 302,
+    async initialize() { calls.push('initialize') },
+    async getSecurityInfo() { return { flags: 0, flashCryptCnt: 0 } },
+    async runStub() { calls.push('stub'); return loader },
+    async flashId() { calls.push('capacity'); return 0x1840ef },
+    async eraseRegion(offset, size) { calls.push(['erase', offset, size]); flash.fill(0xff, offset, offset + size) },
+    async flashData(buffer, progress, offset) { calls.push(['write', offset]); flash.set(new Uint8Array(buffer), offset); progress(buffer.byteLength, buffer.byteLength) },
+    async readFlash(offset, count) { calls.push(['read', offset]); return flash.slice(offset, offset + count) },
+    async readRegister() { return 0 },
+    async hardReset() { calls.push('reset') },
+    async disconnect() { calls.push('close') },
+  }
+  const device = createDevice(), request = { mode: 'install', release, board: 'BOARD', data, async openLoader() { calls.push('open'); return loader } }
+  return { data, calls, release, loader, device, request, flash }
+}