Add a cross-platform SDL emulator for developing the goggle UI without hardware

[christhomas]

Adds a desktop build of the goggle UI (Linux, macOS, Windows) that runs the real
application code — the same main(), menu system, OSD and page logic that ships on the
goggle — rendered through SDL2 instead of the framebuffer, with the hardware peripherals
replaced by compiled-in mocks.

The aim is to make the LVGL interface developable and previewable without hardware, and
to give CI a way to catch UI/driver regressions on every push.

Build and run

.devcontainer/build.sh images     # build the devcontainer images (one-time)
.devcontainer/build.sh linux      # -> build_emu_linux/HDZGOGGLE
.devcontainer/build.sh windows    # -> build_win_x64/HDZGOGGLE.exe   (mingw cross)
.devcontainer/build.sh mac        # -> build_xmac/HDZGOGGLE
./run-native.sh                   # launch it in a window

Every target compiles inside a devcontainer image, so builds are reproducible and need
no host toolchain; the resulting binary runs natively on its OS. macOS is the one exception
and builds on a mac, since a cross image would need Apple's non-redistributable SDK.

Zero cost to the firmware

All emulator code sits behind EMULATOR_BUILD or in src/emulator/*, which CMake compiles
only for the emulator — the goggle firmware binary contains none of it. Hardware drivers
that genuinely differ (UART, I2C, RTC, the framebuffer) are split into per-target files
selected by CMake, so the goggle drivers carry no emulator #ifdefs.

Verified by building the firmware from this branch: it compiles unchanged, with zero
emulator objects linked in.

What's mocked (at the hardware seam, so the app itself is untouched)

Hardware	Emulator stand-in
Display engine / framebuffer	SDL2 window + software compositor
DM5680 video receiver	decodes a looping MPEG-1 clip (vendored pl_mpeg; no ffmpeg is linked) behind the OSD, and only in the video view
DM5680 serial link	socketpair-backed UART + a mock answering version/valid/RSSI
I2C bus, RTC	no-op bus, in-memory clock
Device shell commands (system_exec)	logged and skipped — never touches the host

Also included: configurable filesystem roots (path_app()/path_extsd() from a config file

• env, compiled away on the goggle so the on-device /mnt/app and /mnt/extsd defaults are
  unchanged), and POSIX compat shims for macOS/Windows hosts.

CI

.github/workflows/build_emulator.yml builds all three targets on every push/PR with a
headless screenshot as a regression check, and publishes per-platform binaries on a semver
tag. The existing firmware workflows are untouched (and pass on this branch).

Notes

• Stacked on Fix build on newer toolchains where ATOMIC_VAR_INIT was removed #616 (the ATOMIC_VAR_INIT fix), which the emulator build requires and which
  this branch therefore includes. Once Fix build on newer toolchains where ATOMIC_VAR_INIT was removed #616 merges, this rebases down to a single commit.
• Docs: docs/emulator.md.
• Draft for now — happy to split, reshape or drop pieces if you'd prefer a different shape.

[nerdCopter]

AI Generated comment

Problem: build.sh linux (and windows/mac) calls docker run against hdzero-dev:latest without checking whether the image has been built first. If it hasn't, Docker tries to pull hdzero-dev from a registry and fails with pull access denied, which reads as a login/registry issue rather than a missing local build step.

Proposed solution: Have linux/windows/mac check for the image (e.g. docker image inspect) and run images automatically if missing, or at minimum fail with a clear message pointing to build.sh images. Also worth a one-line note in the README or .devcontainer about running build.sh images before the first per-target build, since this CLI flow isn't covered by the existing VS Code devcontainer docs.

[nerdCopter]

AI Generated comment

Not authoritative — flagging for consideration, deferring to the author's judgment on implementation.

Problem: .devcontainer/Dockerfile builds FROM mcr.microsoft.com/devcontainers/base:ubuntu unpinned, which currently resolves to Ubuntu 26.04 LTS (glibc 2.43). Because glibc symbol versioning is forward-only, a binary built against 2.43 cannot run on any host with an older glibc — e.g. Ubuntu 24.04 (2.39), Ubuntu 22.04 (2.35), or Debian 13 (2.41) all fail with version 'GLIBC_2.43' not found when running run-native.sh after build.sh linux. This breaks the design stated in build.sh's own header: "compiled INSIDE a devcontainer image; each RUNS natively on its OS."

Some floor has to be fixed regardless of implementation — whether via an older base image, a fully static build, or explicit glibc-ABI targeting in the toolchain, all three amount to picking a minimum glibc version the output supports. Tracking whatever LTS is newest leaves that floor undefined and drifting upward every two years.

Proposed solution: Pin the build environment to a deliberately conservative glibc floor. Simplest: change FROM to a specific older LTS (ubuntu:24.04 or ubuntu:22.04). If staying on the newest base image/toolchain is preferred, the same floor can be achieved via static linking or -target-style glibc-version pinning in the compiler/linker instead.

[christhomas]

Thanks @nerdCopter — both are good catches; fixed in 58ae81d.

1 — missing-image build step. Added an ensure_image helper that each per-target
function calls first: if the image isn't present locally (docker image inspect), it
builds it from its Dockerfile before running, so a fresh checkout's first
build.sh linux|windows|mac just works instead of Docker attempting a registry pull and
failing with the confusing pull access denied. Verified — with the image removed,
build.sh linux now prints image 'hdzero-dev' not found locally -- building it from Dockerfile and proceeds. (emulator.md already notes build.sh images for the batch case.)

2 — glibc floor. Pinned .devcontainer/Dockerfile to
mcr.microsoft.com/devcontainers/base:ubuntu-22.04 (glibc 2.35) so the Linux binary no
longer tracks the newest LTS. Verified the built binary's required floor dropped from
GLIBC_2.43 to GLIBC_2.34 (objdump -T … | grep -oE 'GLIBC_[0-9.]+' | sort -V | tail -1),
so it runs on Ubuntu 22.04+, Debian 12+, etc. Windows/macOS outputs are PE/Mach-O and
don't depend on the container's glibc, so they're unaffected.

Both land in the single emulator commit.

[nerdCopter]

• works on Xubuntu 24.04.x.
• Debian 13 is still ./HDZGOGGLE: /lib/x86_64-linux-gnu/libm.so.6: version 'GLIBC_2.43' not found (required by ./HDZGOGGLE) -- presume acceptable.
• wondering if mouse-selections possible (not important).
• congrats! 💪

[christhomas]

@nerdCopter thanks for the follow-up testing — the Xubuntu-works / Debian-13-fails split was the key clue.

Root cause. Your ./HDZGOGGLE on Debian 13 was still linking GLIBC_2.43 even though .devcontainer/Dockerfile is pinned to glibc 2.35. The reason wasn't the pin — it was a stale cached image. My first pass at the build.sh image handling only (re)built the devcontainer image if it was missing. Your machine already had an hdzero-dev image from before the pin (built on the old unpinned base = glibc 2.43), so build.sh reused that stale image and your binary kept the 2.43 floor. On Xubuntu the image was built fresh (after the pin), so it linked 2.34 and ran.

Fix (latest push to feat/sdl-emulator): ensure_image now always runs docker build — near-instant on a cache hit, but it rebuilds whenever the Dockerfile or its base image changes. A stale image can no longer survive a base change.

To pick it up on Debian 13:

git pull                              # latest feat/sdl-emulator
bash .devcontainer/build.sh linux
objdump -T build_emu_linux/HDZGOGGLE | grep -oE 'GLIBC_[0-9.]+' | sort -V | tail -1
# expect: GLIBC_2.34  (runs on Debian 13's 2.41 and anything newer)

(If you want to be certain the old image is gone: docker rmi hdzero-dev first — though the rebuild now handles it.)

Fixing this partly blind. I don't have your exact Debian 13 box here, so I've been reproducing against the same pinned 22.04 base rather than your setup. I'm fairly confident the latest matches, but I'd really appreciate a re-test to confirm the floor drops to 2.34 for you.

Why this isn't going to be whack-a-mole. glibc is forward-compatible: a binary built against 2.34 runs on 2.34 and every newer glibc (2.41, 2.45, …). We only ever have to pick the oldest glibc we want to support (2.35 here, via the 22.04 base) and build once — newer hosts are automatically covered. The bug was simply that the build environment's glibc had drifted too new (2.43).

Won't silently regress again. Added a CI step that reads the built binary's max GLIBC_ symbol and fails the build if it exceeds the 2.35 floor — so if the base image ever drifts upward, CI catches it instead of a user.

Downloadable binaries. For anyone not building locally, I've also re-cut the release as v0.1.1 from the fixed commit (the old v0.1.0 assets were built pre-pin — also 2.43), verified at GLIBC_2.34. Building locally as above is the direct path on your box, though.

Mouse selection. Feasible — SDL can drive an LVGL pointer input device — but the goggle UI is built around the 5-way button + scroll-wheel model (focus-based navigation, not click targets), so it's a real feature rather than a flag flip. Noted as a nice-to-have follow-up; agree it's not important to the emulator's core purpose.

Thanks again for the thorough testing 🙏

[nerdCopter]

• ffac78c works on Debian 🚀
• only remaining thing is that other than up/down keys,unsure how to navigate settings. tab, enter, left/right, do nothing.

[christhomas]

I think I understand what you want with mouse selections, but doesn't that kind of make the emulator diverge from the way the user interface is supposed to be used. It would add probably different user interface access patterns and perhaps not be really that useful. Can you give me a persuasive argument for it?

[nerdCopter]

i dont need mouse. my last comment just called out that i cannot actually focus into the settings panes nor change any settings. maybe such is local-environment issue -- i do not know.

[christhomas]

ohhhhh, I think the latest update might fix that, I use the WSAD or the arrow keys, and I tried it out and played around with it and it seems to work quite nicely. Maybe it was something that was fixed. Try it out and let me know.

[nerdCopter]

oaky... WSAD technically works, but i get locked into a "video feed" screen rather quickly and cannot exit to test other panels.. i'll give you some time to work things out. good work! may simply need to list keys in PR description or potentially a HUD overlay 🤷‍♂️ .

[christhomas]

Isn't it the same as your goggles

W = up = rotate left
S = down = rotate right
D = wheel button, long press takes you into the fpv view, like when you're using the real goggles

the only thing I don't like, which I didn't put much effort into thinking baout right now, is that I'm using WSAD and arrow keys

WSD makes sense, but A doesn't, cause A represents the button on the right of the goggler

UP, DOWN, RIGHT makes sense, but LEFT doesn't because of the same reason

So I think I'm going to change it to WSD and L

Then I think it maps better to how I visually think of how the buttons relate to each other

and to enter the FPV view, you long push D, just like you would the jog wheel button and long press it to get out and back to the menu. Does that make more sense to you too? I'll make the change, then you can tell me whether you agree or not after you use it a bit

[nerdCopter]

awesome, now i know what the W S D do and am able to navigate fine.