Skip to content
HiWord9Public

About

Open firmware for CH552 macropads with custom shortcuts, combos, macros, profiles, RGB lighting, gamepad controls, and reliable knob input. Includes a browser configurator.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Wildpad

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.

What you get

  • 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.

Why

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.

Quick start (Windows)

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).

1. Flash

First time, from the stock firmware (the case has to be opened once):

  1. Remove the four screws on the bottom and lift the bottom plate.
  2. Find the R12 pads next to the WCH chip: two empty pads with no resistor (photo).
  3. Easiest: open the setup page (configure.bat) and press Install on a new pad; it walks you through the rest in the browser. Or run flash.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, name CH552 bootloader, USB ID 4348 55E0, driver WinUSB for the browser or libusb-win32 for flash.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-win32 flash.bat works every time.
  4. 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.)
  5. 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).

2. Set up

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.

Linux and macOS

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).

Factory settings

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.

Gamepad axis

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.

Command line

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

Building

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.

Releases

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.

Boards

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.

How it works

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.

Credits and license

Wildpad, firmware included, is free software under the GNU GPL 3.0.

About

Open firmware for CH552 macropads with custom shortcuts, combos, macros, profiles, RGB lighting, gamepad controls, and reliable knob input. Includes a browser configurator.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages