@esp-vision/device-core 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.3.0
+
+### Added
+
+- Export the passive built-in `openNodeRom({ port, python?, signal? })` adapter from `/node` so Node SDK hosts and the CLI share the same ROM implementation.
+
+- Explicit `mode: 'install'` on firmware check/update and CLI `--mode install` for blank-device ROM installation over USJ/UART, using qualified complete images with bootloader/partition/application hashes and flash-capacity checks. Default application-only updates retain their existing data-preservation contract; no automatic fallback or TCP OTA is introduced.
+
+### Fixed
+
+- Allow up to 151 seconds of bounded metadata propagation backoff after npm accepts publication, with ten uncached verification reads and no repeated publish.
+
 ## 0.2.0
 
 ### Changed

package/README.md

@@ -19,10 +19,10 @@
 | Visibility | Public; installation needs no npm login |
 | Source location | `host/device-core` in the ESP-VISION firmware repository |
 
-The `/node` export and bundled checks were introduced in 0.1.1. This source prepares 0.2.0 with reliable binary uploads; confirm registry publication before installing it. CI authenticates with the protected `NPM_PUBLISH_TOKEN` and verifies that `npm whoami` returns `esp-vision` before publishing. Tokens are not part of this package or its documentation.
+The `/node` byte transports and bundled checks require 0.1.1; complete installation and `/node` `openNodeRom` are introduced in 0.3.0. Check the registry for the published version. CI authenticates with the protected `NPM_PUBLISH_TOKEN` and verifies that `npm whoami` returns `esp-vision` before publishing. Tokens are not part of this package or its documentation.
 
 ```sh
-npm install --save-exact @esp-vision/device-core@0.2.0 --registry=https://registry.npmjs.org/
+npm install --save-exact @esp-vision/device-core@0.3.0 --registry=https://registry.npmjs.org/
 ```
 
 EV-MUX v4 firmware is required. A v3 hello is rejected with `VERSION_MISMATCH`; applications should ask the user to update firmware. Core has no runtime dependency on the IDE, Agent, DOM or Node serial libraries. The host supplies the physical byte transport and discovery adapter; Core owns protocol parsing, session negotiation, REPL coordination and device operations.
