rpi-hid 1.1.0

Raspberry Pi USB HID Keyboard + RubberDucky Interpreter

RPI-HID — Raspberry Pi USB HID Automation Library

RPI-HID is a Python library that allows a Raspberry Pi Zero / Zero 2 W to act as a USB Human Interface Device (HID), emulating a keyboard to automate keystrokes on a connected system.

It provides a high-level API and an advanced Rubber Ducky–style interpreter, abstracting low-level HID report handling into clean, reusable Python functions.

---

Features

• USB HID keyboard emulation using Linux USB gadget mode
• High-level keyboard control API
• Advanced Rubber Ducky–style script execution
• Configurable typing delays and pauses
• Auto-run payload support using systemd
• Clean, modular, and extensible architecture
• Published and installable from PyPI

---

Supported Hardware

• Raspberry Pi Zero
• Raspberry Pi Zero 2 W

⚠️ Other Raspberry Pi models (3/4/5) do not support USB gadget mode.

---

Requirements

• Raspberry Pi OS (Lite recommended)
• Python ≥ 3.7
• USB OTG enabled (dwc2, libcomposite)
• Root access (required for /dev/hidg0)

---

Installation

pip install rpi-hid

---

Quick Start

from rpi_hid import Keyboard

kbd = Keyboard()
kbd.winRun("notepad")
kbd.type("Hello from RPI-HID")
kbd.enter()
kbd.close()

---

Keyboard API

type(text: str)

Types the given string.

kbd.type("Hello World")

---

press(*keys)

Presses a key or key combination.

kbd.press("ENTER")
kbd.press("CTRL", "c")
kbd.press("GUI", "r")

---

pause(seconds: float)

Pauses execution.

kbd.pause(1.5)

---

winRun(command: str)

Opens the Windows Run dialog and executes a command.

kbd.winRun("cmd")

---

spamText(text: str, n: int = 10)

Types a string multiple times.

kbd.spamText("TEST ", 5)

---

Rubber Ducky Script Support

RPI-HID includes a DuckyScript interpreter with near Rubber Ducky v1 compatibility.

Supported Commands

• STRING
• DELAY
• DEFAULT_DELAY
• STRING_DELAY
• ENTER, TAB, SPACE, ESC
• Modifier combos (CTRL, ALT, SHIFT, GUI)
• REPEAT
• HOLD, RELEASE
• REM

Example Ducky Script

REM Demo payload
DEFAULT_DELAY 200
GUI r
STRING notepad
ENTER
STRING Hello from DuckyScript
ENTER

Execute Script

from rpi_hid import DuckyInterpreter

duck = DuckyInterpreter()
duck.run_file("payload.ducky")
duck.close()

---

Permissions Note

HID device access requires root privileges. When using a virtual environment, always run scripts using the venv Python binary:

sudo venv/bin/python script.py

---

Ethical Use

This project is intended for:

• USB HID experimentation
• Automation on owned or authorized systems
• Educational and research purposes

Users are responsible for ensuring lawful and ethical use.

---

License

MIT License

---

Author

Abhirup Rudra

---

Future Enhancements

• Mouse HID support
• Full Rubber Ducky v2 compatibility
• Conditional scripting logic
• GPIO-based payload selection
• udev-based privilege handling (no sudo)