Scriptable USB HID device for STM32F103 blue pill (inspired by USB Rubber Ducky)
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
libopencm3 @ 580a2a4

Pill Duck: Scriptable USB HID device for STM32F103 blue pill


A keyboard/mouse USB HID device for the STM32F103 "blue pill" development board, inspired by the USB Rubber Ducky.

Hardware requirements: Any of the ARM Cortex-M3 STM32F103 "minimum development boards" should work, I've tested with this board which can be acquired for ~$1.70: STM32F103C8T6 ARM STM32 Minimum System Development Board Module

Downloads: Prebuilt firmware binaries can be downloaded from CircleCI artifacts, or see the next step for how to build yourself.

Building: Install ARM GCC Embedded Toolchain (if you're on macOS and have Homebrew, just run brew cask install gcc-arm-embedded) then run make.

Installation: Flash the pill_duck.bin binary file to the blue pill over serial.

Usage: Plug in the device to your PC over USB. It should show up as several device classes, including a serial port (USB modem), on my system the device node is /dev/cu.usbmodemAB2. Connect to this serial port e.g. using screen -L /dev/cu.usbmodemAB2 then you can type various commands, if it works:

duck> v
Pill Duck version da646c9-dirty

Command help reference:

v	    show firmware version
w<hex>	write flash data
d<hex>	write compiled DuckyScript flash data
j	    write mouse jiggler to flash data
r	    read flash data
@	    show current report index
p	    pause/resume execution
s	    single step execution
z	    reset report index to zero

Examples: As a test, you can try installing the built-in mouse jiggler by typing j at the serial prompt. The mouse should begin moving back at forth, keeping the system awake. To pause, type p. You can write raw HID packets using the w command, or d to write hex-encoded binary compiled Duckyscript. Compile the text scripts using duckencoder from the USB-Rubber-Ducky project, then write it to the Pill Duck flash using the 'd' command, for example:

duck> d00ff00ff00ff00eb0b0208000f000f00120036002c001a00120015000f000700
wrote flash

will type out "Hello, world". Type p to resume, if execution was previously paused.

Caution: May be buggy, any help welcome!