Ricardo Fuhrmann

Mostly new

Customizing Drop ALT Keyboard Firmware with Docker

8 min read

If you have a Drop ALT Keyboard you’ve probably already thought about how to customize the firmware and what customization possibilities are available.

Whether to make my daily life easier, such as swapping the Caps Lock key functionality with ESC. The thing is, there’s a world of customizations available, you just need to know where to start.

Below I wrote an example of how to activate the Leader Key functionality, from preparing the keymap to compiling and uploading the firmware to the keyboard! Good luck!

Downloading mdloader

The mdloader will be responsible for uploading the firmware we’re going to generate (at the end of this article) to the keyboard. To download it, access the releases page and download the latest version. I’ll assume we’ll do all the steps in a folder called keyboard, so:

wget https://github.com/Massdrop/mdloader/releases/download/1.0.7/mdloader-Linux.zip -P ~/apps/keyboard
unzip ~/apps/keyboard/mdloader-Linux.zip

A file named mdloader will be extracted from the zipped file in the folder.

Preparing qmk_firmware

To compile and customize the firmware we’ll use qmk_firmware through Docker. To do this, create a docker-compose.yml in the folder we’re working in with the following content:

docker-compose.yml
version: '3.7'
 
services:
  qmk:
    image: qmkfm/qmk_firmware
    container_name: qmk
    volumes:
      - ./keymap:/qmk_firmware/keyboards/massdrop/alt/keymaps/custom
      - ./build:/qmk_firmware/.build
    command: "make massdrop/alt:custom"

We now need the default Massdrop ALT keymap so we can customize it. For this I created a repository containing the default file that can be downloaded:

mkdir ~/apps/keyboard/keymap
wget https://raw.githubusercontent.com/Fuhrmann/massdrop-alt-default/main/default-keymap.c -O ~/apps/keyboard/keymap/keymap.c

If everything went well you’ll see the keymap file at ~/apps/keyboard/keymap/keymap.c.

The Rules File

It’s in the rules.mk file that QMK specifies which features will be activated when compiling the firmware. For each feature used in keymap.c we need to activate them first in this file.

For reference, below is a list of the main features that can be activated and their values:

  • AUTO_SHIFT_ENABLE: enables/disables the autoshift functionality. Press a key to get its value, hold the key to get another.
  • AUTOCORRECT_ENABLE: enables/disables the auto correction functionality. Checks for spelling errors.
  • CAPS_WORD_ENABLE: enables/disables the caps words functionality. Activates an intelligent version of Caps Lock.
  • COMBO_ENABLE: enables/disables the combos functionality. Allows the use of combos when pressing multiple keys and executing custom actions.
  • KEY_LOCK_ENABLE: enables/disables the keylock functionality. Keeps a certain key automatically pressed until the next press.
  • KEY_OVERRIDE_ENABLE: enables/disables the key overrides functionality. Allows you to override the behavior of some modifier keys (shift, ctrl) when used in conjunction with others.
  • SECURE_ENABLE: enables/disables the secure functionality. Allows locking the input of all keys until a certain combination has been entered.
  • SEND_STRING_ENABLE: enables/disables the send string functionality. Allows sequences of letters to be sent in custom shortcuts.
  • TAP_DANCE_ENABLE: enables/disables the tap dance functionality. Allows specifying different behaviors for a key when pressing it more than once quickly.
  • LEADER_ENABLE: enables/disables the leader key functionality. Allows using a specific key to start a combination of keystrokes which will result in an action.

All features in the rules.mk file receive only two values: yes or no. For more information about the rules.mk file, consult the official documentation.

Activating the Leader Key Functionality

The Leader Key (KC_LEAD) allows you to specify a key that will be the leader key: you’ll press it and then a sequence of keys to execute a specific action.

For example, let’s say you want an easy way to control opening and closing tabs in your browser or editor. To do this we can translate the default behavior of shortcuts using the leader key like this:

KC_LEAD + t: reopens the last opened tab;

KC_LEAD + n + t: opens a new tab;

You’ll press the key that represents KC_LEAD, then the n key and finally the t key to open a new tab, in sequence.

The key that will be used as KC_LEAD is defined in the keymap.c file below!

Now that we know the possible main features and how to activate them, create the rules.mk file:

vi ~/apps/keyboard/keymap/rules.mk

And inside it we’ll specify that we want the leader key functionality activated:

LEADER_ENABLE = yes

You’ll see the rules.mk file at ~/apps/keyboard/keymap/rules.mk.

Creating the Configuration File

Some of the features provided by QMK can be further customized, such as changing the leader key timeout, customizing behaviors of specific keys, among others. In this case, we’ll define these configurations in a file called config.h.

