pico-hidkbd

Plug-and-play USB HID keyboard library for MicroPython on Raspberry Pi Pico W (also Pico and Pico 2).

from hidkbd import Keyboard, Key

kb = Keyboard()                 # USB keyboard; REPL stays connected
kb.write("Hello Pico W!\n")     # type a string
kb.hotkey("ctrl", "c")          # named combos
kb.tap(Key.ENTER)

No CircuitPython. No custom UF2. Copy two folders onto the Pico and import.

• CircuitPython adafruit_hid is easy, but it is not MicroPython.
• Official MicroPython usb-device-keyboard only sends raw keycode tuples. There is no write("text").
• Older Pico HID forks need a custom firmware image.

This repo is the missing high-level API on stock MicroPython.

• Raspberry Pi Pico W, Pico, or Pico 2
• MicroPython 1.23 or newer with machine.USBDevice
  • Pico W: https://micropython.org/download/RPI_PICO_W/
  • Pico: https://micropython.org/download/RPI_PICO/
• Host keyboard layout US QWERTY (HID sends scancodes, not characters)

Hold BOOTSEL, plug the Pico in, drop the .uf2 onto the RPI-RP2 drive.

Put both folders on the Pico under /lib:

/lib/hidkbd/
/lib/usb/

Thonny (Windows): interpreter = MicroPython (Raspberry Pi Pico). Upload hidkbd and usb into /lib. Do not upload __pycache__.

mpremote:

pip install mpremote
git clone https://github.com/pardeep2690/pico-hidkbd.git
cd pico-hidkbd
python tools/install_to_pico.py

mip (needs network on the Pico, or mpremote mip):

mpremote mip install github:pardeep2690/pico-hidkbd

from hidkbd import Keyboard
kb = Keyboard()
kb.write("hello\n")

Thonny / serial disconnects once while USB re-enumerates as a keyboard. Reconnect. The REPL still works (keep_repl=True by default).

The Pico stays a USB keyboard. The phone sends keys, strings, or macros over BLE.

python tools/install_to_pico.py --ble

Run ble_demo.py. On the phone install Serial Bluetooth Terminal, connect to PicoHID, then send:

hello from android
/k enter
/k ctrl+c
/m hello

Full steps: docs/BLE.md.

Optional USB-only demo (hold BOOTSEL to type, no extra wiring):

python tools/install_to_pico.py --demo

Then run hid_demo.py on the Pico. Do not replace main.py until you are ready — HID on boot makes Thonny disconnect every power-up.

Full step-by-step: docs/INSTALL.md.

from hidkbd import Keyboard

kb = Keyboard()
kb.write("user@host\n")
kb.writeln("next line")

Unsupported characters raise ValueError.

kb.tap("enter")
kb.tap("f5")
kb.hotkey("ctrl", "c")
kb.hotkey("ctrl+alt+delete")
kb.hotkey("win", "r")

Names: ctrl, shift, alt, win / cmd / gui, enter, esc, tab, space, backspace, delete, arrows, home / end, pageup / pagedown, f1–f24, and characters like "a" or "!".

from hidkbd import Key

kb.press(Key.SHIFT)
kb.tap(Key.A)
kb.release(Key.SHIFT)
kb.release_all()

Must be enabled on the first Keyboard() call:

kb = Keyboard(media=True)
kb.media.volume_up()
kb.media.mute()
kb.media.play_pause()

LED state from the host:

print(kb.caps_lock, kb.num_lock, kb.scroll_lock)

See examples/README.md.

1. Keyboard() registers a USB HID boot keyboard (optional media keys) using machine.USBDevice.
2. builtin_driver=True keeps CDC, so Thonny and mpremote still work.
3. USB re-enumerates once. Windows / macOS / Linux see a standard keyboard. No drivers.

usb/ is the official MicroPython usb.device stack (MIT). hidkbd/ is the high-level API.

Thonny died on first run. Expected. USB re-enumerated. Stop/Restart and reconnect.

Nothing types. Focus a text editor, wait for the Pico LED, then hold BOOTSEL or kb.write("hi").

Wrong characters (@ becomes "). Host OS is not US QWERTY. Switch the PC layout.

REPL gone forever. You passed keep_repl=False. Hold BOOTSEL, re-flash MicroPython, copy files again. Never put keep_repl=False in boot.py.

machine.USBDevice missing. Firmware is too old. Flash MicroPython 1.23+.

no module named 'usb.device'. usb/ is not on the Pico under /lib.

Close Thonny before mpremote. Windows will not share the serial port.

python -m unittest discover -s tests -v

Tests cover key names and the US layout on CPython (no Pico required).

MIT. See LICENSE.

USB device support in usb/ is vendored from micropython-lib (MIT, Angus Gratton). See NOTICE.