Generate a Heatmap for Your QMK Keyboard

With heatmaps you can track the key usage and optimise keyboard layouts for efficiency and comfort.

Step 1: Tell us your layout and get your personal key in return

Assuming your keyboard looks like this ...

create a 2D Python-like list with row_max = 2 rows and col_max + 1 = 4 columns. Each entry in the array specifies the key width in units u, with the following exceptions:

  • The first column is the initial offset (also in u)
  • Rows are padded with zero at the end

For your keyboard above, that is

    [[0.5, 1.0, 1.5, 0.0],
     [0.0, 1.0, 1.0, 1.0]]

After entering the keymap into the textbox on the bottom left and clicking the Register button, you will get a random 64 digit hash. Save that one for the next step.

Step 2: Add the heatmap functions to the QMK firmware

Download heatmap.c and heatmap.h into the folder with your keymap.c. Include it into the build process by adding to the

    SRC += heatmap.c

Assuming your keyboard is wired like this ...

personalise heatmap.h as follows

  1. Insert your personal USERHASH from step 1
  2. Set PHYSICAL_ROWS to 2 and PHYSICAL_COLS to 3, as per the maximum keyboard dimensions
  3. Set the transformation matrices such that each element points to the respective row/column in the wired matrix (and use right-padding of -1)

    transform_row[PHYSICAL_ROWS][PHYSICAL_COLS] = { \
     {0, 0, -1}, \
     {1, 1,  1}, \
    transform_col[PHYSICAL_ROWS][PHYSICAL_COLS] = { \
     {0, 2, -1}, \
     {0, 1,  2}, \

In keymap.c, #include "heatmap.h" and create a custom keycode (e.g. KC_HEAT) for printing out the keycounts in the next step. Then add the following code snippet to the process_record_user function

    // Functions for heatmap generation
    if (record->event.pressed) {
        // Update key counter for heatmap

        // Dump keycount array as a Python list
        if (keycode == KC_HEAT)

Use this example of keymap.c as a reference. Compile the firmware and flash it.

Step 3: Submit your keycounts

Everything is straightforward from here

  1. After some typing, place your cursor into the User Hash field on the top right
  2. Invoke the keycombination you assigned to KC_HASH which fills the two fields
  3. Submit and have your heatmap drawn

Step 4: View the heatmap

To view the heatmap without submitting new keycounts, insert only your hash and submit.

Your heatmap will be displayed here