Since we’re activating the leader key functionality, we’ll change a specific configuration of it that allows increasing/decreasing the press time of sequences. To do this, create the config.h file:

vi ~/apps/keyboard/keymap/config.h

With the following content:

#pragma once
 
// Configures the timeout for pressing leader key sequences
#define LEADER_TIMEOUT 300
 
// Resets the timeout after each press
#define LEADER_PER_KEY_TIMING

You’ll see the config.h file inside the ~/apps/keyboard/keymap/config.h folder.

Configuring the Leader Key

To specify the leader key (KC_LEAD) we need to edit the ~/apps/keyboard/keymap/keymap.c file that we downloaded at the beginning of the article. When opening this file you’ll come across the keyboard layout defined like this:

Where each row of keys on your keyboard is represented by a row in the table above and each column respectively.

Note that there are three layers: the first (0) will be your default key layer, which when you press any key will have its behavior executed. The second (1) is a layer that is only activated by pressing a specific key, in this case represented by the keycode MO(1). And the third layer (X) is disabled.

In the first layer, choose one of the keys to represent your KC_LEAD key. In this case I defined Caps Lock:

Specifying the Behavior

Still in the keymap.c file we’ll add a new function that will be responsible for handling the behavior of keys that are pressed right after pressing KC_LEAD. To do this, add the code below at the end of the file:

LEADER_EXTERNS();
 
void matrix_scan_user(void) {
  LEADER_DICTIONARY() {
    leading = false;
    leader_end();
    
    // Here we configure the sequences
    SEQ_ONE_KEY(KC_T) {
      // When pressing KC_LEAD and then T, sends CTRL + SHIFT + T
      SEND_STRING(SS_LCTRL(SS_LSFT("t")));
    }
 
     SEQ_TWO_KEYS(KC_N, KC_T) {
      // When pressing KC_LEAD and then N followed by T, sends CTRL + T
      SEND_STRING(SS_LCTRL("t"));
    }
  }
}

With the function created we’re ready to compile the firmware and use mdloader to upload the firmware to the keyboard.

Compiling and Sending the Firmware

Compilation is simple, just run:

docker compose run --rm qmk

If everything went well you’ll see this message at the end:

QMK Firmware 0.13.26
Making massdrop/alt with keymap custom
..
..
..
..
Copying massdrop_alt_custom.bin to qmk_firmware folder                                              [OK]
(Firmware size check does not yet support cortex-m4 microprocessors; skipping.)

After compiling the firmware, we need to send it to the keyboard. To do this we’ll use mdloader. The steps will be as follows:

  1. Run ./mdloader --first --download build/massdrop_alt_custom.hex --restart to start uploading the firmware to the keyboard;
  2. Press the Fn + b keys for half a second to restart the keyboard in bootloader. You can find this key represented in keymap.c by the keycode MD_BOOT on layer 1;
  3. Wait for the keyboard to restart and you’re done. The LEDs should light up and the keyboard is ready to use.

Below is an example of the expected output from the command if everything goes well:

./mdloader --first --download build/massdrop_alt_custom.hex --restart
Massdrop Loader 1.07
 
Massdrop Loader  Copyright (C) 2018-2022 Massdrop Inc.
This program is Free Software and has ABSOLUTELY NO WARRANTY
 
Scanning for device for 60 seconds
.........
Device port: /dev/ttyACM0 (SAMD51J18A)
 
Opening port '/dev/ttyACM0'... Success!
Found MCU: SAMD51J18A
Bootloader version: v2.18Sep  4 2018 16:48:28
Applet Version: 1
Writing firmware... Complete!
Booting device... Success!
Closing port... Success!

Now just test if your leader key with the sequences work:

KC_LEAD + t: reopens the last opened tab;

KC_LEAD + n + t: opens a new tab in the browser;

The Makefile

I use a Makefile that helps avoid having to memorize commands:

Makefile
compile:
	docker compose run --rm qmk
 
flash:
	./mdloader --first --download .build/massdrop_alt_custom.hex --restart

With this file, the steps are:

  1. Edit the keymap.c file
  2. make compile
  3. make flash
  4. Press Fn + b to restart in bootloader
  5. Profit!

Troubleshooting

mdloader doesn’t recognize the keyboard

  • Make sure you’ve pressed the Fn + b keys to restart the keyboard in bootloader mode for at least half a second. You can check which key is used to restart to bootloader mode in the keymap.c file, which is represented by the keycode MD_BOOT.
  • You may need to add your user to the dialout group to access the device port;

Repository with content from this article

The QMK Tutorial

The Leader Key: A New Kind of Modifier

QMK Cheatsheet

QMK Basics: Leader Key, using sequences for shortcuts

mdloader docs

Graph View

Backlinks