Como configurar meu teclado com QMK e Vial

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 com fio para sem fio, basta trocar a controladora: por exemplo, tirar a RP2040 e encaixar uma nice!nano (e colocar uma bateria), 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. Desconecte na hora o USB e o TRRS, 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.

Os três andam juntos, mas não são a mesma coisa. QMK é o firmware; VIA e Vial são aplicativos que mudam o QMK na hora, sem compilar.

• QMK: o firmware open-source dos teclados com fio. Faz tudo, mas cada mudança no código exige compilar e gravar o firmware de novo.
• VIA: aplicativo que edita as teclas de um teclado QMK em tempo real, pelo usevia.app. O firmware precisa ter sido compilado com suporte a VIA.
• Vial (recomendado): uma versão do QMK com aplicativo próprio, mais completo que o VIA. Além das teclas e camadas, configura macros, tap dance, combos, key overrides e ajustes do QMK, tudo sem compilar.

É por aqui que você deve começar: todos os nossos teclados com QMK já vêm com Vial. As mudanças valem na hora e ficam salvas no próprio teclado, então funcionam em qualquer computador, mesmo sem o Vial instalado.

1. Baixe o Vial para Windows, macOS ou Linux, ou abra o vial.rocks no Chrome ou no Edge.
2. Conecte o teclado por USB. O Vial reconhece o teclado e mostra o layout; no navegador, autorize o acesso quando ele pedir.
3. Escolha a camada no topo, clique na tecla que quer mudar e depois no novo keycode, na lista de baixo. A mudança vale na hora.
4. Use as abas Macros, Tap Dance, Combos e Key Overrides para os recursos avançados. Em QMK Settings você ajusta, por exemplo, o tapping term (o tempo que separa um toque de uma tecla segurada).
5. Faça um backup: no menu File, use Save current layout. Isso gera um arquivo .vil que você pode carregar depois, com Load saved layout.

Por segurança, o teclado liga bloqueado. Assim, um programa malicioso no computador não consegue mudar macros nem trocar o firmware sem você perceber.

Para ações sensíveis, como editar macros, colocar o teclado em modo de gravação ou atribuir a tecla de reset, o Vial pede que você desbloqueie: ele mostra quais teclas segurar por alguns segundos. O teclado volta a ficar bloqueado quando é desligado ou quando você escolhe Lock no menu.

Só desbloqueie em computadores em que você confia.

Além das teclas normais, o QMK tem teclas que mudam de camada ou fazem duas coisas na mesma tecla. São elas 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.
• TG (alternar): TG(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, KC_SPC) 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(MOD_LSFT, KC_A), ou LSFT_T(KC_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.
• TD (tap dance): a mesma tecla faz coisas diferentes conforme o número de toques. Por exemplo: um toque dá ponto e vírgula, dois toques dão dois-pontos e segurar dá Ctrl.
• OSM (one-shot): OSM(MOD_LSFT) deixa o Shift ligado só para a próxima tecla, sem precisar segurar.

Pelo tapping term: se você soltar a tecla antes desse tempo (200 ms por padrão), 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; se estiver lento, diminua.

No Vial, MO, TG e LT ficam na aba Layers da lista de keycodes, e o mod-tap fica na aba Quantum (ou use a tecla Any e digite, por exemplo, LSFT_T(KC_A)). O tap dance se monta na aba Tap Dance e depois é colocado na tecla como TD(0), TD(1) e assim por diante. O tapping term se ajusta em QMK Settings, na parte de Tap-Hold.

Com o QMK CLI você edita o keymap.c no seu computador e tem acesso a tudo o que o QMK oferece. O guia oficial para iniciantes explica a instalação em cada sistema.

1. Instale o QMK: no Windows, use o QMK MSYS; no macOS, brew install qmk/qmk/qmk; no Linux, siga o guia oficial.
2. Rode qmk setup para baixar o código do QMK.
3. Crie o seu keymap com qmk new-keymap -kb crkbd/rev1 (troque pelo seu teclado) e edite o arquivo keymap.c.
4. Compile com qmk compile -kb crkbd/rev1 -km seu_keymap.
5. Grave com qmk flash -kb crkbd/rev1 -km seu_keymap, ou copie o arquivo gerado como explicado abaixo.
6. Para firmware com Vial, use o repositório vial-qmk e o keymap vial do seu teclado, em vez do QMK oficial.

Os nossos teclados usam a RP2040, que grava como um pendrive. Grave uma metade de cada vez.

• RP2040 (arquivo .uf2): aperte o botão de reset duas vezes rápido, ou segure o botão BOOT enquanto conecta o cabo. O controlador aparece como um pendrive chamado RPI-RP2; arraste o arquivo .uf2 para dentro e ele se desconecta sozinho quando termina.
• Antes de trocar de metade, desconecte o USB e só então mexa no cabo TRRS (veja o aviso no início).
• Nas duas metades: na maioria dos splits com QMK, o mesmo arquivo vai nas duas. Se o firmware guarda o lado de cada metade na memória (EE_HANDS), grave a versão left na esquerda e a right na direita.

Nada que você faça no Vial ou no QMK estraga o teclado: no pior caso, é só gravar o firmware de novo.

• Guarde sempre um backup do seu layout: o arquivo .vil do Vial.
• Se uma tecla sumiu ou o layout ficou estranho, grave de novo o firmware original do teclado.
• Teclado da Tupinikeebs? Peça o firmware original pelo contato, que a gente manda.

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

• Documentação do Vial: recursos, segurança e como adicionar Vial a um teclado.
• Guia do QMK para iniciantes: instalação, primeiro keymap e gravação.
• Lista de keycodes do QMK: o que cada keycode faz.
• Como funcionam layouts e camadas, aqui na Wiki.
• OLED, são úteis? O que fazem?: o que a telinha mostra e como configurar.
• Como configurar meu teclado com ZMK, para teclados sem fio.