mirror of
https://github.com/qmk/qmk_firmware.git
synced 2025-02-27 01:56:43 +00:00
16 lines
12 KiB
JavaScript
16 lines
12 KiB
JavaScript
import { _ as _export_sfc, c as createElementBlock, o as openBlock, a8 as createStaticVNode } from "./chunks/framework.DyMmIvSC.js";
|
||
const __pageData = JSON.parse('{"title":"Building Your First Firmware","description":"","frontmatter":{},"headers":[],"relativePath":"newbs_building_firmware.md","filePath":"newbs_building_firmware.md"}');
|
||
const _sfc_main = { name: "newbs_building_firmware.md" };
|
||
const _hoisted_1 = /* @__PURE__ */ createStaticVNode('<h1 id="building-your-first-firmware" tabindex="-1">Building Your First Firmware <a class="header-anchor" href="#building-your-first-firmware" aria-label="Permalink to "Building Your First Firmware""></a></h1><p>Now that you have set up your build environment you are ready to start building custom firmware. For this section of the guide we will bounce between 3 programs- your file manager, your text editor, and your terminal window. Keep all 3 open until you are done and happy with your keyboard firmware.</p><h2 id="configure-your-build-environment-defaults-optional" tabindex="-1">Configure Your Build Environment Defaults (Optional) <a class="header-anchor" href="#configure-your-build-environment-defaults-optional" aria-label="Permalink to "Configure Your Build Environment Defaults (Optional)""></a></h2><p>You can configure your build environment to set the defaults and make working with QMK less tedious. Let's do that now!</p><p>Most people new to QMK only have 1 keyboard. You can set this keyboard as your default with the <code>qmk config</code> command. For example, to set your default keyboard to <code>clueboard/66/rev4</code>:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> config</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> user.keyboard=clueboard/66/rev4</span></span></code></pre></div><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>The keyboard option is the path relative to the keyboard directory, the above example would be found in <code>qmk_firmware/keyboards/clueboard/66/rev4</code>. If you're unsure you can view a full list of supported keyboards with <code>qmk list-keyboards</code>.</p></div><p>You can also set your default keymap name. Most people use their GitHub username like the keymap name from the previous steps:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> config</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> user.keymap=</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"><</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">github_usernam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span></code></pre></div><h2 id="create-a-new-keymap" tabindex="-1">Create a New Keymap <a class="header-anchor" href="#create-a-new-keymap" aria-label="Permalink to "Create a New Keymap""></a></h2><p>To create your own keymap you'll want to create a copy of the <code>default</code> keymap. If you configured your build environment in the last step you can do that easily with the QMK CLI:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> new-keymap</span></span></code></pre></div><p>If you did not configure your environment, or you have multiple keyboards, you can specify a keyboard name:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> new-keymap</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -kb</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">keyboard_nam</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">e</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span></code></pre></div><p>Look at the output from that command, you should see something like this:</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>Ψ Created a new keymap called <github_username> in: /home/me/qmk_firmware/keyboards/clueboard/66/rev3/keymaps/<github_username>.</span></span></code></pre></div><p>This is the location of your new <code>keymap.c</code> file.</p><h2 id="open-keymap-c-in-your-favorite-text-editor" tabindex="-1">Open <code>keymap.c</code> In Your Favorite Text Editor <a class="header-anchor" href="#open-keymap-c-in-your-favorite-text-editor" aria-label="Permalink to "Open `keymap.c` In Your Favorite Text Editor""></a></h2><p>Open your <code>keymap.c</code> file in your text editor. Inside this file you'll find the structure that controls how your keyboard behaves. At the top of <code>keymap.c</code> there may be some defines and enums that make the keymap easier to read. Farther down you'll find a line that looks like this:</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;">const</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> uint16_t</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> PROGMEM keymaps</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">[]</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">[MATRIX_ROWS][MATRIX_COLS] </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span></code></pre></div><p>This line indicates where the list of Layers begins. Below that you'll find lines containing <code>LAYOUT</code>, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a particular layer.</p><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>When editing your keymap file be careful not to add or remove any commas. If you do, you will prevent your firmware from compiling and it may not be easy to figure out where the extra, or missing, comma is.</p></div><h2 id="customize-the-layout-to-your-liking" tabindex="-1">Customize The Layout To Your Liking <a class="header-anchor" href="#customize-the-layout-to-your-liking" aria-label="Permalink to "Customize The Layout To Your Liking""></a></h2><p>How to complete this step is entirely up to you. Make the one change that's been bugging you, or completely rework everything. You can remove layers if you don't need all of them, or add layers up to a total of 32. There are a lot of features in QMK, explore the sidebar to the left under "Using QMK" to see the full list. To get you started here are a few of the easier to use features:</p><ul><li><a href="./keycodes_basic">Basic Keycodes</a></li><li><a href="./quantum_keycodes">Quantum Keycodes</a></li><li><a href="./features/grave_esc">Grave/Escape</a></li><li><a href="./features/mouse_keys">Mouse keys</a></li></ul><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>While you get a feel for how keymaps work, keep each change small. Bigger changes make it harder to debug any problems that arise.</p></div><h2 id="build-your-firmware" tabindex="-1">Build Your Firmware <a class="header-anchor" href="#build-your-firmware" aria-label="Permalink to "Build Your Firmware {#build-your-firmware}""></a></h2><p>When your changes to the keymap are complete you will need to build the firmware. To do so go back to your terminal window and run the compile command:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> compile</span></span></code></pre></div><p>If you did not configure defaults for your environment, or you have multiple keyboards, you can specify a keyboard and/or keymap:</p><div class="language-sh vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">sh</span><pre class="shiki shiki-themes github-light github-dark vp-code"><code><span class="line"><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">qmk</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> compile</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -kb</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">keyboar</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">d</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> -km</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> <</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">keyma</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">p</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">></span></span></code></pre></div><p>While this compiles you will have a lot of output going to the screen informing you of what files are being compiled. It should end with output that looks similar to this:</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>Linking: .build/planck_rev5_default.elf [OK]</span></span>\n<span class="line"><span>Creating load file for flashing: .build/planck_rev5_default.hex [OK]</span></span>\n<span class="line"><span>Copying planck_rev5_default.hex to qmk_firmware folder [OK]</span></span>\n<span class="line"><span>Checking file size of planck_rev5_default.hex [OK]</span></span>\n<span class="line"><span> * The firmware size is fine - 27312/28672 (95%, 1360 bytes free)</span></span></code></pre></div><h2 id="flash-your-firmware" tabindex="-1">Flash Your Firmware <a class="header-anchor" href="#flash-your-firmware" aria-label="Permalink to "Flash Your Firmware""></a></h2><p>Move on to <a href="./newbs_flashing">Flashing Firmware</a> to learn how to write your new firmware to your keyboard.</p>', 35);
|
||
const _hoisted_36 = [
|
||
_hoisted_1
|
||
];
|
||
function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) {
|
||
return openBlock(), createElementBlock("div", null, _hoisted_36);
|
||
}
|
||
const newbs_building_firmware = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]);
|
||
export {
|
||
__pageData,
|
||
newbs_building_firmware as default
|
||
};
|