Skip to content

Home

Jump to bottom
hasu@tmk edited this page Jun 6, 2022 · 112 revisions

Welcome to the tmk_keyboard wiki!

TMK Products

You can buy here to support this project.

TMK Keyboard Service @ Geekhack.org

Keymap

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

Use git clone to get codes in this repo, 'Download ZIP' won't work because you need to git submodule to build firmware.

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

Build on Linux

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

Flash firmware

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

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

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.

Permission

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.

avrdude

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

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

Atmel FLIP for Windows

FLIP install

Download from: https://www.microchip.com/developmenttools/ProductDetails/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.

Troubleshoot

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

Debug

Debug Console

Refer to FAQ#debug-console also.

hid_listen

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:

For Mac users, you will need run commands below in Terminal once after download hid_listen.mac64.

$ chmod +x hid_listen.mac64
$ xattr -c hid_listen.mac64

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

xprintf()

You can use xprintf() to show values on debug console. You will need to include print.h.

#include "print.h"

xprintf("key: %02X\n", key);

Refer to this for format of xprintf() on AVR.

%[flag][width][size]type

flag
  A '0' means filled with '0' when output is shorter than width.
  ' ' is used in default. This is effective only numeral type.

width
  Minimum width in decimal number. This is effective only numeral type.
  Default width is zero.

size
  A 'l' means the argument is long(32bit). Default is short(16bit).
  This is effective only numeral type.

type
  'c' : Character, argument is the value
  's' : String placed on the RAM, argument is the pointer
  'S' : String placed on the ROM, argument is the pointer
  'd' : Signed decimal, argument is the value
  'u' : Unsigned decimal, argument is the value
  'X' : Hexdecimal, argument is the value
  'b' : Binary, argument is the value
  '%' : '%'

https://github.com/tmk/tmk_keyboard/blob/1a02ebcc612e9a9c0d87e02295c7258de3a70ccc/tmk_core/common/avr/xprintf.h#L64-L83

Magic commands for debug

Magic keybind is LShift + RShift on many keyboards and Power key on ADB converter by default. But Magic keybind can be vary on each project, check config.h in project directory.

  • Magic + H Help

  • Magic + V Version and build options

  • Magic + D General debug print

  • Magic + K Keyboard report

  • Magic + X Matrix state

To change magic keybind you have to change it in config.h and build firmware. You can't change in Keymap Editor.

#define IS_COMMAND() ( \
    keyboard_report->mods == (MOD_BIT(KC_LSHIFT) | MOD_BIT(KC_RSHIFT)) || \
    keyboard_report->mods == (MOD_BIT(KC_LALT) | MOD_BIT(KC_RALT)) \
)
Clone this wiki locally