@esp-vision/device-core 0.4.2 → 0.5.1

package/tests/fixtures/device-checks.py

@@ -286,6 +286,205 @@ def display_stream(opts):
         lcd.deinit()
 
 
+def camera_display_lifecycle(opts):
+    """Exercise camera/LCD coexistence, camera shutdown recovery, and restart."""
+    import gc, esp32, sensor, display, image
+
+    def dma_heaps():
+        return esp32.idf_heap_info(1 << 3)  # ESP-IDF MALLOC_CAP_DMA.
+
+    lcd = None
+    frame = None
+    canvas = None
+    try:
+        sensor.shutdown()
+        gc.collect()
+        lcd = display.Display(backlight=100)
+        panel_width, panel_height = lcd.width(), lcd.height()
+        lcd.deinit()
+        lcd = None
+        gc.collect()
+
+        sensor.reset()
+        sensor.set_pixformat(sensor.RGB565)
+        sensor.set_framesize(sensor.QVGA)
+        sensor.skip_frames(n=3)
+        frame = sensor.snapshot()
+        dma_before = dma_heaps()
+        lcd = display.Display(backlight=100)
+        lcd.write(frame, fit=True)
+        dma_active = dma_heaps()
+        lcd.deinit()
+        lcd = None
+        frame = None
+        gc.collect()
+
+        sensor.shutdown()
+        gc.collect()
+        dma_shutdown = dma_heaps()
+        lcd = display.Display(backlight=100)
+        canvas = image.Image(32, 32, image.RGB565)
+        lcd.write(canvas, fit=True)
+        lcd.deinit()
+        lcd = None
+        canvas = None
+        gc.collect()
+
+        sensor.reset()
+        sensor.set_pixformat(sensor.RGB565)
+        sensor.set_framesize(sensor.QVGA)
+        sensor.skip_frames(n=3)
+        frame = sensor.snapshot()
+        restarted = (frame.width(), frame.height())
+        dma_restarted = dma_heaps()
+        return dict(width=panel_width, height=panel_height,
+                    cameraWidth=restarted[0], cameraHeight=restarted[1],
+                    dmaBefore=dma_before, dmaActive=dma_active,
+                    dmaAfterShutdown=dma_shutdown, dmaAfterRestart=dma_restarted)
+    finally:
+        if lcd is not None:
+            lcd.deinit()
+        frame = None
+        canvas = None
+        sensor.shutdown()
+        gc.collect()
+
+
+def image_copy_to_fb(opts):
+    """The unsupported copy_to_fb keyword must be rejected consistently."""
+    import gc, image
+
+    canvas = None
+    try:
+        try:
+            image.Image(32, 32, image.RGB565, copy_to_fb=True)
+        except TypeError:
+            pass
+        else:
+            raise AssertionError('Image accepted unsupported copy_to_fb')
+
+        canvas = image.Image(32, 32, image.RGB565)
+        try:
+            canvas.to_rgb565(copy_to_fb=True)
+        except TypeError:
+            pass
+        else:
+            raise AssertionError('to_rgb565 accepted unsupported copy_to_fb')
+        canvas.draw_rectangle(0, 0, 32, 32, color=(255, 0, 0), fill=True)
+        assert canvas.size() == 32 * 32 * 2, 'unexpected RGB565 buffer size'
+        return dict(width=canvas.width(), height=canvas.height(), size=canvas.size())
+    finally:
+        canvas = None
+        gc.collect()
+
+
+def image_transform_argument(opts):
+    """Transform is not part of the ESP-VISION Image API."""
+    import image
+
+    canvas = image.Image(32, 32, image.RGB565)
+    source = image.Image(8, 8, image.RGB565)
+    matrix = ((1.0, 0.0, 0.0), (0.0, 1.0, 0.0), (0.0, 0.0, 1.0))
+    for operation in (
+        lambda: canvas.copy(transform=matrix),
+        lambda: canvas.draw_image(source, transform=matrix),
+    ):
+        try:
+            operation()
+        except TypeError as exc:
+            assert 'keyword' in str(exc), 'transform is accepted but unsupported'
+        else:
+            raise AssertionError('Image accepted unsupported transform keyword')
+    return dict(operations=2)
+
+
+def sensor_snapshot_buffer(opts):
+    """Validate the caller-owned writable buffer contract for sensor.snapshot."""
+    import gc, sensor
+
+    buffer = None
+    frame = None
+    try:
+        sensor.shutdown()
+        sensor.reset()
+        sensor.set_pixformat(sensor.RGB565)
+        sensor.set_framesize(sensor.QVGA)
+        sensor.skip_frames(n=3)
+        try:
+            sensor.snapshot(buffer=bytearray(16))
+        except TypeError:
+            pass
+        else:
+            raise AssertionError('sensor.snapshot unexpectedly accepted buffer keyword')
+        try:
+            sensor.snapshot(bytearray(16))
+        except ValueError as exc:
+            assert 'snapshot buffer too small' in str(exc), 'unexpected undersized buffer error: ' + str(exc)
+        else:
+            raise AssertionError('sensor.snapshot accepted an undersized buffer')
+        frame_bytes = 320 * 240 * 2
+        buffer = bytearray(frame_bytes)
+        frame = sensor.snapshot(buffer)
+        assert (frame.width(), frame.height(), frame.size()) == (320, 240, frame_bytes), 'unexpected caller-buffer frame'
+        buffer = None
+        gc.collect()
+        assert (frame.width(), frame.height()) == (320, 240), 'Image did not retain caller buffer after GC'
+        return dict(width=frame.width(), height=frame.height(), size=frame.size())
+    finally:
+        frame = None
+        buffer = None
+        sensor.shutdown()
+        gc.collect()
+
+
+def memory_policy(opts):
+    """Large Image storage follows MicroPython GC; camera snapshots use PSRAM."""
+    import gc, esp32, image, sensor
+
+    def free_bytes(caps):
+        return sum(heap[1] for heap in esp32.idf_heap_info(caps))
+
+    def measure_image(width, height):
+        gc.collect()
+        before = gc.mem_alloc()
+        canvas = image.Image(width, height, image.RGB565)
+        gc.collect()
+        allocated = gc.mem_alloc() - before
+        canvas = None
+        gc.collect()
+        return width * height * 2, allocated
+
+    frame = None
+    try:
+        small_bytes, small_allocated = measure_image(32, 32)
+        assert small_bytes - 512 <= small_allocated <= small_bytes + 8192, 'small Image allocation did not use GC heap'
+        large_bytes, large_allocated = measure_image(640, 480)
+        assert large_bytes - 4096 <= large_allocated <= large_bytes + 16384, 'large Image allocation did not use GC heap'
+
+        sensor.shutdown()
+        gc.collect()
+        sensor.reset()
+        sensor.set_pixformat(sensor.RGB565)
+        sensor.set_framesize(sensor.QVGA)
+        psram_before = free_bytes(1 << 10)  # ESP-IDF MALLOC_CAP_SPIRAM.
+        if psram_before <= 0:
+            raise RuntimeError('ESP_ERR_NOT_SUPPORTED: PSRAM heap unavailable')
+        frame = sensor.snapshot()
+        gc.collect()
+        psram_after = free_bytes(1 << 10)
+        frame_bytes = frame.width() * frame.height() * 2
+        psram_used = psram_before - psram_after
+        assert psram_used >= frame_bytes - 4096, 'camera snapshot buffer was not allocated from PSRAM'
+        return dict(smallBytes=small_bytes, smallAllocated=small_allocated,
+                    largeBytes=large_bytes, largeAllocated=large_allocated,
+                    width=frame.width(), height=frame.height(), frameBytes=frame_bytes,
+                    psramUsed=psram_used)
+    finally:
+        frame = None
+        sensor.shutdown()
+        gc.collect()
+
+
 
 def memory(opts):
     import esp32
@@ -314,7 +513,12 @@ def run_check(name, opts):
     functions = dict(memory=memory, sensor_state=sensor_state, framesizes=framesizes,
                      pixformats=pixformats, orientation=orientation, ipa_stats=ipa_stats,
                      snapshot_rate=snapshot_rate, preview=preview, image_ops=image_ops,
-                     display=display, display_stream=display_stream)
+                     display=display, display_stream=display_stream,
+                     camera_display_lifecycle=camera_display_lifecycle,
+                     image_copy_to_fb=image_copy_to_fb,
+                     image_transform_argument=image_transform_argument,
+                     sensor_snapshot_buffer=sensor_snapshot_buffer,
+                     memory_policy=memory_policy)
     try:
         data = functions[name](opts)
         result = dict(name=name, status='PASS', data=data)

package/tests/test-device-api.mjs

@@ -11,18 +11,36 @@ const capabilities = { ok: true, protocol: { evMuxVersion: 4 },
   features: [...EV_MUX_REQUIRED_FEATURES, 'debug.capture_frame', 'script.write', 'script.run', 'device.control'],
   channels: EV_MUX_REQUIRED_CHANNELS, limits: { ...EV_MUX_DEFAULT_LIMITS, txLargePayloadMax: 262144 },
   session: { policy: 'firstCome', leaseMs: 15000, keepaliveMs: 5000 } }
