Getting the Model 01 to work correctly on a Mac in EFI boot mode

If I try to use the KB in EFI (e.g. when the disk is encrypted you must enter your password before macOS can boot) it does not work.
Any ideas why? Is there a workaround?

As far as I know it’s a common issue for homebrew USB keyboards (QMK, TMK etc).

Thanks, Slava

Are you using the factory firmware, or the most recent from git master? The most recent should not have this issue anymore.

I use released firmware (not from git master), but I updated it last time few weeks ago.

Is there any schedule about releasing this from git master?

Just upgraded to 1.92.0-beta. I’ll let you know how it works now.

I just ported my KB layout to the new version, but I have a few questions.
There is an enumeration:

enum {

Is it related to the keyboard protocol switcher?

USE_MAGIC_COMBOS({.action = toggleKeyboardProtocol,
// Left Fn + Esc + Shift
.keys = { R3C6, R2C6, R3C7 }

As far as I understand this enum defines the name of the magic combo above. If I add a new combo, I should add a new member to this enum. Is it correct?

There is also another question. I want to add a lock light that indicates what keyboard protocol is active. Is there a way to get the current keyboard protocol?

Yes, it is. Turns out we’re not using it, I’ll fix this, thanks for noticing!

You can add one, but it is not strictly required. You can just add another entry, like this:

USE_MAGIC_COMBOS({.action = toggleKeyboardProtocol,
 .keys = {...}
{.action = someOtherAction,
 .keys = { ... }

The name is most useful when you have the same .action for multiple combos, and want to do different things in the action handler, based on what the magic combo index is. A name helps there, so you don’t have to use magic numbers. Other than that, it’s not particularly useful - but does make the code somewhat clearer, I think.

BootKeyboard.getProtocol() will return either HID_BOOT_PROTOCOL or HID_REPORT_PROTOCOL, you can light up stuff based on that.

1 Like

Just checked the KB in the boot mode and it works!

But there is still one more question: it turns out that the mode is controlled automatically.

I chose to highlight the left Fn white when it’s in the report protocol mode and blue when it’s in the boot protocol mode.

When the os is booted and I try to switch the protocol the Fn key simply blinks blue and turns white again. When the EFI is active all is vice versa: the key blinks white and turns back blue. Am I missing something?

Is there a way to control this mode manually? It’s not an issue at all, but still.

Yeah, OSX does that, it’s pretty much the only major OS that works according to the USB spec. I’ll explain below how, and why.

For OSX, no, there is not, unless you want to lose NKRO completely.

The USB spec says that keyboards should start in report protocol mode when connected, and operating systems should request boot protocol when they need that. OSX does exactly this.

The reason you see rapid change to report/boot protocol is because the mode switch under the hood disconnects the keyboard, and reconnects with the other protocol set by default. OSX then tells us to use the appropriate one, and the firmware obeys. If we didn’t do that, then the keyboard either wouldn’t work in EFI, or it would be always in boot protocol mode.

Hope this helps!

1 Like

Yes, it helps a lot, thx!


My kbio doesn’t work when. I’m in the isx boot login screen. It’s the password request screen that appears when you reboot or cold start the machine if the hd is encrypted. The kb leds work but whatever symboi i press does noit appnar in the password prompt.

Can somebody help? Has it happened to anybody else?

This is a known issue, which we are working on. The problem is that the Model01 firmware does not support the “boot protocol”, only the more advanced N-Key Rollover. I have a set of patches that fix this, but they haven’t been merged yet (the most recent version of the patchset is a few hours old).

If you are comfortable with git, I can walk you through the process of applying the patches. Or, I can prepare a factory firmware, with the boot protocol patches already applied.


No need. If its a known issue I can wait. But just to learn a bit about the internals of kaleidoscope, can you link the github commit so I can dig around?

Sorry for the late reply, I was away these past few days.

There are a few pieces of the puzzle that implement this, I collected them in my work log.

Has this patch been applied yet? I’m experiencing this issue with my factory-fresh firmware.

(And apologies for resurrecting such an ancient thread.)

The patch is part of the git repositories, but I’m not sure that the factory firmware has it or not. If it doesn’t work, chances are, it doesn’t. As such, I’d recommend compiling the latest factory firmware, and flashing it - that should solve the issue.

I loaded the most current firmware, and the issue is resolved. I can now use my Model01 on the password screen.

Many thanks!