@@ -31,7 +31,7 @@ EV-MUX v4 firmware is required. A v3 hello is rejected with `VERSION_MISMATCH`;
 
 Read the Device Core guide in the **ESP-VISION Documentation Center**: [English](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/index.html) | [简体中文](https://docs.espressif.com/projects/esp-vision/zh_CN/latest/esp32p4/device-core/index.html).
 
-- [All application APIs](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/api.html), including firmware version checks and updates.
+- [All application APIs](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/api.html), including firmware version checks, application updates and blank-device installation.
 - [Advanced exports](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/advanced.html) and [TCP/Web Serial integration](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/integration.html).
 
 Documentation source lives in this repository under `docs/en/device-core/` and `docs/zh_CN/device-core/` and changes alongside SDK APIs in the same MR. The documentation site renders the RST as HTML; it does not redirect readers to npm or require downloading documentation. The npm package contains the runtime library and this README, not a second RST documentation distribution. Use the documentation center's version selector when reading a published firmware/documentation version; `latest` follows the current development documentation. These new chapter links become available after the corresponding documentation is deployed.
@@ -41,7 +41,7 @@ Documentation source lives in this repository under `docs/en/device-core/` and `
 The npm package installs `esp-vision-device`. `inspect` combines passive wired/LAN enumeration and targeted queries. By default it lists USB serial candidates; `--all-ports` also includes native UART/Bluetooth ports. Explicit `--port` bypasses discovery filtering; `configure`, `control`, and `firmware check/update` cover management. See the [CLI guide](https://docs.espressif.com/projects/esp-vision/en/latest/esp32p4/device-core/cli.html) ([中文](https://docs.espressif.com/projects/esp-vision/zh_CN/latest/esp32p4/device-core/cli.html)).
 
 ```sh
-npm install -g @esp-vision/device-core@0.2.0
+npm install -g @esp-vision/device-core@0.3.0
 esp-vision-device inspect
 esp-vision-device inspect --all-ports
 esp-vision-device inspect --interface usj,usb --probe --json
@@ -49,7 +49,7 @@ esp-vision-device inspect --port COM3 --fields identity,capabilities
 esp-vision-device inspect --tcp 192.168.1.100:3232 --fields network,storage --json
 ```
 
-Wired access/enumeration requires Python with pyserial (`--python` overrides the interpreter); LAN discovery uses optional `multicast-dns`, normally installed by npm. Windows/Linux/macOS paths are accepted. Passive enumeration never opens a serial port; `--probe` and targeted queries acquire a session and may interrupt Python. Unidentified ports, ROM candidates and USB-to-UART adapters remain numbered and visible. Board names are unknown until firmware identification; USB descriptors are hints only. Firmware versions are fetched automatically from dl.espressif.com. Firmware flashing uses the built-in serial adapter with separately installed Python esptool>=5.3,<6; no user loader module is required. Historical releases without qualified update metadata remain listed but cannot be installed by this flow. Check the registry version before installing a newly prepared release.
+Wired access/enumeration requires Python with pyserial (`--python` overrides the interpreter); LAN discovery uses optional `multicast-dns`, normally installed by npm. Windows/Linux/macOS paths are accepted. Passive enumeration never opens a serial port; `--probe` and targeted queries acquire a session and may interrupt Python. Unidentified ports, ROM candidates and USB-to-UART adapters remain numbered and visible. Board names are unknown until firmware identification; USB descriptors are hints only. Firmware versions are fetched automatically from dl.espressif.com. Firmware flashing uses the built-in serial adapter with separately installed Python esptool>=5.3,<6; no user loader module is required. Use `firmware update --mode install --board BOARD --port PORT --version VERSION` for blank-device installation over a ROM-capable USJ/UART port. Install replaces data within the complete image range; default updates preserve the existing layout. Historical releases without qualified metadata remain listed but cannot be installed by this flow. Check the registry version before installing a newly prepared release.
 
 ## Public device API
 
@@ -65,7 +65,7 @@ Import `createDevice` from the package root. Application code uses one device in
 | Interactive Python | `python.input(data)` | Send terminal input without uploading a file |
 | Python execution | `python.execute({ source, path, completion })` | Execute source or a device-side script |
 | Files | `files.list/read/write/remove/mkdir(request)` | File and directory operations, with one object argument |
-| Firmware | `firmware.check(request)`, `firmware.update(request)` | List board firmware versions, select an exact version and perform verified ROM application updates |
+| Firmware | `firmware.check(request)`, `firmware.update(request)` | List board firmware versions, select an exact version and perform verified ROM application updates or explicit complete installation on blank devices |
 | Capture | `capture({ source, format, quality })` | Capture an image from a supported source |
 | Events | `on(event, handler)` | Subscribe; returns an unsubscribe function |
 
@@ -220,7 +220,7 @@ const image = await device.capture({ source: 'camera', format: 'jpeg', timeout:
 
 Paths are absolute device paths. `files.list({ path: '/', recursive: false })` returns entries `{ name, path, type, size }`. `files.read({ path })` returns a `Uint8Array`; use `encoding: 'utf-8'` to return text, and `maxBytes` to bound a read. Writes default to `overwrite: true`; set it to `false` to require a new destination. Uploading and executing are separate operations; create an empty file with `files.write({ path, data: new Uint8Array() })` rather than a second touch API. Remove an empty directory with `files.remove({ path: '/models', type: 'directory' })`; there is no implicit recursive deletion. `files.mkdir({ path, recursive: true })` creates missing parents.
 
-**Binary uploads (SDK 0.2.0):** text, model and image uploads share reliable raw binary `file.write` frames with 16 KiB blocks, continuous native VFS writes and SHA-256 commit. Matching firmware must advertise `file.write.binary`; missing support rejects with a firmware-upgrade message, without a slow upload fallback. File progress is not a durable commit. FAT replacement preserves an old-file backup until ordinary publication succeeds, with rollback on ordinary rename failure; it is not a power-loss-atomic journal. The filesystem must be mounted and allow writing, with room for the temporary upload and any existing destination file. File reads and directory operations currently use the REPL.
+**Binary uploads (SDK 0.3.0):** text, model and image uploads share reliable raw binary `file.write` frames with 16 KiB blocks, continuous native VFS writes and SHA-256 commit. Matching firmware must advertise `file.write.binary`; missing support rejects with a firmware-upgrade message, without a slow upload fallback. File progress is not a durable commit. FAT replacement preserves an old-file backup until ordinary publication succeeds, with rollback on ordinary rename failure; it is not a power-loss-atomic journal. The filesystem must be mounted and allow writing, with room for the temporary upload and any existing destination file. File reads and directory operations currently use the REPL.
 
 `capture({ source: 'screen', format: 'jpeg' })` uses the dedicated `debug.capture_screen` RPC to encode the LCD's last submitted RGB565 framebuffer, including the display's scaling and letterboxing. It does not read the panel electronics or capture the camera. Camera capture uses `debug.capture_frame`. Both return binary JPEG responses correlated to the request; optional `quality` is an integer from 1 to 100. Missing firmware capabilities reject with `UNSUPPORTED_OPERATION`; an uninitialized display returns `DISPLAY_NOT_READY`, and a board without an LCD returns `NOT_SUPPORTED`. Preview is a separate real-time stream and may drop frames under congestion.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esp-vision/device-core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Shared EV-MUX, framed REPL, device session, and action contracts for ESP Vision clients.",
   "type": "module",
   "exports": {
@@ -13,7 +13,7 @@
     "./firmware": "./src/firmware_flash.js",
     "./discovery": "./src/network_discovery.js",
     "./discovery/node": "./src/network_discovery_node.js",
-    "./node": "./src/node_transport.js"
+    "./node": "./src/node.js"
   },
   "files": [
     "src/*.js",

package/schemas/device-actions-v1.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "ESP Vision Device Actions",
-  "deviceCoreVersion": "0.2.0",
+  "deviceCoreVersion": "0.3.0",
   "schemaVersion": 1,
   "actions": [
     {

package/scripts/verify-registry.mjs

@@ -8,7 +8,7 @@ export async function verifyPublishedIntegrity(url, integrity, {
   wait = milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)),
   report = message => console.log(message),
 } = {}) {
-  const attempts = 6
+  const attempts = 10
   for (let attempt = 0; attempt < attempts; attempt++) {
     let response, transient
     try {
@@ -29,7 +29,7 @@ export async function verifyPublishedIntegrity(url, integrity, {
       transient = `HTTP ${response.status}`
     }
     assert.ok(attempt + 1 < attempts, `Published metadata verification unavailable after ${attempts} reads (${transient}); retry the CI job, not publication manually`)
-    const delay = 1000 * 2 ** attempt
+    const delay = Math.min(30000, 1000 * 2 ** attempt)
     report(`Registry verification ${transient}; retrying read ${attempt + 2}/${attempts} in ${delay}ms`)
     await wait(delay)
   }

package/src/cli.js

@@ -21,9 +21,9 @@ esp-vision-device configure (--port PATH | --tcp HOST[:PORT])
 esp-vision-device control (--port PATH | --tcp HOST[:PORT])
   --action stop|reset|bootloader [--mode soft|hard]
 esp-vision-device firmware check [--port PATH | --tcp HOST[:PORT]]
-  [--catalog FILE|HTTPS_URL] [--board BOARD --current-version VERSION] [--version VERSION]
+  [--catalog FILE|HTTPS_URL] [--board BOARD --current-version VERSION] [--version VERSION] [--mode update|install]
 esp-vision-device firmware update [--port PATH | --tcp HOST[:PORT]]
-  [--catalog FILE|HTTPS_URL] --version VERSION [--image APPLICATION.bin]
+  [--catalog FILE|HTTPS_URL] --version VERSION [--image FIRMWARE.bin] [--mode update|install]
   [--board BOARD --current-version VERSION]
 Common: --timeout MS (default 3000 enumeration, 30000 command),
   --probe-timeout MS (default 5000 per device), --role usb|usj|uart|unknown,
@@ -33,7 +33,10 @@ also includes native UART/Bluetooth ports. No serial
 port is opened. --probe and targeted commands acquire a session and can interrupt
 Python. Rows with unknown firmware remain visible; numbering is per invocation.
 Firmware versions come from dl.espressif.com by default; local catalogs are advanced overrides.
-Firmware update uses the built-in serial flasher (Python esptool>=5.3,<6). TCP is not OTA.`
+Firmware update uses the built-in serial flasher (Python esptool>=5.3,<6). TCP is not OTA.
+Default mode update preserves the existing layout/data; explicit mode install writes
+a complete image, replacing data in its written range. Blank boards require --board
+and a ROM-capable USJ/UART port, not an application USB-OTG interface.`
 const error = (code, message) => Object.assign(new Error(message), { code })
 const fields = ['identity', 'capabilities', 'runtime', 'network', 'storage']
 export function parseCli(args) {
@@ -43,7 +46,7 @@ export function parseCli(args) {
   if (v.help) return { help: true }
   const command = p[0] ?? 'inspect', action = command === 'firmware' ? p[1] : null
   if (!['inspect', 'configure', 'control', 'firmware'].includes(command) || p.length > (command === 'firmware' ? 2 : 1) || (command === 'firmware' && !['check', 'update'].includes(action))) throw error('ARGUMENT', 'Unknown command; use --help')
-  const allowed = { inspect: ['all-ports', 'select', 'fields', 'interface', 'probe', 'probe-timeout'], configure: ['ssid', 'forget-wifi', 'password-stdin', 'network-enabled'], control: ['action', 'mode'], firmware: ['catalog', 'board', 'current-version', 'version', 'image'] }[command]
+  const allowed = { inspect: ['all-ports', 'select', 'fields', 'interface', 'probe', 'probe-timeout'], configure: ['ssid', 'forget-wifi', 'password-stdin', 'network-enabled'], control: ['action', 'mode'], firmware: ['mode', 'catalog', 'board', 'current-version', 'version', 'image'] }[command]
   for (const key of Object.keys(v)) if (!['json', 'port', 'tcp', 'python', 'timeout', 'role', ...allowed].includes(key)) throw error('ARGUMENT', `Option --${key} is not valid for ${command}`)
   if ([v.port, v.tcp, v.select].filter(value => value !== undefined).length > 1) throw error('ARGUMENT', 'Select exactly one device address or number')
   if (v.role && !['usb', 'usj', 'uart', 'unknown'].includes(v.role)) throw error('ARGUMENT', 'Invalid serial role')
@@ -74,6 +77,8 @@ export function parseCli(args) {
   }
   if (command === 'control' && (!['stop', 'reset', 'bootloader'].includes(v.action) || (v.action === 'reset' ? !['soft', 'hard'].includes(v.mode) : v.mode !== undefined))) throw error('ARGUMENT', 'Control requires action; reset requires mode soft or hard')
   if (command === 'firmware') {
+    if (v.mode !== undefined && !['update', 'install'].includes(v.mode)) throw error('ARGUMENT', 'Firmware mode must be update or install')
+    if (v.mode === 'install' && !v.board) throw error('ARGUMENT', 'Firmware installation requires explicit --board')
     if (!endpoint && !v.board) throw error('ARGUMENT', 'Firmware requires a connected device or --board')
     if (action === 'update' && (!v.port || !v.version)) throw error('ARGUMENT', 'Firmware update requires local --port and explicit --version')
     if (action === 'check' && v.image) throw error('ARGUMENT', 'Image applies only to firmware update')
@@ -108,9 +113,9 @@ export async function runCli(options, dependencies = {}) {
     endpoint = listing.devices.find(row => row.number === options.select)
     if (!endpoint) throw error('DEVICE_NOT_FOUND', 'Selected result number is unavailable in this enumeration')
   }
-  const device = makeDevice(endpoint ? { transport: (dependencies.transportFor ?? transportFor)(endpoint, options) } : {})
+  const offline = options.command === 'firmware' && options.board
+  const device = makeDevice(endpoint && !offline ? { transport: (dependencies.transportFor ?? transportFor)(endpoint, options) } : {})
   try {
-    const offline = options.command === 'firmware' && options.board
     if (endpoint && !offline) await device.connect({ role: endpoint.interface === 'serial' ? 'unknown' : endpoint.interface, timeout: options.timeout, signal, ...(endpoint.advertisement ? { expectedDevice: endpoint.advertisement } : {}) })
     if (options.command === 'inspect') return await device.inspect({ fields: options.fields, timeout: options.timeout, signal })
     if (options.command === 'configure') {
@@ -123,10 +128,11 @@ export async function runCli(options, dependencies = {}) {
     }
     if (options.command === 'control') return await device.control({ action: options.action, ...(options.mode ? { mode: options.mode } : {}), timeout: options.timeout, signal })
     let catalog = options.catalog
+    const mode = options.mode ?? 'update'
     if (catalog !== undefined && !/^https:\/\//.test(catalog)) catalog = JSON.parse(await (dependencies.readFile ?? readFile)(catalog, 'utf8'))
-    const checked = await device.firmware.check({ catalog, ...(endpoint && !offline ? {} : { identity: { board: options.board, firmwareVersion: options['current-version'] ?? 'unknown' } }), ...(options.version ? { version: options.version } : {}), signal })
+    const checked = await device.firmware.check({ catalog, mode, ...(endpoint && !offline ? {} : { identity: { board: options.board, firmwareVersion: options['current-version'] ?? 'unknown' } }), ...(options.version ? { version: options.version } : {}), signal })
     if (options.action === 'check') return checked
-    return await device.firmware.update({ release: checked.release, board: options.board, ...(options.image ? { data: new Uint8Array(await (dependencies.readFile ?? readFile)(options.image)) } : {}), openLoader: ({ signal }) => (dependencies.openLoader ?? openNodeRom)({ port: options.port, python: options.python, signal }), onPhase: dependencies.onPhase ?? (() => {}), signal })
+    return await device.firmware.update({ mode, release: checked.release, board: options.board, ...(options.image ? { data: new Uint8Array(await (dependencies.readFile ?? readFile)(options.image)) } : {}), openLoader: ({ signal }) => (dependencies.openLoader ?? openNodeRom)({ port: options.port, python: options.python, signal }), onPhase: dependencies.onPhase ?? (() => {}), signal })
   } finally { await device.disconnect() }
 }
 const safe = value => String(value ?? '—').replace(/[\x00-\x1f\x7f-\x9f]/g, '?')

package/src/firmware_feed.js

@@ -23,6 +23,7 @@ export async function loadOfficialFirmware({ board, fetch: fetcher = globalThis.
     if (metadata) {
       const entry = await metadata.json()
       if (entry.board !== name || entry.version !== version || new URL(entry.image?.url).origin !== 'https://dl.espressif.com') throw new TypeError('Official firmware metadata identity/URL mismatch')
+      if (entry.install && new URL(entry.install.url).origin !== 'https://dl.espressif.com') throw new TypeError('Official install URL mismatch')
       releases.push(entry)
     } else {
       const file = web.binaryNameTemplate.replace('{board}', name).replace('{tag}', version)

package/src/firmware_flash.js

@@ -6,18 +6,37 @@ export async function firmwareSha256(bytes) {
   return Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, '0')).join('')
 }
 
-export async function validateFirmwareImage(image, bytes) {
+export function firmwareMode(mode = 'update') {
+  if (!['update', 'install'].includes(mode)) throw new TypeError('Firmware mode must be update or install')
+  return mode
+}
+
+export async function validateFirmwareImage(image, bytes, { mode = 'update' } = {}) {
+  firmwareMode(mode)
   if (image.evMuxVersion !== 4) throw new Error('Only approved EV-MUX v4 firmware can be installed')
   if (!(bytes instanceof Uint8Array) || bytes.byteLength !== image.bytes) throw new Error('Firmware image size does not match the approved build')
-  if (!Number.isSafeInteger(image.offset) || !Number.isSafeInteger(image.partitionSize)
-      || image.offset < 0 || image.bytes <= 0 || image.bytes > image.partitionSize) throw new Error('Invalid application partition bounds')
+  const limit = mode === 'install' ? image.flashSize : image.partitionSize
+  if (!Number.isSafeInteger(image.offset) || !Number.isSafeInteger(limit)
+      || image.offset < 0 || image.bytes <= 0 || image.bytes > limit || (mode === 'install' && image.offset !== 0)) throw new Error('Invalid firmware image bounds')
   if (await firmwareSha256(bytes) !== image.sha256) throw new Error('Firmware SHA-256 does not match the approved build')
+  if (mode === 'install') {
+    const segments = [image.bootloader, image.partitionTable, image.application]
+    let end = 0
+    for (const segment of segments) {
+      if (!segment || !Number.isSafeInteger(segment.offset) || !Number.isSafeInteger(segment.bytes)
+          || segment.offset < end || segment.bytes <= 0 || segment.offset + segment.bytes > bytes.byteLength
+          || !/^[a-f0-9]{64}$/.test(segment.sha256 ?? '')) throw new Error('Complete image requires ordered, non-overlapping bootloader, partition table and application metadata')
+      if (await firmwareSha256(bytes.subarray(segment.offset, segment.offset + segment.bytes)) !== segment.sha256) throw new Error('Complete image does not contain the approved bootloader, partition table and application')
+      end = segment.offset + segment.bytes
+    }
+  }
   return bytes
 }
 
 /** Loader injected by the browser host; no Web Serial or ROM protocol duplicated. */
 export class FirmwareFlashSession {
-  constructor(loader, image, { reset = () => loader.hardReset() } = {}) {
+  constructor(loader, image, { reset = () => loader.hardReset(), mode = 'update' } = {}) {
+    this.mode = firmwareMode(mode)
     this.loader = loader
     this.reset = reset
     this.image = image
@@ -29,7 +48,7 @@ export class FirmwareFlashSession {
     if (this.state !== 'idle') throw new Error('Firmware loader is already in use')
     this.state = 'connecting'
     try {
-      await validateFirmwareImage(this.image, bytes)
+      await validateFirmwareImage(this.image, bytes, { mode: this.mode })
       await this.loader.initialize()
       const revisionMatches = this.image.chipRevision !== undefined ? this.loader.chipRevision === this.image.chipRevision
         : Number.isInteger(this.image.chipRevisionMin) && Number.isInteger(this.image.chipRevisionMax) && this.loader.chipRevision >= this.image.chipRevisionMin && this.loader.chipRevision <= this.image.chipRevisionMax
@@ -43,9 +62,18 @@ export class FirmwareFlashSession {
       const encrypted = security.flashCryptCnt.toString(2).replace(/0/g, '').length % 2 === 1
       if ((security.flags & 1) !== 0 || encrypted) throw new Error('Secure boot or encrypted devices require their signed flashing workflow')
       this.stub = await this.loader.runStub(true)
-      const table = this.image.partitionTable
-      const existing = await this.stub.readFlash(table.offset, table.bytes)
-      if (await firmwareSha256(existing) !== table.sha256) throw new Error('Partition layout differs; use the board migration instructions instead')
+      if (this.mode === 'install') {
+        // JEDEC capacity byte encodes log2(bytes); shared with browser loaders.
+        if (typeof this.stub.flashId !== 'function') throw new Error('Installation requires ROM flash capacity detection (flashId)')
+        const id = await this.stub.flashId()
+        const capacity = (id >>> 16) & 0xff
+        if (!Number.isSafeInteger(id) || id <= 0 || id > 0xffffff || capacity < 18 || capacity > 30
+            || 2 ** capacity < this.image.flashSize) throw new Error('Detected flash is unknown or smaller than the approved complete image layout')
+      } else {
+        const table = this.image.partitionTable
+        const existing = await this.stub.readFlash(table.offset, table.bytes)
+        if (await firmwareSha256(existing) !== table.sha256) throw new Error('Partition layout differs; select explicit install mode to replace the layout')
+      }
       this.state = 'connected'
     } catch (error) { await this.disconnect(); throw error }
   }
@@ -54,11 +82,11 @@ export class FirmwareFlashSession {
     if (this.state !== 'connected') throw new Error('Connect and validate the device before flashing')
     this.state = 'flashing'
     try {
-      await validateFirmwareImage(this.image, bytes)
-      onPhase('Writing application; bootloader, partition table, NVS and user files are preserved')
+      await validateFirmwareImage(this.image, bytes, { mode: this.mode })
+      onPhase(this.mode === 'install' ? 'Installing complete firmware; existing data in the written range will be replaced' : 'Writing application; bootloader, partition table, NVS and user files are preserved')
       await this.stub.flashData(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
         (written, total) => onProgress(total ? Math.min(80, Math.round(written / total * 80)) : 0), this.image.offset, false)
-      onPhase('Verifying the complete application image')
+      onPhase(this.mode === 'install' ? 'Verifying the complete installation image' : 'Verifying the complete application image')
       // maxInFlight is a packet count: one 1 KiB packet bounds USB-JTAG backlog.
       const readback = new Uint8Array(bytes.byteLength)
       for (let offset = 0; offset < bytes.byteLength; offset += 65536) {

package/src/firmware_updates.js

@@ -2,7 +2,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { loadOfficialFirmware } from './firmware_feed.js'
-import { FirmwareFlashSession, validateFirmwareImage } from './firmware_flash.js'
+import { FirmwareFlashSession, validateFirmwareImage, firmwareMode } from './firmware_flash.js'
 
 function record(value, keys, name) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${name} must be an object`)
