Rico wrote: 08 Sep 2022, 15:03
What would be great for me to have:
- Source code of the current QMK firmware, for informative purposes mostly
- Information on matrix/switches topology with always on and off switches(could still find that reading qmk source code)
- Have access to Pandrew utility software: I feel that I could connect the firmware with this tool and why always reinvent the wheel ?
Hi, since I recently wrote a new firmware that supports these keyboards, maybe I can share some experiences (wall of text ensues):
I had already written a USB HID keyboard implementation and "engine" (i.e., layers, macros, combo keys, etc.) from scratch (no library used so the code might be smaller and more specific to keyboards, and it has in some ways more optimised non-NKRO descriptors than in QMK). I suspect you may also have to do something like this unless QMK supports some keyboard that uses the same kind of chip as you (maybe the chibios used by arm-based QMK keyboards would support it). If you end up having to do it on top of QMK, there's quite a bit of boring USB HID descriptor and request/response plumbing that needs to be done in order to support all of QMK's features like mouse keys, media keys, etc... It's not particularly difficult, but not having to support all of QMK is one reason why I prefer my own firmware.
I originally wrote the firmware for a DIY PS/2 to USB converter (to install inside my model M keyboard), but as proof of concept I decided to make a wrapper to support semi-easily porting keyboards from QMK (at least as long as they use the same microcontroller family, since my USB implementation is only for AVR), i.e., taking the low-level keyboard driver from QMK but using my keyboard engine instead of QMK's. This was fairly easy: a dozen or so files from QMK copied as is, and the "main" file of under 400 lines that duplicates the execution flow of the QMK but passes the matrix scan results to my engine instead.
Porting a new keyboard using this approach is theoretically a simple matter of taking the keyboard-specific files from the corresponding "keyboards" directory in QMK and setting up a Makefile to include them in the build. The two things that need customisation are the QMK config.h (this is mostly mechanical changes of changing the files it refers to) and the file which contains the base keymap, i.e., matrix configuration.
So, the things to look in QMK is to find the keyboard directory, e.g., `keyboards/xwhatsit/brand_new_model_f/f77/wcass` and then backtrack any files it refers to in the parent directories. For these keyboards, the keymap/matrix configuration is in this innermost directory, in the .c and .h files with the same name as the directory (here wcass.h and wcass.c). The .h file contains macros that map the actually existing physical key positions to the matrix row and column, and the .c file calls one of these macros with the physical key layout. (The layout is often even written in the text file to look like the actual keyboard, so following this is easy. I recommend copying these pretty much as is, since manually defining each matrix is time-consuming and error-prone. The changes I do is just to make sure all the populated keys are unique, since my engine is based on specifying the differences between this "natural" keymap and what you wish to use.)
Now, the tricky part is the capsense scanning and calibration. In the QMK firmware, this is defined in `keyboards/xwhatsit/matrix.c`. I originally used this file as is, just to get my firmware working with a proven solution, but I have rewritten probably over 80% of that file since, to optimise the speed (the scanning is typically 2-4 times faster, although the worst case is only maybe 20% faster, and calibration is maybe 2–3 times faster – it could be over 6 times faster but I have chosen improved accuracy instead, since the absolute calibration time is already short enough to be negligible in the USB proceedings).
The matrix scanning is done by setting a DAC threshold, then pulsing each column and reading the results from the rows, each giving either high or low (one or zero) depending on whether the key is above or below that threshold. The goal of the calibration is to find some set of thresholds that is small enough to be scanned for every key fast enough to be responsive, while having the thresholds such that the values correspond reliably to the actual state of the the key.
For the calibration premise is that we know the mapped keys (by looking at the non-zero values in the aforementioned keymap) and can assume that those keys "should" be all unpressed on power-up. (I have some code to handle keys pressed on power-up, but we can get back to that later.) The difficulty here is that without user interaction during calibration, we can only presume to find the thresholds for the always unpressed state at that moment in time. We could simply assign the thresholds to the highest value that makes each key read as not pressed, but that will result in phantom presses when the values drift slightly over time, and when pressing adjacent keys causes a slight change in unpressed keys.
The start of calibration in pandrew's firmware is to first do two binary searches across all mapped keys to find out the range of thresholds where the (presumably unpressed) keys give inconsistent values (i.e., the highest threshold below which they will all start to read as pressed, and the lowest threshold above which they all start to read as unpressed). The 5 (or whatever number is configured) calibration bins are then distributed evenly across this range. This is largely the same in my firmware.
Next, pandrew's firmware does a binary search for each individual mapped key, trying to find the "tipping point" of uncertainty, where the result of 16 scans at the same threshold would result in 8 pressed and 8 not pressed values, i.e. half and half. The key is then assigned to the calibration bin closest to this threshold. In the end, each bin is assigned a final threshold as the average of the minimum and maximum threshold of the keys in that bin, and then that threshold is adjusted upwards by a magic number (from the configuration file) to hopefully push it so far up that it will not give phantom presses, and at the same time hopefully still low enough that actual presses register reliably.
This works pretty well in practice, as long as the magic number is configured well. I have a couple of
mostly theoretical issues with it (i.e., please do not interpret this as criticism of the firmware; it works great and without it there probably wouldn't be my firmware for these keyboards!):
- First, this approach tends to always use all the bins. Scanning each bin takes almost a constant amount of time, i.e., scanning 5 bins takes almost 5 times longer than scanning 1 bin. In my experience, 2 bins can still be scanned under 1 millisecond (the maximum USB HID poll rate), and maybe 3 with some other optimisations and some luck in how the keys are distributed across columns in each bin. Often the range of values is also very small, and the bins end up very close together.
- Second, searching for the tipping point where 16 scans reads 8/8 seems theoretically unreliable: if we assume that we are testing at exactly the "correct" threshold where the probabilities are 50/50, the probability of getting that 8/8 result is the same as flipping a coin 16 times and getting exactly 8 heads and 8 tails (in any order), which is under 20%. Likewise, scanning a wrong threshold where the probabilities are unbalanced can still, with bad luck, end up giving the 8/8 result and the search is terminated. Thus, I feel that in theory the threshold found for each key can be any value from the "unreliable range" of thresholds. (This is mitigated a lot by averaging the bins.)
So, what I do instead is I do a slightly more dynamic bin assignment where the thresholds change as keys are assigned to them, and I also use some min/max values for the bin spacing to perhaps better support both small ranges and large ranges resulting from calibrating with some keys pressed (or incorrectly mapping an unpopulated key position, for example). Then, I scan an entire column in parallel (so 8 keys at a time; it takes the same time as scanning one key), and I do the binary searches in parallel for all of those keys, adjusting the thresholds of all of them until all 8 searches have terminated. And, instead of looking for the tipping point where the results of 16 scans are 8/8, I look for the lowest threshold where the results are 0/16 pressed/unpressed. (There are 65536 combinations for the results of 16 scans, and the 0/16 is only one of them, whereas there are 12870 ways it can be 8/8. So, even though it is still possible to have bad luck and end up with a false probabilistic result, it is a lot less likely, especially since the search does not terminate until all 8 keys have been resolved.)
Then, optionally, in the end I also merge nearby bins, to further reduce the number of bins. On my F62 and two F77 keyboards, it actually works fine to just reduce the number of bins to 1, but I recently changed it to be a bit less aggressive and instead it now ends up with 2 bins. As further post-processing, if the highest bin is "suspiciously far" (magic number) from the other bins and contains only a small number of keys (magic number), it is assumed that those keys were actually pressed during calibration and they are merged into the next highest bin. (Both the nearby bin merging and this outlier detection can be de disabled.)
My approach is not nearly as proven in practice as pandrew's, and I am still considering some ways to enhance it, but I
believe it to be theoretically more robust, and it is definitely faster. However, due to the different calibration levels, the magic offset applied at the end (to avoid phantom presses) needs to be re-discovered for each keyboard type. With the F62 and F77 keyboards it seems to very forgiving (at least at the present age of the keyboards), but we had to reduce it somewhat for Muirium's AT keyboard to register keys reliably. (In retrospect, I should have anticipated that since I am looking for the edge, instead of the middle, of the range of uncertainty, and the aggressive bin merging results in larger bins).
I have done numerous other tweaks as well like saving calibration to EEPROM and using it to detect keys pressed on power up, in which case calibration can be skipped and the keys can start registering immediately. (Without this firmware keys pressed on power up tend to calibrate such that they will never be seen as pressed, since the assumption is that no key is pressed during calibration. I do manage to detect that fairly well, but then those keys will still have "random" calibration since the true idle threshold can't be measured.)
Anyway, having a more powerful controller is exciting, and I am also interested in porting my firmware to support it (although it means I have to largely reimplement the USB stack to work cross-platform). Everything is GPL licensed so you may also take the matrix calibration code from either my or pandrew's firmware as you wish; both have some lines of inline assembler related to the actual scanning, but the calibration parts are portable C.
Also, in case anyone actually read all the technical stuff above, I'm definitely interested in hearing ideas about how to improve the calibration. In particular, I would love to get rid of the magic threshold offset, but looking at the values available by calibration, it seems like that info might not be available. (I have two preliminary ideas pending implementation: one would be to do one round of interactive calibration to find and save the offset by having the user press and release two keys with an unpressed key in the middle, and then see the effect on that middle key. The other would be to see if an always-pressed pad has this effect on its adjacent keys, but I doubt it since there isn't a flipper.)
Links:
edit: Re. utility, it is using a generic USB HID endpoint. The source file is util_comm.c, and it is somewhat specific to the LUFA library used by QMK for AVR microcontrollers. I have theoretically made a compatibility layer in my firmware, but TBH I have not been able to test it in practice (I had some issues getting it to work with Windows, and other issues building the utility for Mac). Also, the utility has a hardcoded USB vendor and product id and does not recognise the keyboard with any other ids. The utility's source codes are in both QMK firmwares linked above, in the directory keyboards/xwhatsit/util. My QMK version is using the newly-registered 0x4704 product id, pandrew's is using some repurposed id that seems to be common in unofficial firmwares, so even though the protocol is technically compatible, you need to build the utility for the specific id.
