Easy AVR USB Keyboard Firmware

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.

Features

• 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 time
• 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:

• Epsilon [Tested working]
• Qazpad (Tau) [Tested working]
• CompactTKL (Zeta) [Tested working]
• Sigma [Tested working]
• Phantom [Tested working]
• HID Liberation Device (custom controller for the Filco MJ2) [Tested working]
• Kitten Paw (custom controller for the Filco fullsize)
• Pegasus Hoof (V1/V2) (custom controller for the Filco MJ2)
• Black Petal (custom controller for the Rosewill RK-9000) [Tested working]
• Frosty Flake (v1/v2) (custom controller for the Quickfire Rapid)
• Ghost Squid (custom controller for the Quickfire XT)
• GH60 (rev.B, rev.CHN)
• GH36
• GHpad
• KMAC (OG KMAC / KMAC 1.2 / KMAC 2) [Tested working]
• JD40 (Smallfry)
• JD45 (v1/v2)
• Orion [Tested working]
• Octagon
• Atreus
• Planck PCB
• SixShooter (custom controller for CM Switch Tester)
• Techkeys Card
• Techkeys ThreeKeyBoard
• Techkeys SixKeyBoard

Downloads

Stand-alone Windows Builds:

Latest Version:

easykeymap_windows_2_04_03.zip

Previous Versions:

easykeymap_windows_2_03_01.zip
easykeymap_windows_2_02_02.zip
easykeymap_windows_2_01_14.zip
easykeymap_windows_2_01_13.zip
easykeymap_windows_2_01_12.zip
easykeymap_windows_2_01_11.zip
easykeymap_windows_2_01_10.zip
easykeymap_windows_2_01_09.zip
easykeymap_windows_2_01_08.zip
easykeymap_windows_2_01_07.zip
easykeymap_windows_2_01_06.zip
easykeymap_windows_2_01_05.zip
easykeymap_windows_2_01_04.zip
easykeymap_windows_2_01_03.zip

Multiplatform:
(Windows/Mac/Linux, requires Python 2.7 or 3.3+)

Go to the Github repository and use the "Download ZIP" button.

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. 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.

Developer Notes

Requirements: Atmel Studio 7 and Python 2.7 or 3.3+

The firmware and keymapper are released under the GPL2 license.

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
• USB HID Boot keyboard doesn't work (eg. BIOS screen)