User-mode emulation for PocketBook 6.1-6.11 firmware on Linux desktop (podman + Wayland)

README.md

pbemu #

pbemu runs PocketBook firmware on a Linux PC. It stages an official firmware update, builds the required support binaries, and runs the firmware in a container. The user interface is shown in a Wayland window.

How the emulation works #

Everything runs inside one container.

ARM guest processes run under qemu-arm.
- This includes monitor.app, the firmware applications, and informer.
libshim.so is injected into guest processes with LD_PRELOAD.
- It emulates the hardware-facing interfaces the firmware expects, including the framebuffer, RTC, selected /sys and /dev nodes, and input-related IPC.
- Screen updates are exposed through shared memory instead of a real e-ink device.
informer is an ARM helper process.
- It uses firmware APIs to publish the active task, framebuffer metadata, and touch transform needed by the viewer.
viewer is a native x86-64 Wayland client started inside the same container.
- It reads the framebuffer from shared memory and draws it into a Wayland window.
- It converts mouse input back into the firmware's touch event channel.
The host provides the container runtime and forwards desktop sockets into the container.
- Wayland is required for the viewer.
- A PipeWire/PulseAudio-compatible socket is used when audio relay is enabled.

Getting started #

What you need #

Podman or Docker. If you use Docker, run the scripts as PODMAN=docker ./....
A Wayland desktop session.
A PocketBook firmware zip, usually named sw_YYYYMMDD_DEVICE_VERSION_user.zip.

The firmware can be downloaded from PocketBook support webpage: https://pocketbook.ch/en-ch/support.

Step 1 — Build the base image #

./pbemu image

Step 2 — Stage the firmware #

Run the following command with sw_YYYYMMDD_DEVICE_VERSION_user.zip replaced by the path to the downloaded firmware:

./pbemu install sw_YYYYMMDD_DEVICE_VERSION_user.zip

This creates a staged firmware directory named after the device and version, for example U743g_6.10.2767. The staged tree contains the extracted firmware files, a generated hwconfig, and a baseline mnt/ tree used when the runtime state is created.

Step 3 — Build the final image #

./pbemu build DEVICE_VERSION

All build dependencies are inside the container. ./pbemu build builds the container image if needed, then compiles:

libshim.so
informer
viewer
arm_probe (single ARM ELF exposing send-event, wait-ready, task-info, task-list, task-foreground, mq-attr, audio-status, launch subcommands)
frame_dump and send_event (host-side probes used by the test suite)

If exactly one staged firmware is present, the firmware name can be omitted. ./pbemu start and ./pbemu test invoke build automatically when build artifacts are missing; pass --no-build to suppress this, or --clean to wipe the build directories first.

Step 4 — Run #

./pbemu start DEVICE_VERSION

This creates DEVICE_VERSION/.live/ if it does not already exist, starts the container, prepares the runtime tree, launches monitor.app, starts informer, and starts viewer.

DEVICE_VERSION/.live/ is the runtime state directory. It contains the writable /mnt copy, runtime staging directories, temporary files, and logs under .live/var/log/.

To stop:

./pbemu stop

Stopping the container does not remove .live/.

Starting fresh. To discard accumulated state and recreate the writable /mnt tree from the staged firmware and repository overlay:

./pbemu start --reset DEVICE_VERSION

Developer tooling #

./setup-venv.sh — create .venv/ and install pytest + pylint + the pbemu package itself (editable).
./pbemu image — (re)build the pbdev container image.
./pbemu lint [--strict] [--c-only|--python-only] — run clang-tidy across all build directories and default pylint over Python sources.
./pbemu test [DEVICE_VERSION] [-- pytest args...] — run the host-side pytest integration suite through pbemu; pass the firmware explicitly when multiple firmwares are staged.