Skip to content

Home

Jump to bottom
hasu@tmk edited this page Oct 28, 2023 · 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' link won't work because you need to git submodule to get libraries.

$ git clone https://github.com/tmk/tmk_keyboard.git
$ cd tmk_keyboard
$ git submodule init
$ git submodule update

Move to project directory.

$ {keyboard, converter}/<project_name>

Build with proper makefile such as Makefile.unimap.

$ make clean -f Makefile.unimap
$ make all   -f Makefile.unimap

You will see firmware HEX file in current directory, for example <project_name>_unimap.hex.

Build with custom keymap

To build with your custom keymap file you need to add KEYMAP=<keymap_name> to the commands. <keymap_name> is hasu if your kemap file is unimap_hasu.c, for example.

$ make clean -f Makefile.unimap KEYMAP=<keymap_name>
$ make all   -f Makefile.unimap KEYMAP=<keymap_name>

Build environment

AVR GCC

Cofirmed that AVR GCC 5.4.0(ubuntu) and 7.3.0(Microchip/Atmel) works.

Use toolchain provided by Microchip/Atmel if you have problem with newer versions of GCC.

  • With GCC 8 and newer ibmpc_usb converter has firmware size issue. #741

GCC Release Notes: https://gcc.gnu.org/releases.html

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 you can use one of following tools.

If you are familiar with command line interface dfu-programmer is recommended. Newer version of avrdude can be used also.

If you prefer graphical inteface you can try QMK Toolbox or Atmel FLIP.

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

dfu-programmer

Install dfu-programmer with package manager like Brew, Mac Port, pacman, apt or anything. Or you can just download prebuilt binary file from here.

For Windows see this also.

  1. Boot your device into Flash(Programming) mode before flashing. Usually you can start the mode by pressing button on the 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 older 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

Newer versoins supports AVR DFU protocol.

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

You can use this command like below:

$ 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

This is official tool realeased by chip manufacturer and available for Linux and Windows.

You can download from: https://www.microchip.com/developmenttools/ProductDetails/FLIP

Check this for usage.

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