Como configurar meu teclado com ZMK

O ZMK é o firmware dos teclados sem fio. Você pode configurá-lo de três jeitos, e dá para começar por um e mudar depois.

• Keymap Editor (recomendado): editor visual sem limitações. Você configura camadas, combos, macros, tap dance e behaviors, aprende enquanto configura, e ele salva tudo no seu GitHub.
• ZMK Studio: muda as teclas na hora, sem compilar nem gravar firmware a cada alteração. Ainda está em desenvolvimento e não configura combos, macros nem tap dance.
• Edição manual: você altera o arquivo .keymap direto no GitHub. Não tem nenhuma limitação de interface, só a do seu próprio código, mas pede que você já conheça a documentação do ZMK.

A configuração do seu teclado fica num repositório do GitHub, o zmk-config. Toda vez que ele muda, o GitHub compila o firmware para você, de graça, sem instalar nada no computador.

1. Crie uma conta no GitHub, se ainda não tiver.
2. Faça um fork do repositório do seu teclado. Os teclados da Tupinikeebs têm um repositório pronto (por exemplo, o do Sofle com OLED); se não souber qual é o seu, pergunte pelo contato.
3. Se o seu teclado não tiver um repositório pronto, crie um com o script de configuração do ZMK: ele pergunta o teclado, a placa (na maioria das vezes, nice!nano v2) e já copia o keymap padrão.
4. No seu fork, abra a aba Actions e clique para ativar os workflows. O GitHub deixa os workflows desligados em forks até você ativar.

O Keymap Editor mostra o seu teclado na tela: você clica numa tecla e escolhe o que ela faz. Quando você salva, ele grava a mudança no seu repositório, e isso dispara a compilação do firmware automaticamente.

Quer testar antes? Abra o editor e use o repositório de demonstração do Corne, sem precisar de conta.

1. Abra o Keymap Editor e escolha GitHub como fonte (Source).
2. Entre com a sua conta do GitHub e autorize o app no seu repositório zmk-config.
3. Selecione o repositório (Repository) e o branch.
4. Clique numa tecla para trocar a função. Use as abas Layers, Conditional Layers, Combos, Macros e Behaviors para o resto.
5. Clique em Save, no canto superior esquerdo. A mudança vai para o GitHub e a compilação começa sozinha.
6. Baixe e grave o firmware, como explicado nas próximas seções.

A compilação leva uns 3 a 5 minutos. Quando terminar, o firmware fica disponível na aba Actions do seu repositório.

1. No seu repositório, abra a aba Actions.
2. Clique no build mais recente. Ele precisa estar com o ícone verde (sucesso).
3. Em Artifacts, no fim da página, baixe o arquivo firmware.
4. Descompacte o arquivo. Dentro dele há um arquivo .uf2 para a metade esquerda (left) e outro para a direita (right).

Grave uma metade de cada vez. Conecte o cabo USB na metade e aperte o botão de reset duas vezes, em menos de 1 segundo.

No modo de gravação, o teclado aparece no computador como um pendrive chamado NICENANO (o nome muda conforme o controlador).

1. Copie o arquivo left para a metade esquerda.
2. O drive se desconecta sozinho quando a cópia termina. É comum o computador mostrar um erro de “disco removido”: não é bug, é o jeito do ZMK.
3. Repita com a metade direita e o arquivo right.
4. Não precisa apagar nenhum arquivo do drive. Em toda atualização, basta copiar o arquivo novo.
5. Se as metades pararem de se conectar depois de uma atualização, grave o arquivo settings_reset nas duas (se ele vier no seu build) e depois o firmware normal de novo.

O ZMK Studio é a interface mais nova do ZMK. A grande vantagem é que você quase nunca precisa mexer em código, compilar, baixar e gravar firmware novo a cada alteração: a mudança vale na hora.

Mas ele ainda está em desenvolvimento e tem limitações. Não configura combos, macros, tap dance nem camadas condicionais, e não salva as mudanças no seu GitHub. Por isso eu não recomendo começar por ele, pelo menos enquanto você ainda está aprendendo o ZMK.

Atenção: depois que você passa a usar o ZMK Studio, mudanças feitas no arquivo .keymap deixam de valer, a menos que você use a opção Restore Stock Settings no próprio Studio.

1. O firmware precisa ter suporte ao Studio. No arquivo build.yaml do seu repositório, só na metade esquerda (a central), adicione as linhas snippet: studio-rpc-usb-uart e cmake-args: -DCONFIG_ZMK_STUDIO=y. Veja o exemplo na documentação do ZMK Studio.
2. Coloque uma tecla de desbloqueio no keymap, com o behavior &studio_unlock (dá para fazer pelo Keymap Editor).
3. Baixe e grave o firmware novo, como explicado acima.
4. Conecte a metade esquerda por USB e abra o zmk.studio no Chrome ou no Edge, ou baixe o app para Windows, macOS ou Linux.
5. Selecione o teclado e aperte a tecla de desbloqueio.
6. Clique numa tecla para trocar a função e salve. A mudança fica gravada no teclado.

No seu repositório, o keymap fica em config/[teclado].keymap. Dá para editar direto pelo site do GitHub: cada commit dispara a compilação, e depois é só baixar e gravar o firmware.

Considere esse caminho quando você já leu a documentação de keymaps do ZMK e sabe exatamente o que está fazendo. Aqui não existe limitação de interface, só a do seu próprio código.

No ZMK, cada tecla usa um behavior. Além do &kp (tecla normal), alguns mudam de camada ou fazem duas coisas na mesma tecla, e são eles que deixam um teclado pequeno tão completo. Se camadas ainda são novidade, veja antes como funcionam layouts e camadas.

• &mo (momentânea): &mo 1 liga a camada 1 só enquanto você segura a tecla. Soltou, volta para a camada base.
• &tog (alternar): &tog 1 liga a camada 1 com um toque e desliga com outro. Bom para uma camada de números ou de jogos.
• &lt (layer-tap): &lt 1 SPACE dá espaço quando você toca e liga a camada 1 enquanto você segura. Assim uma tecla do polegar faz duas funções.
• &mt (mod-tap): &mt LSHIFT A dá A quando você toca e vira Shift enquanto você segura. É a base dos home row mods: Ctrl, Alt, Shift e GUI nas teclas do meio do teclado.
• Tap dance: a mesma tecla faz coisas diferentes conforme o número de toques. Por exemplo: um toque dá ponto e vírgula e dois toques dão dois-pontos. No ZMK, ele é criado como um behavior novo no arquivo .keymap (zmk,behavior-tap-dance) e depois usado na tecla, como &td0.
• &sk (sticky key): &sk LSHIFT deixa o Shift ligado só para a próxima tecla, sem precisar segurar.

Pelo tapping-term-ms: se você soltar a tecla antes desse tempo (200 ms por padrão no &mt e no &lt), vale o toque; se segurar por mais tempo, vale a função de segurar. Se o &mt ou o &lt estiver disparando sem querer, aumente um pouco o tempo no arquivo .keymap; se estiver lento, diminua.

No Keymap Editor, clique na tecla e escolha o behavior na lista (&mo, &tog, &lt, &mt, &sk) e depois a camada ou a tecla. No ZMK Studio também: os behaviors que o firmware tem aparecem na lista ao editar a tecla. Um tap dance precisa estar definido no firmware antes de aparecer.

NUNCA! A controladora é uma peça separada, socketada na placa: ela encaixa em soquetes (sockets) e sai com as mãos, sem solda. Se ela queimar, é só tirar e encaixar outra, e o resto do teclado continua igual: placa, switches, keycaps e case.

Para que, se um dia você quiser trocar o seu teclado de sem fio para com fio, basta trocar a controladora: por exemplo, tirar a nice!nano e encaixar uma RP2040, sem solda e sem trocar a placa. O mesmo vale para qualquer eventualidade, como uma controladora queimada ou com defeito.

Mas o mais importante: de forma alguma o teclado vai queimar e você simplesmente perder a placa.

O mesmo vale se você derrubar água ou café no teclado. Desligue na hora a chave liga/desliga de cada metade e tire o cabo USB, se estiver conectado. Depois vire o teclado para o líquido escorrer e deixe secar bem, por um ou dois dias, antes de ligar de novo.

Na maioria das vezes ele volta a funcionar; se alguma peça estragar, ela é trocada, sem precisar de um teclado novo. Fale com a gente pelo contato.

Estes são os guias e documentações que eu mais uso.

• Documentação oficial do ZMK: instalação, keymaps, behaviors e tudo o que o ZMK oferece.
• Documentação do ZMK Studio: o que ele já faz e como ativar no seu teclado.
• Wiki do Keymap Editor: todos os recursos do editor.
• Como funcionam layouts e camadas, aqui na Wiki.
• OLED, são úteis? O que fazem?: o que a telinha mostra e como configurar.
• Instalando e atualizando o firmware, aqui na Wiki.