hasu@tmk edited this page Jun 14, 2018 · 66 revisions

Welcome to the tmk_keyboard wiki!

TMK Products

You can buy here to support this project.

TMK Keyboard Service @ Geekhack.org

TMK Keymap Editor

Keymap editor is available for TMK products. You can edit keymap and download firmware with web browser, you don't have to build firmware from source code.

Build firmware

Read this first.

Build on Windows

Don't use WinAVR with TMK anymore unless you know what you are doing and can help yourself. Instead use one of methods below.

Build on Mac

You can setup tools for AVR with Homebrew by following commands. And refer to build doc.

brew tap osx-cross/avr
brew install avr-gcc
brew install dfu-programmer

MacPorts, CrossPack or Build firmware on VirtualBox may be option if you want.

Flash firmware

To flash firmware there are several tools you can use with keyboard or converter.

  • Atmel FLIP
  • dfu-programmer

Atmel FLIP for Windows

FLIP install

Download from: http://www.microchip.com/developmenttools/productdetails.aspx?partno=flip

Driver install

See Driver-install-on-Windows.

How to use FLIP

  1. Boot your device into programming mode or bootloader. Usually you can start bootloader with pressing program button or specific key combo, consult with document of your device.
  2. On menu bar click Device -> Select, then choose your chip name. (In most cases ATmega32U2 or ATmega32U4)
  3. On menu bar click Settings -> Communication -> USB, then click Open button on USB Port Connection dialog. At this point you'll have to plug into USB and start bootloader.
  4. On menu bar click File -> Load HEX File, then select your firmware hex file on File Selector dialog.
  5. On Operations Flow panel click Run button to load the firmware binary to the chip. Note that you should keep Erase, Blank Check, Program and Verify check boxes selected.
  6. Re-plug USB cord or click Start Application button to restart your controller. Done.

See also FLIP instructions if needed.


First, try to remove current driver and re-install from Device Manager. See Driver-install-on-Windows#troubleshooting.

  • FLIP: AtLibUsbDfu.dll not found
  • Could not open USB device

dfu-programmer for Windows, Mac and Linux

Install dfu-programmer with package manager like Brew, Mac Port or apt. Or refer http://dfu-programmer.github.io/ directly. For Windows see dfu-programmer-for-Windows.

  1. Boot your device into programming mode or bootloader before flashing. Usually you can start bootloader with pressing program button or specific key combo, consult with document of your device.

  2. To flash firmware run three commands in terminal(cmd.exe for Windows/Terminal.app for Mac).

dfu-programmer <controller> erase --force
dfu-programmer <controller> flash <your_firmware.hex>
dfu-programmer <controller> reset
  • Remove --force if you use 0.6.x version.

  • <controller> part will be atmega32u4(for HHKB/FC660C/FC980C Alt Controllers and USB-USB Conveter) or atmega32u2(for other Converters and Alps64).

  • <your_firmware.hex> part should be file path to firmware hex file. You can copy file path by draging the firmware file from Finder or Explorer into terminal window like this.


On Linux and Mac OSX you will need proper permission to program a microcontroller and you can use sudo command for this purpose probably. On Linux you also can configure udev rules to set permission.

QMK Toolbox

This probably works for TMK also. https://github.com/qmk/qmk_toolbox

You can download from: https://github.com/qmk/qmk_toolbox/releases


Refer this. https://github.com/tmk/tmk_keyboard/wiki/FAQ#debug-console

PJRC hid_listen

You can get debug info with this tool. https://www.pjrc.com/teensy/hid_listen.html

Magic commands for debug

Magic keybind is LShift + RShift by default.

  • Magic + H Help

  • Migic + V Version and build options

  • Magic + D General debug print

  • Magic + K Keyboard report

  • Magic + X Matrix state

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.