DIY USB Keyboard with Raspberry Pi Pico for Isadora 4 - Complete Tutorial

Build a custom 20-key USB keyboard using a Raspberry Pi Pico and CircuitPython - perfect for triggering scenes, cues, and effects in Isadora!

🎯 What This Project Does

This tutorial shows you how to transform a $4 Raspberry Pi Pico into a fully functional USB keyboard with 20 customizable keys. The keyboard sends the first 20 letters of the alphabet (a-t) and works seamlessly with Isadora 4 for triggering scenes, controlling parameters, or any other keyboard shortcuts you need.

Key Features:

✅ 20 programmable keys (easily expandable) ✅ Plug-and-play USB HID device (no drivers needed) ✅ Visual feedback with onboard LED ✅ Robust error handling and debugging ✅ Works with any computer (Windows, Mac, Linux) ✅ Perfect for live performance setups 🛠 Hardware Requirements Raspberry Pi Pico (any variant: Pico, Pico W, Pico 2) - ~$4 20x Push buttons/momentary switches - any normally-open type Breadboard or perfboard for connections Jumper wires USB cable (data-capable, not charge-only!)

Total cost: Under $15!

🔌 Wiring Diagram

The wiring is incredibly simple - no resistors needed!

GP0 ←→ Button ←→ GND (sends 'a') GP1 ←→ Button ←→ GND (sends 'b') GP2 ←→ Button ←→ GND (sends 'c') ... GP19 ←→ Button ←→ GND (sends 't')

Important: Each button connects between a GPIO pin and any GND pin. The Pico's internal pull-up resistors handle the rest!

📥 Software Installation Step 1: Install CircuitPython

Download CircuitPython firmware:

For Pico: https://circuitpython.org/boar... For Pico W: https://circuitpython.org/boar... For Pico 2: https://circuitpython.org/boar...

Install firmware:

Hold BOOTSEL button on Pico Connect USB cable (keep BOOTSEL pressed) Release BOOTSEL → "RPI-RP2" drive appears Drag the downloaded .UF2 file to RPI-RP2 Drive disappears and "CIRCUITPY" appears Step 2: Install Required Library

Download the library bundle:

Go to: https://circuitpython.org/libr... Download the bundle matching your CircuitPython version

Install adafruit_hid:

Extract the downloaded ZIP file Copy the adafruit_hid folder from the bundle's lib directory Paste it into the lib folder on your CIRCUITPY drive

Your CIRCUITPY drive should look like:

CIRCUITPY/ ├── code.py └── lib/ └── adafruit_hid/ ├── __init__.py ├── keyboard.py ├── keycode.py └── ... 💻 The Complete Code

Save this as code.py on your CIRCUITPY drive:

""" Raspberry Pi Pico USB Keyboard Emulator for Isadora 4 ====================================================== FUNCTION: --------- This program transforms the Raspberry Pi Pico into a USB keyboard with 20 keys. The keys correspond to the first 20 lowercase letters of the alphabet (a-t). The onboard LED lights up briefly with each key press for visual feedback. HARDWARE WIRING: --------------- Each button is connected between a GPIO pin and GND (Ground): GP0 <-> Button <-> GND (sends 'a') GP1 <-> Button <-> GND (sends 'b') GP2 <-> Button <-> GND (sends 'c') ... GP19 <-> Button <-> GND (sends 't') IMPORTANT NOTES: --------------- - No external pull-up resistors needed (internal pull-ups are enabled) - Use simple momentary switches/buttons between pin and GND - Onboard LED shows every key press - Debouncing is already implemented - Only works with CircuitPython (not standard MicroPython) INSTALLATION: ------------ 1. Install CircuitPython on Pi Pico 2. Copy adafruit_hid library to lib/ folder 3. Save this code as code.py AUTHOR: Pi Pico Keyboard Project for Isadora VERSION: 1.1 (with LED feedback and robust error handling) """ import board import digitalio import usb_hid from adafruit_hid.keyboard import Keyboard from adafruit_hid.keycode import Keycode import time # Error handling for USB HID initialization try: kbd = Keyboard(usb_hid.devices) print("✓ USB HID Keyboard successfully initialized") except Exception as e: print(f"✗ ERROR initializing USB keyboard: {e}") print("Make sure CircuitPython is properly installed!") raise # Initialize onboard LED try: led = digitalio.DigitalInOut(board.LED) led.direction = digitalio.Direction.OUTPUT led.value = False # LED off print("✓ Onboard LED initialized") except Exception as e: print(f"✗ ERROR initializing LED: {e}") led = None # Disable LED if error occurs # GPIO pins for the 20 buttons and their states button_pins = [] button_states = [] button_last_states = [] # First 20 lowercase letters of the alphabet (a-t) keycodes = [ Keycode.A, Keycode.B, Keycode.C, Keycode.D, Keycode.E, Keycode.F, Keycode.G, Keycode.H, Keycode.I, Keycode.J, Keycode.K, Keycode.L, Keycode.M, Keycode.N, Keycode.O, Keycode.P, Keycode.Q, Keycode.R, Keycode.S, Keycode.T ] # Configure GPIO pins (GP0-GP19) print("Initializing GPIO pins...") pin_numbers = list(range(20)) failed_pins = [] for i, pin_num in enumerate(pin_numbers): try: # Configure pin as input with pull-up resistor pin = digitalio.DigitalInOut(getattr(board, f'GP{pin_num}')) pin.direction = digitalio.Direction.INPUT pin.pull = digitalio.Pull.UP button_pins.append(pin) button_states.append(False) button_last_states.append(True) # Pull-up: not pressed = True except Exception as e: print(f"✗ ERROR with pin GP{pin_num}: {e}") failed_pins.append(pin_num) # Placeholder for failed pins button_pins.append(None) button_states.append(False) button_last_states.append(True) if failed_pins: print(f"⚠ Warning: Pins {failed_pins} could not be initialized") else: print("✓ All 20 GPIO pins successfully configured") # LED feedback configuration LED_ON_TIME = 0.1 # LED lights up for 100ms on key press led_off_time = 0 print("\n" + "="*50) print("🎹 USB KEYBOARD READY!") print("="*50) print("Key mapping:") for i in range(20): char = chr(ord('a') + i) if i < len(failed_pins) and pin_numbers[i] in failed_pins: print(f" GP{i:2d} -> '{char}' (ERROR)") else: print(f" GP{i:2d} -> '{char}'") print("\nConnect buttons between GPx and GND") print("Onboard LED shows each key press") print("="*50) # Main loop with robust error handling try: while True: current_time = time.monotonic() # Automatically turn off LED after defined time if led and led.value and current_time >= led_off_time: led.value = False # Scan all available buttons for i in range(20): # Skip pin if initialization failed if button_pins[i] is None: continue try: # Read current pin state (Pull-up: LOW = pressed) current_state = not button_pins[i].value last_state = button_states[i] # Button was pressed (edge from LOW to HIGH) if current_state and not last_state: char = chr(ord('a') + i) # Send key press kbd.send(keycodes[i]) print(f"🔤 Key '{char}' pressed (GP{i})") # Turn on LED with timer if led: led.value = True led_off_time = current_time + LED_ON_TIME button_states[i] = True # Button was released (edge from HIGH to LOW) elif not current_state and last_state: char = chr(ord('a') + i) print(f" Key '{char}' released") button_states[i] = False except Exception as e: print(f"✗ ERROR reading GP{i}: {e}") # Mark pin as faulty button_pins[i] = None # Short pause for debouncing and CPU relief time.sleep(0.005) # 5ms - good balance between responsiveness and debouncing except KeyboardInterrupt: print("\n🛑 Program terminated by user") if led: led.value = False except Exception as e: print(f"\n💥 UNEXPECTED ERROR: {e}") print("Restart required...") if led: led.value = False raise finally: # Cleanup: turn off LED if led: led.value = False print("🔧 Cleanup completed") 🎭 Using with Isadora 4

Once connected, your Pico keyboard works like any standard keyboard:

Scene Triggers: Assign keys a-t to trigger different scenes Parameter Control: Use keyboard shortcuts to control actor parameters Cue Sequences: Create complex cue sequences triggered by your custom keys Live Performance: Perfect for hands-on control during performances

Tip: You can easily modify the keycodes array in the code to send different keys, function keys, or even key combinations!