# Working With Qemu

> Use when building, launching, debugging, or capturing screenshots of PebbleOS under QEMU.

- Skill: `tomevault-io/working-with-qemu` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/working-with-qemu`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/working-with-qemu/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/working-with-qemu

---


# Working with QEMU

PebbleOS can run under a custom QEMU version shipped with the PebbleOS SDK.

## Configure & build

```sh
./pbl configure --board $BOARD
./pbl build
```

where `$BOARD` is any of the `qemu_*` boards:

- `qemu_emery`
- `qemu_flint`
- `qemu_gabbro`

QEMU boards target a specific platform, e.g. `qemu_emery` targets the Emery platform, which is the platform used by Pebble Time 2.

## Launch

```sh
./pbl qemu
```

The launched QEMU exposes:

- Interactive QEMU monitor on the launching terminal (`-monitor stdio`)
- Programmatic socket monitor (`-monitor unix:build/qemu-mon.sock`)
- Serial console over TCP on `localhost:12345` (console) and `localhost:12344` (pebble-tool)

UART1 output is also captured to `build/uart1.log`.

## Console

```sh
./pbl console
```

Requires QEMU to be running.
Uses the TCP serial port to connect to the QEMU console, and provides a prompt for sending commands and receiving responses.

## Screenshot

```sh
./pbl screenshot # defaults to build/screenshot.png
./pbl screenshot --screenshot-output /tmp/foo.png
```

Requires QEMU to be running.
Uses the programmatic socket monitor to capture a screenshot of the QEMU display and save it to disk.
Useful to validate or iterate on UI changes.

## Interaction

Keyboard input is captured by QEMU, so you can interact with the PebbleOS UI.
Keys can also be send programmatically over the socket monitor using the `sendkey` command.
They key mapping is:

| QEMU key | PebbleOS key |
| -------- | ------------ |
| `left`   | `back`       |
| `right`  | `select`     |
| `up`     | `up`         |
| `down`   | `down`       |

---
> Source: [coredevices/PebbleOS](https://github.com/coredevices/PebbleOS) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-07-03 -->