The wildcard for your macropad. Open firmware and setup app for the cheap CH552 “keys + knob” macropads: every knob click counts, every control does what you want.
These little macropads are sold under dozens of brand names: three or six mechanical
keys, a clickable rotary knob, RGB LEDs and a WCH CH552 microcontroller (stock USB ID
1189:8890, configured with an app called “MINI KeyBoard”). The stock firmware loses
most knob clicks as soon as you turn it with any speed, and its app can only assign a
key per button. Wildpad replaces both. One Wildpad firmware runs all of these pads,
and one it doesn't know yet is set up by pressing its keys once.
- No lost clicks. The knob is read in a 4 kHz timer interrupt, independent of USB, with bounce filtering. Turn it as fast as you like: every click arrives, in the right direction.
- Any control, any action. Each key, the knob press and each turning direction can send a keyboard shortcut, a media key, a mouse click, scrolling, pointer movement or a gamepad button, switch profiles or control the lights.
- Combos. Hold any control and press or turn another to do something else, for example hold the knob and turn it for brightness, hold key 1 and press key 2 for a shortcut. Holding a key on its own (long press) can do something else too. A key's own action can wait until you let go (so it doesn't fire when you use a combo) or be held right away, so combos add to it.
- Several steps. Any action can be a short sequence: tap things, hold something for as long as you hold the control, wait, and do more when you let go. For example tap A, tap A again, then hold RT for a double jump and throttle in a game.
- Three profiles, each with its own light color and effect; switch with a combo, a key or the app.
- Gamepad axis. The knob can be an absolute gamepad axis (stick or triggers) with a configurable range and hard stop, for racing and steering games. The pad adds an Xbox controller (XInput, built into Windows) automatically when an action needs it, while the keys keep working as a keyboard. Nothing to install, no modes to switch.
- Lights. Off, solid, breathe, rainbow, light on press, or knob position, per profile.
- Setup in the browser. Click a key on the drawing, pick what it does, done: every change takes effect on the pad immediately and is saved on it. Undo, presets, backup to a file. A command-line tool does the same.
- Updates from the browser, without a driver: the pad hands its own USB connection to the chip's bootloader.
- Safe to try. The CH552 bootloader lives in ROM, so a macropad can always be re-flashed.
Measured on a stock unit, logging every HID event:
| Turning | Clicks that arrive |
|---|---|
| Slowly | all |
| Fast | about 40–50 % |
Knob events never arrive closer than 47 ms apart: the stock firmware polls the encoder from its main loop and blocks on USB for every step, so it tops out at about 21 clicks per second. Every open firmware for this board we found reads the encoder the same way. Details in docs/findings.md. With Wildpad, every click arrives at any speed.
You need Chrome, Edge or Opera. The setup page runs from the project's website, or
from the release download (configure.bat, which needs
Python 3: winget install Python.Python.3.12).
First time, from the stock firmware (the case has to be opened once):
- Remove the four screws on the bottom and lift the bottom plate.
- Find the R12 pads next to the WCH chip: two empty pads with no resistor (photo).
- Easiest: open the setup page (
configure.bat) and press Install on a new pad; it walks you through the rest in the browser. Or runflash.bat. Either way, the first time on a PC Windows needs a driver for the chip's bootloader, set up with Zadig (no macropad needs to be connected): Device → Create New Device, nameCH552 bootloader, USB ID434855E0, driver WinUSB for the browser or libusb-win32 forflash.bat, then the big button must say Install Driver (if it says Install WCID Driver, switch it with the arrow on its right). With WinUSB, Windows doesn't start the bootloader's driver every time, so the browser may need a few plug-ins; with libusb-win32flash.batworks every time. - Short the R12 pads (tweezers or a paper clip) and, while holding them shorted, plug in the USB cable. The LEDs stay dark in the bootloader; that's normal. (Connecting chip pin P1.5 to GND while plugging in also works.)
- Flashing starts by itself and takes a few seconds.
The stock firmware can't be backed up first: the CH552 bootloader has no read command.
Updates need no screwdriver and no driver: press Update firmware on the setup
page (Settings → Firmware), or run flash.bat. The pad switches to its update mode
by itself; Windows sets it up without Zadig. If that ever fails, unplug the pad and
plug it back in while holding key 1 (that starts the chip's own bootloader, which
needs the Zadig driver like the first flash).
Run configure.bat. It opens the setup page; click Connect and pick the
macropad (only needed the first time). Click a key or the knob on the drawing and
choose what it does.
The setup page works the same in Chrome or Edge, and no driver is needed: the first install and updates run from the page. On Linux the browser may use the pad only after an udev rule is installed once:
sudo cp web/60-wildpad.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules && sudo udevadm trigger
Serve the page with python3 -m http.server 8765 in the Wildpad folder and open
http://127.0.0.1:8765/web/. The command-line tools need
pip install -r requirements.txt (hidapi, pyusb).
| Profile | Key 1 | Key 2 | Key 3 | Knob press | Knob turn |
|---|---|---|---|---|---|
| 1, cyan | previous track | play / pause | next track | mute | volume |
| 2, amber | Ctrl+C | Ctrl+V | Ctrl+Z | Enter | scroll |
| 3, teal | Win+D (desktop) | Win+E (files) | Win+Shift+S (screenshot) | Win+Tab (task view) | switch windows (Alt+Tab) |
In every profile: hold the knob and press key 1, 2 or 3 to switch profiles, hold the knob and turn it to change the brightness. Because the knob starts combos, its own action (mute) is sent when you let go of it.
Profile 3 switches windows: turn the knob and Alt stays held while you turn, so the window switcher moves along; stop for 0.8 s and the window is picked. The preset Switch windows: press and turn does it the other way round: pressing the knob opens the switcher (Alt+Tab with Alt held) and turning moves through it until you let go.
Plug the pad in while holding key 1 to start the bootloader for flashing.
Select the knob, set Turning sends to Gamepad axis, pick the axis and how many clicks it takes from center to full. The pad reconnects once and Windows shows an Xbox controller. Set the knob press to Center the knob axis, and turn down the game's controller deadzone. The knob has 20 clicks per turn, so the axis moves in steps: with 10 clicks to full, each click is 10 %. More clicks give finer steps but more turning. Combos still work while the knob is an axis: for example hold key 3 and turn can scroll without moving the axis.
python tools/wildpad.py show # everything on the pad
python tools/wildpad.py set 1 key1 key:ctrl+c # profile 1, key 1
python tools/wildpad.py set 2 right axis:lx:10 # profile 2, knob = stick X
python tools/wildpad.py combo add key1 key2 media:mute
python tools/wildpad.py set 1 key3 "seq:tap pad:a; wait 60; tap pad:a; hold pad:rt"
python tools/wildpad.py option profiles 1 # more memory for combos and steps
python tools/wildpad.py light 1 breathe #ff8800
python tools/wildpad.py export backup.json # same format as the setup page
python tools/wildpad.py actions # all action and key names
winget install SDCC.SDCC # SDCC 4.5 (see below)
python firmware/build.py # -> firmware/build/wildpad.bin
python firmware/test/run_tests.py # tests in the s51 8051 simulator
python firmware/test/check_descriptors.py # USB descriptor checks on the binary
python test/test_actions.py # action text, as test/actions.json says
python test/test_web.py # the setup page in Chrome (test/requirements.txt)
The tests run the real firmware sources in a simulator with the USB layer stubbed
out: knob decoding (slow, fast, bounce, reversals), every click becoming exactly one
press and release, combos with keys and the knob, long press, profile switching and
the gamepad axis, multi-step actions, app switchers and a 6-key board. The firmware
fills the 14 KB of code flash almost completely and is sized for SDCC 4.5; older
versions may not fit it. On Linux, bash tools/ci.sh fetches SDCC 4.5 and runs all
of the above, as GitHub does for every push. build.py works around a packaging bug
of SDCC 4.5 on Windows.
test/actions.json lists action text with what it must turn into. The setup page and
wildpad.py both read it in the tests, and the page test also compares every key name
and the settings file of every board between the two, so they can't drift apart.
A release tag starts with the firmware version it carries (FW_MAJOR/MINOR/PATCH in
firmware/src/config.h); a fourth number counts releases that keep that firmware
and only bring a newer setup page or tools:
| Tag | Firmware | What changed |
|---|---|---|
v0.2.0 |
0.2.0 | new firmware |
v0.2.0.1 |
0.2.0 | setup page or tools; no need to update the pad |
v0.2.0.2 |
0.2.0 | setup page or tools again |
v0.2.1 |
0.2.1 | new firmware |
v0.3.0-beta.1 |
0.3.0 | pre-release for testing |
The firmware version follows the usual rules: patch (0.2.1) for fixes, minor (0.3.0) for new features, major for 1.0 and later for changes that break settings files or older pads.
Publishing a release on GitHub builds and tests everything, attaches the zip and updates the website; a pre-release only gets the zip. The release workflow checks the tag: the first three numbers must be the firmware version, and it builds the previous release's firmware to compare: a changed firmware needs a new version, an unchanged one needs the fourth number. The release notes start with a line saying which firmware the release carries and whether it is new.
Known boards: 3 keys + knob, 6 keys + knob, and a 6-key variant wired in reverse. The
board is a setting (Settings → Board on the setup page, or wildpad.py board). For
any other CH552 pad, Another pad: find its keys asks you to press the keys in order
and stores their pins. The memory for actions follows the number of keys: the 6-key
pad fits 2 profiles, the 3-key pad 3. See docs/porting.md.
| Path | What |
|---|---|
firmware/src/input.c |
Timer interrupt: quadrature decoder, key debounce, millisecond clock |
firmware/src/main.c |
Action engine: profiles, combos, long press, knob step queue, gamepad report, lights, configuration protocol |
firmware/src/usbdev.c, descr.c |
USB device with three layouts: keyboard; keyboard + gamepad; update mode |
firmware/src/settings.c |
Settings in the 128-byte Data-Flash, factory settings |
firmware/src/sys.c, ch552.h |
Clock, delays, watchdog, resets, WS2812 output; the chip's registers |
web/ |
Setup page (WebHID) |
tools/flash.py, winusb.py |
Flasher (update mode, or the chip's bootloader through WinUSB or libusb-win32) |
tools/wildpad.py |
Command-line tool |
test/, tools/ci.sh |
Action text and setup page tests; everything GitHub runs on each push |
With a gamepad action the pad is a composite USB device: a HID keyboard/mouse, a vendor
HID interface for configuration and live state, and an XInput interface. A Microsoft
OS descriptor gives that interface the compatible ID XUSB10, so Windows loads its
built-in Xbox driver for just that interface; nothing has to be installed and no
Microsoft IDs are borrowed. The configuration protocol and the settings layout are
documented in docs/protocol.md.
Settings live in the chip's 128-byte Data-Flash, which limits how much fits. Combos and multi-step actions share what the profiles leave: on the 3-key pad 48 bytes with 3 profiles (a combo takes 4, a step 3, a wait 1), 92 bytes with a single profile. The setup page shows how much is used. Long text macros don't fit.
- XInput interface layout from GP2040-CE.
- Bootloader protocol from chprog by Stefan Wagner, based on chflasher and wchprog.
- Pinout and bootloader entry cross-checked with eccherda/ch552g_mini_keyboard and nelsonjchen/c3-touchkey-keyboard.
Wildpad, firmware included, is free software under the GNU GPL 3.0.