@esp-vision/device-core 0.6.1 → 0.7.0

package/src/firmware_updates.js

@@ -5,6 +5,7 @@ import { loadOfficialFirmware } from './firmware_feed.js'
 import { FirmwareFlashSession, validateFirmwareImage, firmwareMode } from './firmware_flash.js'
 import { validateFirmwareRelease as release } from './firmware_release.js'
 import { downloadBytes, MAX_FIRMWARE_BYTES } from './firmware_io.js'
+import { planInstallFilesystemErase } from './firmware_partitions.js'
 
 function record(value, keys, name) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${name} must be an object`)
@@ -79,6 +80,7 @@ export async function updateFirmware(request, connectedIdentity, disconnect) {
     bytes = bytes.slice(source.offset, source.offset + image.bytes)
   }
   await validateFirmwareImage(image, bytes, { mode })
+  if (mode === 'install') planInstallFilesystemErase(image, bytes)
   abort(signal)
   // Validate everything before releasing EV-MUX or acquiring a download port.
   await disconnect()
@@ -87,10 +89,11 @@ export async function updateFirmware(request, connectedIdentity, disconnect) {
   let session
   try {
     abort(signal)
-    session = new FirmwareFlashSession(loader, image, { mode, reset: reset ? () => reset(loader) : undefined })
+    session = new FirmwareFlashSession(loader, image, { mode, signal, reset: reset ? () => reset(loader) : undefined })
     await session.connect(bytes)
     abort(signal)
-    // No interruption after writing starts: finish verification and reset policy.
+    // Erase/erase-verification honor cancellation; once firmware writing starts,
+    // finish verification/reset as before. No uncertain operation is replayed.
     const result = await session.flash(bytes, { onProgress, onPhase })
     return { ...result, version: target.version, board: target.board, reconnected: false }
   } finally {

package/src/node_rom.js

@@ -10,22 +10,22 @@ export function openNodeRom({ port, python = defaultPython, signal } = {}, depen
   if (!port) throw new TypeError('Firmware update requires a local --port')
   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
+  let child, input, pending, sequence = 0, closed = false, initializing = false, romReady = false, stubReady = false
   const fail = code => Object.assign(new Error(code === 'ESPTOOL_UNAVAILABLE' ? 'Install Python esptool==5.6.0 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 = []) {
+  function rpc(method, args = [], timeout = 180000) {
     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
-      pending = { id, resolve, reject: rejectPromise, timer: setTimeout(() => { reject('ROM_TIMEOUT'); void loader.disconnect() }, 180000) }
+      pending = { id, resolve, reject: rejectPromise, timer: setTimeout(() => { reject('ROM_TIMEOUT'); void loader.disconnect() }, timeout) }
       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
+    child = null; romReady = stubReady = 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)
@@ -97,7 +97,35 @@ export function openNodeRom({ port, python = defaultPython, signal } = {}, depen
     },
     flashId: () => rpc('flashId'),
     getSecurityInfo: () => rpc('security'),
-    async runStub() { await rpc('stub'); return loader },
+    get IS_STUB() { return romReady && stubReady },
+    async runStub() {
+      stubReady = false
+      try {
+        const result = await rpc('stub')
+        if (result?.stubRunning !== true) throw fail('ROM_STUB_REQUIRED')
+        stubReady = true
+        return loader
+      } catch (error) { await loader.disconnect(); throw error }
+    },
+    async eraseRegion(address, size) {
+      if (!Number.isSafeInteger(address) || address < 0 || address % 4096 !== 0
+          || !Number.isSafeInteger(size) || size <= 0 || size > 0xffffffff || size % 4096 !== 0
+          || address + size > 0x100000000) throw new RangeError('ROM erase requires a positive, sector-aligned 32-bit address range')
+      if (closed) throw fail('ROM_CLOSED')
+      if (!romReady) throw fail('ROM_NOT_INITIALIZED')
+      if (!stubReady) throw fail('ROM_STUB_REQUIRED')
+      const cancelled = () => { reject('CANCELLED'); void loader.disconnect() }
+      signal.addEventListener('abort', cancelled, { once: true })
+      try {
+        signal.throwIfAborted()
+        // esptool 5.6.0 permits 40 seconds per decimal MB. Large FFAT regions
+        // must not inherit the shorter generic RPC timeout.
+        await rpc('eraseRegion', [address, size], Math.max(180000, Math.ceil(size / 1000000 * 40000) + 30000))
+        signal.throwIfAborted()
+        if (closed || !stubReady) throw fail('ROM_CLOSED')
+      } catch (error) { await loader.disconnect(); throw error }
+      finally { signal.removeEventListener('abort', cancelled) }
+    },
     async readFlash(offset, bytes, progress, options) {
       if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(bytes) || bytes <= 0 || bytes > 0xffffffff
           || offset + bytes > 0x100000000) throw new RangeError('ROM read requires a positive 32-bit address range')

package/src/node_rom.py

@@ -122,12 +122,25 @@ def _read_flash(esp, offset, length, options=None):
                     esp.FLASH_SECTOR_SIZE = old_block
 
 
+def _erase_region(esptool, esp, address, size):
+    """Erase only the qualified range through the external official command."""
+    if type(address) is not int or address < 0 or address % 4096 or type(size) is not int or size <= 0 or size > 0xffffffff or size % 4096 or address + size > 0x100000000:
+        raise ValueError('ROM erase requires a positive, sector-aligned 32-bit address range')
+    if not getattr(esp, 'IS_STUB', False):
+        raise RuntimeError('Flash region erase requires an initialized flasher stub')
+    if getattr(esp, 'FLASH_SECTOR_SIZE', None) != 4096 or not callable(getattr(esp, 'erase_region', None)):
+        raise RuntimeError('Unsupported esptool stub region erase; use esptool==5.6.0')
+    # Do not use force: the official command also checks active security state.
+    esptool.erase_region(esp, address, size, force=False)
+
+
 def main():
     with contextlib.redirect_stdout(sys.stderr):
         import esptool
     if esptool.__version__ != '5.6.0':
         raise RuntimeError('Install esptool==5.6.0 for the verified bounded Flash reader')
     esp = None
+    erase_failed = False
     families = {'ESP32-P4': 0x3280, 'ESP32-S3': 0x3253, 'ESP32-S31': 0x3231}
     try:
         for line in sys.stdin:
@@ -136,6 +149,8 @@ def main():
                 with contextlib.redirect_stdout(sys.stderr):
                     method, args = request['method'], request.get('args', [])
                     result = None
+                    if erase_failed:
+                        raise RuntimeError('Flash region erase failed; start a fresh ROM session')
                     if method != 'initialize' and esp is None:
                         raise RuntimeError('Initialize the ROM adapter before issuing operations')
                     if method == 'initialize':
@@ -158,12 +173,17 @@ def main():
                         result = {'flags': security['flags'], 'flashCryptCnt': security['flash_crypt_cnt']}
                     elif method == 'stub':
                         esp = esptool.run_stub(esp)
+                        if not esp.IS_STUB:
+                            raise RuntimeError('A validated flasher stub is required')
                         esptool.attach_flash(esp)
                         esp.change_baud(460800)
+                        result = {'stubRunning': True}
                     elif method == 'flashId':
                         result = esp.flash_id()
                     elif method == 'read':
                         result = base64.b64encode(_read_flash(esp, *args)).decode('ascii')
+                    elif method == 'eraseRegion':
+                        _erase_region(esptool, esp, *args)
                     elif method == 'write':
                         offset, encoded = args
                         data = base64.b64decode(encoded, validate=True)
@@ -178,9 +198,14 @@ def main():
                         raise ValueError('Unknown ROM adapter method')
                 print(json.dumps({'id': request['id'], 'result': result}), flush=True)
             except Exception as error:
+                if request['method'] == 'eraseRegion':
+                    erase_failed = True
+                    with contextlib.suppress(Exception):
+                        if esp is not None and esp._port.is_open:
+                            esp._port.close()
                 print(json.dumps({'id': request['id'], 'error': 'ROM_OPERATION_FAILED', 'method': request['method'], 'detail': str(error)}), flush=True)
     finally:
-        if esp is not None:
+        if esp is not None and esp._port.is_open:
             esp._port.close()
 
 

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

@@ -45,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');
@@ -63,7 +70,7 @@ 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(...npmCommand(['test']), { cwd: installed, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024 })

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 }
+}