Qukeys issue after updating to Kaleidoscope 1.99.4?

I am an happy user of Model01 for more than two years, the only issue I had so far was fixed by cleaning a couple of switches with alcohol.

However, not so long after upgrading from 1.99.3 to 1.99.4 and 1.99.5, I started to notice that the keyboard sometimes got stuck and needed to be unplugged/re-plugged to be working again.

This does not looks like an hardware issue as all the switches have the same consistent behavior with the hardware test mode, the issue does not seem to be due to a flaky USB connection on keyboard side as unplugging the other end of the USB (on the computer side) made it work again.

When this happens, I noticed that:

  • the blue “boot greeting” on the led key is triggered.
  • sometimes it’s like a shift-key is held when typing on the laptop keyboard, but no shift key is held down, and I don’t have any caps-lock key in my mapping
  • the “active modifier color” (LED-ActiveModColor) is behaving as expected and lights modifier keys (or their qukeys alternative).
  • modifying Qukeys settings did not help
  • the keyboard does not respond to any command on serial port.
  • no key mapping set in any layer can be triggered (it’s not stuck in a specific layer).

I use Qukeys on the home row, thus it’s more than likely that some Qukeys modifiers are involved, but I did not managed to reliably reproduce it, it just happens randomly between once and 5 times a day, which tends to be quite annoying (I’m using InteliJ IDE thus Ctrl-Shift-Alt+key combos are now usable).

Whenever I re-flashed a new version of the firmware, I properly reset the EEPROM setting with Chrysalis and I don’t have any custom mappings in EEPROM (thus in theory only the ones in code are used).

I’m using Arduino IDE 1.8.x to compile and flash the firmware.

However, the good news is that after reverting back to Kaleidoscope 1.99.3, I haven’t had any single single occurrence of this problem in almost a week.

My current Arduino sketch is here, there is nothing really fancy nor any custom plugin.

By looking at the source code, there are plenty of changes (500+ files changed) between 1.99.3 and 1.99.4 (which is the same as 1.99.5), thus it won’t be trivial to find what could be the issue here, thus I really wonder what could be the best strategy to identify and fix this issue.

1 Like

Thanks for reporting this issue. I don’t have any immediate ideas about the cause, but I do have a few questions that might help get us there:

  1. When the keyboard gets “stuck”, the host seems to be disconnected from it, but the keyboard itself appears to still be functioning, correct? In other words, LED-ActiveModColor is updating LEDs as if the keyboard was still functioning, but no input is received by the host?
  2. Have you tried commenting out the QUKEYS() macro from setup() and instead put the equivalent definitions in the keymap (e.g. SFT_T(F), et al)? I wouldn’t expect any differences in behaviour, but most people are using Chrysalis, and therefore the in-keymap qukeys only. The codepaths are very slightly different, so maybe there’s a bug in one but not the other.
  3. Does this always happen while you’re typing (i.e. in response to some sequence of events) or sometimes when the keyboard isn’t receiving input?

I hope we can get this sorted out; lots of bugs got fixed as part of the major rewrite that took place between 1.99.3 and 1.99.4 (which probably ought to have been a major version increase rather than a point release).

1 Like

Thanks for your very fast response @merlin !

  1. Yes, the keyboard seems to be still working, but the host does not seem to receive any input.
  2. I wasn’t aware of this variant, I will definitely give it a try to see if that makes a difference here.
  3. Yes, it’s always triggered while typing, I don’t remember it happening when not typing.

Thus as a next step I’ll try with SFT_T and similar and let you know how it goes.

Quick update after typing a week on this new version, it definitely feels better, but it does not seem to 100% solve it as I got:

  • one time keyboard completely blocked, ActiveModColor still running
  • one time the Shift modifier locked active, one keystroke on regular shift key allowed it to return to normal.

I’ll keep this post updated after further testing, at least we know it’s better than it used to.

Also, would there be an option to also allow to split right and left ALT keys with Qukeys ?
There are quite a few keyboard layouts that have a different behavior, for example I’m using the qwerty-international layout, and I know that some other layouts also have a different behavior on the right-alt key (French azerty, Japanese and Korean are the examples that come to mind).

1 Like

You can get any right side modifier like this: MT(RightAlt, X).

1 Like

I had a peek at your github sketch, and it looks like your QUKEYS() definitions are still there. If so, you might try commenting out that whole block.

Are you a very fast typist? I’m wondering if you might be getting into rollover sequences extreme enough to overflow the event queue that Qukeys uses. If so, I can suggest a change that you could try (doubling the event queue size from 8 to 16), which might be an effective workaround.

I’m still basically without ideas for what might cause the symptoms you described, alas…

I hadn’t pushed to the github repository and I only re-built it locally, which explains why there was still a QUKEYS() block. Here is the updated version that I am currently running.

I’m really not a fast typist, at best close to 60wpm. thus it would be surprising to be an issue with the Qukeys event queue size. However, that would be something worth testing. If it would be the case, I expect that the Qukeys plugin shoud probably clear the queue or drop events to provide a failsafe behavior. I saw that there are some unit tests, would it be something we could reproduce with them ?

