Difference between revisions of "Easy AVR USB Keyboard Firmware"

From Deskthority wiki
Jump to navigation Jump to search
(Downloads: Add release 2.1.5)
 
(41 intermediate revisions by 4 users not shown)
Line 1: Line 1:
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.
+
[[Category:Firmware]]
  
The project is maintained by Metalliqaz and is hosted on Github<ref>https://github.com/dhowland/EasyAVR</ref>. Most discussion and support occurs in a dedicated thread<ref>https://geekhack.org/index.php?topic=51252.0</ref> at [[Geekhack]].
+
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 hosted on [https://github.com/dhowland/EasyAVR Github]. Most discussion and support occurs in a [https://geekhack.org/index.php?topic=51252.0 dedicated thread] at [[Geekhack]].
  
 
==Features==
 
==Features==
Line 10: Line 12:
 
* Rapid fire (auto-repeat) keys
 
* Rapid fire (auto-repeat) keys
 
* Keys can be assigned with automatic modifiers
 
* Keys can be assigned with automatic modifiers
* 14 firmware macros
+
* 16 firmware macros
 
* 1 RAM macro, recordable on the fly
 
* 1 RAM macro, recordable on the fly
 
* N-Key Rollover (NKRO)
 
* N-Key Rollover (NKRO)
Line 22: Line 24:
 
* Win Lock on Scroll Lock
 
* Win Lock on Scroll Lock
 
* Default layer selection
 
* Default layer selection
* Customizable debounce time
+
* Customizable debounce algorithms and timing
 
* Unlink Num Lock
 
* Unlink Num Lock
* Embedded password generator
 
  
 
==Supported Hardware==
 
==Supported Hardware==
Line 55: Line 56:
 
* [http://techkeys.us/collections/accessories/products/techkeys-keyboard-business-card Techkeys Card]
 
* [http://techkeys.us/collections/accessories/products/techkeys-keyboard-business-card Techkeys Card]
 
* [http://techkeys.us/products/threekeyboard Techkeys ThreeKeyBoard]
 
* [http://techkeys.us/products/threekeyboard Techkeys ThreeKeyBoard]
 +
* [http://techkeys.us/products/sixkeyboard Techkeys SixKeyBoard]
 +
* ... and many more
  
 
==Downloads==
 
==Downloads==
  
The normal download is a stand-alone build for Windows.  To obtain a multiplatform version that supports most OS (Windows/Mac/Linux, requires Python 2.7 or 3.3+), go to the [https://github.com/dhowland/EasyAVR Github repository] and use the "Download ZIP" button.
+
'''Releases are now hosted on Github'''
 +
 
 +
[https://github.com/dhowland/EasyAVR/releases Latest Releases]
  
Latest Version: [https://www.dropbox.com/s/1we2doefz6vu6sc/easykeymap_windows_2_01_05.zip?dl=0 easykeymap_windows_2_01_05.zip]
+
Windows users can use the stand-alone builds, which are formatted "easykeymap_windows_X_XX_XX.zip"
  
Previous Versions:
+
Developers and Mac/Linux users can use the Python package.  This requires an installation of Python 3.5+ and wxPython 4.0+.
  
[https://www.dropbox.com/s/6ovw9lspajiyb4f/easykeymap_windows_2_01_04.zip?dl=0 easykeymap_windows_2_01_04.zip]
+
More information is available in the [http://dhowland.github.io/EasyAVR/build/html/install.html User's Guide]
[https://www.dropbox.com/s/xvghfool2egdgv8/easykeymap_windows_2_01_03.zip?dl=0 easykeymap_windows_2_01_03.zip]
 
  
 
==How To Use==
 
==How To Use==
  
 
# Unzip
 
# Unzip
# Run easy_keymap.exe (or 'python main.py' for the multiplatform version)
+
# Run easykeymap.exe (or 'python -m easykeymap' for the package version)
# Create a new layout and select your board - or- open a previously saved layout (File menu)
+
# Create a new layout and select your board -or- open a previously saved layout (File menu)
# 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
+
# Modify your layout by clicking a button and pressing the new key you want mapped, or selecting the scancode from the selection dialog
 
# Save your layout (File menu)
 
# Save your layout (File menu)
# Build your firmware into a .hex file (File menu)
+
# Build your firmware into a .hex file (Build menu)
 
# Put your keyboard into bootloader mode
 
# Put your keyboard into bootloader mode
 
# Program your new .hex file using the [http://www.pjrc.com/teensy/loader.html Teensy] loader for Phantom/JD40/JD45/GH36 or [http://www.atmel.com/tools/FLIP.aspx Flip] for everything else
 
# Program your new .hex file using the [http://www.pjrc.com/teensy/loader.html Teensy] loader for Phantom/JD40/JD45/GH36 or [http://www.atmel.com/tools/FLIP.aspx Flip] for everything else
# Read the Help menu for help
 
  
Find more detailed instructions in the [https://github.com/dhowland/EasyAVR/blob/master/README.md README]
+
Find more detailed instructions in the [http://dhowland.github.io/EasyAVR/build/html/userguide.html User's Guide]
  
 
==Frequently Asked Questions==
 
==Frequently Asked Questions==
 +
Q. I get a runtime error, "The program can't start because MSVCP100.dll is missing from your computer."<br>
 +
A. Install the Visual Studio 2010 redistributable package for x86 from [http://www.microsoft.com/en-in/download/details.aspx?id=5555 microsoft.com].
  
 
Q. Hey, my number row is mapping to numpad and I didn't tell it to do that!<br>
 
Q. Hey, my number row is mapping to numpad and I didn't tell it to do that!<br>
Line 113: Line 118:
 
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?<br>
 
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?<br>
 
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.
 
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.<br>
 +
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.<br>
 +
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==
 
==Developer Notes==
  
Requirements: Atmel Studio 7 and Python 2.7 or 3.3+
+
Requirements: Atmel Studio 7 and Python 3.5+
  
 
The firmware and keymapper are released under the GPL2 license.
 
The firmware and keymapper are released under the GPL2 license.
 +
 +
All development activity is managed at [https://github.com/dhowland/EasyAVR Github]
  
 
==ToDo and Requests==
 
==ToDo and Requests==
  
Users, edit this page with requests.
+
Users, edit this page with requests, or start a discussion in the official Geekhack thread, or create a new issue on Github.
 +
 
 +
Note: The Github [https://github.com/dhowland/EasyAVR#supporting-custom-boards README] contains information for creating a custom layout with keyboard-layout-editor.com.  It is considered "good manners" to give this a shot first, and to provide a link to a hardware description of the new board.
  
 
* Support KMAC Mini
 
* Support KMAC Mini
Line 132: Line 148:
 
* Support Nerd60
 
* Support Nerd60
 
* Support TMK64 Alps
 
* Support TMK64 Alps
* Fix Lightsaver
+
* Support KBDfans DZ60
* USB HID Boot keyboard doesn't work (eg. BIOS screen)
 
 
 
==See Also==
 
 
 
  
 
[[Category:Keyboard modding]]
 
[[Category:Keyboard modding]]
 
[[Category:Keyboard creation‏‎]]
 
[[Category:Keyboard creation‏‎]]

Latest revision as of 21:57, 18 August 2018


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 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
  • 16 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

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:

Downloads

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 package. This requires an installation of Python 3.5+ and wxPython 4.0+.

More information is available in the User's Guide

How To Use

  1. Unzip
  2. Run easykeymap.exe (or 'python -m easykeymap' for the package 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, or selecting the scancode from the selection dialog
  5. Save your layout (File menu)
  6. Build your firmware into a .hex file (Build 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

Find more detailed instructions in the User's Guide

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 3.5+

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, or start a discussion in the official Geekhack thread, or create a new issue on Github.

Note: The Github README contains information for creating a custom layout with keyboard-layout-editor.com. It is considered "good manners" to give this a shot first, and to provide a link to a hardware description of the new board.

  • Support KMAC Mini
  • Support Viper
  • Support Lightpad
  • Support Lightsaver
  • Support KC60
  • Support RS60
  • Support Nerd60
  • Support TMK64 Alps
  • Support KBDfans DZ60