Welcome to the tmk_keyboard wiki!

You can buy here to support this project.

TMK Keyboard Service @ Geekhack.org

• HHKB Alt Controllers
• Converters(USB-USB, PS/2, ADB, NeXT, M0110, IBM4704, SUN, X68K...)
• Alps64 PCB(60% keyboard for Alps SKCM/SKCL)
• FC660C Alt Controller
• FC980C Alt Controller

• Keymap - internal details
• FAQ Keymap
• Keymap examples - share ideas
• Keymap: Custom Key Action
• Keycode

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.

• TMK Keymap Editor online
• TMK Keymap Editor Usage
• TMK Keymap Editor FAQ

Check this first.

• https://github.com/tmk/tmk_keyboard/blob/master/tmk_core/doc/build.md

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 VirtualBox (recommended)
• Build on Ubuntu On Windows10
• Atmel AVR toolchain + Cygwin/MinGW

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 on VirtualBox may be option if you want.

If you are on Ubuntu or similar distribution you will need to install following packages.

git unzip build-essential make

for AVR microcntroller:

gcc-avr avr-libc binutils-avr dfu-programmer

for ARM Cortex-M:

binutils-arm-none-eabi gcc-arm-none-eabi libnewlib-arm-none-eabi libstdc++-arm-none-eabi-newlib dfu-util

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

• dfu-programmer
• avrdude
• QMK Toolbox
• Atmel FLIP

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.

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

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

https://manpages.debian.org/testing/avrdude/avrdude.1.en.html

$ avrdude -patmega32u4 -cflip1 -Uflash:w:example.hex

Or

$ avrdude -patmega32u2 -cflip1 -Uflash:w:example.hex

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

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

Download from: https://www.microchip.com/developmenttools/ProductDetails/FLIP

See Driver-install-on-Windows.

0. 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.
1. On menu bar click Device -> Select, then choose your chip name. (In most cases ATmega32U2 or ATmega32U4)
2. 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.
3. On menu bar click File -> Load HEX File, then select your firmware hex file on File Selector dialog.
4. 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.
5. 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

Refer to FAQ#debug-console also.

Use hid_listen command line tool to see debug outputs. Run hid_listen from command line interface such as Terminal.app or Command Prompt.

Download:

• Linux: hid_listen.linux
• Mac: hid_listen.mac64
• Windwos: hid_listen.exe

Note: You can't use QMK Toolbox for debug instead. It misses debug outputs for some reason as of 2021-09. Use hid_listen directly from cmd.exe, PowerShell or Terminal.

Magic keybind is LShift + RShift by default on many keyboards.

• Magic + H Help

• Magic + V Version and build options

• Magic + D General debug print

• Magic + K Keyboard report

• Magic + X Matrix state