Dvorak Hardware Keyboard by Reflashing the Framework’s Embedded Controller

Context

I use the dvorak keyboard layout for reasons¹. On my Ergodox, I’m able to set the keymap in hardware, so the experience is pretty much flawless. C is C is C, everywhere… it just happens to be up from my right middle finger, as opposed to somewhere down for my left hand. On my laptops, though, it’s an entirely different ballgame. Most things work, but anything being done inside of a VM or before the OS boots means I’m back in qwerty land. These things alone aren’t the worst, but the most annoying things are the key vs keycode issues for shortcuts that many apps deal with.

But… I have a Framework laptop. They use a modified version of the base ChromeOS Embedded Controller, which is open source. I can change that, right?

Yes! And thankfully, a ton of great work has been done by Dustin Howett in both tools to reflash the EC, and in information (Dustin seems active in the Framework community when anyone is messing about with this as well).

For more information about what these tools actually do, check out Dustin’s blog and github. In this post, I’ll just give a very quick tl;dr for anyone who wants to make use of the tools to modify their keyboard layout in any way (and will give the exact code changes necessary for dvorak with caps/esc swapped). Some of these instructions come straight from the aforementioned blog post, so huge props again to Dustin Howett.

Take note: I did this first on an 11th gen intel main board (hx20) that I had laying around because my partner upgraded from it to the AMD main board, and then did it on my 13th gen intel main board (hx30), so I can say this process works for those. I don’t see why the AMD board would be any different, but that testing will come at a later date.

Steps

1. Install the necessary dependencies; in debian it was apt install build-essential libftdi1-dev gcc-arm-none-eabi libftdi1. n.b. on Dustin’s blog, he mentions that a GCC version of 10 or below is necessary to not brick the device. The bug that caused this has been fixed in the framework repo, so as long as you clone from there, this is fine. I did this with GCC version 12 with no issues.

2. Clone the repo: git clone https://github.com/FrameworkComputer/EmbeddedController ec

3. Find the file keyboard_customization.c in build/hx20 for 11th gen boards, or build/hx30 for other intel boards, and modify the scancode_set2 variable to match your heart’s desire. The hex numbers here are the make keycodes from scancode set 2, which can be found in a number of places online. The easiest I found to read was from a university course in Alberta (Thanks prof Amaral!). The general idea is as follows: Say you want your laptop to register the esc key when you hit the caps lock key. You would find esc scancode (76) and the caps lock scancode (58), find the caps lock scancode in the variable (0x0058), and replace it with the scancode for esc (0x0076). Put the 0x0058 scancode where the old 0x0076 scancode was to swap them.

For a full dvorak with caps/esc swap, here is the final code variable:

uint16_t scancode_set2[KEYBOARD_COLS_MAX][KEYBOARD_ROWS] = {
    {0x003b, 0x007b, 0x0079, 0x0072, 0x007a, 0x0071, 0x0069, 0xe04a},
    {0xe071, 0xe070, 0x007d, 0xe01f, 0x006c, 0xe06c, 0xe07d, 0x0077},
    {0x0052, 0x0070, 0x00ff, 0x000d, 0x000e, 0x0016, 0x0067, 0x001c},
    {0xe011, 0x0011, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000},
    {0xe05a, 0x0029, 0x0049, 0x000c, 0x0076, 0x0026, 0x0004, 0xe07a},
    {0x0015, 0x004c, 0x0006, 0x0005, 0x0044, 0x001e, 0x0041, 0x0058},
    {0x0042, 0x0022, 0x0043, 0x0035, 0x002e, 0x0025, 0x004d, 0x003c},
    {0x003a, 0x0032, 0x0023, 0x002b, 0x0036, 0x003d, 0x0034, 0x0033},
    {0x002a, 0xe072, 0x005d, 0x002d, 0x0009, 0x0046, 0x0078, 0x0031},
    {0x0059, 0x0012, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000},
    {0x001d, 0x007c, 0x0083, 0x000b, 0x0003, 0x003e, 0x0021, 0x002c},
    {0x0013, 0x0064, 0x0075, 0x0001, 0x0051, 0x0061, 0xe06b, 0xe02f},
    {0xe014, 0x0014, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000},
    {0x001a, 0xe075, 0x0054, 0x0007, 0x0045, 0x004b, 0x004a, 0x001b},
    {0x004e, 0x005a, 0xe03c, 0xe069, 0x005b, 0x0066, 0x0055, 0x0024},
    {0x006a, 0x000a, 0xe074, 0xe054, 0x0000, 0x006b, 0x0073, 0x0074},
};

4. Build it: make BOARD=hx20 CROSS_COMPILE=arm-none-eabi- -j

5. Download Dustin’s ectool from the releases page– I did this with version v0.1.0.

6. Unzip the ectool onto a fat32 formatted flash drive, and stick the ec.bin file from build/hx20/ or build/hx30 right next to it.

7. Restart, spam F12, boot from the usb

8. Make a backup with ectool flashread 0 524288 fs0:\ec-backup.bin

9. Run ectool reflash fs0:\ec.bin. If the file can’t be found, check other fs’s– on my intel 13th gen the thumb drive was actually fs1.

10. Hopefully after a minute you get a message saying to run ectool reboot– and hopefully when you get back into your OS, you have dvorak without needing to apply any keymaps!

I am so happy this worked and that it was relatively easy– things like this are the reason companies like Framework or MNT exist. I’m glad to support both of them, and hope to be able to for years to come.