-function peer({ silent = false, screen = false } = {}) {
+function peer({ silent = false, screen = false, vmReady = true, interactiveScripts = false } = {}) {
   let handlers, subscriptions = 0, disconnects = 0
   const requests = [], order = [], id = 'a'.repeat(32)
+  const requestWaiters = []
   const stdout = payload => handlers?.data(makeEvMuxFrame({ channel: 'repl.stdout', type: 'data', sessionId: id, vmEpoch: 1, payload }))
+  const recordRequest = request => {
+    requests.push(request)
+    for (let i = requestWaiters.length - 1; i >= 0; i -= 1) {
+      if (requestWaiters[i].predicate(request)) {
+        requestWaiters.splice(i, 1)[0].resolve(request)
+      }
+    }
+  }
+  const waitForRequest = predicate => {
+    const existing = requests.find(predicate)
+    return existing ? Promise.resolve(existing) : new Promise(resolve => requestWaiters.push({ predicate, resolve }))
+  }
   const parser = new EvMuxParser({ filterFrame(metadata, bytes) {
     if (silent) return false
     const payload = metadata.channel.endsWith('.rpc') ? JSON.parse(new TextDecoder().decode(bytes)) : new TextDecoder().decode(bytes)
-    requests.push({ metadata, payload })
-    if (metadata.channel === 'repl.stdin') { stdout(`${payload}\r\n${payload.includes('EVIDE_BOOT_OK') ? 'EVIDE_BOOT_OK' : 'result'}\r\n>>> `); return false }
+    recordRequest({ metadata, payload })
+    if (metadata.channel === 'repl.stdin') {
+      const startMarker = interactiveScripts && /~~EVSCRIPT-START:[A-Za-z0-9-]+~~/.exec(payload)?.[0]
+      if (startMarker) stdout(`${payload}\r\n${startMarker}\r\n`)
+      else stdout(`${payload}\r\n${payload.includes('EVIDE_BOOT_OK') ? 'EVIDE_BOOT_OK' : 'result'}\r\n>>> `)
+      return false
+    }
     if (!metadata.channel.endsWith('.rpc')) return false
     let result = { ok: true }
-    if (metadata.method === 'hello') result = { ok: true, evMuxVersion: 4, deviceId: 'e8f60ae75642', hostname: 'esp-vision-test', board: 'TEST', firmware: { version: 'test' }, vmReady: true, session: { id, vmEpoch: 1, leaseMs: 15000, keepaliveMs: 5000 } }
+    if (metadata.method === 'hello') result = { ok: true, evMuxVersion: 4, deviceId: 'e8f60ae75642', hostname: 'esp-vision-test', board: 'TEST', firmware: { version: 'test' }, vmReady, session: { id, vmEpoch: 1, leaseMs: 15000, keepaliveMs: 5000 } }
     if (metadata.method === 'capabilities') result = { ...capabilities, features: [...capabilities.features, ...(screen ? ['debug.capture_screen'] : [])] }
     if (metadata.method === 'session.keepalive') result = { ok: true, sessionId: id, vmEpoch: 1 }
     if (metadata.method === 'debug.capture_frame' || (screen && metadata.method === 'debug.capture_screen')) {
@@ -37,7 +55,7 @@ function peer({ silent = false, screen = false } = {}) {
     async disconnect() { disconnects++; order.push('disconnect') },
     async writeBytes(bytes) { parser.feedBytes(bytes) },
   }
-  return { transport, requests, order, stdout, close: () => handlers.close(), get subscriptions() { return subscriptions }, get disconnects() { return disconnects } }
+  return { transport, requests, order, stdout, waitForRequest, close: () => handlers.close(), get subscriptions() { return subscriptions }, get disconnects() { return disconnects } }
 }
 
 test('root exports only the application API; protocols remain explicit adapters', () => {
@@ -57,6 +75,8 @@ test('facade subscribes before connection, negotiates, streams input and dispose
   assert.equal(ready.identity.deviceId, 'e8f60ae75642')
   assert.deepEqual(p.order.slice(0, 2), ['subscribe','connect'])
   assert.equal(p.subscriptions, 1)
+  assert.ok(p.requests.some(x => x.metadata.channel === 'repl.signal'), 'default connection retains the REPL readiness probe')
+  assert.ok(p.requests.some(x => x.metadata.channel === 'repl.stdin' && x.payload.includes('EVIDE_BOOT_OK')))
   await d.python.input('print(2)\r')
   assert.ok(output.some(text => text.includes('result')))
   unsubscribe(); const count = output.length; p.stdout('ignored\r\n'); assert.equal(output.length,count)
@@ -66,6 +86,28 @@ test('facade subscribes before connection, negotiates, streams input and dispose
   await assert.rejects(d.files.read({path:'/x'}), {code:'DEVICE_NOT_READY'})
 })
 
+test('connect can acquire and inspect a session without interrupting the REPL', async () => {
+  const p = peer({ vmReady: false }), d = api.createDevice({ transport: p.transport })
+  try {
+    const ready = await d.connect({ role: 'tcp', probeRepl: false })
+    assert.equal(ready.runtime.vmReady, false, 'passive negotiation preserves the device readiness report')
+    assert.ok(p.requests.some(x => x.metadata.method === 'hello' && x.payload.acquire === true))
+    assert.ok(p.requests.some(x => x.metadata.method === 'capabilities'))
+    assert.equal(p.requests.some(x => x.metadata.channel === 'repl.signal' || x.metadata.channel === 'repl.stdin'), false)
+    await assert.rejects(d.python.execute({ source: 'print(1)' }), /requires a ready VM/)
+    assert.equal(p.requests.some(x => x.metadata.channel === 'repl.signal' || x.metadata.channel === 'repl.stdin'), false)
+  } finally { await d.disconnect() }
+})
+
+test('connect validates probeRepl before opening the transport', async () => {
+  const p = peer(), d = api.createDevice({ transport: p.transport })
+  for (const probeRepl of [null, 'false', 0]) {
+    await assert.rejects(d.connect({ role: 'tcp', probeRepl }), { name: 'TypeError' })
+  }
+  assert.deepEqual(p.order, [])
+  assert.deepEqual(p.requests, [])
+})
+
 test('capture returns binary bytes and unsupported LCD capture never captures the camera', async () => {
   const p = peer(), d = api.createDevice({transport:p.transport})
   try {
@@ -102,6 +144,53 @@ test('transport loss clears the connection and permits reconnection',async()=>{
   await d.connect({role:'tcp'});await d.disconnect();assert.equal(p.disconnects,2)
 })
 
+test('disconnect releases the session without interrupting a publicly started run', async () => {
+  const p = peer({ interactiveScripts: true }), d = api.createDevice({ transport: p.transport })
+  try {
+    await d.connect({ role: 'tcp', probeRepl: false })
+    const run = await d.python.execute({ path: '/main.py', completion: 'start' })
+    const doneRejected = assert.rejects(run.done)
+    const beforeDisconnect = p.requests.length
+    await d.disconnect()
+    await doneRejected
+    const released = p.requests.slice(beforeDisconnect)
+    assert.ok(released.some(request => request.metadata.method === 'session.release'))
+    assert.equal(released.some(request => request.metadata.channel === 'repl.signal'
+      || (request.metadata.method === 'device.control' && request.payload.action === 'stop')), false)
+  } finally { await d.disconnect() }
+})
+
+test('caller AbortSignal still interrupts a publicly started run', async () => {
+  const p = peer({ interactiveScripts: true }), d = api.createDevice({ transport: p.transport })
+  const controller = new AbortController()
+  try {
+    await d.connect({ role: 'tcp', probeRepl: false })
+    const run = await d.python.execute({ path: '/main.py', completion: 'start', signal: controller.signal })
+    const doneRejected = assert.rejects(run.done, { name: 'AbortError' })
+    const beforeAbort = p.requests.length
+    controller.abort()
+    await doneRejected
+    assert.ok(p.requests.slice(beforeAbort).some(request => request.metadata.method === 'device.control'
+      && request.payload.action === 'stop'))
+  } finally { await d.disconnect() }
+})
+
+test('disconnect still interrupts Python execution in completion-wait mode', async () => {
+  const p = peer(), d = api.createDevice({ transport: p.transport })
+  try {
+    await d.connect({ role: 'tcp', probeRepl: false })
+    const execution = d.python.execute({ path: '/main.py' })
+    await p.waitForRequest(request => request.metadata.channel === 'repl.stdin'
+      && String(request.payload).includes('~~EVSCRIPT-END:'))
+    const failed = assert.rejects(execution)
+    const beforeDisconnect = p.requests.length
+    await d.disconnect()
+    await failed
+    assert.ok(p.requests.slice(beforeDisconnect).some(request => request.metadata.method === 'device.control'
+      && request.payload.action === 'stop'))
+  } finally { await d.disconnect() }
+})
+
 test('discovery works before any transport is connected',async()=>{
   const d=api.createDevice({discovery:{async list(){return [{deviceId:'e8f60ae75642',hostname:'esp-vision-test',board:'TEST',firmwareVersion:'1',evMuxVersion:4,port:3232,addresses:['192.168.1.2']}]}}})
   assert.equal((await d.discover({timeout:50}))[0].compatible,true)
@@ -126,8 +215,9 @@ test('long Unicode paths stay within REPL budget for directory reads and inline
   repl.execPy=async source=>{commands.push(source);assert.ok(repl.execInputBytes(source)<=511);return source.includes('__EVLIST__')?'__EVLIST__[]\n':''}
   assert.deepEqual(await repl.listFs(path),[])
   assert.equal(commands.length,2,'Long escaped paths are assigned separately from directory code')
-  const command=repl.createScriptRunCommand(path)
+  const command=repl.createScriptRunCommand(path,{acknowledgeStart:true})
   assert.ok(new TextEncoder().encode(command).length<=511)
+  assert.match(command,/EVSCRIPT-START:/)
   if(repl.scriptRunPrelude)assert.ok(repl.execInputBytes(repl.scriptRunPrelude)<=511)
   repl.cancelScriptEndSentinel()
 })