RP2040 Programmable Shortcut Keyboard (Keyboard Advanced RP2)

English | 中文

A USB HID programmable shortcut keyboard firmware based on Raspberry Pi Pico (RP2040). Key mappings for 4 physical buttons can be modified in real-time via the host-side USB CDC serial connection — no firmware re-flashing required.

---

✨ Features

• 4 physical buttons, each supporting up to 4-key combinations (including modifiers) to simulate keyboard shortcuts
• USB CDC binary protocol for real-time key configuration over serial — changes take effect immediately
• DTR signal auto mode switching: opening the COM port enters config mode, closing it restores keyboard mode
• WS2812 rainbow LED: breathing rainbow effect in normal mode, solid blue in config mode
• Persistent configuration: key mappings, polling interval, and debounce time stored in onboard Flash via LittleFS — survives power loss
• Dual-core parallelism: Core0 handles HID keyboard + CDC protocol, Core1 independently drives LED animations
• Configurable parameters:
  • bInterval — USB HID polling interval (1–255 ms), affects key response latency
  • debounce — key debounce time (ms)
  • HID keycode sequences per button (supports key combos)

---

🛠 Hardware Requirements

Component	Description
MCU	Raspberry Pi Pico (RP2040)
Buttons	4 tactile switches, connected to GPIO 15, 14, 8, 7
LED	1 × WS2812B (NeoPixel), connected to GPIO 16
Wiring	Button: one leg to GPIO, other leg to GND (internal pull-up)

---

📦 Software Dependencies

• Arduino-Pico (RP2040 core support)
• Adafruit TinyUSB (USB HID stack)
• Adafruit NeoPixel (WS2812 driver)
• LittleFS (Flash filesystem)

---

🚀 Quick Start

1. Open firmware/firmware.ino in Arduino IDE or PlatformIO
2. Select board: Raspberry Pi Pico (RP2040)
3. Set USB Stack to TinyUSB
4. Compile and flash to Pico
5. After plugging in USB, the device enumerates as a USB HID keyboard
6. Open the COM port to enter config mode, then use the manager tool to send configuration (see cdc_protocol_spec.md)

---

🖥️ Configuration Manager

A cross-platform GUI tool (manager/kb_manager.py) is provided for configuring the keyboard:

• Bilingual interface: auto-detects system language (Chinese/English), with manual toggle
• Serial port management: identifies RP2040 devices by VID/PID
• Live config read/write: reads current key mappings from the device, writes new ones
• Parameter tuning: debounce delay and polling interval adjustment

To run the manager:

pip install pyserial
python manager/kb_manager.py

---

📡 CDC Configuration Protocol

The project defines a self-describing binary frame protocol for host-to-MCU configuration communication:

• Sync header 0xAA 0x55 for frame alignment
• CRC-8-ATM checksum for data integrity
• Supports CONFIG_SET (send config), CONFIG_GET (read config), ACK/NAK (response)

See cdc_protocol_spec.md for the full protocol specification.

---

📁 Project Structure

keyboard_advanced_rp2/
├── firmware/
│   ├── firmware.ino          # Main entry: setup() / loop() / setup1() / loop1()
│   ├── config.h              # Pin definitions, protocol constants, global config
│   ├── button.h              # Button struct declaration
│   ├── button.cpp            # Button debounce, state change detection, HID report trigger
│   ├── keyboard.h            # USB HID keyboard interface declaration
│   ├── keyboard.cpp          # HID keyboard report generation: active key set management, modifier separation
│   ├── led.h                 # WS2812 LED interface (runs on Core1)
│   ├── led.cpp               # Breathing rainbow effect + config mode solid blue
│   ├── cdc_protocol.h        # CDC binary protocol interface (runs on Core0)
│   ├── cdc_protocol.cpp      # Frame parsing state machine, CRC-8, DTR mode switching
│   ├── config_store.h        # Flash persistent config interface
│   ├── config_store.cpp      # LittleFS read/write for config files under /kb/
│   ├── sketch.yaml           # Arduino CLI build config
│   └── libraries/            # Local dependency libraries (NeoPixel, TinyUSB, LittleFS, SPI)
├── manager/
│   └── kb_manager.py         # Cross-platform GUI configuration tool (bilingual)
├── cdc_protocol_spec.md      # CDC binary protocol full specification
├── cdc_protocol_spec.pdf     # Protocol specification (PDF)
├── README.md                 # Project documentation (Chinese)
├── README_EN.md              # Project documentation (English)
└── .gitignore

File	Responsibility
firmware.ino	Dual-core scheduler entry: Core0 runs button scan + CDC, Core1 runs LED
config.h	Centralized tunable parameters: pins, protocol constants, timeouts, button max
button.cpp	Software debounce + state machine, calls addKey() on press, removeKey() on release
keyboard.cpp	Manages up to 6-key + modifier active key set, auto-separates modifiers, sends standard HID report
led.cpp	HSV hue gradient + sine-wave breathing brightness, runs independently on Core1
cdc_protocol.cpp	Byte-by-byte state machine parsing binary frames, DTR-controlled mode switching, 5s idle timeout
config_store.cpp	Stores each parameter as a separate file using LittleFS, version file as atomic write marker

---

🎯 Default Key Mapping

Button	GPIO	Default Function
BTN0	15	← (Left Arrow)
BTN1	14	↓ (Down Arrow)
BTN2	8	↑ (Up Arrow)
BTN3	7	→ (Right Arrow)

Key mappings can be changed at runtime via the CDC protocol to any key combination (e.g. Ctrl+C, Alt+Tab, Win+Shift+S, etc.).

---

📄 License

MIT License