Ricardo Fuhrmann

Software Engineer @ fuhrmanns
Open Source /#linux
5 min read

Customizando firmware drop ALT Keyboard com docker

Se você tem um Drop ALT Keyboard provavelmente já deve ter pensado em como customizar o firmware e quais as possibilidades de customizações disponíveis.

Seja para facilitar meu dia a dia, como por exemplo, trocar a funcionalidade da tecla Caps Lock pela ESC. A questão é que existe um mundo de customizações disponíveis, basta saber por onde começar.

Abaixo escrevi um exemplo de como ativar a funcionalidade da Leader Key, desde a preparação do keymap até a compilação e upload do firmware para o teclado! Boa sorte!

Baixando mdloader

O mdloader será responsável por fazer upload do firmware que iremos gerar (no final deste artigo) no teclado. Para baixá-lo acesse a página de releases e baixe a ultima versão. Vou assumir que iremos fazer todos os passos em uma pasta chamada keyboard, portanto:

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

Um arquivo com o nome de mdloader será extraído do arquivo zipado na pasta.

Preparando o qmk_firmware

Para compilar e customizar o firmware iremos utilizar o qmk_firmware através do docker. Para isso, crie um docker-compose.yml na pasta que estamos trabalhando com o seguinte conteúdo:

docker-compose.yml yaml 
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"

Precisamos agora do keymap padrão do Massdrop ALT para que possamos customizá-lo. Para isso criei um repositório contendo o arquivo padrão que pode ser baixado:

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

Se tudo deu certo você verá o arquivo de keymap em ~/apps/keyboard/keymap/keymap.c.

O arquivo de rules

É no arquivo rules.mk que o QMK especifica quais features serão ativadas ao compilar o firmware. Para cada feature utilizada no keymap.c precisamos ativá-las antes neste arquivo.

Para referência, abaixo uma lista das principais funcionalidades que podem ser ativadas e seus valores:

Todos as funcionalidades do arquivo rules.mk recebem apenas dois valores: yes ou no. Para mais informações sobre o arquivo de rules.mk, consulte a documentação oficial.

Ativando a funcionalidade de Leader Key

A Leader Key (KC_LEAD) permite que você especifique uma tecla que será a tecla líder: você irá pressionar ela e depois uma sequência de teclas para executar uma ação especifica.

Por exemplo, digamos que você queria de forma fácil controlar a abertura e fechamento das abas do seu browser ou do seu editor. Para tal podemos traduzir o comportamento padrão dos atalhos utilizando a leader key desta forma:

KC_LEAD + t: reabre a última aba aberta;

KC_LEAD + n + t: abre uma nova aba;

Você irá apertar a tecla que representa o KC_LEAD, depois a tecla n e por último a tecla t para abrir uma nova aba, em sequência.

A tecla que será utilizada como KC_LEAD é definida no arquivo keymap.c mais abaixo!

Agora que sabemos as possíveis principais funcionalidades e como ativá-las crie o arquivo de rules.mk:

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

E dentro dele vamos especificar que queremos a funcionalidade de leader key ativada

LEADER_ENABLE = yes

Você verá o arquivo de rules.mk em ~/apps/keyboard/keymap/rules.mk.

Criando o arquivo de configuração

Algumas das funcionalidades disponibilizadas pelo QMK podem ser personalizadas mais ainda, como por exemplo, mudar o timeout da leader key, personalizar comportamentos de teclas específicas, entre outros. Neste caso, vamos definir essas configurações em um arquivo chamado config.h.

Como estamos ativando a funcionalidade de leader key, vamos alterar uma configuração específica dela que permite aumentar/diminuir o tempo de pressionamento das sequências. Para isso, crie o arquivo config.h:

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

Com o seguinte conteúdo:

#pragma once

// Configura o timeout de pressionamento das sequências da leader key
#define LEADER_TIMEOUT 300