I will continue testing for another week (I usually have time to tinker with firmware on weekends) and if the issues persist I’ll try increasing the queue size.

Thanks again for your help here, that’s really kind of you to spend time on this.

Indeed, it does. Of course, by design, it’s not expected to get that far in the vast majority of cases, so it may be rare enough that only a few people will notice if it’s buggy (as it was a few months ago).

So, after testing this over a couple of weeks, I can confirm that it’s definitely getting in the right direction, but still not perfect

  • I only had 2 times the keyboard that gets blocked with the “blue boot greeting effect”.
  • I also had a few “stuck like in caps-lock” mode, but that’s definitely less impacting.

I wonder what we could do here to properly debug what is happening, for example having a kind of keylogging with timing of the raw input (before any plugin) on the serial port would probably help here.

Alternatively, trying to use LED-Stalker plugin could maybe provide a visual clue, but at best that would only help to narrow down the keys involved and not the exact sequence with timing.

Unfortunately, debugging tools are very limited, and I still don’t have any testable hypotheses that would explain the behaviour you’re seeing. I did write a keylogger plugin a while ago whose purpose was to gather data to improve Qukeys settings, and it might possibly be useful for debugging this problem, if I update it, but I’d like to have some idea of what I would be looking for in the data before going to that much effort.

1 Like

Hi !

This has been a while since my last update.

I tweaked a bit the settings, and I am now back to getting this issue about once per day, which is definitely annoying, but it means that it’s quite likely related to timings.

I have now found a slightly better work-around than unplug-replug with the “soft reset” solution here to just reboot the keyboard when it happens: Sequence to reboot keyboard - #4 by polsonst.

The updated version of my sketch.

I also tried to do some simple serial-debugging, but it’s definitely tedious and if you have already a working (or almost working) plugin for that I’d be happy to take a look at it and give it a try.

I also tried to write a very minimal plugin (not in the current sketch) that logs to serial the timings between events in microseconds. When hitting a single key I get a rather large value about 100 000us, but sometimes get very short ones slightly less than 1000us. Given most plugins rely on the current millisecond, it could also possibly trigger a corner case.

Last but not least, when trying the hardware test mode to check for key chatter, the weird thing is that with some effort and very short keystrokes I am able to make ANY key marked as red, even the ones that are almost never used like num-lock.

Are you using a keymap in EEPROM (via Chrysalis)? I’d like to try to reproduce this issue, and I want to know I’m starting from the same firmware and keymap that you’re using.

No I don’t use EEPROM settings nor Chrysalis, I did reset it a few firmwares flashing away as I find it’s definitely confusing to me as the effective keymap is not the one in code. I can provide a dump of it through serial just to be sure if you want.

Thanks again for spending time on this issue !

I’m sorry this has taken so long; I’ve been very busy with other things. I have tried, but so far I’ve had no luck reproducing this problem. Any hints you can give me regarding what to try would be appreciated.

Hi !

Don’t be sorry, you already spent a fair amount of time on this already and it would be completely OK even if we don’t manage to sort this out. There is no expectation on my end to solve this quickly as it tends to be randomly happening, also it’s free support for a very niche (but awesome) product and use-case, so there is no reason to complain here.

Hi !

I think that I’ve accidentally found a way to reproduce this unexpected behavior:


  • the computer wakes up, which means at least one character was sent to the computer
  • the <Esc> key blinks green (boot greeting indicator)
  • no more keystrokes are sent to computer for all keys
  • I have to hit <NumPad> key to manually reboot the keyboard and make it work again.

The issue is reproducible on all keys that have QuKeys enabled, doing the same on another key does not trigger it. Also, I really don’t know how it is related to making the computer going to sleep, but at least it helps to reproduce the symptom.

When your laptop goes to sleep, does it stop supplying power to the keyboard? Are you waking it up by pressing a key on the laptop’s built-in keyboard, or on the Model01? I can’t figure out specifically what the steps are that you’re executing—sorry.

I am only using the Model01 here, it does not happen when waking up the computer by another mean like the laptop keyboard, lid or mouse.

It seems to me that the keyboard remains powered through the USB port, but how could I be sure of that ? For example plugging a smartphone on the same port stops charging it when suspending, but while supended hitting the <num> key allows to trigger my “reboot macro” without waking the computer up.
If the keyboard would not be powered at all, I don’t think it would be possible to wake the computer from the keyboard, but I could definitely be wrong here. The behavior is the same when using another USB port that has the small “battery” indicator that seems to be an “always-on” port.

Once the sketch I’ve linked above has been flashed, the steps are:

  • suspend computer (in my case it’s a thinkpad thus I can see a glowing dot), if there is an active led effect the keyb. goes dark.
  • tap quickly 2 times one of the fn keys. Interestingly if there was a led effect active it is shown briefly on the 1st tap, but then we have the glowing green esc boot sequence. After that hitting the <num> key is required to manually reboot the keyboard.

I can make a quick video/gif if needed.