New port: ErgoDox

Plugin name: Kaleidoscope-Hardware-EZ-ErgoDox
Author: @algernon
Source URL:


This isn’t a plugin per-se, rather a port of Kaleidoscope to the ErgoDox (the ErgoDox EZ in particular, but should work on original ErgoDox too; it does not support the Infinity ErgoDox). While it will run on more recent versions of the EZ (such as the Shine), the additional features - such as the LED strip - are (not yet) supported.


Everything on the original ErgoDox should work, including the status LEDs. It is in a pretty good shape, so much so that I’m using it at my day job.


Love it! How is the keyswitch geometry defined?

14x6, same matrix layout as with QMK:

Does this make an OLKB port easier now?

I hope so. OLKB port should be even easier because there is no IO expander in use there.

1 Like

OMG thanks for this. I wired my Dactyl to the Ergodox EZ spec, so I was able to flash it with Kaleidoscope today.


As of today, I’m using the port on my EZ at work. There are a number of things that could likely be improved, but it should be ready for real, day-to-day use now.

For anyone interested, my EZ sketch is at:


Hello @algernon. Do all Kaleidoscope plugins work? (Except perhaps for the LED stuff?)

Yes, all plugins save the LED ones should work just as well as they do on the Model01.

1 Like

Shouldn’t these lines:

#define COLS 6
#define ROWS 14


#define COLS 14
#define ROWS 6


No, the ErgoDox is wired like that, a bit rotated, because we store each row in an uint8_t. If it was wired regularly, we’d need an uint16_t, or a very different scanner and matrix processing method. This may not be the most intuitive thing, but having the hardware wired this way made the firmware simpler.

(Every other firmware - QMK included - that supports the original ErgoDox and the EZ does this the same way, because that’s how the hardware was set up.)

1 Like

To further clarify, this was done for the same reason as the Model01 having the thumb arc on the seventh column, instead of its own row, among other things.

1 Like

Arguably, we should be using words other than ROWS and COLS to make this more intuitive and a non-issue.

1 Like

But ROWS and COLS are the intuitive names for the dimensions of a matrix layout. This really isn’t a problem. I was just curious. Anybody digging this far deep should be able to accept the explanation that it is based on the internal wiring.

Is this kind of row/col addressing a must for this kind of hardware or using Kaleidoscope, or is it just a convenience? If a keyboard is created where the number of keys doesn’t lend itself to such rectangular addressing, could Kaleidoscope be similarly extended to such a keyboard or not?


You can always XXX out a few keys from the matrix. The ErgoDox port does that, and so does the Raise, and the Shortcut. In general, to make a port a lot easier, you’ll want to arrange keys into a rectangular matrix. That should be possible with almost any shape, at the cost of nulling a few keys out.

IIRC there are hardware reasons for this too, but that’s a few levels deeper than I’m familiar with =)

1 Like

Ah yes I should have noticed this since the number of keys on the ErgoDox 76 ≠ ROWS 14 × COLS 6.

Anyhow re this line is there a particular reason you left out k50 and started at k51?

k50 would have been the Key_NoKey to the right of k40. :slight_smile:

FWIW, the ErgoDox plugin transitioned to the more Kaleidoscopic rXcY naming scheme since then, which I think is a bit clearer.

Yeah but the corollary question would obviously be: what is the problem with mapping the thumb keys anywhere on that logical column… Whether 1-6 thumb cluster with 0 as XXX or 0-5 thumb cluster with 6 as XXX it doesn’t make any difference does it?

Ah I didn’t realize I was looking at an old version of the file.

My assumption is that this is because it was easier to lay out the hardware this way, and the matrix - obviously - matches the hardware. But like I said before, this is an area where I have no experience yet.