Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
This branch is 66 commits ahead, 73 commits behind cub-uanic:master.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

TMK Keyboard Firmware for Ergodox – Neo2 Edition

This is my fork of the popular TMK Keyboard Firmware Collection. Actually it is built upon cub-uanic’s adaptation for the Ergodox. I use Neo2, this is my take at an Ergodox layout most suited for that.


I like thumb keys. I like them a lot. The main task I use them for is modifiers.
This means moving Shift, Mod3/Mod4 (Neo stuff), Ctrl, Alt and Super there.
Because I use i3 as my window manager and rely heavily on the Super modifier, it has to be present on both thumb clusters. That means Ctrl and Alt are not.

Another thing I wanted to modify compared to the “original” Ergodox layout was the F keys. I want them to be on the default layer. As Neo2 has built in Navigation keys, I used the keys in the bottommost row and in the topmost row of the thumb clusters. The latter I can‘t reach without huge stretching anyway.

Gaming is a thing I often do in my spare time. For some of those pesky buggers, I have to make compromises that result in extra layers (see below).


The firmware has 4 “main” layers at present. More information including the actual keymaps can be found in keymap_neo.h.

In addition, each layer has a toggle key for Layer5 that hosts some media keys, a teensy key and my very own special macro that is intended to switch computers on my kvm switch. And I added some roll call macros for my favorite MOBA, Smite :)

Recently I also added F15 through F24 keys to Layer5. I have a programmable mouse and needed a comfortable way to map all the extra buttons to keyboard buttons without interfering with anything else. Turns out that the upper half of function keys are pretty much unused.

Layout View

Keyboard Layout Editor link

The layout on the image is as follows:

| Layer0            |
|            Layer3 |
| Layer1            | 
|       Layer5      |

Blank Layer1/3 Slots means the key is the same as on Layer 0. Blank Layer5 slots are actually empty. Layer2 is basically Layer1 with QWERTZ letters. See below for more information.

Layer0: Neo2

Standard bread and butter layer for general purpose Neo ownage :)

Includes non-standard F13 and F14 keys for use as hotkeys.

Layer1: gamer’s Neo2

This layer has the left Shift thumb key replaced with space bar. The Shift keys move to the dead key locations on the outmost keys of the bottom row. Extra CTRL keys added below them. This as closely as possible mirrors standard keyboard key locations in order to have games usable that don’t allow (re-)mapping of certain keys. This mostly happens with Shift.

Additionally, Mod4 is replaced with a Layer4 toggle key. Layer4 has most of the features of Neo2’s software Layer4 rebuilt in hardware. This is, again, to increase compatibility with certain pieces of software.

Layer2: poor man’s QWERTZ

Sometimes, you need all of your keys in QWERTZ-like locations. This layer allows you to do that without switching the OS’ keyboard layout. Also, hardware Layer4 again.

Layer3: poor man’s Neo2

Last but not least, the “I can’t change the computers keyboard layout but I can’t be arsed to type QWERTZ” layer. Within the limitations of the crappy default German layout, this forms a pretty usable hardware implementation of Neo2.


I re-purposed all of the three default, right-hand side, LEDs. The topmost formerly known as num lock one now is caps lock. This is mostly because my KVM switch flashes this one in command mode. The other LEDs indicate the currently active layer:

  • no LED: Layer0
  • middle LED: Layer1
  • bottom LED: Layer2
  • middle & bottom LED: Layer3

Firmware Download

You can find the blobs for the latest stable version under releases.

Building from Source

  1. Do the prerequisite stuff in the build doc.
  2. git clone
  3. cd tmk_keyboard/keyboard/ergodox.
  4. make clean, just to be sure.
  5. KEYMAP=neo make -f Makefile.pjrc.
  6. Either flash manually using teensy loader or (with teensy_loader_cli in your PATH) run KEYMAP=neo make -f Makefile.pjrc teensy.


  • Shift + Mod4 + <key> sucks. Granted, that pretty much only applies to Shift + arrow keys and Shift + Insert, but it really sucks.
  • Ctrl + <left hand side key> requires both hands. But I can’t swap Ctrl and Alt or Ctrl + Shift + arrow keys becomes my new worst nightmare with 3 keys to press simultaneously on the left thumb cluster.


TMK Keyboard Firmware for Ergodox – Neo2 Edition






No packages published


  • C 92.0%
  • Assembly 3.8%
  • C++ 2.7%
  • Python 0.7%
  • HTML 0.6%
  • Makefile 0.2%