Evil ducky

Evil Ducky

Evil Ducky is a compact USB-C HID automation board based on the RP2040. It appears to the host as a USB HID device and can send keyboard and mouse actions from a small text script embedded into the firmware.

Repository layout

• hardware/evil_ducky_pcb/ - KiCad project for the custom RP2040 PCB.
• firmware/dev_hid_composite/ - Raspberry Pi Pico SDK firmware using TinyUSB.
• firmware/dev_hid_composite/main.evil_ducky - the automation script that gets embedded at build time.

Hardware

The board design includes:

• RP2040 microcontroller
• W25Q32JV 4 MB QSPI flash
• USB-C plug
• TLV75533 3.3 V regulator
• TPD2EUSB30 USB data-line ESD protection
• ABM8 crystal
• Upload/run slide switch
• Status LED on GPIO16

The KiCad project and custom footprints live in hardware/evil_ducky_pcb/.

Firmware

The firmware is a Pico SDK C project that uses TinyUSB to expose HID reports for keyboard and mouse support. During the CMake build, tools/embed_script.py converts main.evil_ducky into a generated C header, so changing the script currently requires rebuilding and reflashing the board.

At runtime, the board waits for USB HID to become ready, delays briefly for host setup, runs the embedded script once, and then leaves the status LED on if the script completed successfully. A fast blink indicates script failure.

Script format

Edit firmware/dev_hid_composite/main.evil_ducky:

# Lines starting with # are comments
WAIT 1000
PRESS SPACE
HOLD TAB
WAIT 500
RELEASE TAB
MOVE 50 50

Supported commands:

• WAIT <milliseconds>
• PRESS <key>
• HOLD <key>
• RELEASE <key>
• MOVE <x> <y>

Keys can be letters, digits, common names like SPACE, TAB, ENTER, arrow keys, F1 through F12, modifiers like CTRL, SHIFT, ALT, GUI, or raw HID usages such as 0x2C.

Build and flash

1. Open firmware/dev_hid_composite/ in VS Code with the Raspberry Pi Pico extension, or build it with the Pico SDK CMake toolchain.
2. Build the project. The script is embedded automatically.
3. Set the board switch to UPLOAD and connect it over USB-C.
4. Copy the generated .uf2 file to the RPI-RP2 drive.
5. Unplug the board, set the switch to RUN, and reconnect it.

Notes

• The configured flash size is 4 MB (PICO_FLASH_SIZE_BYTES=4194304).
• The USB descriptors are based on TinyUSB examples and currently identify as TinyUSB Device.
• Script lines are limited to 160 characters.