181 lines
17 KiB
HTML
181 lines
17 KiB
HTML
<!DOCTYPE html>
|
|
<html class="no-js" lang="en">
|
|
<head>
|
|
<title>Building Your First Firmware - QMK Firmware</title>
|
|
<meta name="description" content="Keyboard controller firmware for Atmel AVR and ARM USB families">
|
|
<meta name="author" content="QMK Community">
|
|
<meta charset="UTF-8">
|
|
<meta http-equiv="X-UA-Compatible" content="IE=edge">
|
|
|
|
<link rel="icon" href="../themes/daux/img/favicon-blue.png" type="image/x-icon">
|
|
|
|
<!-- Mobile -->
|
|
<meta name="apple-mobile-web-app-capable" content="yes" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
|
<!-- Font -->
|
|
|
|
<!-- CSS -->
|
|
<link href='../themes/daux/css/theme-blue.min.css' rel='stylesheet' type='text/css'>
|
|
<!-- Tipue Search -->
|
|
<link href="../tipuesearch/tipuesearch.css" rel="stylesheet">
|
|
|
|
<!--[if lt IE 9]>
|
|
<script src="../themes/daux/js/html5shiv-3.7.3.min.js"></script>
|
|
<![endif]-->
|
|
</head>
|
|
<body class=" ">
|
|
<div class="Columns content">
|
|
<aside class="Columns__left Collapsible">
|
|
<button type="button" class="Button Collapsible__trigger">
|
|
<span class="Collapsible__trigger__bar"></span>
|
|
<span class="Collapsible__trigger__bar"></span>
|
|
<span class="Collapsible__trigger__bar"></span>
|
|
</button>
|
|
|
|
<a class="Brand" href="../index.html">QMK Firmware</a>
|
|
|
|
<div class="Search">
|
|
<svg class="Search__icon" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 451 451">
|
|
<path d="M447.05 428l-109.6-109.6c29.4-33.8 47.2-77.9 47.2-126.1C384.65 86.2 298.35 0 192.35 0 86.25 0 .05 86.3.05 192.3s86.3 192.3 192.3 192.3c48.2 0 92.3-17.8 126.1-47.2L428.05 447c2.6 2.6 6.1 4 9.5 4s6.9-1.3 9.5-4c5.2-5.2 5.2-13.8 0-19zM26.95 192.3c0-91.2 74.2-165.3 165.3-165.3 91.2 0 165.3 74.2 165.3 165.3s-74.1 165.4-165.3 165.4c-91.1 0-165.3-74.2-165.3-165.4z"/>
|
|
</svg>
|
|
<input type="search" id="tipue_search_input" class="Search__field" placeholder="Search..." autocomplete="on"
|
|
results=25 autosave=text_search>
|
|
</div>
|
|
|
|
<div class="Collapsible__content">
|
|
<!-- Navigation -->
|
|
<ul class='Nav'><li class='Nav__item has-children'><a href="../Getting_Started/index.html" class="folder"><i class="Nav__arrow"> </i>Getting Started</a><ul class='Nav'><li class='Nav__item '><a href="../Getting_Started/Install_Build_Tools.html">Install Build Tools</a></li><li class='Nav__item '><a href="../Getting_Started/Vagrant.html">Vagrant</a></li><li class='Nav__item '><a href="../Getting_Started/Build_Compile_Instructions.html">Build Compile Instructions</a></li><li class='Nav__item '><a href="../Getting_Started/Flashing_Firmware.html">Flashing Firmware</a></li><li class='Nav__item '><a href="../Getting_Started/Contributing.html">Contributing</a></li><li class='Nav__item '><a href="../Getting_Started/How_to_Use_GitHub.html">How to Use GitHub</a></li><li class='Nav__item '><a href="../Getting_Started/Getting_Help.html">Getting Help</a></li></ul></li><li class='Nav__item Nav__item--open has-children'><a href="../Complete_Newbs_Guide/index.html" class="folder"><i class="Nav__arrow"> </i>Complete Newbs Guide</a><ul class='Nav'><li class='Nav__item '><a href="../Complete_Newbs_Guide/Complete_Newbie's_Guide.html">Complete Newbie's Guide</a></li><li class='Nav__item Nav__item--active'><a href="../Complete_Newbs_Guide/Building_Your_First_Firmware.html">Building Your First Firmware</a></li><li class='Nav__item '><a href="../Complete_Newbs_Guide/Flashing_Firmware.html">Flashing Firmware</a></li><li class='Nav__item '><a href="../Complete_Newbs_Guide/Testing_and_Debugging.html">Testing and Debugging</a></li></ul></li><li class='Nav__item has-children'><a href="../FAQ/index.html" class="folder"><i class="Nav__arrow"> </i>FAQ</a><ul class='Nav'><li class='Nav__item '><a href="../FAQ/General_FAQ.html">General FAQ</a></li><li class='Nav__item '><a href="../FAQ/Build_Compile_QMK.html">Build Compile QMK</a></li><li class='Nav__item '><a href="../FAQ/Debugging_and_Troubleshooting.html">Debugging and Troubleshooting</a></li><li class='Nav__item '><a href="../FAQ/Keymaps.html">Keymaps</a></li></ul></li><li class='Nav__item has-children'><a href="../Hardware/index.html" class="folder"><i class="Nav__arrow"> </i>Hardware</a><ul class='Nav'><li class='Nav__item '><a href="../Hardware/AVR_Processors.html">AVR Processors</a></li><li class='Nav__item '><a href="../Hardware/Drivers.html">Drivers</a></li></ul></li><li class='Nav__item has-children'><a href="../Features/index.html" class="folder"><i class="Nav__arrow"> </i>Features</a><ul class='Nav'><li class='Nav__item '><a href="../Features/Advanced_Keycodes.html">Advanced Keycodes</a></li><li class='Nav__item '><a href="../Features/Audio.html">Audio</a></li><li class='Nav__item '><a href="../Features/Auto_Shift.html">Auto Shift</a></li><li class='Nav__item '><a href="../Features/Backlight.html">Backlight</a></li><li class='Nav__item '><a href="../Features/Bluetooth.html">Bluetooth</a></li><li class='Nav__item '><a href="../Features/Bootmagic.html">Bootmagic</a></li><li class='Nav__item '><a href="../Features/Command.html">Command</a></li><li class='Nav__item '><a href="../Features/Dynamic_Macros.html">Dynamic Macros</a></li><li class='Nav__item '><a href="../Features/Grave_Escape.html">Grave Escape</a></li><li class='Nav__item '><a href="../Features/Key_Lock.html">Key Lock</a></li><li class='Nav__item '><a href="../Features/Layouts.html">Layouts</a></li><li class='Nav__item '><a href="../Features/Leader_Key.html">Leader Key</a></li><li class='Nav__item '><a href="../Features/Macros.html">Macros</a></li><li class='Nav__item '><a href="../Features/Mouse_Keys.html">Mouse Keys</a></li><li class='Nav__item '><a href="../Features/Pointing_Device.html">Pointing Device</a></li><li class='Nav__item '><a href="../Features/PS_2_Mouse.html">PS 2 Mouse</a></li><li class='Nav__item '><a href="../Features/RGB_Lighting.html">RGB Lighting</a></li><li class='Nav__item '><a href="../Features/Space_Cadet_Shift.html">Space Cadet Shift</a></li><li class='Nav__item '><a href="../Features/Space_Cadet_Shift_Enter.html">Space Cadet Shift Enter</a></li><li class='Nav__item '><a href="../Features/Stenography.html">Stenography</a></li><li class='Nav__item '><a href="../Features/Swap_Hands.html">Swap Hands</a></li><li class='Nav__item '><a href="../Features/Tap_Dance.html">Tap Dance</a></li><li class='Nav__item '><a href="../Features/Terminal.html">Terminal</a></li><li class='Nav__item '><a href="../Features/Thermal_Printer.html">Thermal Printer</a></li><li class='Nav__item '><a href="../Features/Unicode.html">Unicode</a></li><li class='Nav__item '><a href="../Features/Userspace.html">Userspace</a></li></ul></li><li class='Nav__item has-children'><a href="../Keycodes/index.html" class="folder"><i class="Nav__arrow"> </i>Keycodes</a><ul class='Nav'><li class='Nav__item '><a href="../Keycodes/Advanced_Keycodes.html">Advanced Keycodes</a></li><li class='Nav__item '><a href="../Keycodes/Backlight.html">Backlight</a></li><li class='Nav__item '><a href="../Keycodes/Basic.html">Basic</a></li><li class='Nav__item '><a href="../Keycodes/Bluetooth.html">Bluetooth</a></li><li class='Nav__item '><a href="../Keycodes/Bootmagic.html">Bootmagic</a></li><li class='Nav__item '><a href="../Keycodes/Quantum_Keycodes.html">Quantum Keycodes</a></li><li class='Nav__item '><a href="../Keycodes/RGB_Lighting.html">RGB Lighting</a></li><li class='Nav__item '><a href="../Keycodes/Stenography.html">Stenography</a></li><li class='Nav__item '><a href="../Keycodes/Thermal_Printer.html">Thermal Printer</a></li><li class='Nav__item '><a href="../Keycodes/US_ANSI_Shifted_keys.html">US ANSI Shifted keys</a></li></ul></li><li class='Nav__item has-children'><a href="../Reference/index.html" class="folder"><i class="Nav__arrow"> </i>Reference</a><ul class='Nav'><li class='Nav__item '><a href="../Reference/Keyboard_Guidelines.html">Keyboard Guidelines</a></li><li class='Nav__item '><a href="../Reference/Compatable_Microcontrollers.html">Compatable Microcontrollers</a></li><li class='Nav__item '><a href="../Reference/Config_Options.html">Config Options</a></li><li class='Nav__item '><a href="../Reference/Custom_Code.html">Custom Code</a></li><li class='Nav__item '><a href="../Reference/Documentation_Best_Practices.html">Documentation Best Practices</a></li><li class='Nav__item '><a href="../Reference/Documentation_Templates.html">Documentation Templates</a></li><li class='Nav__item '><a href="../Reference/Glossary.html">Glossary</a></li><li class='Nav__item '><a href="../Reference/Keymap_Overview.html">Keymap Overview</a></li><li class='Nav__item '><a href="../Reference/Unit_Testing.html">Unit Testing</a></li></ul></li><li class='Nav__item has-children'><a href="../For_Makers_And_Modders/index.html" class="folder"><i class="Nav__arrow"> </i>For Makers And Modders</a><ul class='Nav'><li class='Nav__item '><a href="../For_Makers_And_Modders/Hand_Wiring_Guide.html">Hand Wiring Guide</a></li><li class='Nav__item '><a href="../For_Makers_And_Modders/ISP_Flashing_Guide.html">ISP Flashing Guide</a></li></ul></li><li class='Nav__item has-children'><a href="../IDEs/index.html" class="folder"><i class="Nav__arrow"> </i>IDEs</a><ul class='Nav'><li class='Nav__item '><a href="../IDEs/Eclipse.html">Eclipse</a></li></ul></li><li class='Nav__item has-children'><a href="../For_a_Deeper_Understanding/index.html" class="folder"><i class="Nav__arrow"> </i>For a Deeper Understanding</a><ul class='Nav'><li class='Nav__item '><a href="../For_a_Deeper_Understanding/How_Keyboards_Work.html">How Keyboards Work</a></li><li class='Nav__item '><a href="../For_a_Deeper_Understanding/Understanding_QMK.html">Understanding QMK</a></li></ul></li></ul>
|
|
|
|
<div class="Links">
|
|
<hr/>
|
|
<a href="https://qmk.fm/" target="_blank">QMK Link</a>
|
|
<br />
|
|
</div>
|
|
|
|
|
|
|
|
</div>
|
|
</aside>
|
|
<div class="Columns__right Columns__right--full">
|
|
<div class="Columns__right__content">
|
|
<div class="doc_content">
|
|
<article class="Page">
|
|
|
|
<div class="Page__header">
|
|
<h1><a href="../Complete_Newbs_Guide/index.html">Complete Newbs Guide</a> <svg class="Page__header--separator" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 477.175 477.175"><path d="M360.73 229.075l-225.1-225.1c-5.3-5.3-13.8-5.3-19.1 0s-5.3 13.8 0 19.1l215.5 215.5-215.5 215.5c-5.3 5.3-5.3 13.8 0 19.1 2.6 2.6 6.1 4 9.5 4 3.4 0 6.9-1.3 9.5-4l225.1-225.1c5.3-5.2 5.3-13.8.1-19z"/></svg> <a href="../Complete_Newbs_Guide/Building_Your_First_Firmware.html">Building Your First Firmware</a></h1>
|
|
</div>
|
|
|
|
<div class="s-content">
|
|
<ul class="TableOfContents">
|
|
<li>
|
|
<p><a href="#page_Building-Your-First-Firmware">Building Your First Firmware</a></p>
|
|
<ul class="TableOfContents">
|
|
<li>
|
|
<p><a href="#page_Navigate-To-Your-Keymaps-Folder">Navigate To Your Keymaps Folder</a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#page_Create-a-Copy-Of-The-Keymap">Create a Copy Of The <code>default</code> Keymap</a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#page_Open-In-Your-Favorite-Text-Editor">Open <code>keymap.c</code> In Your Favorite Text Editor</a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#page_Customize-The-Layout-To-Your-Liking">Customize The Layout To Your Liking</a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#page_Build-Your-Firmware">Build Your Firmware</a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#page_Flash-Your-Firmware">Flash Your Firmware</a></p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<h1 id="page_Building-Your-First-Firmware">Building Your First Firmware</h1>
|
|
<p>Now that you have setup 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>
|
|
<p>If you have closed and reopened your terminal window since following the first part of the guide, don't forget to <code>cd qmk_firmware</code> so that your terminal is in the correct directory.</p>
|
|
<h2 id="page_Navigate-To-Your-Keymaps-Folder">Navigate To Your Keymaps Folder</h2>
|
|
<p>Start by navigating to the <code>keymaps</code> folder for your keyboard.</p>
|
|
<p>{% hint style='info' %}
|
|
If you are on macOS or Windows there are commands you can use to easily open the keymaps folder.</p>
|
|
<p>macOS:</p>
|
|
<pre><code>open keyboards/<keyboard_folder>/keymaps
|
|
</code></pre>
|
|
<p>Windows:</p>
|
|
<pre><code>start keyboards/<keyboard_folder>/keymaps
|
|
</code></pre>
|
|
<p>{% endhint %}</p>
|
|
<h2 id="page_Create-a-Copy-Of-The-Keymap">Create a Copy Of The <code>default</code> Keymap</h2>
|
|
<p>Once you have the <code>keymaps</code> folder open you will want to create a copy of the <code>default</code> folder. We highly recommend you name your folder the same as your GitHub username, but you can use any name you want as long as it contains only lower case letters, numbers, and the underscore character.</p>
|
|
<h2 id="page_Open-In-Your-Favorite-Text-Editor">Open <code>keymap.c</code> In Your Favorite Text Editor</h2>
|
|
<p>Open up your <code>keymap.c</code>. 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>
|
|
<pre><code>const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
|
|
</code></pre>
|
|
<p>This line indicates the start of the list of Layers. Below that you'll find lines containing either <code>LAYOUT</code> or <code>KEYMAP</code>, and these lines indicate the start of a layer. Below that line is the list of keys that comprise a that particular layer.</p>
|
|
<p>{% hint style='danger' %}
|
|
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.
|
|
{% endhint %}</p>
|
|
<h2 id="page_Customize-The-Layout-To-Your-Liking">Customize The Layout To Your Liking</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. Check the following documentation to find out what you can define here:</p>
|
|
<ul>
|
|
<li>
|
|
<a href="../Keycodes/index.html">Keycodes</a>
|
|
</li>
|
|
<li>
|
|
<a href="../Features/index.html">Features</a>
|
|
</li>
|
|
<li>
|
|
<a href="../FAQ/index.html">FAQ</a>
|
|
</li>
|
|
</ul>
|
|
<p>{% hint style='info' %}
|
|
While you get a feel for how keymaps work, keep each change small. Bigger changes make it harder to debug any problems that arise.
|
|
{% endhint %}</p>
|
|
<h2 id="page_Build-Your-Firmware">Build Your Firmware</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 build command:</p>
|
|
<pre><code>make <my_keyboard>:<my_keymap>
|
|
</code></pre>
|
|
<p>For example, if your keymap is named "xyverz" and you're building a keymap for a rev5 planck, you'll use this command:</p>
|
|
<pre><code>make planck/rev5:xyverz
|
|
</code></pre>
|
|
<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>
|
|
<pre><code>Linking: .build/planck_rev5_xyverz.elf [OK]
|
|
Creating load file for flashing: .build/planck_rev5_xyverz.hex [OK]
|
|
Copying planck_rev5_xyverz.hex to qmk_firmware folder [OK]
|
|
Checking file size of planck_rev5_xyverz.hex [OK]
|
|
* File size is fine - 18392/28672
|
|
</code></pre>
|
|
<h2 id="page_Flash-Your-Firmware">Flash Your Firmware</h2>
|
|
<p>Move on to <a href="Flashing_Firmware.html">Flashing Firmware</a> to learn how to write your new firmware to your keyboard.</p>
|
|
</div>
|
|
|
|
<nav>
|
|
<ul class="Pager">
|
|
<li class=Pager--prev><a href="../Complete_Newbs_Guide/Complete_Newbie's_Guide.html">Previous</a></li> <li class=Pager--next><a href="../Complete_Newbs_Guide/Flashing_Firmware.html">Next</a></li> </ul>
|
|
</nav>
|
|
</article>
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<!-- JS -->
|
|
<script src="../themes/daux/js/jquery-1.11.3.min.js"></script><script src="../themes/daux/js/highlight.pack.js"></script><script src="../themes/daux/js/daux.js"></script>
|
|
<!-- Tipue Search -->
|
|
<script type="text/javascript" src="../tipuesearch/tipuesearch.js"></script>
|
|
|
|
<script>
|
|
window.onunload = function(){}; // force $(document).ready to be called on back/forward navigation in firefox
|
|
$(function() {
|
|
tipuesearch({
|
|
'base_url': '../'
|
|
});
|
|
});
|
|
</script>
|
|
|
|
</body>
|
|
</html>
|