Easy AVR USB Keyboard Firmware

From Deskthority wiki
Jump to: navigation, search

The Easy AVR USB Keyboard Firmware Project is an open source keyboard firmware and keymapping GUI for custom keyboards based on USB AVRs. It's powerful but also really easy to use.

The project is maintained by Metalliqaz and is hosted on Github. Most discussion and support occurs in a dedicated thread at Geekhack.


  • Fully programmable (of course)
  • 10 layers
  • Fn and modifier keys can be configured for normal (combination) style, toggle style, or dual-use (tap keys)
  • Rapid fire (auto-repeat) keys
  • Keys can be assigned with automatic modifiers
  • 14 firmware macros
  • 1 RAM macro, recordable on the fly
  • N-Key Rollover (NKRO)
  • 1kHz polling rate
  • Media keys
  • Mouse keys
  • Programmable LEDs
  • Backlighting effects
  • LED dimming
  • Virtual Numpad
  • Win Lock on Scroll Lock
  • Default layer selection
  • Customizable debounce algorithms and timing
  • Unlink Num Lock
  • Embedded password generator

Supported Hardware

Easy AVR will run on any Atmel USB AVR part. Currently supported hardware includes ATmega32U4, ATmega32U2, and ATmega16U2, including project boards such as the Teensy. Other parts such as the AT90USB1287 are possible.

The firmware has been ported to the following programmable keyboards:


Releases are now hosted on Github

Latest Releases

Windows users can use the stand-alone builds, which are formatted "easykeymap_windows_X_XX_XX.zip"

Developers and Mac/Linux users can use the Python source directly by downloading the source code. This requires an installation of Python 2.7 or 3.3+ (with tk support) and the setuptools package.

For example, on Ubuntu, this command will give you the basics: sudo apt-get install python python-tk python-setuptools

How To Use

  1. Unzip
  2. Run easy_keymap.exe (or 'python main.py' for the multiplatform version)
  3. Create a new layout and select your board - or- open a previously saved layout (File menu)
  4. Modify your layout by clicking a button and pressing the new key you want mapped, selecting the scancode from the menu, or using the scancode picker
  5. Save your layout (File menu)
  6. Build your firmware into a .hex file (File menu)
  7. Put your keyboard into bootloader mode
  8. Program your new .hex file using the Teensy loader for Phantom/JD40/JD45/GH36 or Flip for everything else
  9. Read the Help menu for help

Find more detailed instructions in the README

Frequently Asked Questions

Q. I get a runtime error, "The program can't start because MSVCP100.dll is missing from your computer."
A. Install the Visual Studio 2010 redistributable package for x86 from microsoft.com.

Q. Hey, my number row is mapping to numpad and I didn't tell it to do that!
A. TKL boards have Virtual Numpad on by default. Either turn off NumLock or disable Virtual Numpad.

Q. Why is my numpad is sending the wrong scancodes?
Q. Why won't the Numlock LED turn on?
A. You have "Unlink Numlock" enabled. Disable that setting to get normal numpad scancodes.

Q. Why doesn't my Windows key work?
A. Turn off Scroll Lock or disable the "Win Lock on Scroll Lock" setting.

Q. Why does my QFR turn on the Windows Lock LED when Scroll Lock is pressed?
A. Disable the "Win Lock on Scroll Lock" setting.

Q. I lost all my configuration settings!
A. You probably installed a new version of the firmware. If the firmware detects an different version of EEPROM data, it erases everything and installs defaults to be on the safe side. The settings are easy to change, just put them back the way you like.

Q. I bricked my keyboard! What are you going to do about it?
A. I'll help you fix it if I can, but I don't owe you anything. I've programmed all sorts of boards with all kinds of firmware (both good and bad) and I've never bricked anything. Just press the reset switch. If you really managed to brick it, it's your own fault.

Q. My computer acts weird when the keyboard is plugged in, or the keyboard just isn't recognized by some of my computers.
A. Try disabling the advanced USB interfaces in the config console. This will limit you to 6KRO, but it should improve compatibility with quirky hosts.

Q. If this software is supposed to be so "easy", why do I have to use Flip or Teensy Loader?
A. It has to do with the bootloader software that's already part of the supported boards. The short answer is that a goal of the project is to be easy to setup and use with good compatibility, and that means using the "OEM" software loading methods.

Q. Can you add a swap Caps/Ctrl (or Backspace/Backslash, Esc/grave, etc.) feature?
A. Those are great features on a normal keyboard. However, this firmware is used on programmable keyboards. The way to implement those features is with alternate layers. You have 10 to work with.

Q. Why am I getting unwanted extra characters while typing in Linux when pressing the NON_US_HASHMARK_AND_TILDE and/or the BACKSLASH_AND_PIPE key?
A. The bit-packed vector that is used for NKRO support is not well supported in linux when using those keys. I think there may be some kind of translation layer for internationalization that is causing keys to be virtually lifted and redetected even though the user holds the key steady IRL. To work around this you can use the "Basic keyboard" config option to disable NKRO and use 6KRO instead.

Q. The F13-F24 keys don't work.
A. The NKRO field is not wide enough to fit those nonstandard scancodes. AVR microcontrollers are extremely limited in memory and this was a compromise that had to be made. To use those scancodes, disable NKRO.

Q. The BOOT key doesn't work.
A. This usually means that the firmware doesn't have the correct address of the bootloader. Make sure the "Teensy" config item is set correctly for your board. A. On boards that use the Astar microcontroller, this is a known problem. The custom bootloader on the Astar requires a boot key in a specific place that is not reserved by the EasyAVR firmware.

Developer Notes

Requirements: Atmel Studio 7 and Python 2.7 or 3.3+

The firmware and keymapper are released under the GPL2 license.

All development activity is managed at Github

ToDo and Requests

Users, edit this page with requests.

  • GUI Layout Editor for custom layouts (similar to keyboard-layout-editor.com - or by importing the RAW data from there, would save you from adding more of the existing layouts)
  • Support KMAC Mini
  • Support Viper
  • Support Lightpad
  • Support Lightsaver
  • Support KC60
  • Support RS60
  • Support Nerd60
  • Support TMK64 Alps