@esp-vision/device-core 0.6.1 → 0.7.0

package/tests/fixtures/device-checks.py

@@ -496,6 +496,361 @@ def memory_policy(opts):
 
 
 
+_model_bytes = None
+_model_offset = 0
+_model_path = None
+_model_vfs = None
+_model_nonce = None
+
+
+class ModelVfs:
+    """A single read-only RAM file; no Flash/SD volume or writer is touched."""
+    def mount(self, readonly, mkfs):
+        pass
+
+    def umount(self):
+        pass
+
+    def stat(self, path):
+        if path not in ('/', '/model.espdl'):
+            raise OSError(2)
+        return (0x4000 if path == '/' else 0x8000, 0, 0, 0, 0, 0, len(_model_bytes), 0, 0, 0)
+
+    def open(self, path, mode):
+        import io
+        if path != '/model.espdl' or mode not in ('r', 'rb'):
+            raise OSError(13)
+        return io.BytesIO(_model_bytes)
+
+
+def begin_model(nonce, size, path):
+    global _model_bytes, _model_offset, _model_path, _model_nonce
+    assert _model_bytes is None and _model_path is None, 'model already active'
+    assert isinstance(nonce, str) and nonce, 'invalid model nonce'
+    assert 0 < size <= 2 * 1024 * 1024, 'model size out of bounds'
+    _model_nonce = nonce
+    _model_bytes = bytearray(size)
+    _model_offset = 0
+    _model_path = path
+    return dict(size=len(_model_bytes), offset=_model_offset, path=_model_path)
+
+
+def append_model(offset, encoded):
+    import binascii
+    global _model_offset
+    chunk = binascii.a2b_base64(encoded)
+    end = offset + len(chunk)
+    assert isinstance(offset, int) and offset >= 0 and chunk, 'invalid model chunk'
+    assert _model_bytes is not None and end <= len(_model_bytes), 'model upload overflow'
+    if offset == _model_offset:
+        # An interrupt between copying and committing leaves the same offset;
+        # replay safely overwrites the same slice before committing it.
+        _model_bytes[offset:end] = chunk
+        _model_offset = end
+    else:
+        assert _model_offset == end, 'model chunk out of order'
+        assert _model_bytes[offset:end] == chunk, 'model chunk conflict'
+    return dict(offset=offset, end=end, bytes=len(chunk), current=_model_offset)
+
+
+def mount_model(expected):
+    import binascii, hashlib, vfs
+    global _model_vfs
+    assert _model_bytes is not None and _model_offset == len(_model_bytes), 'incomplete model upload'
+    actual = binascii.hexlify(hashlib.sha256(_model_bytes).digest()).decode()
+    assert actual == expected, 'model SHA-256 mismatch'
+    # MicroPython refuses an already mounted path; never unmount another VFS.
+    _model_vfs = ModelVfs()
+    vfs.mount(_model_vfs, _model_path, readonly=True)
+    assert any(filesystem is _model_vfs and path == _model_path for filesystem, path in vfs.mount()), 'model mount missing'
+    return dict(path=_model_path, bytes=len(_model_bytes), sha256=actual)
+
+
+def close_model():
+    import gc, vfs
+    global _model_bytes, _model_offset, _model_path, _model_vfs, _model_nonce
+    # A cancelled mount may have completed before the host observed its result.
+    # Match object identity, so an uncertain call never unmounts another VFS.
+    if _model_vfs is not None:
+        for filesystem, _ in vfs.mount():
+            if filesystem is _model_vfs:
+                vfs.umount(_model_vfs)
+        assert not any(filesystem is _model_vfs for filesystem, _ in vfs.mount()), 'model still mounted'
+        _model_vfs = None
+    _model_bytes = None
+    _model_offset = 0
+    _model_path = None
+    _model_nonce = None
+    gc.collect()
+    return dict(bytes=0, offset=_model_offset, mounted=False)
+
+
+def model_command(operation, *args):
+    import json
+    assert operation in ('begin', 'append', 'mount', 'close'), 'invalid model operation'
+    nonce = globals()['_fixture_nonce']
+    assert _model_nonce is None or _model_nonce == nonce, 'model nonce conflict'
+    if operation == 'begin':
+        assert args[0] == nonce, 'model nonce conflict'
+    result = globals()[operation + '_model'](*args)
+    # A caught/printed Python exception must never look like a semantic ACK.
+    print('__EVHILACK__' + json.dumps([nonce, operation, result]))
+
+
+def espdl_inference(opts):
+    """Load the SHA-256-verified RAM model and run real camera inference."""
+    import espdl, sensor, time
+    det = None
+    frame = None
+    try:
+        sensor.reset()
+        sensor.set_pixformat(sensor.RGB565)
+        sensor.set_framesize(getattr(sensor, opts['framesize']))
+        sensor.skip_frames(n=3)
+        started = time.ticks_ms()
+        det = espdl.ESPDet(opts['modelPath'], score=0.3, nms=0.7)
+        load_ms = time.ticks_diff(time.ticks_ms(), started)
+        frame = sensor.snapshot().copy()
+        width, height = frame.width(), frame.height()
+
+        def checked(results):
+            assert isinstance(results, list), 'detect() did not return a list'
+            for item in results:
+                assert len(item) == 6, 'malformed detection tuple'
+                x, y, w, h, score, category = item
+                assert w > 0 and h > 0, 'empty detection box'
+                assert x < width and y < height and x + w > 0 and y + h > 0, 'detection box outside the frame'
+                assert 0.0 <= score <= 1.0, 'detection score outside 0..1'
+                assert category >= 0, 'negative detection category'
+            return results
+
+        first = checked(det.detect(frame))
+        assert first == checked(det.detect(frame)), 'inference differs for the same input frame'
+        detections, total_us, worst_us = 0, 0, 0
+        for _ in range(opts['frames']):
+            img = sensor.snapshot()
+            start = time.ticks_us()
+            results = det.detect(img)
+            elapsed = time.ticks_diff(time.ticks_us(), start)
+            detections += len(checked(results))
+            total_us += elapsed
+            worst_us = max(worst_us, elapsed)
+        assert total_us > 0, 'implausible inference time'
+        return dict(width=width, height=height, loadMs=load_ms, frames=opts['frames'], detections=detections,
+                    meanMs=total_us // opts['frames'] / 1000, worstMs=worst_us / 1000)
+    finally:
+        try:
+            if det is not None:
+                det.deinit()
+        finally:
+            frame = None
+            sensor.shutdown()
+
+
+def isp_frame_sample(frame):
+    """Measure rendered RGB565 pixels, independently of ISP configuration."""
+    saturation = 0.0
+    bright = 0
+    rgb = [0, 0, 0]
+    for y in range(8, frame.height(), 16):
+        for x in range(8, frame.width(), 16):
+            pixel = frame.get_pixel(x, y)
+            maximum = max(pixel)
+            if maximum >= 16:
+                saturation += (maximum - min(pixel)) / maximum
+                bright += 1
+            for channel in range(3):
+                rgb[channel] += pixel[channel]
+    if bright < 16:
+        raise RuntimeError('ISP image effect unobservable: illuminate a stationary target (at least 16 bright samples required)')
+    return dict(saturation=saturation / bright, brightSamples=bright, rgb=rgb)
+
+
+def isp_ccm_frames(opts):
+    """One write per stage; consume old frames instead of repeating the write."""
+    import sensor, time
+    stages = []
+    identity = [1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]
+    grey = [0.33] * 9
+    red = [1.0, 1.0, 1.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0]
+
+    def stage(name, matrix, delay=0):
+        sensor.set_isp('ccm', enable=True, matrix=matrix)
+        # Deliberately leave completed buffers queued; elapsed time is no flush.
+        if delay:
+            time.sleep_ms(delay)
+        started = time.ticks_ms()
+        frames = []
+        for index in range(8):
+            sample = isp_frame_sample(sensor.snapshot())
+            sample.update(frame=index + 1, ms=time.ticks_diff(time.ticks_ms(), started))
+            frames.append(sample)
+        result = dict(name=name, writes=1, frames=frames, readback=sensor.get_isp('ccm'))
+        stages.append(result)
+        return frames
+
+    try:
+        sensor.reset()
+        sensor.set_pixformat(sensor.RGB565)
+        sensor.set_framesize(sensor.QVGA)
+        sensor.skip_frames(time=1000)
+        if sensor.get_ipa() is None or sensor.get_isp('ccm') is None:
+            raise RuntimeError('ESP_ERR_NOT_SUPPORTED: manual ISP CCM unavailable')
+        # Automatic controller ownership must reject manual writes explicitly.
+        sensor.set_ipa(True)
+        try:
+            sensor.set_isp('ccm', enable=True, matrix=grey)
+        except OSError as exc:
+            ownership_error = str(exc)
+            assert 'disable IPA before setting ISP parameters' in ownership_error, 'unexpected manual-write ownership error: ' + ownership_error
+        else:
+            raise RuntimeError('manual CCM write accepted while IPA owns tuning')
+        sensor.set_ipa(False)
+        sensor.set_isp('wb', enable=False)
+        sensor.skip_frames(n=3)
+        for name, matrix, delay, expect_grey in (('red', red, 0, False), ('grey_after_sleep', grey, 2000, True), ('red_again', red, 0, False), ('grey_again', grey, 0, True)):
+            frames = stage(name, matrix, delay)
+            # Never require the first captured frame to be from the new tuning.
+            for sample in frames[-3:]:
+                if expect_grey:
+                    assert sample['saturation'] < 0.15, 'single CCM write did not produce grey frames after consumption'
+                else:
+                    assert sample['saturation'] > 0.8, 'single CCM write did not produce red frames after consumption'
+                    assert sample['rgb'][0] > 4 * max(1, sample['rgb'][1], sample['rgb'][2]), 'CCM red output has wrong channels'
+        sensor.set_isp('wb', enable=True, rg=1.5, bg=0.75)
+        before = stage('explicit_wb', identity)
+        wb_before = sensor.get_isp('wb')
+        after = stage('ccm_preserves_explicit_wb', identity)
+        wb_after = sensor.get_isp('wb')
+        assert wb_before == wb_after, 'CCM write changed explicit WB driver configuration'
+        for channel in (0, 2):
+            ratios = [sum(s['rgb'][channel] for s in samples[-3:]) / max(1, sum(s['rgb'][1] for s in samples[-3:])) for samples in (before, after)]
+            assert abs(ratios[0] - ratios[1]) < 0.2, 'CCM write changed rendered explicit WB on stationary target'
+        return dict(sensorId=sensor.get_id(), stages=stages, wbBefore=wb_before, wbAfter=wb_after,
+                    frameBudget=8, ownershipError=ownership_error,
+                    note='Driver readback is not a frame acknowledgement; sensor-internal AWB is not measured')
+    finally:
+        sensor.shutdown()
+
+
+def isp_heap_sample():
+    import gc, esp32
+    gc.collect()
+    result = {}
+    for name, caps in (('dma', 1 << 3), ('psram', 1 << 10), ('internal', (1 << 11) | (1 << 2))):
+        heaps = esp32.idf_heap_info(caps)
+        result[name] = dict(free=sum(item[1] for item in heaps), largest=max([item[2] for item in heaps] or [0]))
+    return result
+
+
+def isp_release_camera_lcd(lcd):
+    import sensor, gc
+    # A display cleanup failure must not strand the camera's DMA/LSC resources.
+    try:
+        if lcd is not None:
+            lcd.deinit()
+    finally:
+        try:
+            sensor.shutdown()
+        finally:
+            gc.collect()
+
+
+def isp_lsc_display(opts):
+    """LSC changes and CCM bursts during the original canvas/LCD preview path."""
+    import sensor, display, image, time, gc
+    lcd = None
+    canvas = None
+    frame = None
+    sensor.shutdown()
+    before = isp_heap_sample()
+    result = {}
+    try:
+        sensor.reset()
+        sensor.set_pixformat(sensor.RGB565)
+        sensor.set_framesize(sensor.QVGA)
+        sensor.skip_frames(n=3)
+        if sensor.get_ipa() is None or sensor.get_isp('lsc') is None:
+            raise RuntimeError('ESP_ERR_NOT_SUPPORTED: manual ISP LSC unavailable')
+        sensor.set_ipa(False)
+        lsc = sensor.get_isp('lsc')
+        count = lsc['lsc_gain_size']
+        assert count > 1, 'invalid LSC table size'
+        ramp = [1.0 - 0.5 * (i / (count - 1)) ** 2 for i in range(count)]
+        matrix = sensor.get_isp('ccm')['matrix']
+        lcd = display.Display()
+        canvas = image.Image(lcd.width(), lcd.height(), image.RGB565)
+        scale = min(lcd.width() / 320, lcd.height() / 240)
+        x = int((lcd.width() - 320 * scale) / 2)
+        y = int((lcd.height() - 240 * scale) / 2)
+
+        def write_frame():
+            frame = sensor.snapshot()
+            canvas.draw_image(frame, x, y, x_scale=scale, y_scale=scale)
+            lcd.write(canvas)
+
+        # Warm both persistent LSC banks and the display's reusable DMA staging.
+        for _ in range(2):
+            sensor.set_isp('lsc', enable=True, gain_r=ramp, gain_gr=ramp, gain_gb=ramp, gain_b=ramp)
+            write_frame()
+            sensor.set_isp('lsc', enable=False)
+            write_frame()
+        active = isp_heap_sample()
+        samples = []
+        frames = max(80, opts['frames'])
+        sample_every = max(40, (frames + 9) // 10)
+        started = time.ticks_ms()
+        switches = 0
+        for index in range(frames):
+            if index % 20 == 0:
+                sensor.set_isp('lsc', enable=(switches % 2 == 0), gain_r=ramp, gain_gr=ramp, gain_gb=ramp, gain_b=ramp)
+                switches += 1
+            sensor.set_isp('ccm', enable=True, matrix=matrix)
+            sensor.set_isp('ccm', enable=True, matrix=matrix)
+            write_frame()
+            if (index + 1) % sample_every == 0 or index + 1 == frames:
+                samples.append(dict(frame=index + 1, heap=isp_heap_sample()))
+        after = isp_heap_sample()
+        for name in active:
+            assert after[name]['free'] >= active[name]['free'] - 4096, 'ISP/LCD pressure lost ' + name + ' heap'
+            assert after[name]['largest'] >= active[name]['largest'] - 4096, 'ISP/LCD pressure fragmented ' + name + ' heap'
+        # Rejected parameters must leave preview usable; do not induce OOM.
+        try:
+            sensor.set_isp('lsc', enable=True, gain_r=[1.0], gain_gr=ramp, gain_gb=ramp, gain_b=ramp)
+        except ValueError:
+            pass
+        else:
+            raise RuntimeError('invalid LSC table accepted')
+        write_frame()
+        result = dict(sensorId=sensor.get_id(), frames=frames, ccmWrites=2 * frames, lscSwitches=switches,
+                      gainCount=count, elapsedMs=time.ticks_diff(time.ticks_ms(), started),
+                      before=before, active=active, samples=samples, after=after,
+                      rejectedWriteRecovered=True, note='Software preview and allocation evidence; physical LCD requires observation')
+    finally:
+        try:
+            isp_release_camera_lcd(lcd)
+        finally:
+            lcd = None
+            canvas = None
+            frame = None
+            gc.collect()
+    result['released'] = isp_heap_sample()
+    for name in before:
+        assert result['released'][name]['free'] >= before[name]['free'] - 4096, 'ISP/LCD cleanup leaked ' + name + ' heap'
+    # Prove that normal cleanup permits another camera/LCD lifetime.
+    try:
+        sensor.reset()
+        sensor.set_pixformat(sensor.RGB565)
+        sensor.set_framesize(sensor.QVGA)
+        lcd = display.Display()
+        lcd.write(sensor.snapshot(), fit=True)
+        result['restartRecovered'] = True
+    finally:
+        isp_release_camera_lcd(lcd)
+    result['afterRestartRelease'] = isp_heap_sample()
+    return result
+
+
 def memory(opts):
     import esp32
     heaps = esp32.idf_heap_info(esp32.HEAP_DATA)
@@ -528,7 +883,8 @@ def run_check(name, opts):
                      image_copy_to_fb=image_copy_to_fb,
                      image_transform_argument=image_transform_argument,
                      sensor_snapshot_buffer=sensor_snapshot_buffer,
-                     memory_policy=memory_policy)
+                     memory_policy=memory_policy, espdl_inference=espdl_inference,
+                     isp_ccm_frames=isp_ccm_frames, isp_lsc_display=isp_lsc_display)
     try:
         data = functions[name](opts)
         result = dict(name=name, status='PASS', data=data)

