Working with the QMK Firmware

QMK is short for Quantum Mechanical Keyboard. Built primarily for keyboards, QMK can be used for mice as well, as is the case with the Ploopy Mouse. QMK is fully open-source and driven by a community that has developed several tools allowing one to make use of QMK's capabilities.

The QMK Firmware in Theory and Practice

With the Ploopy Mouse, most of the novelty comes from working with a QMK firmware. Accordingly, I'll dedicate a rather large section to what possibilities there are and how user-friendly the process is. Instead of describing everything one can do, which would be a rather lengthy undertaking, I'll cover what I did in particular.


First of all, the basics: As of this writing, the Ploopy Mouse ships with QMK Release Version 0.10.48, which has been vetted to be stable. However, this firmware won't be compatible with VIA, which in turn allows one to configure the Ploopy Mouse without having to compile and flash the firmware every time a change is made. To this end, I've first downloaded and installed QMK Toolbox, along with all necessary drivers. Within QMK Toolbox, all one needs to do is select the hex file available on Ploopy's Github, put the Ploopy Mouse into bootloader mode by keeping the "back" button (mouse 4) pressed while plugging in, and then flash the new firmware.


The next step is downloading and installing VIA, which provides a graphical interface for conveniently assigning button binds. In the example above, I've assigned the volume up and down media functions to the buttons next to the left and right main buttons. All changes are applied live, and even macros and layered functions can be set up.


If one wants to do more advanced stuff, some additional work is required. In this case, my goal is to edit the default CPI steps to 400, 800, 1600, and 3200 CPI. In order to do so, several things are required. I've already mentioned QMK Toolbox above, which will be used to flash the firmware. Furthermore, for those on Windows, MSYS will be used to make a firmware. Doing so in turn will require cloning a GitHub repository fork, which requires creating a GitHub account in the first place. Without going into details, not everything will be obvious to first-time users. In any case, I was able to make a firmware with default steps of 400, 800, 1600, and 3200 CPI. The resulting hex file was then flashed to the Ploopy Mouse without issue.

Even after uninstalling QMK Toolbox, VIA, and MSYS, several driver packages (libwdi) will remain intact. In order to uninstall these, open an elevated command prompt and run pnputil /enum-drivers. After having done so, identify all inf-packages associated with libwdi. Each of them needs to be deleted individually by running pnputil /delete-driver oem0.inf, with "oem0.inf" being replaced with the driver package of choice (e.g., oem32.inf).

A Closer Look at the QMK Firmware

Being open-source, the firmware for the Ploopy Mouse can be modified in great detail. What follows are some excerpts I've stumbled upon while looking through the code.

#define USB_POLLING_INTERVAL_MS 1

By setting this to 2, polling rate could be lowered to 500 Hz if needed.

#define DEBOUNCE 5

By lowering this value, the debounce time for the switches can be lowered. Setting it to 0 disables debouncing altogether.

#ifndef PLOOPY_DPI_OPTIONS
# define PLOOPY_DPI_OPTIONS { 400, 800, 1600, 3200 }
# ifndef PLOOPY_DPI_DEFAULT
# define PLOOPY_DPI_DEFAULT 1
# endif
#endif

This can be used to define the available CPI steps. Only values that are multiples of 100 will be accepted.

// Wrap to HID size
data.dx = constrain(data.dx, -127, 127);
data.dy = constrain(data.dy, -127, 127);
if (debug_mouse) dprintf("Cons] X: %d, Y: %d\n", data.dx, data.dy);
// dprintf("Elapsed:%u, X: %f Y: %\n", i, pgm_read_byte(firmware_data+i));

process_mouse_user(mouse_report, data.dx, data.dy);

No doubt the most interesting part is the one above. Here, we finally find the reason why x and yCounts are limited to +127 to -127. Digging deeper into the firmware, one can see that the HID descriptor is limited to 8 bit:

HID_RI_LOGICAL_MINIMUM(8, -127),
HID_RI_LOGICAL_MAXIMUM(8, 127),

In order to prevent an integer overflow, all counts are constrained to +127 to -127. Lifting these constraints results in this:


Accordingly, the most straightforward solution would be to support a 16-bit HID descriptor. Addressing this restriction is on Ploopy's roadmap. Those more versed in this than I am are free to pursue this fix by themselves, of course.

In fact, there is no need to restrict oneself to QMK firmware. For instance, with adjustments to PID/VID, buttons, and MCU, one could create a fork of this firmware that would work on the Ploopy Mouse. The possibilities are only limited by one's own ability.

Further options include a function called "Drag Scrolling," for instance, which allows one to translate mouse movement into scrolling. This function is already fully set-up and can be accessed by a keymap.