Cómo configurar un teclado por capas con QMK y VIA

Inicio » Software » Cómo configurar un teclado por capas con QMK y VIA

Si has llegado hasta aquí es porque quieres configurar tu teclado por capas usando QMK y VIA sin volverte loco entre documentación, foros y repositorios de GitHub. Tranquilo, no eres el único: casi todos los que hemos comprado un teclado dividido ergonómico hemos pasado por esa fase de pruebas eternas hasta las tantas de la madrugada intentando que todo funcione como queremos.

El objetivo de esta guía es que cualquier persona con cierta soltura con el ordenador, pero que no sea programadora profesional, pueda montar un entorno QMK, compilar su firmware, flashear un Corne (o teclado similar) y aprovechar al máximo las capas en VIA, incluyendo diseños avanzados como Miryoku o keymaps en español. Todo en un solo sitio, sin tener que ir saltando de una referencia a otra.

Qué necesitas antes de empezar

Para seguir esta guía con comodidad es importante que tengas a mano unos pocos requisitos básicos de hardware y software, además de cierta familiaridad con la terminal.

• Teclado Corne (crkbd) u otro teclado compatible con QMK: el ejemplo principal se centra en el Corne de 42 teclas, un teclado dividido y ortolineal, pero los pasos son extrapolables a otros modelos soportados por QMK.
• VIA: la aplicación o versión web de VIA, el firmware y herramienta gráfica que permite reasignar teclas y capas en tiempo real, sin recompilar cada vez.
• Editor de código: VS Code o cualquier otro editor/IDE que te resulte cómodo para editar archivos como keymap.c, config.h, rules.mk o los JSON de VIA.
• Conocimientos básicos de terminal: no hace falta ser un gurú, pero sí saber ejecutar comandos, navegar entre carpetas y leer mensajes de compilación.
• Homebrew instalado (en macOS, si aplica): para poder instalar QMK CLI y cualquier dependencia de forma sencilla. En Linux/WSL usarás el gestor de paquetes correspondiente.

Además de esto, te van a venir genial las referencias oficiales de QMK y algunos recursos específicos que complementan los pasos que verás aquí:

• Guía oficial de QMK para compilar firmware
• Guía oficial de QMK para flashear el firmware
• Keycodes avanzados y modificadores en QMK
• Página oficial de Homebrew
• JSON de Miryoku para crkbd (ideal si quieres ese diseño ya preparado)

Muchos de los archivos específicos de ejemplo, keymaps personalizados o layouts preparados para VIA suelen estar en repositorios de GitHub del propio usuario que escribe la guía. Ten en cuenta que, para tu caso concreto, lo normal será usar un fork o repo propio donde mantengas tu versión del firmware.

QMK y VIA: el cerebro de tu teclado

Antes de tocar nada es clave entender que tu teclado no es solo un conjunto de teclas y switches, sino un pequeño sistema programable. Lo que hace que cada tecla envíe un carácter u otro no es el sistema operativo, sino el firmware del teclado.

El firmware funciona como el cerebro que traduce cada pulsación en la acción correspondiente: una letra, una combinación de teclas, un atajo, el cambio de capa o incluso una macro compleja. En el ecosistema de teclados mecánicos personalizados destacan dos nombres: QMK y VIA.

QMK: potencia y control total

QMK (Quantum Mechanical Keyboard) es un firmware de código abierto extremadamente flexible que se ha convertido en el estándar de facto para teclados personalizados. Permite definir exactamente qué hace cada tecla, cómo se comportan las capas, qué macros quieres, cómo interactúan las teclas modificadoras y mucho más.

Con QMK puedes crear layouts completamente personalizados: reorganizar todo el teclado, definir diseños como Colemak-DH, Miryoku u otros, hacer que ciertas teclas cambien de función según si las pulsas, las mantienes o las tocas varias veces (tap dance), o configurar capas especiales para símbolos, números, navegación o funciones de programación.

La contrapartida es que toda esa flexibilidad se gestiona editando código C (principalmente en archivos como keymap.c) y compilando un firmware que luego flasheas en tu teclado. Cada cambio grande en la lógica suele implicar recompilar y volver a flashear.

VIA: cambios en tiempo real sin recompilar

VIA aparece como la herramienta complementaria orientada a la accesibilidad: un firmware y una aplicación que permiten modificar el mapa de teclas y las capas desde una interfaz gráfica, con efecto inmediato, sin tener que recompilar cada vez.

Si tu teclado es compatible con VIA (de fábrica o gracias a un firmware preparado), podrás reasignar teclas, mover símbolos, definir capas y crear macros con unos clics en la app, y verás los cambios al instante mientras escribes, sin necesidad de profundizar en el código.

La gracia del combo QMK + VIA es que puedes definir la base de tu firmware con QMK (número de capas, funciones avanzadas, soporte VIA, etc.) y luego usar VIA para ir retocando detalles del layout día a día, sin reflashear cada vez.

El contexto: teclados divididos, ergonomía y layouts

Muchos usuarios llegan a QMK y VIA después de comprar un teclado dividido ergonómico, como el Corne, para mejorar la postura, reducir molestias al escribir y ganar comodidad en sesiones largas.

En un teclado como el Corne, que suele ser dividido y ortolineal, el cambio respecto a un teclado tradicional es notable, pero también muy gratificante: menos distancia de desplazamiento de los dedos, menos tensión en muñecas y hombros y, con algo de práctica, una escritura muy precisa.

El problema típico es que la mayoría de estos teclados vienen con un keymap en inglés (generalmente US ANSI o ISO-UK) y, si trabajas habitualmente en español, acabas en una mezcla rara: teclado físico con mapeo US pero sistema operativo configurado en ES, o al revés.

Esto provoca situaciones como no acertar ni una tecla en otros ordenadores porque estás acostumbrado a un layout distinto, tener que instalar layouts en cada máquina donde conectas el teclado, o no encontrar símbolos clave para programar con comodidad.

El “camino corto”: usar firmware ya preparado (ej. Miryoku)

Si no quieres complicarte demasiado al principio, hay un método relativamente sencillo para tener un firmware funcional y compatible con VIA sin tener que aprender a escribir keymaps desde cero.

• Instala las herramientas básicas (Homebrew, QMK CLI).
• Descarga archivos ya preparados como config.h, keymap.c y rules.mk de un repositorio confiable.
• Crea una carpeta de keymap en la ruta de tu teclado dentro de QMK.
• Copia esos archivos en la nueva carpeta y compila el firmware para tu teclado (por ejemplo, crkbd).
• Flashea cada mitad del teclado usando el modo bootloader y QMK.
• Abre VIA y comprueba que detecta las capas y que puedes reasignar teclas.

En muchos casos, la comunidad ya ha creado diseños muy refinados como Miryoku, pensados precisamente para teclados pequeños y divididos. El JSON de Miryoku para crkbd se puede cargar en VIA o usar como base en tu firmware QMK, lo que te permite tener de golpe un layout muy optimizado.

Aun así, aunque uses un layout preconfigurado, es importante saber cómo tocar ciertos detalles si algo no te gusta o si, por ejemplo, necesitas soporte para español o más capas.

Preparar el entorno de compilación

Instalar Homebrew (macOS)

En macOS, la forma más cómoda de instalar QMK y sus dependencias es mediante Homebrew. Para ello, abre una terminal y ejecuta el comando de instalación indicado en la web oficial de Brew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Con esto tendrás un gestor de paquetes preparado para instalar QMK CLI y otras herramientas necesarias. En Linux, usarás el gestor de tu distribución; en Windows, lo más habitual es WSL o el instalador específico de QMK Toolbox/CLI.

Instalar y configurar QMK CLI

Una vez tengas un gestor de paquetes operativo, el siguiente paso es instalar QMK CLI, la herramienta de línea de comandos oficial para gestionar el repositorio de firmware, compilar y flashear.

Tras instalarla (por ejemplo con Homebrew o el método recomendado en la documentación), ejecuta en la terminal:

qmk setup

Durante este proceso se clonará el repositorio de qmk_firmware y se configurarán varias opciones. Según la propia documentación de QMK, en la mayoría de escenarios lo más sencillo es responder “y” (sí) a todas las preguntas, salvo que tengas una preferencia muy concreta.

Si quieres indicar una carpeta distinta para el repositorio QMK, puedes usar:

qmk setup -H <ruta_que_quieras>

Más adelante, esos valores se pueden modificar con qmk config cambiando la variable user.qmk_home. Para ver todas las opciones disponibles, tienes el comando:

qmk setup --help

Probar que el entorno compila correctamente

Antes de meterte a personalizar capas, es muy buena idea compilar un firmware de prueba y confirmar que todo el entorno QMK está bien configurado y que el compilador funciona.

Si usas un Corne (crkbd), asegúrate de que la carpeta crkbd aparece dentro de qmk_firmware/keyboards/. QMK descarga multitud de teclados, así que busca el tuyo en esa ruta para confirmar que está disponible.

Para compilar un firmware sencillo para el Corne, puedes usar:

qmk compile -kb crkbd -km <nombre_de_tu_nueva_carpeta_de_keymap>

Si en tu caso estás probando otro teclado, la sintaxis genérica es:

qmk compile -kb <nombre_teclado> -km default

En la salida de la terminal deberías ver algo del estilo:

Linking: .build/clueboard_66_rev3_default.elf [OK]
Creating load file for flashing: .build/clueboard_66_rev3_default.hex [OK]
Copying clueboard_66_rev3_default.hex to qmk_firmware folder [OK]
Checking file size of clueboard_66_rev3_default.hex [OK]
* The firmware size is fine - 26356/28672 (2316 bytes free)

Este tipo de mensaje indica que la compilación ha ido bien y que el firmware cabe en la memoria del microcontrolador, algo importante cuando empiezas a añadir capas y funciones extra.

Crear un nuevo keymap para tu teclado

Una vez verificado que compila, llega el momento de crear tu propio mapa de teclas. Puedes hacerlo de dos formas: definiendo parámetros por defecto en QMK CLI o creando directamente un keymap nuevo con un comando más explícito.

Si quieres trabajar casi siempre con el mismo teclado, puedes fijarlo así:

qmk config user.keyboard=crkbd

Y luego establecer un nombre por defecto para tu keymap:

qmk config user.keymap=<nombre_de_tu_keymap>

A partir de ahí, generar un nuevo mapa de teclas con:

qmk new-keymap

Si prefieres ir más directo, QMK proporciona un comando general:

qmk new-keymap -kb <nombre_teclado> -km <nombre_keymap>

Esto creará una nueva carpeta dentro de la ruta del teclado, por ejemplo en qmk_firmware/keyboards/crkbd/keymaps/<tu_keymap>, con unos archivos base que luego podrás adaptar (como keymap.c, rules.mk y, si lo necesitas, config.h).

Configurar el teclado en español (ISO) con QMK

Un caso muy habitual es querer seguir usando el sistema operativo con layout español sin tener que estar cambiando la configuración de idioma cada vez que conectas tu teclado dividido.

En QMK, las asignaciones específicas de idioma se resuelven gracias a los archivos de keymap extra que encontrarás en /quantum/keymap_extras. Dentro de esa carpeta hay definiciones para diferentes idiomas; en tu caso, te interesará especialmente keymap_spanish.h, que contiene todas las teclas específicas del layout español.

El flujo típico es:

• Partir de un keymap existente para tu teclado (por ejemplo el default del crkbd).
• Copiar esos archivos a tu nueva carpeta de keymap para no empezar de cero.
• Incluir el archivo keymap_spanish.h en tu keymap.c.
• Sustituir las keycodes adecuadas por las constantes definidas para español (por ejemplo para la ñ, acentos, símbolos específicos, etc.).

En el propio keymap_spanish.h verás todas las constantes disponibles mapeadas desde ISO inglés a ISO español. Para el resto de teclas genéricas puedes consultar las cabeceras de QMK o utilizar el QMK Configurator online para ver qué código corresponde a cada tecla que quieras.

Una estrategia muy práctica, sobre todo en teclados compactos como el Corne, es concentrar la mayoría de símbolos en una capa aparte. De este modo, en la capa base priorizas letras y caracteres habituales, y dejas símbolos de programación, números o funciones en otra capa accesible mediante una tecla de función o un modificador.

Añadir y gestionar capas en VIA

Aquí empieza la parte más entretenida: exprimir VIA para trabajar con varias capas y diseños complejos sin perderte. Muchos firmwares de fábrica solo ofrecen 4 capas, pero si usas diseños tipo Miryoku o quieres un sistema más sofisticado, probablemente necesites más.

El procedimiento general es:

• Editar el firmware QMK para definir cuántas capas quieres manejar y asegurarte de que el teclado tiene memoria suficiente.
• Descargar o crear los archivos que usarás para VIA (normalmente un JSON de layout que describe las teclas físicas y su orden).
• Guardar o mover esos archivos en una carpeta destinada a VIA dentro de tu proyecto (por ejemplo una carpeta llamada via).

Si necesitas ir más allá de las capas que vienen por defecto en tu configuración VIA, basta con abrir el archivo correspondiente (por ejemplo keyboard.c si tu proyecto lo usa para esa definición) en VS Code y copiar/pegar otra plantilla de capa vacía, respetando la estructura que ya tengan las anteriores.

No olvides que el microcontrolador de tu teclado tiene memoria limitada: aunque QMK permita definir muchas capas, no conviene pasarse. En muchos casos, 6 o 7 capas bien organizadas son más que suficientes.

Una vez recompilado el firmware con más capas, VIA las detectará y podrás asignar funciones a cada una desde la interfaz. Aquí es donde tus gustos, tu flujo de trabajo y tus atajos cobran protagonismo.

Particularidades de los JSON de VIA

VIA usa archivos JSON para describir la disposición física de las teclas y su orden interno. Esto puede ser un poco confuso al principio, porque la correspondencia entre lo que ves en pantalla y el orden numérico de las teclas no siempre es intuitiva.

Por ejemplo, para un Corne dividido, es frecuente que la mitad izquierda se mapee a algo como:

1, 2, 3, 4, 5, 6,
7, 8, 9, 10, 11, 12,
13, 14, 15, 16, 17, 18,
KC_NO, KC_NO, KC_NO, 19, 20, 21

Mientras que la mitad derecha se recorre al revés:

6, 5, 4, 3, 2, 1,
12, 11, 10, 9, 8, 7,
18, 17, 16, 15, 14, 13,
KC_NO, KC_NO, KC_NO, 19, 20, 21

La clave es entender que VIA recorre las teclas en un orden concreto y que KC_NO significa que no hay tecla física en esa posición, por lo que no debes asignarle nada. Mientras sigas esa secuencia en el JSON y mantengas el número correcto de teclas, VIA representará tu teclado correctamente.

Uso de teclas mod-tap en VIA

Las teclas mod-tap (una tecla que hace una cosa al tocarla y actúa como modificador al mantenerla) tienen una sintaxis distinta en VIA que en el código de QMK. En VIA, la forma habitual es:

MT(<keystroke_1> | <keystroke_2>)

Es decir, en lugar de la típica macro de QMK en C, usarás un formato específico en el JSON o en la interfaz de VIA que combine la pulsación normal y el modificador. Conviene revisar la documentación de QMK y de VIA para ver ejemplos de mod-tap, pero ten presente que el concepto es el mismo aunque la sintaxis cambie.

Flashear el firmware en el teclado

Con el firmware ya compilado y tu keymap preparado, llega el momento de flashear ambas mitades del teclado (en el caso de un Corne u otro teclado dividido) o el teclado completo si es una sola pieza.

Antes de nada deberías asignar en VIA una tecla con función de Reset, para poder poner el teclado en modo bootloader sin tener que tocar el microcontrolador físicamente. Esto te ahorrará muchísimos dolores de cabeza en futuros cambios.

Para flashear con QMK CLI, lo típico es:

qmk flash -kb crkbd -km <tu_nombre_de_keymap>

El comando qmk flash compila (si hace falta) y, a continuación, se queda esperando a que el teclado entre en modo de programación. En la terminal verás algo como:

Waiting for USB serial port - reset your controller now

En ese momento, mantén pulsada la tecla de Reset que hayas configurado (o el botón físico de reset del microcontrolador) hasta que el proceso de flasheo comience. Verás mensajes de progreso y, si todo va bien, el teclado volverá a funcionar con el nuevo firmware.

En un teclado dividido, tendrás que repetir el proceso para la otra mitad: desconectas una, conectas la otra, pones en modo bootloader y flasheas el mismo firmware (o el que corresponda si usas controladores distintos).

Trabajar con VIA tras flashear

Cuando ambas mitades estén correctamente flasheadas, el siguiente paso es abrir VIA en tu navegador o aplicación de escritorio y comprobar que detecta el teclado, las capas y el layout que has definido.

Existe un bug conocido en VIA por el cual, si alguna capa no tiene asignaciones de teclas, la interfaz web puede quedarse bloqueada en la pantalla de carga. Si te ocurre, recarga la página y, en la mayoría de los casos, VIA terminará de cargar sin problema. Siempre es buena idea rellenar mínimamente todas las capas definidas para evitar este tipo de errores.

Desde VIA podrás:

• Reasignar letras, símbolos y teclas modificadoras a placer.
• Crear capas dedicadas a escritura, programación, juego o navegación.
• Definir macros sencillas para acciones repetitivas.
• Guardar layouts en ficheros para compartirlos o moverlos entre ordenadores.

Si quieres usar el diseño Miryoku con Colemak-DH u otros layouts avanzados, suele haber ya JSONs preparados en repositorios públicos. Puedes cargarlos en VIA, ajustarlos a tu gusto y, si algo no te convence, entrar al código QMK para retocar el comportamiento base.

Otras formas de crear layouts y consideraciones prácticas

En sistemas como Windows tienes también herramientas para definir layouts personalizados a nivel de sistema operativo, que generan un instalador (.exe) con tu disposición concreta de teclas. Esto puede ser útil si solo quieres un mapa específico, pero tiene un inconveniente: necesitarás instalar ese layout en cada PC donde quieras usarlo.

La ventaja de usar QMK y VIA es que el layout “vive” dentro del teclado. Da igual en qué ordenador lo conectes: siempre se comportará igual, sin tener que tocar nada en el sistema. Para quienes usan portátiles del trabajo, ordenadores ajenos o cambian mucho de equipo, esto marca la diferencia.

Cuando empiezas a jugar con capas y símbolos, es normal que pases por varias iteraciones de diseño hasta encontrar una combinación que te resulte realmente cómoda. Lo más recomendable es:

• Probar una configuración durante varios días antes de cambiarla otra vez.
• Tomar notas de qué teclas echas en falta o qué combinaciones te resultan incómodas.
• Ir ajustando poco a poco en VIA y, cuando la base esté clara, consolidar los cambios en el firmware QMK.

Si en algún momento necesitas asignar teclas que no aparecen de forma evidente en la interfaz de VIA, puedes exportar tu layout a un archivo, abrirlo en VS Code y editar directamente el JSON, añadiendo los códigos necesarios siguiendo el patrón que usa VIA para ese teclado.

Con el tiempo, verás que tu teclado deja de ser un simple periférico y pasa a convertirse en una herramienta muy personal, adaptada a tu manera de trabajar y escribir, tanto si programas, escribes texto largo o juegas.

Todo este proceso puede parecer largo al principio, pero una vez que dominas el flujo de instalar QMK, crear keymaps, compilar, flashear y retocar capas con VIA, configurar un teclado por capas se convierte en algo casi rutinario y muy gratificante, especialmente cuando sientes que cada tecla y cada combinación están exactamente donde deberían para ti.