package/tests/hardware-check.mjs

@@ -7,7 +7,7 @@ export { tcpTransport, serialTransport } from '../src/node_transport.js'
 import { createDevice } from '../src/index.js'
 import { DEVICE_CHECKS, runDeviceChecks, saveJpeg } from './device-checks.mjs'
 
-export const usage = 'Usage: npm run test:hardware -- (--tcp HOST[:PORT] | --serial PATH) [--role usj|usb|uart] [--python PYTHON] [--expect-board BOARD] [--expect-firmware-version VERSION] [--write] [--capture] [--checks all|CSV] [--require-all] [--frames N] [--framesize QVGA] [--pixformat RGB565] [--quality 60] [--frame-timeout SECONDS] [--display-hold SECONDS] [--output CAMERA.jpg] [--screen-output LCD.jpg] [--timeout MILLISECONDS]'
+export const usage = 'Usage: npm run test:hardware -- (--tcp HOST[:PORT] | --serial PATH) [--role usj|usb|uart] [--python PYTHON] [--expect-board BOARD] [--expect-firmware-version VERSION] [--write] [--capture] [--checks all|CSV] [--require-all] [--frames N] [--framesize QVGA] [--pixformat RGB565] [--quality 60] [--frame-timeout SECONDS] [--display-hold SECONDS] [--output CAMERA.jpg] [--screen-output LCD.jpg] [--model MODEL.espdl] [--model-sha256 HEX] [--timeout MILLISECONDS]'
 const fail = (code, message) => Object.assign(new Error(message), { code })
 
 export function parseArgs(args) {
@@ -17,7 +17,7 @@ export function parseArgs(args) {
     const option = args[index]
     if (option === '--help') return { help: true }
     if (['--write', '--capture', '--require-all'].includes(option)) { options[option === '--require-all' ? 'requireAll' : option.slice(2)] = true; continue }
-    if (!['--tcp', '--serial', '--role', '--python', '--timeout', '--checks', '--screen-output', '--output', '--frames', '--display-hold', '--framesize', '--pixformat', '--quality', '--frame-timeout', '--expect-board', '--expect-firmware-version'].includes(option)) throw fail('ARGUMENT', 'Unknown argument')
+    if (!['--tcp', '--serial', '--role', '--python', '--timeout', '--checks', '--screen-output', '--output', '--frames', '--display-hold', '--framesize', '--pixformat', '--quality', '--frame-timeout', '--expect-board', '--expect-firmware-version', '--model', '--model-sha256'].includes(option)) throw fail('ARGUMENT', 'Unknown argument')
     const value = args[++index]
     if (!value || value.startsWith('--')) throw fail('ARGUMENT', 'Missing argument value')
     const key = option.slice(2).replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase())
@@ -37,6 +37,7 @@ export function parseArgs(args) {
   if (!Number.isFinite(options.frameTimeout) || options.frameTimeout <= 0 || options.frameTimeout > 120) throw fail('ARGUMENT', 'Frame timeout must be positive and at most 120 seconds')
   if (!Number.isFinite(options.displayHold) || options.displayHold < 0 || options.displayHold > 60) throw fail('ARGUMENT', 'Display hold must be 0 to 60 seconds')
   if (![options.framesize, options.pixformat].every(value => /^[A-Z][A-Z0-9_]{0,30}$/.test(value))) throw fail('ARGUMENT', 'Sensor settings must be uppercase constant names')
+  if (options.modelSha256 && !/^[a-f0-9]{64}$/.test(options.modelSha256)) throw fail('ARGUMENT', 'Model SHA-256 must be 64 lowercase hexadecimal characters')
   if (options.output && !options.checks.includes('camera')) options.capture = true
   options.timeout = Number(options.timeout)
   if (!Number.isSafeInteger(options.timeout) || options.timeout < 1000 || options.timeout > 600000) throw fail('ARGUMENT', 'Timeout must be 1000 to 600000 milliseconds')

package/tests/test-browser-rom.mjs

@@ -7,6 +7,10 @@ import { openBrowserRom } from '../src/browser.js'
 import { createOfficialBrowserLoader, browserRomInterface, ROM_UART_BAUD_RATES } from '../src/browser_rom.js'
 import { browserTransportCompatibility, browserRomCompatibility, readBrowserFlash, romWords } from '../src/browser_rom_compat.js'
 import { romMd5 } from '../src/rom_md5.js'
+import { ESPLoader } from 'esptool-js'
+import { ESP32S3ROM } from 'esptool-js/lib/targets/esp32s3.js'
+import { ESP32P4ROM } from 'esptool-js/lib/targets/esp32p4.js'
+import { ESP32S31ROM } from 'esptool-js/lib/targets/esp32s31.js'
 
 const passivePort = () => ({ open() { throw new Error('Port must remain passive') }, close() {} })
 test('browser ROM construction and disconnect remain passive without browser globals', async () => {
@@ -14,6 +18,7 @@ test('browser ROM construction and disconnect remain passive without browser glo
   assert.equal(adapter.chipFamily, null)
   assert.equal(adapter.chipRevision, null)
   assert.equal(adapter.chipName, null)
+  assert.equal(adapter.chipMac, null)
   await adapter.disconnect(); await adapter.disconnect()
   await assert.rejects(adapter.initialize(), { code: 'ROM_CLOSED' })
 })
@@ -24,6 +29,22 @@ test('browser ROM validates its port and cancellation before loading the depende
   controller.abort(new Error('cancelled before open'))
   await assert.rejects(openBrowserRom({ port: passivePort(), signal: controller.signal }).initialize(), /cancelled before open/)
 })
+test('expectedMac is validated synchronously and construction does not mutate options or ports', async () => {
+  for (const expectedMac of [null, true, 1, {}, [], '', '30eda0eda1b', '30eda0eda1b00', '30:ed:a0:ed:a1:b0', '30eda0eda1bg', ' 30eda0eda1b0', '30eda0eda1b0\n']) {
+    let touched = 0
+    const port = Object.freeze({ getInfo() { touched++; return {} }, open() { touched++ }, close() { touched++ } })
+    const options = Object.freeze({ port, expectedMac })
+    assert.throws(() => openBrowserRom(options), /expectedMac/)
+    assert.throws(() => createOfficialBrowserLoader({}, port, {}, { expectedMac }), /expectedMac/)
+    assert.equal(touched, 0)
+    assert.equal(options.expectedMac, expectedMac)
+  }
+  const port = Object.freeze(passivePort()), options = Object.freeze({ port, expectedMac: '30EDA0EDA1B0' })
+  const adapter = openBrowserRom(options)
+  assert.equal(adapter.chipMac, null)
+  assert.equal(options.expectedMac, '30EDA0EDA1B0')
+  await adapter.disconnect()
+})
 test('interface discovery separates known bridge, OTG and JTAG; custom descriptors need evidence', () => {
   const port = (usbVendorId, usbProductId) => ({ getInfo: () => ({ usbVendorId, usbProductId }) })
   assert.equal(browserRomInterface(port(0x10c4, 0xea60)), 'uart')
@@ -94,7 +115,7 @@ test('native USB MEM_END timeout exception never bypasses validated stub greetin
   const lost = browserRomCompatibility({ memFinish: async () => { throw new Error('Port disconnected') } }, { nativeUsb: true })
   await assert.rejects(lost.memFinish(), /disconnected/)
 })
-function officialFixture({ failRates = [], usb = false, security = { flags: 0, flashCryptCnt: 0 }, failWrite = false, recoverSecurity, recoverFamily, detach = false, reopenResets = false, flashId = 0x1840ef, stubStarts = true } = {}) {
+function officialFixture({ failRates = [], usb = false, security = { flags: 0, flashCryptCnt: 0 }, failWrite = false, recoverSecurity, recoverFamily, detach = false, reopenResets = false, flashId = 0x1840ef, stubStarts = true, signal, expectedMac, mac = '30:ed:a0:ed:a1:b0', recoverMac } = {}) {
   const events = [], calls = [], loaders = [], opens = [], reads = []
   const port = { readable: null, writable: null,
     getInfo: () => ({ usbVendorId: usb ? 0x303a : 0x10c4, usbProductId: usb ? 32 : 0xea60 }),
@@ -112,15 +133,17 @@ function officialFixture({ failRates = [], usb = false, security = { flags: 0, f
     async setRTS(value) { calls.push(['rts', value]) }
   }
   class FakeLoader {
-    constructor({ transport }) { this.transport = transport; this.CHIP_DETECT_MAGIC_REG_ADDR = 0x40001000; this.ESP_CHANGE_BAUDRATE = 15; this.ESP_READ_FLASH = 0xd2; this.chip = { CHIP_NAME: loaders.length && recoverFamily ? recoverFamily : 'ESP32-S31', getChipRevision: async () => 0, postConnect: async () => calls.push('postConnect') }; loaders.push(this) }
+    constructor({ transport }) { this.transport = transport; this.CHIP_DETECT_MAGIC_REG_ADDR = 0x40001000; this.ESP_CHANGE_BAUDRATE = 15; this.ESP_READ_FLASH = 0xd2; this.ESP_ERASE_REGION = 0xd1; this.ERASE_REGION_TIMEOUT_PER_MB = 30000; this.chip = { CHIP_NAME: loaders.length && recoverFamily ? recoverFamily : 'ESP32-S31', getChipRevision: async () => 0, readMac: async reader => { assert.equal(reader, this); calls.push('mac'); return loaders.length > 1 && recoverMac !== undefined ? recoverMac : mac }, postConnect: async () => calls.push('postConnect') }; loaders.push(this) }
     async detectChip(mode) { calls.push(['detect', mode]); await port.open({ baudRate: 115200 }); this.transport.baudrate = 115200 }
     async getSecurityInfo() { return loaders.length > 1 && recoverSecurity ? recoverSecurity : security }
     async runStub() { calls.push('stub'); this.IS_STUB = stubStarts }
     async readReg() { if (!this.IS_STUB || failRates.includes(this.transport.baudrate)) throw new Error('speed probe timeout'); return 123 }
     async readFlashId() { return flashId }
     async writeReg(...args) { calls.push(['register-write', ...args]) }
+    timeoutPerMb(...args) { return ESPLoader.prototype.timeoutPerMb.apply(this, args) }
     async checkCommand(description, _opcode, request) {
       if (description === 'change baud rate') { calls.push(['change', new DataView(request.buffer).getUint32(0, true)]); return 0 }
+      if (description === 'erase region') { calls.push(['erase', ...new Uint32Array(request.buffer)]); return 0 }
       const length = new DataView(request.buffer).getUint32(4, true), data = new Uint8Array(length)
       const frame = bytes => new Uint8Array([0xc0, ...bytes, 0xc0])
       // All-zero bytes and their digest need no SLIP escaping in this fixture.
@@ -134,9 +157,73 @@ function officialFixture({ failRates = [], usb = false, security = { flags: 0, f
     }
     async writeFlash(options) { calls.push(['write', options.compress, options.eraseAll, options.fileArray[0].address]); if (failWrite) throw new Error('write interrupted'); options.reportProgress(0, 10, 10) }
   }
-  const adapter = createOfficialBrowserLoader({ ESPLoader: FakeLoader, Transport: FakeTransport }, port, {}, { onStatus: event => events.push(event) })
+  const adapter = createOfficialBrowserLoader({ ESPLoader: FakeLoader, Transport: FakeTransport }, port, {}, { onStatus: event => events.push(event), signal, expectedMac })
   return { adapter, events, calls, port, loaders, opens, reads }
 }
+test('the official P4/S3/S31 factory MAC readers supply the normalized public chipMac', async () => {
+  for (const Chip of [ESP32P4ROM, ESP32S3ROM, ESP32S31ROM]) {
+    const chip = new Chip(), registers = []
+    const mac = await chip.readMac({ async readReg(address) {
+      registers.push(address)
+      return address === chip.MAC_EFUSE_REG ? 0xa0eda1b0 : 0x30ed
+    } })
+    assert.equal(mac, '30:ed:a0:ed:a1:b0')
+    assert.deepEqual(registers, [chip.MAC_EFUSE_REG, chip.MAC_EFUSE_REG + 4])
+    const f = officialFixture({ usb: true, mac, expectedMac: '30EDA0EDA1B0' })
+    assert.equal(f.adapter.chipMac, null)
+    await f.adapter.initialize()
+    assert.equal(f.adapter.chipMac, '30eda0eda1b0')
+    assert.ok(!f.calls.includes('stub'))
+    await f.adapter.disconnect()
+  }
+})
+test('a first expected MAC mismatch keeps the identity error on USB and UART and permanently closes', async () => {
+  for (const usb of [true, false]) {
+    const f = officialFixture({ usb, expectedMac: '30eda0eda1b1' })
+    await assert.rejects(f.adapter.initialize(), { code: 'ROM_IDENTITY_CHANGED' })
+    assert.equal(f.adapter.chipMac, null)
+    assert.equal(f.port.readable, null)
+    assert.equal(f.calls.filter(call => call === 'close').length, 1)
+    assert.ok(!f.calls.includes('stub'))
+    assert.ok(!f.calls.some(call => Array.isArray(call) && ['write', 'erase', 'register-write'].includes(call[0])))
+    await assert.rejects(f.adapter.initialize(), { code: 'ROM_CLOSED' })
+    await assert.rejects(f.adapter.runStub(), { code: 'ROM_CLOSED' })
+    assert.equal(f.loaders.length, 1)
+  }
+})
+test('a recovered same-family/revision device with a different MAC never receives another stub or write', async () => {
+  for (const expectedMac of [undefined, '30eda0eda1b0']) {
+    const f = officialFixture({ expectedMac, failRates: [2000000], recoverMac: '30:ed:a0:ed:a1:b1' })
+    await f.adapter.initialize()
+    await assert.rejects(f.adapter.runStub(), { code: 'ROM_IDENTITY_CHANGED' })
+    assert.equal(f.adapter.chipMac, '30eda0eda1b0')
+    assert.equal(f.calls.filter(call => call === 'stub').length, 1)
+    assert.equal(f.loaders.length, 2)
+    assert.equal(f.port.readable, null)
+    assert.ok(!f.calls.some(call => Array.isArray(call) && ['write', 'erase'].includes(call[0])))
+    await assert.rejects(f.adapter.runStub(), { code: 'ROM_CLOSED' })
+  }
+})
+test('malformed official MAC replies fail closed before stub startup on native USB', async () => {
+  for (const mac of [null, false, [], new Uint8Array(6), '', '30eda0eda1b0', '30:ed:a0:ed:a1', '30:ed:a0:ed:a1:gg', '30:ed:a0:ed:a1:b0\n']) {
+    const f = officialFixture({ usb: true, mac })
+    await assert.rejects(f.adapter.initialize(), { code: 'ROM_IDENTITY_INVALID' })
+    assert.equal(f.adapter.chipMac, null)
+    assert.equal(f.port.readable, null)
+    assert.ok(!f.calls.includes('stub'))
+    await assert.rejects(f.adapter.runStub(), { code: 'ROM_CLOSED' })
+  }
+})
+test('an invalid recovery MAC stops baud fallback without opening another port or starting another stub', async () => {
+  const f = officialFixture({ failRates: [2000000], recoverMac: '' })
+  await f.adapter.initialize()
+  await assert.rejects(f.adapter.runStub(), { code: 'ROM_IDENTITY_INVALID' })
+  assert.equal(f.loaders.length, 2)
+  assert.equal(f.calls.filter(call => call === 'stub').length, 1)
+  assert.equal(f.port.readable, null)
+  assert.ok(!f.calls.some(call => Array.isArray(call) && ['write', 'erase'].includes(call[0])))
+  await assert.rejects(f.adapter.initialize(), { code: 'ROM_CLOSED' })
+})
 test('ROM UART starts at 115200, checks candidates in order and stops at the first success', async () => {
   const f = officialFixture({ failRates: [2000000, 1500000] })
   await f.adapter.initialize(); assert.equal(f.adapter.chipFamily, 0x3231)
@@ -220,3 +307,82 @@ test('missing native stub handshake never creates a usable stub or starts a writ
   assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'write'))
   assert.equal(f.port.readable, null)
 })
+
+test('region erase uses the real official checked command and size-scaled timeout without chip erase', async () => {
+  const f = officialFixture({ usb: true })
+  await f.adapter.initialize(); const stub = await f.adapter.runStub()
+  const requests = [], upstream = f.loaders[0]
+  upstream.debug = () => {}
+  upstream.checkCommand = ESPLoader.prototype.checkCommand
+  upstream.command = async (...args) => { requests.push(args); return [0, new Uint8Array([0, 0])] }
+  await stub.eraseRegion(0x710000, 0x8f0000)
+  await stub.eraseRegion(0xfffff000, 4096)
+  assert.deepEqual(requests, [[0xd1, romWords(0x710000, 0x8f0000), 0, undefined,
+    upstream.timeoutPerMb(30000, 0x8f0000)], [0xd1, romWords(0xfffff000, 4096), 0, undefined, 3000]])
+  assert.deepEqual(f.events.at(-1), { phase: 'erasing-region', address: 0xfffff000, size: 4096 })
+  assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'write'))
+  await f.adapter.disconnect()
+})
+
+test('region erase rejects malformed ranges before sending an erase command', async () => {
+  for (const [address, size] of [[-4096, 4096], [1, 4096], [0, 0], [0, 1], [0, 0x100000000],
+    [0xfffff000, 8192], [NaN, 4096], [true, 4096], [0, true], [0x100000000, 4096]]) {
+    const f = officialFixture({ usb: true })
+    await f.adapter.initialize(); const stub = await f.adapter.runStub()
+    await assert.rejects(stub.eraseRegion(address, size), RangeError)
+    assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'erase'))
+    await f.adapter.disconnect()
+  }
+})
+
+test('region erase requires a live validated stub and supported upstream command primitives', async () => {
+  for (const invalid of ['stub', 'command', 'timeout', 'budget']) {
+    const f = officialFixture({ usb: true })
+    await f.adapter.initialize(); const stub = await f.adapter.runStub()
+    if (invalid === 'stub') f.loaders[0].IS_STUB = false
+    if (invalid === 'command') f.loaders[0].ESP_ERASE_REGION = 0xd0
+    if (invalid === 'timeout') f.loaders[0].timeoutPerMb = null
+    if (invalid === 'budget') f.loaders[0].ERASE_REGION_TIMEOUT_PER_MB = NaN
+    await assert.rejects(stub.eraseRegion(0x710000, 4096), { code: invalid === 'stub' ? 'ROM_STUB_REQUIRED' : 'ROM_ERASE_UNSUPPORTED' })
+    assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'erase'))
+    await f.adapter.disconnect()
+  }
+})
+
+test('real upstream region erase status, truncated replies and operation errors invalidate the session without retry', async () => {
+  for (const reply of [[0, new Uint8Array([1, 0])], [0, new Uint8Array([0])], [1, new Uint8Array([0, 0])], new Error('erase interrupted')]) {
+    const f = officialFixture({ usb: true })
+    await f.adapter.initialize(); const stub = await f.adapter.runStub()
+    let commands = 0
+    f.loaders[0].debug = () => {}
+    f.loaders[0].checkCommand = ESPLoader.prototype.checkCommand
+    f.loaders[0].command = async () => { commands++; if (reply instanceof Error) throw reply; return reply }
+    await assert.rejects(stub.eraseRegion(0x710000, 4096))
+    await assert.rejects(stub.flashData(new ArrayBuffer(4), () => {}, 0))
+    await assert.rejects(stub.eraseRegion(0x710000, 4096))
+    assert.equal(commands, 1)
+    assert.equal(f.port.readable, null)
+  }
+})
+
+test('region erase cancellation closes a pending request and never reports completion or retries', async () => {
+  const controller = new AbortController(), f = officialFixture({ usb: true, signal: controller.signal })
+  await f.adapter.initialize(); const stub = await f.adapter.runStub()
+  let started, commands = 0
+  f.loaders[0].checkCommand = () => new Promise(resolve => { commands++; started = resolve })
+  const erasing = stub.eraseRegion(0x710000, 4096), failed = assert.rejects(erasing, { name: 'AbortError' })
+  controller.abort(); await failed
+  started(0)
+  await assert.rejects(stub.flashData(new ArrayBuffer(4), () => {}, 0))
+  assert.equal(commands, 1); assert.equal(f.port.readable, null)
+})
+
+test('a detached port cannot report region erase success even after a stale successful reply', async () => {
+  const f = officialFixture({ usb: true })
+  await f.adapter.initialize(); const stub = await f.adapter.runStub()
+  let commands = 0
+  f.loaders[0].checkCommand = async () => { commands++; await f.port.close(); return 0 }
+  await assert.rejects(stub.eraseRegion(0x710000, 4096), { code: 'ROM_PORT_LOST' })
+  await assert.rejects(stub.eraseRegion(0x710000, 4096))
+  assert.equal(commands, 1)
+})

package/tests/test-ci-check-selection.mjs

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert/strict'
+import { existsSync, readFileSync } from 'node:fs'
+import test from 'node:test'
+import { DEVICE_CHECKS } from './device-checks.mjs'
+import { parseArgs } from './hardware-check.mjs'
+
+const ciConfig = new URL('../../../.gitlab/ci/target_test.yml', import.meta.url)
+test('CI keeps its qualified hardware suite explicit while manual ISP checks remain selectable', {
+  skip: !existsSync(ciConfig) && 'Repository CI configuration is not included in the npm package',
+}, () => {
+  const yaml = readFileSync(ciConfig, 'utf8')
+  const commands = yaml.replace(/\\\r?\n\s*/g, ' ').split(/\r?\n/)
+    .map(line => line.trim()).filter(line => line.startsWith('python3 tools/ci/flash_and_test.py '))
+  assert.equal(commands.length, 1)
+  const selections = [...commands[0].matchAll(/(?:^|\s)--checks\s+(\S+)/g)]
+  assert.equal(selections.length, 1)
+  assert.match(commands[0], /(?:^|\s)--require-all(?:\s|$)/)
+  const expected = ['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']
+  const selected = parseArgs(['--serial', 'policy-test', '--checks', selections[0][1], '--require-all'])
+  assert.deepEqual(selected.checks, expected)
+  assert.equal(selected.requireAll, true)
+  assert.deepEqual(parseArgs(['--serial', 'policy-test', '--checks', 'all']).checks, [...DEVICE_CHECKS])
+  const manual = ['isp_ccm_frames', 'isp_lsc_display']
+  assert.deepEqual(parseArgs(['--serial', 'policy-test', '--checks', manual.join(',')]).checks, manual)
+  for (const name of manual) assert.ok(DEVICE_CHECKS.includes(name))
+})