Skip to content

Instantly share code, notes, and snippets.

Last active July 19, 2023 00:21
  • Star 19 You must be signed in to star a gist
  • Fork 6 You must be signed in to fork a gist
Star You must be signed in to star a gist
What would you like to do?
Instructions on how to get a Plover keymap working with NKRO on ErgoDox keyboard.

Plover is an awesome open source stenography program, but to run the software you need an NKRO keyboard. The ErgoDox keyboard can be made to run in NKRO mode by following these steps.

Install dependencies

These instructions are based on this document, which assumes you're using Windows. I'm using a mac, and I had to download and install the CrossPack for AVR Development before the build process worked.

Download the source

The NKRO firmware and Plover keymap can be found in the simon_layout branch of @shayneholmes fork of tmk_keyboard. Get the source:

git clone
cd tmk_keyboard
git fetch origin
git checkout -b simon_layout origin/simon_layout 

Build the firmware

cd keyboard/ergodox
make -f Makefile.pjrc clean
make -f Makefile.pjrc plover

The keyboard/ergodox directory should now contain ergodox_pjrc.eep and ergodox_pjrc.hex files.

Put the firmware on the Teensy chip

The following steps are copied from steps 13-21 from the ErgoDox assembly instructions:

  1. Connect the ErgoDox keyboard to your computer via USB.
  2. Launch the Teensy loader app.
  3. Enable “Auto” mode in
  4. Drag the .eep file onto
  5. Press the reset button on the Teensy chip. (You may see a dialogue box. That’s fine. After this step, “auto” mode will be disabled)
  6. Drag the .hex file onto
  7. Enable “Auto” mode in
  8. Press the reset button on the Teensy chip. (You’ll see “erasing” then “programming” progress bars, followed by “Reboot Ok”)

Toggle NKRO-mode and Plover layout

NKRO is enabled by default. You can toggle the feature off and on by pressing shift-shift-N (i.e. press and hold the left and right shift keys, then press the N key). Use this NKRO test widget to confirm.

The Plover keymap looks like this:

Plover keymap

You can toggle the Plover layer on and off by pressing the FN5 key (here it is in code). That's the left-thumb key above the "O" key in the diagram above.

If any of these steps are unclear or incorrect, please feel free to fork+edit this gist. Thanks to Shayne Holmes for providing the Plover keymap and for answering my questions. -- Drew Neil

Copy link

Peeja commented Apr 23, 2014

Huh. I thought USB couldn’t support >6KRO. How does it get around that?

Copy link

No clue how tmk's firmware enables NKRO over USB, but I can confirm that it does work! Also, a recent commit removed the requirement to turn on NKRO by hitting shift+shift+n and defaults it to be on at boot.

Also, I used this tap to install avr-libc on OS X:

Copy link

ecerulm commented Mar 28, 2015

USB can support NKRO but keyboard manufactures usually only implement the USB HID profile with the 6key+modifiers because that is the only report structure supported at low speed USB and to make life easier for the BIOS manufactures (the reports are easier to parse). If the keyboard supports full speed USB and send the reports for NKRO and the operating system supports them you can have NKRO over USB. But the support for NKRO over USB is rare (in mainstream keyboards)

Copy link

I've added the Plover layer to the QMK firmware fork that I'm working on. (QMK is a fork of TMK with a bit different structure, originally designed for the ortholinear keyboards like Planck and Atomic but also ported for the ErgoDox EZ.)
Currently its in the default keymap, but I'll probably be moving it to its own file before submitting a pull request upstream.

Copy link

@nelstrom -- looks like the image link for "The Plover keymap looks like this" is broken -- would you be willing to fix that?

Copy link

the first command where it goes:
git clone

should be:
git clone

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment