21.01.2023 | 11 minutos de leitura

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:

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:

AUTO_SHIFT_ENABLE: ativa/desativa a funcionalidade de autoshift. Aperte uma tecla para ter o seu valor, segure a tecla para ter outro.
AUTOCORRECT_ENABLE: ativa/desativa a funcionalidade de auto correção. Checa por erros de ortografia.
CAPS_WORD_ENABLE: ativa/desativa a funcionalidade de caps words. Ativa uma versão inteligente do Caps Lock
COMBO_ENABLE: ativa/desativa a funcionalidade de combos. Permite a utilização de combos ao pressionar diversas teclas e executar ações personalizadas.
KEY_LOCK_ENABLE: ativa/desativa a funcionalidade de keylock. Mantém pressionado uma certa tecla automaticamente até o próximo pressionamento.
KEY_OVERRIDE_ENABLE: ativa/desativa a funcionalidade de key overrides. Permite que você substitua o comportamento de algumas teclas modificadores (shift, ctrl) quando usadas em conjunto com outras.
SECURE_ENABLE: ativa/desativa a funcionalidade secure. Permite bloquear o input de todas as teclas até certa combinação ter sido entrada.
SEND_STRING_ENABLE: ativa/desativa a funcionalidade de send string. Permite o envio de sequências de letras serem enviadas em atalhos personalizados.
TAP_DANCE_ENABLE: ativa/desativa a funcionalidade de tap dance. Permite especificar diferentes comportamentos para uma tecla ao pressionar ela mais de uma vez rapidamente.
LEADER_ENABLE: ativa/desativa a funcionalidade de leader key. Permite utilizar uma tecla específica para iniciar uma combinação de keystrokes no qual irão resultar em uma ação.

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:

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:

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:

Executar ./mdloader --first --download build/massdrop_alt_custom.hex --restart para iniciar o upload do firmware para o teclado;
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;
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:

compile:
	docker compose run --rm qmk

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

Com este arquivo, os passos são esses:

Editar o arquivo keymap.c
make compile
make flash
Pressione Fn + b para reiniciar no bootloader
Profit!

Resolvendo problemas #

O mdloader não reconhece o teclado

Certifique-se que tenha apertado as teclas Fn + b para reiniciar o teclado em modo do bootloader por pelo menos meio segundo. Você pode conferir qual tecla é utilizada para reiniciar para o modo bootloader no arquivo keymap.c, que é representado pelo keycode MD_BOOT.
Talvez você precise adicionar o seu usuário no grupo dialout para acessar a porta do device;