Porting Kaleidoscope to other hardware

As someone who’s lucky enough not to suffer from any RSI pain, I’ve been thinking about trying an ortholinear keyboard, but even though I’ve never tried it, I’m sure I want some of the features that I think are unique to Kaleidoscope, and I have no idea what it would take to get it to run on a Planck (for example).


I built an Atreus while waiting on my M01, and am now contemplating figuring out what it would take to be able to run Kaleidoscope on the Atreus. The underlying chip seems to be the same (atmega32u4), so I think it should be possible, in theory.


Porting Kaleidoscope to other hardware is very doable. Anything based on a 32U4 is…not trivial, but not bad. The Planck and Atreus are both candidates.

Everything you’d need to customize ought to live inside a Kaleidoscope-Hardware-Something plugin.

https://github.com/keyboardio/Kaleidoscope-Hardware-Model01 is ours

This is the API you’d need to implement:

This is a port to other hardware:

Thanks, and for splitting the thread - I didn’t mean to hijack it. I had found the first, but not the second - having another port example to look at would be extremely helpful I’m sure.

I’m a software dev by profession, and my husband’s an electrical engineer, so I’m hopeful we can figure it out without having to ask too many questions - I don’t want to distract you or Algernon from the mainline Kaleidoscope stuff.


Ask tons of questions! Especially in a nice, logged medium like this forum site.
Every question answered in public is one that never ought to have to get asked again.

(Be patient if replies are slow are incoherent. Both @algernon and I have infants at home :wink:


Do ask questions! Our twins distract me enough, good questions help me focus. :wink:

1 Like

How many licks does it take to get to the center of a tootise pop?

Oh, sorry, you meant technical questions… Owls know this answer.


I’ll be able to tell as soon as someone ports Kaleidoscope to my tongue. Gut feeling tells me it should be around 42 licks, but your mileage may vary.


Your exposure to early 1980’s American television commercials is probably too limited for you to know that the answer is three.


Douglas Adams would say 42, but excellent guess. Mike is right, 3.


Ok, here’s a few questions…

  1. Atreus doesn’t have any LEDs. Can I just define LED_COUNT to be 0, and leave out the imports related to LEDs from the hardware .h and .cpp files? Do I still need to define CRGB(r,g,b)?
  2. There’s a column with a couple empty spots - is there something like KC_NO that I can put somewhere (KEYMAP macro?) to specify where those are? [Answering my own question, I see XXX used in the shortcut example.]
  3. Is there somewhere I need to specify which pins on the board map to which rows, columns? I see that the Model01 hardware header includes KeyboardioScanner.h, but I expect that’s not going to apply to other hardware, since it’s labeled Keyboardio vs Kaleidoscope. I found keyboardio/AtmegaScanner, but it seems to be just a stub. I’m guessing I’ll need to flesh this out?

Stuff I know I need to do:

  • define COLS & ROWS for this board [X]
  • define KEYMAP & KEYMAP_STACKED macros that fit the Atreus layout
  • map row,col to corresponding SCANBIT (once I figure out what the correspondence is!)

You should probably still define it. I’d probably recommend, at least for now, mocking having LEDs to make plugins that expect LEDs to be there not croak. But we ought to support what you’re suggesting.

XXX works. XXX is an alias for Key_NoKey, which also works.

Yes. You’ll need to write something that scans the physical map and does debouncing. If you look in the ancient git history of Kaleidoscope, you can find the code where I used to do that for the Model00s that were hardwired to an ATMega.

If that gives you trouble, poke me and I can find you sample code.

1 Like

Kaleidoscope-Hardware-Virtual is another plugin that implements the hardware interface, and it is (currently) an example of a “hardware” that doesn’t have LEDs. It has LED_COUNT defined as 0; it still defines struct cRGB and the CRGB macro (to reasonable defaults); and it accepts LED-related commands, it just doesn’t do anything when receiving them. I’d recommend that approach for hardware that doesn’t have LEDs.


I have little experience with this kind of work; is there a Getting Started / things-to-know I should gander at before attempting anything like this? I know the M01 was given extra attention to prevent bricking it which I’m guessing other boards don’t have.

My wife and I built an Iris for our daughter for Christmas. I’ll probably keep QMK on it for now, but would like to one day move to this :slight_smile:

At the moment, there isn’t. If using a compatible MCU, porting should be easy. If you have a look at the Kaleidoscope-Hardware, Kaleidoscope-Hardware-Shortcut, Kaleidoscope-Hardware-Model01 repos, you’ll see plenty of examples. If you are familiar with QMK, porting should be easy.

Except for one thing: if using a Teensy, you need a different HID library, and that, at the moment, is not possible to replace without gross hacks. We are working on that, though. If you can wait 'till early next year (or thereabouts), porting should be a whole lot easier by then, and we may even have a porting guide by then, too. It’s something we are actively working towards right now.

1 Like

Cool! I think I will wait then and be a guinea pig for the new stuff.

1 Like

There’s always the ergodone. Ergodox with arduino pro board.

I am planning to port Kaleidoscope to Teensy based keyboards (Planck and ErgoDox EZ). It might take a while until I can actually start. Currently I am in a planning phase where I try to collect all necessary information about how to do the port and how complex it will be.

Is this statement still valid?

Teensyduino looks quite promising as a basis for a teensy port. There is also a keyboard library provided by Teensyduino project. Could that be a replacement for the Arduino USB HID library currently used for the Model01?

@algernon, I read your blog entries about your attempt to port Kaleidoscope to ErgoDox EZ. Did you take parts of Kaleidoscope and stuffed it into QMK, thereby using its build system, or did you go another way (Teensyduino, etc.)?

It is tempting to take the keyboard specific Teensy matrix scanner stuff from QMK. Is that ok or is it bad practice? Are there any FOSS rules or conventions how to cite the origin of code snippets?

1 Like

I believe that to make things go, you’d have an easier time doing a straight port of Arduino to the Teensy, rather than PJRC’s Teensyduino. (A 32u4 based teensy should be able to be treated as a variant of an Arduino Leonardo)

  1. Make sure you don’t accidentally try to relicense their code under an incompatible license
  2. Always include any copyright statements from code you’re taking from elsewhere
  3. If the code doesn’t have a clear copyright and license, write the author and ask them before copying their code.
  4. Include detailed notes about what came from where in your README and commit messages. I find it very helpful to point at a specific repository and commit id when doing this. That way, I have a much easier time figuring out what came from where later
  5. By doing this, you’re creating a derivative work. That can have licensing implications. If you’re ever in the position of submitting any of this code “upstream”, be VERY clear about what came from where and what license it had.

In general:

  1. Be clear and honest about who wrote what code.
  2. If an author’s intent isn’t written down explicitly, ask them.
  3. When in doubt, don’t copy code.

It’s not valid anymore, you can do it without gross hacks. Nor am I sure that you’d need a different HID library. It is certainly easier than when I last tried it. Especially if you know what the heck you are doing :slight_smile: (I still don’t have any clue about what the Pins are and what am I supposed to do with them when porting, or how to figure out the difference between Teensy’s Pin layout and the Arduino Leonardo’s…)

TeensyDuino is… ancient. It does not support PluggableUSB, among other things. As @jesse said, a straight port is probably easier. If I started again, I would go that route, TeensyDuino was a dead-end.

I tried TeensyDuino first, but gave up quickly. It was too old. Then I took large parts of QMK and stuffed it into Arduino. That worked, but it was a huge hack.