Pi-HID turns a Raspberry Pi Zero/Zero 2 (or other Pi with USB OTG) into a USB Human Interface Device (HID) that emulates both a keyboard and a mouse on a host computer. Using libcomposite and Python, the Pi can send keypresses or mouse movements to any connected system—including macOS, Windows, or Linux—over a single USB cable.

• ✅ Emulate a composite USB HID (keyboard + mouse) with one USB port.
• ✅ Learn libcomposite: understand strings/0x409, configurations, and HID descriptors.
• ✅ Automate startup: run the gadget setup automatically a few seconds after boot usinga systemd service.
• ✅ Provide Python examples for sending key events and mouse movement via /dev/hidg*.

• Raspberry Pi Zero / Zero 2 W (or another Pi with OTG support).
• Raspberry Pi OS (Lite or Full).
• USB OTG cable.
• Packages:

sudo apt update
sudo apt install python3-venv python3-pip git

• Python libraries:

python3 -m venv hid-venv
source hid-venv/bin/activate
pip install adafruit-hid

1. Enable USB Gadget Mode Add to /boot/config.txt:

dtoverlay=dwc2

And to /boot/cmdline.txt (after rootwait):

modules-load=dwc2

2. Run the bootstrap script

sudo ./driver/bootstrap.sh

This script:

• Loads libcomposite
• Creates mouse and keyboard HID functions
• Sets Vendor/Product IDs (defaults to Apple VID 0x05ac)
• Binds them to the USB controller

3. Test installation

python ./python/checkusb.py
python ./python/checklib.py

both need to run successfully

4. Run python script

python ./python/run.py

Linux Foundation VID (0x1d6b): Useful for testing linux behaviors, but consider using a PID/VID you own or from pid.codes for production.

MaxPower: Set in configs/c.1/MaxPower (in 2 mA units). For keyboard+mouse, 100 (200 mA) is sufficient.

Descriptors: Customize report_desc for different buttons or extra keys.

Composite Devices: Add more functions (serial, Ethernet) to the same configuration if needed.

MIT License — see LICENSE.

Linux USB Gadget API

Adafruit HID Library

USB ID Database