// Reseta o timeout após cada pressionamento
#define LEADER_PER_KEY_TIMING

Você verá o arquivo de config.h dentro da pasta ~/apps/keyboard/keymap/config.h.

Configurando a leader key

Para especificar a leader key (KC_LEAD) temos que editar o arquivo ~/apps/keyboard/keymap/keymap.c que baixamos no início do artigo. Ao abrir este arquivo você irá se deparar com o layout do keyboard definido desta forma:

Meta/Imagens/customizando-drop-alt/1.png

Onde cada linha de teclas do seu teclado é representado por uma linha da tabela acima e cada coluna respectivamente.

Note que existem três camadas (layers): a primeira (0) será a sua camada padrão das teclas, que ao pressionar qualquer tecla terá seu comportamento executado. A segunda (1) é uma camada que só é ativada com o pressionamento de uma tecla específica, neste caso representado pelo keycode MO(1). E a terceira cama (X) está desativada.

Na primeira camada, escolha uma das teclas para representar a sua tecla KC_LEAD. Neste caso eu defini a Caps Lock:

Meta/Imagens/customizando-drop-alt/2.png

Especificando o comportamento

Ainda no arquivo keymap.c vamos adicionar uma nova função que será responsável por lidar com o comportamento das teclas que são pressionadas logo após o pressionamento da KC_LEAD. Para isso acrescente o código abaixo no final arquivo:

LEADER_EXTERNS();

void matrix_scan_user(void) {
  LEADER_DICTIONARY() {
    leading = false;
    leader_end();
    
    // Aqui configuramos as sequências
    SEQ_ONE_KEY(KC_T) {
      // Ao pressionar KC_LEAD e então T, envia CTRL + SHIFT + T
      SEND_STRING(SS_LCTRL(SS_LSFT("t")));
    }

     SEQ_TWO_KEYS(KC_N, KC_T) {
      // Ao pressionar KC_LEAD and então N seguido de T, envia CTRL + T
      SEND_STRING(SS_LCTRL("t"));
    }
  }
}

Com a função criada estamos prontos para compilar o firmware e usar o mdloader para fazer upload do firmware no teclado.

Compilando e enviando o firmware

A compilação é simples, basta executar:

docker compose run --rm qmk

Se tudo deu certo você verá essa mensagem no final:

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

Após a compilação do firmware, temos que enviá-lo para o teclado. Para fazer isso vamos utilizar o mdloader. Os passos serão o seguinte:

  1. Executar ./mdloader --first --download build/massdrop_alt_custom.hex --restart para iniciar o upload do firmware para o teclado;
  2. Apertar as teclas Fn + b por meio segundo para reiniciar o teclado no bootloader. Você pode achar essa tecla representada no keymap.c por meio do keycode MD_BOOT na layer 1;
  3. Aguarde o teclado reiniciar e pronto. As leds devem acender e o teclado está pronto para utilização.

Abaixo um exemplo da saída esperada pelo comando se tudo der certo:

./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!

Agora só testar se a sua leader key com as sequências funcionam:

KC_LEAD + t: reabre a última aba aberta;

KC_LEAD + n + t: abre uma nova aba no browser;

O arquivo Makefile

Eu uso um arquivo Makefile que ajuda a não precisar ficar memorizando os comandos:

Makefile Makefile 
compile:
	docker compose run --rm qmk

flash:
	./mdloader --first --download .build/massdrop_alt_custom.hex --restart

Com este arquivo, os passos são esses:

  1. Editar o arquivo keymap.c
  2. make compile
  3. make flash
  4. Pressione Fn + b para reiniciar no bootloader
  5. Profit!

Resolvendo problemas

O mdloader não reconhece o teclado

Repositório com conteúdo deste artigo

The QMK Tutorial

The Leader Key: A New Kind of Modifier

QMK Chearsheet

QMK Basics: Leader Key, using sequences for shortcuts

mdloader docs