@@ -16,7 +16,7 @@ function identity(value) {
   if (!value || typeof value.board !== 'string' || !value.board || typeof value.firmwareVersion !== 'string' || !value.firmwareVersion) throw new TypeError('An inspected identity with board and firmwareVersion is required')
   return structuredClone(value)
 }
-function release(value) {
+function release(value, mode = 'update') {
   if (!value || typeof value.board !== 'string' || !value.board || typeof value.version !== 'string' || !value.version) throw new TypeError('Release requires board and version')
   const image = value.image
   const revisionValid = image?.chipRevision !== undefined
@@ -29,6 +29,23 @@ function release(value) {
       || !/^[a-f0-9]{64}$/.test(image.sha256 ?? '') || !Number.isSafeInteger(image.partitionTable?.offset) || image.partitionTable.offset < 0
       || !Number.isSafeInteger(image.partitionTable?.bytes) || image.partitionTable.bytes <= 0
       || !/^[a-f0-9]{64}$/.test(image.partitionTable?.sha256 ?? '')) throw new TypeError('Release requires complete EV-MUX v4 application/chip/partition/SHA-256 metadata')
+  if (mode === 'install') {
+    const install = value.install
+    if (!install || install.offset !== 0 || !Number.isSafeInteger(install.bytes) || install.bytes <= 0
+        || !Number.isSafeInteger(install.flashSize) || install.flashSize < install.bytes || install.flashSize > 2 ** 30
+        || !Number.isInteger(Math.log2(install.flashSize)) || install.flashSize < 2 ** 18
+        || !/^[a-f0-9]{64}$/.test(install.sha256 ?? '') || !install.bootloader
+        || !Number.isSafeInteger(install.chipRevisionMin) || !Number.isSafeInteger(install.chipRevisionMax)
+        || install.chipRevisionMin < (image.chipRevision ?? image.chipRevisionMin) || install.chipRevisionMax > (image.chipRevision ?? image.chipRevisionMax)
+        || install.chipRevisionMin < 0 || install.chipRevisionMax < install.chipRevisionMin) throw Object.assign(new TypeError('Release lacks qualified complete-install metadata'), { code: 'FIRMWARE_INSTALL_UNAVAILABLE' })
+    let end = 0
+    for (const part of [install.bootloader, image.partitionTable, image]) {
+      if (!Number.isSafeInteger(part.offset) || !Number.isSafeInteger(part.bytes) || part.bytes <= 0
+          || part.offset < end || part.offset + part.bytes > install.bytes
+          || !/^[a-f0-9]{64}$/.test(part.sha256 ?? '')) throw new TypeError('Invalid complete-install segment bounds or hashes')
+      end = part.offset + part.bytes
+    }
+  }
   return structuredClone(value)
 }
 async function download(url, fetcher, signal) {
@@ -41,10 +58,11 @@ async function download(url, fetcher, signal) {
 }
 
 export async function checkFirmware(request = {}, connectedIdentity) {
-  record(request, ['catalog', 'identity', 'version', 'fetch', 'signal'], 'firmware.check')
+  record(request, ['catalog', 'identity', 'version', 'mode', 'fetch', 'signal'], 'firmware.check')
   const { signal, fetch: fetcher = globalThis.fetch } = request
   abort(signal)
   if (request.version !== undefined && (typeof request.version !== 'string' || !request.version.trim())) throw new TypeError('version must be a non-empty firmware version string')
+  const mode = firmwareMode(request.mode)
   const current = identity(connectedIdentity ?? request.identity)
   const catalog = request.catalog === undefined ? await loadOfficialFirmware({ board: current.board, fetch: fetcher, signal }) : typeof request.catalog === 'string' ? await (await download(request.catalog, fetcher, signal)).json() : structuredClone(request.catalog)
   abort(signal)
@@ -56,22 +74,30 @@ export async function checkFirmware(request = {}, connectedIdentity) {
     return structuredClone(item)
   })
   if (new Set(candidates.map(item => item.version)).size !== candidates.length) throw new TypeError('Catalog must not contain duplicate versions for one board')
-  const selected = request.version === undefined ? candidates.find(item => item.compatible !== false) ?? null : candidates.find(item => item.version === request.version)
+  const selected = request.version === undefined ? candidates.find(item => item.compatible !== false && (mode !== 'install' || item.install)) ?? null : candidates.find(item => item.version === request.version)
   if (request.version !== undefined && !selected) throw Object.assign(new Error('Requested firmware version is unavailable for this board'), { code: 'FIRMWARE_VERSION_UNAVAILABLE' })
   if (selected?.compatible === false) throw Object.assign(new Error('This published version lacks approved v4 update metadata'), { code: 'FIRMWARE_INCOMPATIBLE' })
+  if (selected) release(selected, mode)
   return { available: selected !== null && (selected.firmwareVersion ?? selected.version) !== current.firmwareVersion, currentVersion: current.firmwareVersion, release: selected, releases: candidates }
 }
 
 export async function updateFirmware(request, connectedIdentity, disconnect) {
-  record(request, ['release', 'board', 'data', 'fetch', 'openLoader', 'reset', 'onProgress', 'onPhase', 'signal'], 'firmware.update')
+  record(request, ['release', 'board', 'mode', 'data', 'fetch', 'openLoader', 'reset', 'onProgress', 'onPhase', 'signal'], 'firmware.update')
   const { signal, fetch: fetcher = globalThis.fetch, openLoader, reset, onProgress = () => {}, onPhase = () => {} } = request
   abort(signal)
   if (typeof openLoader !== 'function' || typeof onProgress !== 'function' || typeof onPhase !== 'function' || (reset !== undefined && typeof reset !== 'function')) throw new TypeError('Firmware update requires openLoader and valid callbacks')
-  const target = release(request.release)
+  const mode = firmwareMode(request.mode)
+  const target = release(request.release, mode)
+  const image = mode === 'install' ? {
+    ...target.image, offset: target.install.offset, bytes: target.install.bytes,
+    flashSize: target.install.flashSize, sha256: target.install.sha256, url: target.install.url,
+    bootloader: target.install.bootloader, application: target.image,
+    chipRevision: undefined, chipRevisionMin: target.install.chipRevisionMin, chipRevisionMax: target.install.chipRevisionMax,
+  } : target.image
   const board = connectedIdentity?.board ?? request.board
   if (!board || board !== target.board || (request.board !== undefined && request.board !== board)) throw new TypeError('Firmware release does not match the connected or explicitly selected board')
-  const bytes = request.data === undefined ? new Uint8Array(await (await download(target.image.url, fetcher, signal)).arrayBuffer()) : request.data instanceof Uint8Array ? request.data.slice() : request.data
-  await validateFirmwareImage(target.image, bytes)
+  const bytes = request.data === undefined ? new Uint8Array(await (await download(image.url, fetcher, signal)).arrayBuffer()) : request.data instanceof Uint8Array ? request.data.slice() : request.data
+  await validateFirmwareImage(image, bytes, { mode })
   abort(signal)
   // Validate everything before releasing EV-MUX or acquiring a download port.
   await disconnect()
@@ -80,7 +106,7 @@ export async function updateFirmware(request, connectedIdentity, disconnect) {
   let session
   try {
     abort(signal)
-    session = new FirmwareFlashSession(loader, target.image, { reset: reset ? () => reset(loader) : undefined })
+    session = new FirmwareFlashSession(loader, image, { mode, reset: reset ? () => reset(loader) : undefined })
     await session.connect(bytes)
     abort(signal)
     // No interruption after writing starts: finish verification and reset policy.

package/src/node.js

@@ -0,0 +1,5 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+// Node-only adapters. Creating them does not acquire a session or serial port.
+export { tcpTransport, serialTransport } from './node_transport.js'
+export { openNodeRom } from './node_rom.js'

package/src/node_rom.js

@@ -41,6 +41,7 @@ export function openNodeRom({ port, python = defaultPython, signal } = {}) {
       try { Object.assign(loader, await rpc('initialize')) }
       finally { signal?.removeEventListener('abort', cancelled) }
     },
+    flashId: () => rpc('flashId'),
     getSecurityInfo: () => rpc('security'),
     async runStub() { await rpc('stub'); return loader },
     async readFlash(offset, bytes) { return new Uint8Array(Buffer.from(await rpc('read', [offset, bytes]), 'base64')) },

package/src/node_rom.py

@@ -32,6 +32,8 @@ def main():
                         esp = esptool.run_stub(esp)
                         esptool.attach_flash(esp)
                         esp.change_baud(460800)
+                    elif method == 'flashId':
+                        result = esp.flash_id()
                     elif method == 'read':
                         result = base64.b64encode(esp.read_flash(*args)).decode('ascii')
                     elif method == 'write':

package/tests/check-package.mjs

@@ -38,7 +38,7 @@ try {
   if (Object.keys(api).sort().join(',') !== 'createDevice') throw new Error('Root must expose only the application API');
   const { DeviceSession } = await import('@esp-vision/device-core/session');
   const { FirmwareFlashSession } = await import('@esp-vision/device-core/firmware');
-  const { tcpTransport, serialTransport } = await import('@esp-vision/device-core/node');
+  const { tcpTransport, serialTransport, openNodeRom } = await import('@esp-vision/device-core/node');
   if (typeof tcpTransport !== 'function' || typeof serialTransport !== 'function') throw new Error('Missing public Node transports');
   const { createNodeDiscovery } = await import('@esp-vision/device-core/discovery/node');
   const { EventEmitter } = await import('node:events');
@@ -49,6 +49,7 @@ try {
   const device = api.createDevice({ discovery: provider });
   if (typeof provider.list !== 'function') throw new Error('Discovery providers must expose list()');
   if ((await device.discover({ timeout: 50 })).length !== 0 || !queries) throw new Error('Device discovery did not call its provider');
+  if (typeof openNodeRom !== 'function' || typeof openNodeRom({ port: 'not-opened' }).initialize !== 'function') throw new Error('Missing passive Node ROM adapter');
   // Constructors must be passive: these endpoints need not exist to create adapters.
   api.createDevice({ transport: tcpTransport({ host: '127.0.0.1', port: 1 }) });
   api.createDevice({ transport: serialTransport({ python: 'python3', serial: 'not-opened' }) });

package/tests/test-firmware-install.mjs

@@ -0,0 +1,126 @@
+// SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+// SPDX-License-Identifier: Apache-2.0
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { createDevice } from '../src/index.js'
+import { firmwareSha256 } from '../src/firmware_flash.js'
+import { parseCli, runCli } from '../src/cli.js'
+
+async function fixture() {
+  const data = new Uint8Array(0x11000).fill(0xff), calls = []
+  data.set([0xe9, 1, 2, 3], 0x2000)
+  data.set([0xaa, 0x50, 4, 5], 0x8000)
+  data.set([0xe9, 6, 7, 8], 0x10000)
+  const part = async offset => ({ offset, bytes: 4, sha256: await firmwareSha256(data.subarray(offset, offset + 4)) })
+  const release = { board: 'BOARD', version: 'new', image: {
+    evMuxVersion: 4, chipFamily: 0x3280, chipRevision: 302, ...(await part(0x10000)),
+    partitionSize: 4096, partitionTable: await part(0x8000), 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(data.length).fill(0xff)
+  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 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 }
+}
+
+test('blank device installs through ROM without an EV-MUX transport or existing partition table', async () => {
+  const f = await fixture(), progress = []
+  const result = await f.device.firmware.update({ ...f.request, onProgress: value => progress.push(value) })
+  assert.equal(result.verified, true); assert.equal(result.reconnected, false)
+  assert.deepEqual(f.flash, f.data)
+  assert.deepEqual(f.calls, ['open', 'initialize', 'stub', 'capacity', ['write', 0], ['read', 0], ['read', 65536], 'reset', 'close'])
+  assert.equal(progress.at(-1), 100)
+})
+
+test('default application update refuses blank layout and never falls back to installing', async () => {
+  const f = await fixture()
+  await assert.rejects(f.device.firmware.update({ ...f.request, mode: undefined, data: f.data.slice(65536, 65540) }), /Partition layout/)
+  assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'write'))
+  assert.ok(!f.calls.includes('capacity'))
+})
+
+test('complete image is downloaded from install URL with the requested cancellation signal', async () => {
+  const f = await fixture(), controller = new AbortController()
+  await f.device.firmware.update({ ...f.request, data: undefined, signal: controller.signal,
+    async fetch(url, options) { assert.equal(url, f.release.install.url); assert.equal(options.signal, controller.signal); return { ok: true, arrayBuffer: async () => f.data.buffer } },
+  })
+  assert.deepEqual(f.flash, f.data)
+})
+
+test('install selection skips app-only releases and rejects explicit unqualified versions', async () => {
+  const f = await fixture(), appOnly = { ...f.release, version: 'app-only', install: undefined }
+  const request = { mode: 'install', identity: { board: 'BOARD', firmwareVersion: 'unknown' }, catalog: { schemaVersion: 1, releases: [appOnly, f.release] } }
+  const result = await f.device.firmware.check(request)
+  assert.equal(result.release.version, 'new'); assert.equal(result.releases.length, 2)
+  await assert.rejects(f.device.firmware.check({ ...request, version: 'app-only' }), { code: 'FIRMWARE_INSTALL_UNAVAILABLE' })
+  const updates = await f.device.firmware.check({ ...request, mode: 'update' })
+  assert.equal(updates.release.version, 'app-only')
+  assert.deepEqual(f.calls, [])
+})
+
+for (const change of ['hash', 'bootloader', 'table', 'application', 'overlap', 'bounds', 'revision-range', 'missing-metadata', 'mode', 'board']) {
+  test(`invalid ${change} rejects installation before opening or releasing a port`, async () => {
+    const f = await fixture()
+    if (change === 'hash') f.data[1] = 0
+    if (change === 'bootloader') f.release.install.bootloader.sha256 = '0'.repeat(64)
+    if (change === 'table') f.release.image.partitionTable.sha256 = '0'.repeat(64)
+    if (change === 'application') f.release.image.sha256 = '0'.repeat(64)
+    if (change === 'overlap') f.release.install.bootloader.bytes = 0x8000
+    if (change === 'bounds') f.release.install.offset = 0x1000
+    if (change === 'revision-range') f.release.install.chipRevisionMin = 301
+    if (change === 'missing-metadata') delete f.release.install
+    if (change === 'mode') f.request.mode = 'auto'
+    if (change === 'board') f.request.board = 'WRONG'
+    await assert.rejects(f.device.firmware.update(f.request))
+    assert.deepEqual(f.calls, [])
+  })
+}
+
+for (const change of ['wrong-chip', 'wrong-revision', 'secure-boot', 'encryption', 'small-flash', 'unknown-flash', 'missing-capacity']) {
+  test(`physical ${change} refuses installation before any write`, async () => {
+    const f = await fixture()
+    if (change === 'wrong-chip') f.loader.chipFamily = 0x3253
+    if (change === 'wrong-revision') f.loader.chipRevision = 301
+    if (change === 'secure-boot') f.loader.getSecurityInfo = async () => ({ flags: 1, flashCryptCnt: 0 })
+    if (change === 'encryption') f.loader.getSecurityInfo = async () => ({ flags: 0, flashCryptCnt: 1 })
+    if (change === 'small-flash') f.loader.flashId = async () => 0x1740ef
+    if (change === 'unknown-flash') f.loader.flashId = async () => 0xffffff
+    if (change === 'missing-capacity') delete f.loader.flashId
+    await assert.rejects(f.device.firmware.update(f.request))
+    assert.ok(!f.calls.some(call => Array.isArray(call) && call[0] === 'write'))
+    assert.equal(f.calls.at(-1), 'close')
+  })
+}
+
+test('installation with damaged readback does not reset or report success', async () => {
+  const f = await fixture(); f.loader.readFlash = async (_offset, count) => new Uint8Array(count)
+  await assert.rejects(f.device.firmware.update(f.request), /verification failed/)
+  assert.ok(!f.calls.includes('reset')); assert.equal(f.calls.at(-1), 'close')
+})
+
+test('CLI install uses ROM directly and passes mode through both check and update', async () => {
+  const f = await fixture(), checked = []
+  const options = parseCli(['firmware', 'update', '--mode', 'install', '--board', 'BOARD', '--port', '/dev/ttyACM0', '--version', 'new'])
+  const result = await runCli(options, {
+    transportFor: () => { throw new Error('No application transport should be acquired') },
+    async readFile() { throw new Error('No user catalog required') },
+    createDevice: () => ({ firmware: {
+      async check(request) { checked.push(request.mode); return { release: f.release } },
+      async update(request) { assert.equal(request.mode, 'install'); return { verified: true } },
+    }, async disconnect() {} }),
+  })
+  assert.equal(result.verified, true); assert.deepEqual(checked, ['install'])
+  assert.throws(() => parseCli(['firmware', 'update', '--mode', 'install', '--port', 'COM3', '--version', 'new']), /explicit --board/)
+  assert.throws(() => parseCli(['firmware', 'update', '--mode', 'install', '--tcp', 'host', '--board', 'BOARD', '--version', 'new']), /local --port/)
+})

package/tests/test-release-verification.mjs

@@ -51,8 +51,16 @@ test('missing published integrity is not accepted', async () => {
   await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), /integrity mismatch/)
   assert.deepEqual(f.waits, [])
 })
-test('persistent propagation failures stop after six reads with bounded backoff', async () => {
-  const f = fixture(Array.from({ length: 6 }, () => new Response('', { status: 404 })))
-  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), /after 6 reads/)
-  assert.equal(f.calls.length, 6); assert.deepEqual(f.waits, [1000, 2000, 4000, 8000, 16000])
+test('persistent propagation failures stop after ten reads with bounded backoff', async () => {
+  const f = fixture(Array.from({ length: 10 }, () => new Response('', { status: 404 })))
+  await assert.rejects(verifyPublishedIntegrity(url, integrity, f.options), /after 10 reads/)
+  assert.equal(f.calls.length, 10); assert.deepEqual(f.waits, [1000, 2000, 4000, 8000, 16000, 30000, 30000, 30000, 30000])
+})
+
+test('registry visibility delayed beyond the original 31-second window is verified without another publish', async () => {
+  const f = fixture([...Array.from({ length: 7 }, () => new Response('', { status: 404 })), published(integrity)])
+  await verifyPublishedIntegrity(url, integrity, f.options)
+  assert.equal(f.calls.length, 8)
+  assert.ok(f.waits.reduce((total, delay) => total + delay, 0) > 31000)
+  assert.ok(f.waits.every(delay => delay <= 30000))
 })