Developer CLI (pbemu) #

pbemu is the single host-side entry point for staging firmware, building emulator components, running the emulator, linting, and running the integration tests. It is a thin wrapper around python -m pbemu (see pbemu/cli.py) and runs out of the project virtualenv created by setup-venv.sh.

The CLI itself does not run inside the container; it dispatches container work via podman (or docker if PODMAN=docker).

Subcommands #

Command	Purpose
pbemu install <firmware.zip>	Stage a PocketBook firmware update into a Model_Version/ directory. Extracts the firmware archive, derives hwconfig, and seeds the baseline mnt/ tree.
pbemu image	Build the pbdev container image from Dockerfile.
pbemu build [firmware] [--clean]	Configure + compile shim, informer, viewer, and probes inside the container. Auto-cleans when switching firmwares.
pbemu start [firmware] [--reset] [--no-viewer] [--no-audio] [--no-build] [--clean]	Create <firmware>/.live/, run the container, launch monitor.app, informer, and viewer. Auto-builds first when artifacts are missing.
pbemu stop	Stop and remove the running emulator container. Leaves <firmware>/.live/ intact.
`pbemu lint [--strict] [--c-only	--python-only]`
pbemu test [firmware] [--no-build] [--clean] [-- pytest args...]	Auto-build, start the emulator headless, run the pytest integration suite, then stop the emulator.

If exactly one staged firmware exists, every subcommand that takes [firmware] can be invoked without it.

Layout #

Path	Purpose
pbemu/cli.py	Argparse wiring for every subcommand.
pbemu/install.py	Firmware staging (zip extraction, hwconfig synthesis, mnt/ baseline).
pbemu/build.py + pbemu/build_inner.sh	Container-side build orchestration. build_inner.sh runs inside pbdev and drives CMake for shim, informer, arm_probe (ARM), and viewer + host probes (PC).
pbemu/run/	start / stop implementation: container lifecycle, .live/ staging, monitor + informer + viewer launch, readiness probes, device-config materialisation.
pbemu/lint.py	clang-tidy (in-container, per build dir) + pylint (host venv) drivers.
pbemu/test.py	Headless emulator boot + pytest driver used by pbemu test.
pbemu/firmware.py	Staged-firmware discovery / single-firmware auto-detect.
pbemu/paths.py	Repo paths, image / container / podman name resolution from environment.

Environment overrides #

Variable	Default	Purpose
PODMAN	podman	Container CLI. Set to docker to use Docker instead.
PB_IMAGE	pbdev	Container image tag built by pbemu image.
PB_CONTAINER	pbemu	Name of the long-running emulator container started by pbemu start.
PYTHON	python3	Fallback interpreter when .venv/ is absent.

Setup #

./setup-venv.sh   # one-time: creates .venv/ with pytest + pylint + editable pbemu
./pbemu image     # build the pbdev container image
./pbemu install <firmware.zip>
./pbemu build
./pbemu start