Skip to content

Web console: the WebUSB landing page (configure and inspect the emulator) - #20

Merged
finger563 merged 23 commits into
mainfrom
feat/web-console
Nov 14, 2026
Merged

finger563 merged 23 commits into
mainfrom
feat/web-console

Conversation

@finger563

@finger563 finger563 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

This PR adds the Emulator Console, a web page that configures and inspects the emulator over USB. The firmware now advertises it as its WebUSB landing page, so Chrome or Edge offers to open it when the board is plugged in. It is published at https://esp-cpp.github.io/tab5-emu/ (see setup below), and the source is in web/: plain HTML, CSS and ES modules with no build step.

Tabs:

  • Dashboard: the running game with its boxart, the frame rate, memory (with a history), firmware, partition and uptime, the last reset, the last crash, and the SD card's USB drive mode.
  • Screen: the game's screen, or the launcher's when no game runs, captured once or live. It has an on-screen controller (or keyboard), save/load slots and Quit.
  • Library: the games grouped by console with their boxart, read from the SD card. You can search, play, and filter by console; the filter optionally applies to the launcher too. You can also add a game (ROM, optional boxart and the metadata.csv line) or remove one.
  • Files: browse the SD card, download files, upload them (with drag and drop), create folders and delete.
  • Settings: the launcher's settings, applied and saved the same way as its own controls.
  • System: the chip, partitions, OTA state, reset reason and the other link services, plus restart, restart into download mode, and firmware update. An update reboots into the updater and opens espp's OTA console in a new tab. The generic services (core dump, system, monitor) open in their espp apps; the page picks the app from espp's registry.js by protocol and hands the device over.
  • Console: the console log over Web Serial, with a filter, follow mode and save.

Firmware changes:

  • Link protocol 4: a SETTINGS request to read the launcher's settings or change one (name=value), with each setting's limits. LIST_ROMS now includes each game's console key and boxart path. There's a matching emulink settings [name=value].
  • WebUSB landing page: esp-cpp.github.io/tab5-emu/ instead of esp-cpp.github.io/espp/apps/device_hub.html, which doesn't exist; the hub is dispatcher_hub.html, and this page links to it.
  • Pages workflow: .github/workflows/pages.yml publishes web/ on a push to main. It needs Settings → Pages → Source: GitHub Actions enabled once.

link.js (framing, emu.control and the system service) and app.js are the same files in esp-box-emu and tab5-emu, like tools/emulink. The page also accepts the Device Hub's hand-off query string (?autoconnect=1&transport=usb&vid=…&pid=…&serial=…).

Tested on both boards in Chrome from http://localhost:8737:

  • connecting, and reconnecting automatically after a restart;
  • the dashboard;
  • the library, including launching a game, filtering, and loading all the boxart;
  • the live screen (about 0.2 s per NES frame on the box, and 3.7 s for a 1280×720 launcher shot on the Tab5, whose USB link is full speed);
  • the controller;
  • a file round trip (200 KB, byte for byte), folder creation and deletion;
  • the settings, with the brightness slider, the system info and the services list.

The JS framing is also cross-checked against emulink's Python codec.

Not tested: the Console tab (Web Serial needs the port picked in the browser's chooser) and the OTA hand-off.

Known issue (not caused by this PR): during these tests the box crashed while Sonic 2 (Genesis) was running. The crash was in the link task's next allocation, with a corrupted heap: a TLSF assert or an MMU fault. It is intermittent, and I couldn't pin it to a change; details are in the conversation. The page itself only makes ordinary link requests.

Screenshots (on the ESP-Box-Emu)

Dashboard (Sonic 2 running) Library
Screen and controller (Super Mario Bros. 3) System and services

🤖 Generated with Claude Code

https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY

finger563 and others added 8 commits November 12, 2026 23:42
- Left / right on the game list jump to the previous / next console (the
  game buttons take left / right as keys: LV_OBJ_FLAG_USER_1 in
  Tab5Emu::keypad_read()).
- The console above the boxart opens a console picker (tap it, X on a
  gamepad, F on a keyboard): all consoles, or only one console's games.
  The console is outlined while the list is filtered, and left / right
  then move the filter. Launching a game the filter hides lifts it.
- The selected game is highlighted in the list (the theme has no checked
  style for list buttons, so it was not).
- USB link (protocol 3, same remote_control.hpp / emulink as the box):
  CONSOLE_FILTER, the filter in STATUS, launcher screenshots.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
- web/: the Emulator Console, plain HTML / CSS / ES modules (no build):
  dashboard (what runs, frame rate, memory, firmware, last crash, USB
  drive), the screen live with an on-screen / keyboard controller and save
  states, the library by console with boxart (play, filter the launcher,
  add / remove games), the SD card's files (download, upload, delete), the
  launcher's settings, the system (info, restart, firmware update through
  the updater and espp's OTA console, the other services in their espp
  apps) and the console log (Web Serial). link.js is the protocol, shared
  with tab5-emu like tools/emulink.
