Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
12d6894
Launcher: console filter and quick console navigation
finger563 Nov 13, 2026
32a69b9
Web console: the WebUSB landing page, on GitHub Pages
finger563 Nov 13, 2026
13c5a11
web: history graphs fill their width from the first samples
finger563 Nov 13, 2026
400f7c5
Pin esp_tinyusb to 3.0.0
finger563 Nov 13, 2026
557ff5b
Merge branch 'feat/console-filter' into feat/web-console
finger563 Nov 13, 2026
6c34033
Revert "Pin esp_tinyusb to 3.0.0"
finger563 Nov 13, 2026
57799db
Revert "Pin esp_tinyusb to 3.0.0"
finger563 Nov 13, 2026
c6df4c2
Merge branch 'feat/console-filter' into feat/web-console
finger563 Nov 13, 2026
f891e64
Merge remote-tracking branch 'origin/main' into feat/console-filter
finger563 Nov 14, 2026
1c9dd3d
Merge branch 'feat/console-filter' into feat/web-console
finger563 Nov 14, 2026
7613e0d
Console filter: close the picker on return from a game; read-only fil…
finger563 Nov 14, 2026
4e80ee9
Web console: no reconnect after a hand-off, release held buttons, per…
finger563 Nov 14, 2026
d905d48
Merge branch 'feat/console-filter' into feat/web-console
finger563 Nov 14, 2026
1a10e0e
Console filter: select a remotely chosen game once; intptr_t for butt…
finger563 Nov 14, 2026
b3dc9db
Web console: strict settings numbers, no '..' in card paths, PNG and …
finger563 Nov 14, 2026
b655ce1
Web console: queue reads with file writes and main-loop commands behi…
finger563 Nov 14, 2026
61ebc30
Merge branch 'feat/console-filter' into feat/web-console
finger563 Nov 14, 2026
209cd4b
Console filter: an empty request only reports it; not while a launch …
finger563 Nov 14, 2026
4663b35
Web console: take esp-box-emu's web/ fixes, keep this branch's extras
finger563 Nov 14, 2026
b31209a
README: the web console, how it works and what it does, with screenshots
finger563 Nov 14, 2026
b994815
Console filter: split the assignment out of the condition (cppcheck c…
finger563 Nov 14, 2026
9be4b95
Merge branch 'feat/console-filter' into feat/web-console
finger563 Nov 14, 2026
256c3c1
Merge main (the squash of #19) into feat/web-console
finger563 Nov 14, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions .github/workflows/pages.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
name: Web console (GitHub Pages)

# The Emulator Console (web/): the page the firmware advertises as its WebUSB
# landing page (esp-cpp.github.io/<repo>/). Needs Settings -> Pages -> Source:
# GitHub Actions.
on:
push:
branches: [main]
paths:
- 'web/**'
- '.github/workflows/pages.yml'
workflow_dispatch:

permissions:
contents: read
pages: write
id-token: write

concurrency:
group: pages
cancel-in-progress: true

jobs:
deploy:
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- uses: actions/checkout@v4
- name: Check the scripts parse (as ES modules)
run: for f in web/*.js; do node --input-type=module --check < "$f" || exit 1; done
- uses: actions/configure-pages@v5
- uses: actions/upload-pages-artifact@v3
with:
path: web
- id: deployment
uses: actions/deploy-pages@v4
48 changes: 48 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,54 @@ https://github.com/user-attachments/assets/641a64b0-b3af-429b-8582-a38fc9a5cdad
<img src="docs/images/gba-title.jpg" width="32%"> <img src="docs/images/gba-town.jpg" width="32%">
</p>

## Web Console

Plug the Tab5 into a computer and it brings its own control panel. Chrome or
Edge pops up a notification for
**[esp-cpp.github.io/tab5-emu](https://esp-cpp.github.io/tab5-emu/)**, the
firmware's WebUSB landing page: click it, pick the Tab5, and the page talks
to the device straight from the browser. There's nothing to install and no
server in between.

<p>
<img src="docs/images/web-console-screen.jpg" alt="Web console Screen tab: a capture of Donkey Kong Country next to an on-screen controller and save-state buttons" width="49%"> <img src="docs/images/web-console-library.jpg" alt="Web console Library tab: Super Nintendo games with boxart, console filters and Play / Remove buttons" width="49%">
</p>

- **Dashboard**: what's running (with its boxart), live frame-rate and
memory graphs, the firmware and partition, the last reset reason, and a
button that hands the SD card to the PC as a USB drive.
- **Screen**: capture the game's or the launcher's screen (or keep it
**Live**), save it as a PNG, play with the on-screen controller or the
keyboard (arrows, Z / X / A / S, Q / W for L / R, Enter = Start), save and
load states, quit.
- **Library**: the games by console with their boxart and counts. Search,
filter (the launcher too, if you like), **Play** any of them, or **Add a
game**: choose the ROM and its cover and the page uploads both and adds the
`metadata.csv` line. **Remove** undoes it.
- **Files**: browse the SD card, download, upload by drag and drop, new
folder, delete.
- **Settings**: volume, mute, brightness, video scaling and resume last save,
shown in the launcher at once and saved to the card a moment later.
- **System**: chip, memory, ESP-IDF, OTA state and the services on the link;
restart (or into download mode), and **Update firmware**, which restarts
into the updater and opens the espp OTA console for `build/tab5-emu.bin`.
- **Console**: the log over Web Serial (pick the console's port), filtered,
followed, saved to a file.

<p>
<img src="docs/images/web-console-dashboard.jpg" alt="Web console Dashboard: Donkey Kong Country running, with performance, memory, device and SD card panels" width="32%"> <img src="docs/images/web-console-settings.jpg" alt="Web console Settings tab: volume, mute, brightness, video scaling and resume last save" width="32%"> <img src="docs/images/web-console-system.jpg" alt="Web console System tab: ESP32-P4 details, firmware update and restart" width="32%">
</p>

How it works: the composite USB device has a vendor (WebUSB) interface that
carries the same link as `tools/emulink`, and its descriptor names the
landing page, which is how the browser knows where to go. The page is plain
HTML, CSS and ES modules in [`web/`](./web) (shared with esp-box-emu, no build
step), published to GitHub Pages from `main`. One program owns the link at a
time, so close `emulink` before opening the page and the other way round. To
work on the page, `python3 -m http.server -d web 8000` and open
http://localhost:8000 (WebUSB needs https or localhost); [`web/README.md`](./web/README.md)
has the details.

## Hardware

| | |
Expand Down
9 changes: 9 additions & 0 deletions components/gui/include/gui.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -75,6 +75,15 @@ class Gui {
/// Show only `console`'s games (nullopt: every console's); false if it has none.
bool set_console_filter(std::optional<Console> console);

/// The settings the launcher shows, for the USB link: {settings: {name:
/// value}, limits: {name: [min, max]}} (volume, muted, brightness, video,
/// resume).
std::string settings_json() const;
/// Change one of them as its control in the launcher does (shown, applied,
/// saved once the changes stop); false for an unknown name or a value out
/// of range.
bool set_setting(const std::string &name, int value);

/// The launcher screen (RGB565, little endian, rows packed), for the USB
/// link's screenshot when no game runs; empty if it cannot be drawn.
struct Snapshot {
Expand Down
50 changes: 50 additions & 0 deletions components/gui/src/gui.cpp
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
#include "gui.hpp"

#include <cmath>

#include "lvgl_private.h"

#include <algorithm>
Expand Down Expand Up @@ -510,6 +512,54 @@ void Gui::picker_event(lv_event_t *e) {
}
}

namespace {
struct SettingLimit {
const char *name;
int min, max;
};
// (the same ranges as the launcher's own sliders)
constexpr SettingLimit kSettingLimits[] = {
{"volume", 0, 100}, {"muted", 0, 1}, {"brightness", 5, 100}, {"video", 0, 2}, {"resume", 0, 1}};
} // namespace

std::string Gui::settings_json() const {
auto &emu = Tab5Emu::get();
const auto s = AppSettings::get().get_settings();
std::string limits;
for (const auto &l : kSettingLimits) {
limits += fmt::format("{}\"{}\":[{},{}]", limits.empty() ? "" : ",", l.name, l.min, l.max);
}
return fmt::format("{{\"settings\":{{\"volume\":{},\"muted\":{},\"brightness\":{},\"video\":{},\"resume\":{}}},"
"\"limits\":{{{}}}}}",
(int)std::lround(emu.volume()), emu.is_muted() ? 1 : 0, (int)std::lround(emu.brightness()),
(int)emu.video_setting(),
s.resume_last_save ? 1 : 0, limits);
}

bool Gui::set_setting(const std::string &name, int value) {
const auto *limit = std::find_if(std::begin(kSettingLimits), std::end(kSettingLimits),
[&](const SettingLimit &l) { return name == l.name; });
if (limit == std::end(kSettingLimits) || value < limit->min || value > limit->max) {
return false;
}
std::lock_guard<std::recursive_mutex> lk(mutex_);
auto &emu = Tab5Emu::get();
// (saved to the SD card by the main loop once the changes stop, as from the launcher)
AppSettings::get().modify([&](Settings &s) {
if (name == "volume") s.volume = value;
else if (name == "muted") s.muted = value != 0;
else if (name == "brightness") s.brightness = value;
else if (name == "video") s.video_setting = value;
else if (name == "resume") s.resume_last_save = value != 0;
});
if (name == "volume") emu.volume(value);
else if (name == "muted") emu.mute(value != 0);
else if (name == "brightness") emu.brightness(value);
else if (name == "video") emu.video_setting(static_cast<VideoSetting>(value));
update_shared_state(); // the launcher's controls show it
return true;
}

Gui::Snapshot Gui::snapshot() {
std::lock_guard<std::recursive_mutex> lk(mutex_);
Snapshot shot;
Expand Down
2 changes: 1 addition & 1 deletion components/tab5-emu/src/usb_device.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ bool Tab5Emu::initialize_usb_device() {
espp::UsbDevice::VendorFunction vendor;
vendor.interface_name = "Tab5 Emu link";
vendor.webusb = true;
vendor.landing_page_url = "esp-cpp.github.io/espp/apps/device_hub.html";
vendor.landing_page_url = "esp-cpp.github.io/tab5-emu/";
vendor.on_receive = [this](std::span<const uint8_t> data) {
if (vendor_rx_) vendor_rx_(data);
};
Expand Down
Binary file added docs/images/web-console-dashboard.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/web-console-library.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/web-console-screen.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/web-console-settings.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/web-console-system.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
54 changes: 46 additions & 8 deletions main/remote_control.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@

#include <algorithm>
#include <cctype>
#include <charconv>
#include <cerrno>
#include <condition_variable>
#include <cstring>
Expand Down Expand Up @@ -111,11 +112,12 @@ class RemoteControl {
public:
static constexpr uint8_t kModule = 0x20;
static constexpr const char *kProtocol = "emu.control";
static constexpr uint16_t kProtocolVersion = 3; // 2: in-memory screenshots, 3: console filter, launcher screenshots
// 2: in-memory screenshots, 3: console filter, launcher screenshots, 4: settings, boxart / console keys in the list
static constexpr uint16_t kProtocolVersion = 4;

enum class Type : uint8_t {
STATUS = 0x01, ///< () -> {state, rom, platform, console, heap, uptime, ...}
LIST_ROMS = 0x02, ///< (offset: text) -> {total, roms: [{name, path, platform, console}]}
LIST_ROMS = 0x02, ///< (offset: text) -> {total, roms: [{name, path, platform, console, key, boxart}]}
LAUNCH = 0x03, ///< (rom path or part of a name / path) -> {rom}
QUIT = 0x04, ///< ()
BUTTONS = 0x05, ///< (u16 buttons, u16 hold ms; 0 = until the next BUTTONS)
Expand All @@ -136,6 +138,10 @@ class RemoteControl {
/// consoles: [keys]}: the launcher's list shows only that console's games.
/// An empty payload only reports them (nothing changes on the device).
CONSOLE_FILTER = 0x0D,
/// (empty, or "name=value" to change one) -> {settings: {name: value},
/// limits: {name: [min, max]}}: the launcher's settings (volume,
/// brightness, ...), applied and saved like the launcher's own controls
SETTINGS = 0x0E,
FILE_LIST = 0x10, ///< (path[\0offset]) -> {entries: [{name, dir, size}], truncated?, next?}
FILE_READ = 0x11, ///< (u32 offset, u16 length, path) -> raw bytes (short at the end)
FILE_WRITE = 0x12, ///< (u32 offset, path_len u16, path, data); offset 0 truncates
Expand Down Expand Up @@ -234,9 +240,11 @@ class RemoteControl {
size_t i = offset;
for (; i < roms.size(); i++) {
const auto &r = roms[i];
auto e = fmt::format("{}{{\"name\":{},\"path\":{},\"platform\":\"{}\",\"console\":{}}}",
i > offset ? "," : "", quote(r.name), quote(r.rom_path), r.platform,
quote(console_info(console_of(r.platform)).name));
const auto &console = console_info(console_of(r.platform));
auto e = fmt::format(
"{}{{\"name\":{},\"path\":{},\"platform\":\"{}\",\"console\":{},\"key\":{},\"boxart\":{}}}",
i > offset ? "," : "", quote(r.name), quote(r.rom_path), r.platform, quote(console.name),
quote(console.key), quote(r.boxart_path));
// (room for the trailer, `],"next":N}`, and reply()'s status byte)
if (j.size() + e.size() + 24 > espp::stream_frame::kMaxPayloadSize) break; // the host asks for the rest
j += e;
Expand Down Expand Up @@ -498,6 +506,29 @@ class RemoteControl {
else json(filter_json());
break;
}
case Type::SETTINGS: {
if (!text.empty()) {
const auto eq = text.find('=');
if (eq == std::string_view::npos) {
fail("payload: name=value");
break;
}
const std::string name(text.substr(0, eq));
const std::string value(text.substr(eq + 1));
int v = 0;
const auto [end, ec] = std::from_chars(value.data(), value.data() + value.size(), v);
if (value.empty() || ec != std::errc() || end != value.data() + value.size()) {
fail(fmt::format("{}: '{}' is not a number", name, value));
break;
}
if (!gui_.set_setting(name, v)) {
fail(fmt::format("unknown setting '{}' (or {} is out of range)", name, v));
break;
}
}
json(gui_.settings_json());
break;
}
case Type::FILE_LIST: {
// path, optionally followed by '\0' and the index to start at (the "next" of a truncated
// reply)
Expand Down Expand Up @@ -592,10 +623,14 @@ class RemoteControl {
write_pos_ = offset + n;
break;
}
case Type::FILE_CLOSE:
// (a buffered write that fails shows up here)
if (!close_file()) fail("closing the file failed (card full?)");
case Type::FILE_CLOSE: {
// (a buffered write that fails shows up here, also one closed earlier
// by a read of the file or the card handover)
const bool closed = close_file();
if (!closed || write_lost_) fail("closing the file failed (card full?)");
write_lost_ = false;
break;
}
case Type::FILE_DELETE: {
const std::string path(text);
close_file(path);
Expand Down Expand Up @@ -816,6 +851,7 @@ class RemoteControl {
}
if (!close_file()) return false; // (the previous file's last data did not land)
if (offset == 0) {
write_lost_ = false; // (a new file: an older one's failure is not its)
std::error_code ec;
std::filesystem::create_directories(std::filesystem::path(path).parent_path(), ec);
write_file_ = fopen(path.c_str(), "wb");
Expand All @@ -838,6 +874,7 @@ class RemoteControl {
const bool ok = fclose(write_file_) == 0;
write_file_ = nullptr;
write_path_.clear();
if (!ok) write_lost_ = true; // (told by the next FILE_CLOSE)
return ok;
}
return true;
Expand Down Expand Up @@ -875,4 +912,5 @@ class RemoteControl {
FILE *write_file_{nullptr};
std::string write_path_;
uint32_t write_pos_{0};
bool write_lost_{false}; ///< an implicit close_file() lost buffered data
};
15 changes: 15 additions & 0 deletions tools/emulink/emulink/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,18 @@ def cmd_filter(args) -> int:
return 0


def cmd_settings(args) -> int:
with _open(args) as link:
c = Control(link)
r = None
for change in args.change or [None]:
r = c.settings(change)
for name, value in r["settings"].items():
lo, hi = r["limits"].get(name, ("", ""))
print(f"{name:<11} {value:>4} ({lo}..{hi})")
return 0


def cmd_ls(args) -> int:
with _open(args) as link:
for e in Control(link).ls(args.path):
Expand Down Expand Up @@ -497,6 +509,9 @@ def build_parser() -> argparse.ArgumentParser:
s.add_argument("--delete", action="store_true", help="also delete the file")
s.set_defaults(fn=cmd_remove_rom)
sub.add_parser("reload", help="re-read metadata.csv").set_defaults(fn=cmd_reload)
s = sub.add_parser("settings", help="the launcher's settings; name=value changes one (volume=40, muted=1, ...)")
s.add_argument("change", nargs="*", help="name=value")
s.set_defaults(fn=cmd_settings)
s = sub.add_parser("filter", help="show only one console's games in the launcher (a key such as snes, or all)")
s.add_argument("console", nargs="?", help="console key, or all (default: show the current filter)")
s.set_defaults(fn=cmd_filter)
Expand Down
6 changes: 6 additions & 0 deletions tools/emulink/emulink/control.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@
STATUS, LIST_ROMS, LAUNCH, QUIT, BUTTONS, SAVE, LOAD, SCREENSHOT, USB_DRIVE, RELOAD_ROMS, ENTER_UPDATER = range(1, 12)
SCREENSHOT_READ = 0x0C
CONSOLE_FILTER = 0x0D
SETTINGS = 0x0E
FILE_LIST, FILE_READ, FILE_WRITE, FILE_DELETE, MKDIR, FILE_STAT, FILE_CLOSE = range(0x10, 0x17)

#: one FILE_WRITE: the frame payload is at most 4096 bytes, of which 6 + the path are the header
Expand Down Expand Up @@ -209,6 +210,11 @@ def console_filter(self, console: str | None = None) -> dict:
return self._call(CONSOLE_FILTER, b"")
return self._call(CONSOLE_FILTER, (console or "all").encode())

def settings(self, change: str | None = None) -> dict:
"""The launcher's settings ({settings, limits}); `change` ("name=value")
sets one first (protocol 4)."""
return self._call(SETTINGS, (change or "").encode())

def reload_roms(self) -> int:
return self._call(RELOAD_ROMS)["total"]

Expand Down
33 changes: 33 additions & 0 deletions web/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Emulator Console (web)

The page esp-box-emu and tab5-emu advertise as their WebUSB landing page
(`esp-cpp.github.io/esp-box-emu/`, `esp-cpp.github.io/tab5-emu/`): Chrome or
Edge offers it when the emulator is plugged in. It talks to the device's link
(the vendor interface, the same protocol as `tools/emulink`) and its console
(the CDC port, with Web Serial).

- **Dashboard**: what runs, frame rate, memory, firmware, uptime, last crash,
and the SD card's USB drive mode.
- **Screen**: the game's (or the launcher's) screen, live, with an on-screen
controller (or the keyboard), save states and quit.
- **Library**: the games by console with their boxart; play, filter (the
launcher too), add a game (ROM + boxart + metadata.csv), remove one.
- **Files**: browse the SD card, download, upload (drag and drop), new
folder, delete.
- **Settings**: volume, mute, brightness, video scaling, resume last save
(haptics on the box), as in the launcher.
- **System**: chip, partitions, reset reason, the services on the link,
restart (or into download mode), and the firmware update (the updater with
the espp OTA console). The generic services open in their espp web apps.
- **Console**: the console log, filtered, saved.

Plain HTML / CSS / ES modules, no build step. `link.js` is the protocol
(stream_frame frames, emu.control, the espp system service), `app.js` the
page. The files are the same in both repositories (like `tools/emulink`).

Try it locally: `python3 -m http.server -d web 8000`, then open
http://localhost:8000 (WebUSB needs https or localhost). Only one program can
use the link at a time: close `emulink` first.

The pages workflow (`.github/workflows/pages.yml`) publishes this folder
on a push to main.
Loading
Loading