Skip to content

Add --throttle flag to prevent QEMU buffer overflows on large payloads#54

Open
JunderscoreB wants to merge 1 commit intocoredevices:mainfrom
JunderscoreB:main
Open

Add --throttle flag to prevent QEMU buffer overflows on large payloads#54
JunderscoreB wants to merge 1 commit intocoredevices:mainfrom
JunderscoreB:main

Conversation

@JunderscoreB
Copy link
Copy Markdown

Add Transfer Throttling for Large Payloads on QEMU (--throttle)

Overview

This PR introduces an optional --throttle flag to the pebble install command. It solves a notorious edge-case bug where installing large apps (e.g., 1MB+ payloads with heavy audio/image assets) on local QEMU emulators causes catastrophic timeouts or hardware panics, particularly on the emery (Pebble Time 2) emulator.

The Root Cause

Modern host machines execute Python networking scripts significantly faster than the 2016-era QEMU emulators can simulate flash memory writes.

  • Buffer Overflow: When sending a massive .pbw via BlobDB, the host CPU overwhelms the QEMU serial buffer. QEMU locks the virtual CPU to catch up on flash writes, triggering the watchdog timer and causing a result=2 failure.
  • The "Emery" PLL Bug: The emery emulator features an unpatched prototype hardware bug. If the watchdog timer resets the watch, or if the transfer takes longer than the 60-second idle timer, the watch attempts to enter Stop Mode while the PLL is active, resulting in a fatal QEMU panic: qemu stm32: hardware warning: PLL cannot be disabled while it is selected as the system clock.

The Solution

By injecting a microscopic time.sleep() into the libpebble2 packet sender, we can safely drip-feed the packets to the emulator.

A default delay of 4 milliseconds (0.004) limits the transfer to ~250 packets per second. This completely prevents the flash controller lock-up while ensuring a 1MB payload finishes installing in ~32 seconds—safely beating the 60-second idle sleep timeout.

What Changed

  • Added --throttle flag to pebble_tool/commands/install.py (defaults to 0.004s).
  • Dynamically intercepts and throttles PebbleConnection.send_packet if the flag is passed, keeping the fix localized to pebble-tool without requiring cross-repo changes to libpebble2.

@ericmigi ericmigi requested a review from jplexer April 29, 2026 19:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant