pimoroni-emu

Desktop emulator for Pimoroni devices. Run MicroPython and Raspberry Pi apps on your desktop with simulated displays, buttons, and touch input.

Note: This is an unofficial community project and is not affiliated with or endorsed by Pimoroni.

Screenshots

Badges & displays

Tufty 2350	Badger 2350

Badgeware (LED matrix)

Blinky 2350

Inky

Inky Frame 7.3"	Inky Impression 5.7"

Presto

Presto

Install

pip install pimoroni-emulator

Or from source:

git clone --recurse-submodules https://github.com/iksaif/pimoroni-emu
cd pimoroni-emulator
pip install -e ".[dev]"

Usage

# Run an app on a specific device
pimoroni-emulator --device tufty apps/tufty/hello_badge.py
pimoroni-emulator --device presto apps/presto/touch_demo.py
pimoroni-emulator --device badger apps/badger/hello_badge.py
pimoroni-emulator --device inky_frame apps/inky_frame/hello_inky.py
pimoroni-emulator --device inky_impression apps/inky_impression/hello_impression.py

# Run Blinky apps (auto-detected from path)
pimoroni-emulator apps/blinky/snake.py

# Device is auto-detected from app path
pimoroni-emulator apps/tufty/hello_badge.py

# List all supported devices
pimoroni-emulator --list-devices

# Headless mode (for CI/testing)
pimoroni-emulator --device tufty --headless --max-frames 5 app.py

# Save frames to disk
pimoroni-emulator --device presto --autosave frames/ app.py

# Enable API call tracing
pimoroni-emulator --device tufty --trace app.py

# Scale display window
pimoroni-emulator --device tufty --scale 3 app.py

Keyboard controls

• Q / Escape - Quit
• A, S, D, F, G - Buttons A-E (device-dependent)
• Up / Down - UP/DOWN buttons (Tufty, Badger)
• Mouse click - Touch input (Presto)

QwSTPad gamepad (Presto, Blinky)

When an app creates a QwSTPad instance, a clickable gamepad widget appears below the display:

• Arrow keys - D-pad (U/D/L/R)
• Z / X / C / V - Face buttons (A/B/X/Y)
• = / - - Plus/Minus buttons

Running on a real Raspberry Pi with --hardware

For Inky HATs on a real Raspberry Pi, --hardware routes the emulator's framebuffer to the physical panel via the upstream inky library:

pip install 'pimoroni-emulator[hardware]'
pimoroni-emulator --device inky_impression_73 --hardware --headless main.py

--headless is recommended (and auto-enabled when no display server is available); add --trace to see every call to the real HAT (entry, args, return value, elapsed time).

Bookworm: the SPI overlay

On Raspberry Pi OS Bookworm, the default device tree reserves the SPI0 CE0/CE1 GPIOs as hardware chip-selects. On 7.3" Impression HATs that GPIO is also the BUSY pin inky.show() polls — so show() blocks forever (or returns silently with no flicker) until you free the pins.

Add dtoverlay=spi0-0cs to /boot/firmware/config.txt and reboot:

sudo cp /boot/firmware/config.txt /boot/firmware/config.txt.bak
echo "dtoverlay=spi0-0cs" | sudo tee -a /boot/firmware/config.txt
sudo reboot

Symptom if missing: with --trace, you'll see [Hardware] -> show() followed by no <- show line for minutes. The wiring on our side is fine — userspace just can't read BUSY.

Compatibility matrix

Devices

Mock modules

Not yet working

Hard

• Memory constraints - Basic heap tracking exists (--memory-tracking) via tracemalloc with CPython-to-MicroPython scaling, but it's approximate. True byte-accurate simulation would need a custom allocator.
• I2C/SPI peripherals - Stubs return zeros. Full simulation would require modeling each breakout board's register map.

Testing

pytest tests/ -v

The test harness supports headless execution, screenshot capture, button simulation, and touch input:

from emulator.testing import DeviceTest

class TestMyApp(DeviceTest):
    device = "tufty"
    app = "apps/tufty/hello_badge.py"

    def test_display(self):
        self.run_frames(5)
        self.screenshot("output.png")

    def test_button(self):
        self.click_button("A")
        self.run_frames(3)

Architecture

emulator/
  __main__.py          # CLI entry point
  main.py              # App runner, event loop
  devices/             # Device configs (resolution, buttons, features)
  display/             # Renderers (TFT, LED matrix, e-ink)
  hardware/            # Input simulation (buttons, touch, sensors)
  mocks/               # MicroPython module replacements (~38 modules)
  testing/             # Test harness and screenshot comparison
vendor/                # Upstream submodules (read-only reference)
apps/                  # Demo applications

The emulator injects mock modules into sys.modules before running your app. Three mock profiles exist:

• PicoGraphics - For Tufty, Presto, Badger, Inky Frame
• Badgeware - For Blinky 2350
• inky - For Inky Impression (Raspberry Pi)

License

MIT. See LICENSE.

Vendor submodules under vendor/ are all MIT-licensed (Pimoroni Ltd).