mirror of
https://github.com/qmk/qmk_firmware.git
synced 2025-02-27 01:56:43 +00:00
168 lines
42 KiB
JavaScript
168 lines
42 KiB
JavaScript
|
import { _ as _export_sfc, c as createElementBlock, o as openBlock, a8 as createStaticVNode, l as createBaseVNode } from "./chunks/framework.DyMmIvSC.js";
|
|||
|
|
const __pageData = JSON.parse('{"title":"Supporting Your Keyboard in QMK Configurator","description":"","frontmatter":{},"headers":[],"relativePath":"reference_configurator_support.md","filePath":"reference_configurator_support.md"}');
|
|||
|
|
const _sfc_main = { name: "reference_configurator_support.md" };
|
|||
|
|
const _hoisted_1 = /* @__PURE__ */ createStaticVNode('<h1 id="supporting-your-keyboard-in-qmk-configurator" tabindex="-1">Supporting Your Keyboard in QMK Configurator <a class="header-anchor" href="#supporting-your-keyboard-in-qmk-configurator" aria-label="Permalink to "Supporting Your Keyboard in QMK Configurator""></a></h1><p>This page covers how to properly support keyboards in the <a href="https://config.qmk.fm/" target="_blank" rel="noreferrer">QMK Configurator</a>.</p><h2 id="how-the-configurator-understands-keyboards" tabindex="-1">How the Configurator Understands Keyboards <a class="header-anchor" href="#how-the-configurator-understands-keyboards" aria-label="Permalink to "How the Configurator Understands Keyboards""></a></h2><p>To understand how the Configurator understands keyboards, first one must understand layout macros. For this exercise, we're going to imagine a 17-key numpad PCB, which we're going to call <code>numpad</code>.</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span>|---------------|</span></span>\n<span class="line"><span>|NLk| / | * | - |</span></span>\n<span class="line"><span>|---+---+---+---|</span></span>\n<span class="line"><span>|7 |8 |9 | + |</span></span>\n<span class="line"><span>|---+---+---| |</span></span>\n<span class="line"><span>|4 |5 |6 | |</span></span>\n<span class="line"><span>|---+---+---+---|</span></span>\n<span class="line"><span>|1 |2 |3 |Ent|</span></span>\n<span class="line"><span>|-------+---| |</span></span>\n<span class="line"><span>|0 | . | |</span></span>\n<span class="line"><span>|---------------|</span></span></code></pre></div><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>For more on layout macros, see <a href="./understanding_qmk#matrix-scanning">Understanding QMK: Matrix Scanning</a> and <a href="./understanding_qmk#matrix-to-physical-layout-map">Understanding QMK: Matrix to Physical Layout Map</a>.</p></div><p>The Configurator's API reads the keyboard's <code>.h</code> file from <code>qmk_firmware/keyboards/<keyboard>/<keyboard>.h</code>. For our numpad, this file would be <code>qmk_firmware/keyboards/numpad/numpad.h</code>:</p><div class="language-c vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">c</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">#pragma</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> once</span></span>\n<span class="line"></span>\n<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">#define</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> LAYOUT</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">( </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> k00, k01, k02, k03, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> k10, k11, k12, k13, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> k20, k21, k22, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> k30, k31, k32, k33, </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> k40, k42 </span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\</span></span>\n<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> ) { </span><
|
|||
|
|
const _hoisted_28 = /* @__PURE__ */ createBaseVNode("table", {
|
|||
|
|
"label:.,": "",
|
|||
|
|
"x:2,": "",
|
|||
|
|
"y:4": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("thead", null, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", null, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("th", { style: { "text-align": "center" } }, "key in layout macro"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("th", { style: { "text-align": "left" } }, "JSON object used")
|
|||
|
|
])
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tbody", null, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:NumLock,": "",
|
|||
|
|
"x:0,": "",
|
|||
|
|
"y:0": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k00"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:,": "",
|
|||
|
|
"x:1,": "",
|
|||
|
|
"y:0": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k01"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:*,": "",
|
|||
|
|
"x:2,": "",
|
|||
|
|
"y:0": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k02"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:-,": "",
|
|||
|
|
"x:3,": "",
|
|||
|
|
"y:0": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k03"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:7,": "",
|
|||
|
|
"x:0,": "",
|
|||
|
|
"y:1": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k10"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:8,": "",
|
|||
|
|
"x:1,": "",
|
|||
|
|
"y:1": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k11"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:9,": "",
|
|||
|
|
"x:2,": "",
|
|||
|
|
"y:1": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k12"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:+,": "",
|
|||
|
|
"x:3,": "",
|
|||
|
|
"y:1,": "",
|
|||
|
|
"h:2": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k13"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:4,": "",
|
|||
|
|
"x:0,": "",
|
|||
|
|
"y:2": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k20"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:5,": "",
|
|||
|
|
"x:1,": "",
|
|||
|
|
"y:2": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k21"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:6,": "",
|
|||
|
|
"x:2,": "",
|
|||
|
|
"y:2": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k22"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:1,": "",
|
|||
|
|
"x:0,": "",
|
|||
|
|
"y:3": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k30"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:2,": "",
|
|||
|
|
"x:1,": "",
|
|||
|
|
"y:3": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k31"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:3,": "",
|
|||
|
|
"x:2,": "",
|
|||
|
|
"y:3": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k32"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:Enter,": "",
|
|||
|
|
"x:3,": "",
|
|||
|
|
"y:3,": "",
|
|||
|
|
"h:2": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k33"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", {
|
|||
|
|
"label:0,": "",
|
|||
|
|
"x:0,": "",
|
|||
|
|
"y:4,": "",
|
|||
|
|
"w:2": ""
|
|||
|
|
}, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k40"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
]),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("tr", null, [
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "center" } }, "k42"),
|
|||
|
|
/* @__PURE__ */ createBaseVNode("td", { style: { "text-align": "left" } })
|
|||
|
|
])
|
|||
|
|
])
|
|||
|
|
], -1);
|
|||
|
|
const _hoisted_29 = /* @__PURE__ */ createStaticVNode('<p>When a user selects the top-left key in the Configurator, and assigns Num Lock to it, the Configurator builds a keymap file with <code>KC_NUM</code> as the first key, and so on as the keymap is built. The <code>label</code> keys are not used; they are only for the user's reference in identifying specific keys when debugging the <code>info.json</code> file.</p><h2 id="issues-and-hazards" tabindex="-1">Issues and Hazards <a class="header-anchor" href="#issues-and-hazards" aria-label="Permalink to "Issues and Hazards""></a></h2><p>Currently, the Configurator does not support key rotation or non-rectangular key shapes like ISO Enter. Additionally, keys that are vertically-offset from their "row" — the arrow keys on 1800-layouts like the <a href="https://github.com/qmk/qmk_firmware/tree/4ac48a61a66206beaf2fdd5f2939d8bbedd0004c/keyboards/tkc1800/" target="_blank" rel="noreferrer">TKC1800</a> being a prominent example — confuse the KLE-to-JSON Converter, if not adjusted for by the contributor of the <code>info.json</code> file.</p><h3 id="workarounds" tabindex="-1">Workarounds <a class="header-anchor" href="#workarounds" aria-label="Permalink to "Workarounds""></a></h3><h4 id="non-rectangular-keys" tabindex="-1">Non-rectangular keys <a class="header-anchor" href="#non-rectangular-keys" aria-label="Permalink to "Non-rectangular keys""></a></h4><p>For ISO Enter keys, QMK custom is to display it as a rectangular key, 1.25u wide and 2u high, aligned so its right edge is aligned with the right edge of the alphanumeric key block.</p><p><img src="https://i.imgur.com/JKngtTw.png" alt=""><br><em>A 60% keyboard in standard ISO layout, as rendered by QMK Configurator.</em></p><h4 id="vertically-offset-keys" tabindex="-1">Vertically-offset keys <a class="header-anchor" href="#vertically-offset-keys" aria-label="Permalink to "Vertically-offset keys""></a></h4><p>For vertically-offset keys, place them in KLE as if they were not offset, then edit the Y-values as needed in the converted JSON file</p><p><img src="https://i.imgur.com/fmDvDzR.png" alt=""><br><em>An 1800-layout keyboard as rendered in Keyboard Layout Editor, without the vertical offset applied to the arrow keys.</em></p><p><img src="https://i.imgur.com/8beYMBR.png" alt=""><br><em>A Unix diff file, showing the changes needed to vertically-offset the arrow keys in our keyboard's JSON file.</em></p>', 11);
|
|||
|
|
const _hoisted_40 = [
|
|||
|
|
_hoisted_1,
|
|||
|
|
_hoisted_28,
|
|||
|
|
_hoisted_29
|
|||
|
|
];
|
|||
|
|
function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
|
|||
|
|
return openBlock(), createElementBlock("div", null, _hoisted_40);
|
|||
|
|
}
|
|||
|
|
const reference_configurator_support = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]);
|
|||
|
|
export {
|
|||
|
|
__pageData,
|
|||
|
|
reference_configurator_support as default
|
|||
|
|
};
|