Keyboard Builders' Digest / Tips & Tricks
Square or round-robin matrix
Let me introduce the square or round-robin matrix (aka Charlieplexing for keyboards) – a very tricky one promising 380 keys with a single Pro Micro.
Published May 1, 2022
After the (Japanese) duplex matrix, let's cover another one utilizing the voltage drop across diodes to avoid ghosting: the square or round-robin matrix with the promise of 380 switches handled by a single Pro Micro.
Attention! To avoid ghosting, electronic components have to be chosen very carefully!
Apparently, if this would work flawlessly in all situations, bidirectional scan would be already part of QMK and all the other keyboard firmware I guess.
The fact that this isn't the case (except PRK) means you have to keep in mind some limitations when using this matrix.
Regardless, even if you can't avoid ghosting entirely in your project, this matrix approach is absolutely fine for e.g. macropads – when you want to minimize the number of pins used.
Caveats
Let's start right with the caveats since I got plenty of questions and suggestions after posting the previous duplex matrix write-up.
- The threshold voltage for LOW state should be reached with only two diodes this time (unlike with the duplex/double matrix where three diodes had enough cumulative voltage drop to prevent false positives).
- So you have to carefully select electronic parts.
- You may use two diodes with each key in certain scenarios (e.g. Atmega32u4 at 5V).
- Fully eliminating ghosting isn't possible with some controller vs logic level combinations (e.g. RP2040 at 2.5V).
- And you probably shouldn't use this for wireless builds either: As ZMK's petejohanson points out, these matrices may force a constant scan, which has a significant impact on battery life.
Other than that, feel free to experiment with this matrix. :D
Basic concept
In the Round-robin matrix, we place two switches between each pair of pins (in all combinations).
There are no dedicated column and row pins either, which may be confusing if you're used to basic keyboard matrices. Each pin behaves both as col and row pin at some point during the matrix scan.
Don't panic if this doesn't make much sense at this point, we are going to explain all the details.
Naming conventions
Charlieplexing? Square matrix? Round-robin matrix? Yet again, naming of this kind of matrix may be confusing.
Apparently, this is an adaptation of Charlieplexing for keyboard matrices (which itself has alternative names like tristate multiplexing, reduced pin-count LED multiplexing or complementary LED drive) – however, I've never really heard any of these expressions with regards to keyboards.
Ikejima, whose great matrix classification is actually the main source and reference for this write-up, calls this the Square matrix – simply because we can scan N-square keys with this method. (Well, almost: N*(N-1) or N2-N.)
Another name is round-robin matrix, used e.g. in the PRK wiki. The term round-robin is quite apt since two switches (with opposing diodes) are placed between each pair of pins – just like contestants meet each other in a round-robin tournament.
3-pin example
To provide a relatively easy-to-understand example, let's start with only 3 pins, putting our switches between them in every possible combination:
This doesn't even resemble a proper keyboard matrix so let's look at a 4-pin one arranged into a grid:
Ghosting issue & feasibility
Unlike the duplex matrix, where three diodes ensure false positives won't occur, the round robin matrix may require very careful planning.
With the round-robin we have only two diodes so we may easily experience ghosting:
In the example above, while holding down SW1 and SW5, SW3 is registered as pressed too.
Let's see if we can eliminate this by utilizing the voltage drop across diodes.
There are all kinds of diodes with different voltage drops: the 1N4148, probably the most generic diode in this hobby, has a forward voltage drop of around 0.7-1.0V (0.72V according to some datasheets). However, this voltage depends on multiple factors like the current, temperature, etc. Other diodes have different voltage drops, e.g. a 1N4001 is characterized by 1.1V.
In hindsight, the duplex matrix was easy: by the time the signal makes its way through 3 diodes it's low enough that the GPIO registers it as off (in most scenarios).
However, we have only two diodes here in the round-robin. Let's investigate two popular controllers with some common logic levels to figure out which one work. Firstly, let's do some math with RP2040 as w0lfwood suggested last week.
RP2040
The RP2040's digital IO voltage (IOVDD) can be configured to be 1.8V, 2.5 V, or 3.3 V (table 5.2.3.4). But things are not black or white here. HIGH is not just 3.3V but a range. Similarly, LOW is not 0V but a range too. The RP2040's GPIO pin will sense 0 reliably with a maximum voltage of 0.63 V, 0.7 V and 0.8 V, respectively.
So our goal is to bring e.g. the initial 3.3V into the VIL range of 0-0.8V.
The question is: is there any chance to reach those low voltages with only two diodes (AND staying in the HIGH range at the same time with one diode)?
1.8V -> (1.8-0.63)/2=0.59. Looks good at first sight. We need at least 0.59V drop per diode, and we have 0.7-1V with the most common 1N4148 diode. One box checked. However, at 1.8V logic level, the lower threshold for HIGH is 1.17V and we are below that (in the undefined zone) with a single 1N4148 (1.8-0.7)…
So for this setup to work we need diodes with above 0.59 but below 0.63V drop… I'm not an electrical engineer, just a keyboard hobbyist, so don't ask me if this is possible in a reliable way.
2.5V -> (2.5-0.7)/2=0.9. This is the only clearly impossible combination in the studied cases. Two diodes with at least 0.9V drop are needed to get to LOW, but the minimum voltage to stay in the HIGH zone (1.7V) would allow only a drop of 0.8V…
3.3V -> (3.3-0.8)/2=1.25. We need a diode with a voltage drop between 1.25 and 1.3 (to stay above the 2V lower limit of HIGH at the same time). Hm.
Atmega32u4 (2.7-5.5V)
From the Atmega32u4 datasheet (29.2 table):
5V->VIL=0.9V, VIH=1.9V. 3.3V->VIL=0.56V, VIH=1.56V.
3.3V -> (3.3-0.56)/2=1.37. We need a diode with a voltage drop between 1.37 and 1.74 (to stay above the 1.56V lower limit of HIGH at the same time).
5V -> (5-0.9)/2=2.05. We need a diode with a voltage drop between 2.05 and 3.10 (to stay above the 1.9V lower limit of HIGH at the same time).
However, this is when you can try two diodes. E.g. many diodes have a nominal voltage drop of 1.1V, but Ikeji used 2x1N4148 with success.
Firmware
For the software part, e.g. in QMK without a custom matrix.c (or elfmimi's pull request), we can set the same pins in the MATRIX_ROW_PINS and MATRIX_COL_PINS arrays (but in different order to trick bootmagic – explained here), and utilize a matrix mask.
Check Ikeji's full example here.
Hey, you babbled about 380 keys…
Yeah. So with 18 pins of the Pro Micro we handled 81 (9x9) keys with the basic matrix, doubled that (162) with the Japanese duplex, and with the round-robin matrix we can increase that to 18x17=306.
However, by utilizing the two LED pins of the Pro Micro you get 20 GPIO pins or 10x10=100 keys (basic matrix), twice as much with the Japanese duplex (200), and 20x19=380 with Charlieplexing.
At this point I should probably include a nice photo of a kick-ass 380-key macropad but I'm not gonna try to build anything like this, sorry. :D
Outro
Wow, you made it to the very end! Congratulations and thanks for reading. I hope this wasn't entirely useless.
Your reward is a dad joke:
"What did the fish say when he hit the wall? Dam."
Credits & Resources
Many thanks to Ikeji for all the awesome resources and his assistance.
- (Japanese) duplex matrix or double matrix
- Petejohanson's comment on duplax vs wireless builds
- Charlieplexing
- Ikejima's keyboard matrix classification
- PRK firmware – Keyscan matrix
- Round-robin tournament
- RP2040 datasheet
- ATmega32U4 datasheet
- elfmimi's QMK pull request
- QMK setup with custom matrices by Ikejima
- QMK code example by Ikeji
Published on Sun 1st May 2022. Featured in KBD #76.
Related
JESK56
T. G. Marbach's JESK56 is a diodeless 56-key ortholinear keyboard, using a single RP2040-based microcontroller thanks to some fancy math and graph theory.Low Power Improved Square Matrix
This post by wolfwood proposes a modification to the improved square keyboard matrix in order to support a low power wake-on-keypress mode, which has been a deficiency of this design until now.
Improved square matrix
The improved square matrix is actually a round-robin matrix handling the same number of switches – but with less diodes.
Kazik
Kazik is a cute 30% keyboard by monokēēbs – with versatile PCB, XIAO RP2040, and Japanese duplex matrix!
The (Japanese) duplex matrix
There are two completely different keyboard matrices referred to as duplex matrix. Let's examine the Japanese one, which makes possible to handle 160-200 keys with a single Pro Micro.