Repository navigation
Web console: the WebUSB landing page (configure and inspect the emulator) - #20
Conversation
- 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
There was a problem hiding this comment.
🟡 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
Release held inputs before disconnect and clear stale input · New Prevent reconnects during firmware-update hand-off · New Hand off USB before opening the core-dump console · New Invalidate boxart cache across connections and transient read failures · New Serialize library edits and related file operations · New
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
…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
There was a problem hiding this comment.
Warning
Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.
Copilot review overview
10 open issues
node --checkwill treatweb/*.jsas CommonJS by default, so parsing will fail on `import ...… · New Parsing viastrtoland thenstatic_cast<int>(v)can allow overflow/wrap to produce an in-range… · New Ifst.game_framesis0, this will incorrectly display—. Use a null/undefined check (e.g.… · NewHTMLCanvasElement.toBlobcan passnull(and may fail under memory pressure). Guard against… · Newremote()does not prevent path traversal (e.g.../) and will happily generate/sdcard/../...… · New The chunk size calculation is inconsistent with the stated 4096-byte max payload (MAX_PAYLOAD)… · New Serialize library edits and related file operations Invalidate boxart cache across connections and transient read failures Prevent reconnects during firmware-update hand-off Release held inputs before disconnect and clear stale input
1 resolved since last review
Review effort: Lite
…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
There was a problem hiding this comment.
🟡 Changes recommended
Concurrent file downloads can interrupt uploads and cause silent data loss, with additional unresolved capture-serialization and modal-focus issues.
3 open issues
10 resolved since last review
node --checkwill treatweb/*.jsas CommonJS by default, so parsing will fail on `import ...… The chunk size calculation is inconsistent with the stated 4096-byte max payload (MAX_PAYLOAD)…remote()does not prevent path traversal (e.g.../) and will happily generate/sdcard/../...…HTMLCanvasElement.toBlobcan passnull(and may fail under memory pressure). Guard against… Ifst.game_framesis0, this will incorrectly display—. Use a null/undefined check (e.g.… Parsing viastrtoland thenstatic_cast<int>(v)can allow overflow/wrap to produce an in-range… Serialize library edits and related file operations Invalidate boxart cache across connections and transient read failures Prevent reconnects during firmware-update hand-off Release held inputs before disconnect and clear stale input
Review effort: Balanced
| 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); |
There was a problem hiding this comment.
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.
| 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); | ||
| }); | ||
| } |
There was a problem hiding this comment.
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.
| 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 }); |
There was a problem hiding this comment.
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.
…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
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
ESP-IDF Size Report for 'Tab5 Emu'
FLASH uses app .bin size or json2 flash sum. RAM sums DRAM+IRAM via idf_size. Percentages shown when totals are available. |


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 inweb/: plain HTML, CSS and ES modules with no build step.Tabs:
metadata.csvline) or remove one.registry.jsby protocol and hands the device over.Firmware changes:
SETTINGSrequest to read the launcher's settings or change one (name=value), with each setting's limits.LIST_ROMSnow includes each game's console key and boxart path. There's a matchingemulink settings [name=value].esp-cpp.github.io/tab5-emu/instead ofesp-cpp.github.io/espp/apps/device_hub.html, which doesn't exist; the hub isdispatcher_hub.html, and this page links to it..github/workflows/pages.ymlpublishesweb/on a push to main. It needs Settings → Pages → Source: GitHub Actions enabled once.link.js(framing, emu.control and the system service) andapp.jsare the same files in esp-box-emu and tab5-emu, liketools/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: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)
🤖 Generated with Claude Code
https://claude.ai/code/session_01SFCMzomCZ5wRHJN4sxwkvY