- The WebUSB landing page is now this console on the project's GitHub
  Pages (the old espp device_hub.html URL does not exist).
- Link protocol 4: SETTINGS (get / set the launcher's settings, as its
  controls do) and the console key and boxart path in LIST_ROMS;
  emulink settings [name=value].
- .github/workflows/pages.yml publishes web/ (Pages source: GitHub Actions).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
esp_tinyusb 3.0.1 (TinyUSB 0.21.0~6, the DWC2 SETUP-DMA erratum
workaround) corrupts the PSRAM heap on esp-box-emu while a Genesis game
runs (the link task's next allocation hits a tlsf assert or an MMU entry
fault); 3.0.0 is fine. The Tab5 shares the USB device code, and a fresh
build resolves '>=3.0.0' to 3.0.1, so pin it here too.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
The heap corruption seen with Sonic 2 on the box turned out to be
intermittent: the same builds that failed also pass repeated trials, so
the runs that blamed esp_tinyusb 3.0.1 were not evidence of a cause. The
corruption is tracked separately; no pin until it is understood.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
The heap corruption seen with Sonic 2 on the box turned out to be
intermittent: the same builds that failed also pass repeated trials, so
the runs that blamed esp_tinyusb 3.0.1 were not evidence of a cause. The
corruption is tracked separately; no pin until it is understood.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
Copilot AI balanced review requested due to automatic review settings November 13, 2026 16:20

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved concurrency and connection-lifecycle issues can lose library edits, block firmware-update and core-dump consoles, and leave emulator inputs held after disconnect.

5 open issues
What changed in this PR

Adds a browser-based Emulator Console for configuring and inspecting the emulator over USB, alongside the existing emulink tools.

Changes:

  • Adds dashboard, screen/controller, library, file management, settings, system, and serial-console views.
  • Extends control protocol 4 with settings access and richer game listings, including matching CLI support.
  • Points the firmware’s WebUSB landing page to the console and adds GitHub Pages deployment.
File Description
web/​README.md Documents console features, local hosting, and deployment.
web/​link.js Implements browser USB framing and device-control APIs.
web/​index.html Defines console tabs, controls, and dialogs.
web/​app.js Implements connection management and console interactions.
web/​app.css Styles the responsive console interface.
tools/​emulink/​emulink/​control.py Adds the settings protocol request.
tools/​emulink/​emulink/​cli.py Adds the emulink settings command.
README.md Introduces and links the web console.
main/​remote_control.hpp Adds protocol 4 settings and game-list metadata.
components/​tab5-emu/​src/​usb_device.cpp Updates the WebUSB landing-page URL.
components/​gui/​src/​gui.cpp Implements settings serialization, validation, and application.
components/​gui/​include/​gui.hpp Declares the GUI’s remote-settings interface.
.github/​workflows/​pages.yml Checks JavaScript syntax and deploys web/ to GitHub Pages.

Review effort: Balanced

Comment thread web/app.js Resolved
Comment thread web/app.js Resolved
Comment thread web/app.js Resolved
Comment thread web/app.js Resolved
Comment thread web/link.js Resolved
finger563 and others added 4 commits November 13, 2026 21:31
…ter query

A game started from the PC (emulink launch) with the console picker open
left it on screen after the game while the keypad drove the list behind
it: resume() closes it. CONSOLE_FILTER takes "?" as a query that changes
nothing, and emulink filter with no argument uses it instead of writing
the current filter back.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
…-device caches, serialized file edits

- Automatic reconnection only follows a lost link: a disconnect asked for
  here, a hand-off to another app and the OTA hand-off (whose updater
  comes up with the same serial) turn it off, and a scheduled reconnect
  checks again before it runs.
- The core-dump link hands the device off like the System tab's buttons.
- A button held while the page disconnects is released on the device
  first; the pad forgets it; a new connection releases stale input.
- Box art and the last capture are dropped with the link (reads in flight
  check their session); missing art is retried once the library reloads
  or the card comes back from the PC.
- File writes, deletes and the whole metadata.csv read-modify-write-reload
  run one at a time per Control.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment thread .github/workflows/pages.yml Resolved
Comment thread main/remote_control.hpp Resolved
Comment thread web/app.js Resolved
Comment thread web/app.js Resolved
Comment thread web/link.js Resolved
Comment thread web/link.js Resolved
finger563 and others added 3 commits November 13, 2026 21:58
…on indices; tolerant emulink filter output

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
…frame-count guards, ESM parse check

- SETTINGS values parse with std::from_chars into an int (no long -> int wrap).
- Control.remote() refuses '..' segments.
- Game frames shows 0 in a game, a dash only in the launcher.
- Save PNG reports a failed toBlob instead of downloading null.
- The Pages workflow checks web/*.js as ES modules.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY

Copilot AI left a comment

Copy link
Copy Markdown

Comment thread web/link.js Outdated
Comment on lines +374 to +377
async readFile(path, progress) {
const p = enc.encode(this.remote(path));
const st = await this.call(T.FILE_STAT, p);
return this.readChunks(st.size, (off, n) => this.call(T.FILE_READ, cat(u32le(off), u16le(n), p), { raw: true }), progress);

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in b655ce1: readFile() now runs whole inside the file queue (addRomNow() uses the unqueued readFileNow()), so a read cannot land between a file's chunks. On the device, buffered data lost when a read of the file (or the card handover) closes the writer is now remembered and reported by the next FILE_CLOSE, so an upload can no longer succeed after losing data.

Comment thread web/app.js
Comment on lines +45 to +53
function confirmModal(title, text, ok = "OK") {
return new Promise((resolve) => {
$("modalTitle").textContent = title; $("modalText").textContent = text; $("modalOk").textContent = ok;
$("modal").hidden = false; $("modalOk").focus();
const done = (v) => { $("modal").hidden = true; $("modalOk").onclick = $("modalCancel").onclick = null; resolve(v); };
$("modalOk").onclick = () => done(true);
$("modalCancel").onclick = () => done(false);
});
}

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in b655ce1: while the confirmation is open every other top-level element is inert, Tab/Shift+Tab cycle between its two buttons, Escape cancels, focus returns to the control that opened it, and a second confirmation answers a still-open one with 'no' instead of leaving it unresolved.

Comment thread web/link.js
Comment on lines +345 to +346
const head = await this.readChunks(last, (off, n) => this.call(T.SCREENSHOT_READ, cat(u32le(off), u16le(n)), { raw: true }), progress);
const tail = await this.call(T.SCREENSHOT_READ, cat(u32le(last), u16le(info.size - last)), { raw: true });

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in b655ce1: Control.onMain() serializes the whole capture (SCREENSHOT through the last SCREENSHOT_READ) with launch, quit, save, load, the drive switch and the ROM reload, so those wait for the capture to finish instead of stalling it.

finger563 and others added 6 commits November 13, 2026 22:15
…nd a capture; modal focus; report lost writes

- Whole file reads join the file queue (a read of a file being written
  closes its writer on the device).
- Launch, quit, save, load, the drive switch and the ROM reload wait for a
  screenshot in progress (it holds the main loop until its last chunk).
- The confirmation is modal for real: the page behind it is inert, Tab
  stays on its buttons, Escape cancels, focus returns afterwards, and a
  second question answers the first with no.
- Firmware: buffered data lost when a read or the card handover closed
  the file is reported by the next FILE_CLOSE.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
…is pending; a list reload closes the picker

As esp-box-emu (3f9a022, 2968e88), so the protocol and emulink match:
- CONSOLE_FILTER with an empty payload returns {filter, consoles}
  without touching the launcher ("all" clears the filter); emulink
  filter with no console sends that query.
- Setting it runs on the main loop under the GUI lock, like LAUNCH, and
  is refused while a launch the loop has taken has not started its cart.
- Re-reading metadata.csv closes an open console picker.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
web/app.js and web/link.js now match esp-box-emu feat/web-console
(734b32d: session counter, reconnect only when wanted, uploads and Add
Game bound to their board, stale settings writes dropped, timeouts
reject cleanly, keyboard on the pad buttons, ...), plus what it lacks:
- the main-loop queue (a capture is not stalled by save/load/quit/launch)
- no '..' in card paths
- Escape / Tab in the confirmation, and a second one answers the first
- stale input released on connect; the last capture's picture cleared on
  disconnect
- missing box art retried after a library reload or the card's return
- game frames shows 0 in a game; a failed toBlob is reported

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
Moves the Web Console section up after Emulators, explains the WebUSB
landing page and each tab, and adds screen / library / dashboard / settings /
system screenshots from the Tab5 (docs/images/web-console-*.jpg). The MAC
address is blanked in the system shot.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
…larifyCondition)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
Base automatically changed from feat/console-filter to main November 14, 2026 06:06
main's tree is feat/console-filter's tip (b994815), already merged here, so
this branch's tree is kept as is.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY
@github-actions

Copy link
Copy Markdown

ESP-IDF Size Report for 'Tab5 Emu'

Metric Base PR Delta
FLASH 0 bytes (0.00%) 0 bytes (0.00%) 0 bytes (0.00%)
DRAM 267,732 bytes (60.67%) 267,732 bytes (60.67%) 0 bytes (0.00%)
IRAM 0 bytes 0 bytes 0 bytes
RAM (DRAM+IRAM) 267,732 bytes 267,732 bytes 0 bytes (0.00%)

FLASH uses app .bin size or json2 flash sum. RAM sums DRAM+IRAM via idf_size. Percentages shown when totals are available.
DRAM/IRAM usage does not include memory used by the heap allocator at runtime.
This report was generated by esp-idf-size-delta.

@finger563
finger563 merged commit e66806f into main Nov 14, 2026
1 check passed
@finger563
finger563 deleted the feat/web-console branch November 14, 2026 06:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants