227 lines
19 KiB
HTML
227 lines
19 KiB
HTML
<!DOCTYPE html>
|
|
<html class="no-js" lang="en">
|
|
<head>
|
|
<title>Userspace - 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-navy.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-navy.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 has-children'><a href="../Getting_Started/Install_Build_Tools/index.html" class="folder"><i class="Nav__arrow"> </i>Install Build Tools</a><ul class='Nav'><li class='Nav__item '><a href="../Getting_Started/Install_Build_Tools/Vagrant.html">Vagrant</a></li></ul></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 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 '><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 Nav__item--open 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 Nav__item--active'><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">
|
|
</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="../Features/index.html">Features</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="../Features/Userspace.html">Userspace</a></h1>
|
|
<span class="EditOn">
|
|
<a href="https://github.com/qmk/qmk_firmware/blob/master/docs/05_Features/Userspace.md" target="_blank">
|
|
Edit on GitHub </a>
|
|
</span>
|
|
</div>
|
|
|
|
<div class="s-content">
|
|
<ul class="TableOfContents">
|
|
<li>
|
|
<p><a href="#page_Userspace-Sharing-Code-Between-Keymaps">Userspace: Sharing Code Between Keymaps</a></p>
|
|
<ul class="TableOfContents">
|
|
<li>
|
|
<p><a href="#page_Readme">Readme</a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#page_section_3"><code>Config.h</code></a></p>
|
|
</li>
|
|
<li>
|
|
<p><a href="#page_Example">Example</a></p>
|
|
<ul class="TableOfContents">
|
|
<li>
|
|
<p><a href="#page_Consolidated-Macros">Consolidated Macros</a></p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li>
|
|
<p><a href="#page_Override-default-userspace">Override default userspace</a></p>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<h1 id="page_Userspace-Sharing-Code-Between-Keymaps">Userspace: Sharing Code Between Keymaps</h1>
|
|
<p>If you use more than one keyboard with a similar keymap, you might see the benefit in being able to share code between them. Create your own folder in <code>users/</code> named the same as your keymap (ideally your github username, <code><name></code>) with the following structure:</p>
|
|
<ul>
|
|
<li>
|
|
<code>/users/<name>/</code> (added to the path automatically)
|
|
<ul>
|
|
<li>
|
|
<code>readme.md</code> (optional, recommended)</li>
|
|
<li>
|
|
<code>rules.mk</code> (included automatically)</li>
|
|
<li>
|
|
<code><name>.h</code> (optional)</li>
|
|
<li>
|
|
<code><name>.c</code> (optional)</li>
|
|
<li>
|
|
<code>config.h</code> (optional)</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
<p><code><name>.c</code> will need to be added to the SRC in <code>rules.mk</code> like this:</p>
|
|
<pre><code>SRC += <name>.c
|
|
</code></pre>
|
|
<p>Additional files may be added in the same way - it's recommended you have one named <code><name></code>.c/.h though.</p>
|
|
<p>All this only happens when you build a keymap named <code><name></code>, like this:</p>
|
|
<pre><code>make planck:<name>
|
|
</code></pre>
|
|
<p>For example,</p>
|
|
<pre><code>make planck:jack
|
|
</code></pre>
|
|
<p>Will include the <code>/users/jack/</code> folder in the path, along with <code>/users/jack/rules.mk</code>.</p>
|
|
<p>Additionally, <code>config.h</code> here will be processed like the same file in your keymap folder. This is handled separately from the <code><name>.h</code> file.</p>
|
|
<p>The reason for this, is that <code><name>.h</code> won't be added in time to add settings (such as <code>#define TAPPING_TERM 100</code>), and including the <code><name.h></code> file in any <code>config.h</code> files will result in compile issues.</p>
|
|
<p>So you should use the <code>config.h</code> for QMK settings, and the <code><name>.h</code> file for user or keymap specific settings.</p>
|
|
<h2 id="page_Readme">Readme</h2>
|
|
<p>Please include authorship (your name, github username, email), and optionally <a href="https://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses" class="Link--external">a license that's GPL compatible</a>.</p>
|
|
<h2 id="page_section_3"><code>Config.h</code></h2>
|
|
<p>If you do add a <code>config,h</code> file, you want to make sure that it only gets processed once. So you may want to start off with something like this:</p>
|
|
<pre><code class="language-c">#ifndef USERSPACE_CONFIG_H
|
|
#define USERSPACE_CONFIG_H
|
|
|
|
// Put normal config.h settings here:
|
|
|
|
#endif // !USERSPACE_CONFIG_H
|
|
</code></pre>
|
|
<p>You can use any option hre that you could use in your keymap's <code>config.h</code> file. You can find a list of vales <a href="../Reference/Config_Options.html">here</a>.</p>
|
|
<h2 id="page_Example">Example</h2>
|
|
<p>For a brief example, checkout <code>/users/_example/</code> , or for a more detailed examples check out <a href="https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.h" class="Link--external"><code>template.h</code></a> and <a href="https://github.com/qmk/qmk_firmware/blob/master/users/drashna/template.c" class="Link--external"><code>template.c</code></a> in <code>/users/drashna/</code> .</p>
|
|
<h3 id="page_Consolidated-Macros">Consolidated Macros</h3>
|
|
<p>If you wanted to consolidate macros and other functions into your userspace for all of your keymaps, you can do that. The issue is that you then cannot call any function defined in your userspace, or it gets complicated. To better handle this, you can call the functions here and create new functions to use in individual keymaps.</p>
|
|
<p>First, you'd want to go through all of your <code>keymap.c</code> files and replace <code>process_record_user</code> with <code>process_record_keymap</code> instead. This way, you can still use keyboard specific codes on those boards, and use your custom "global" keycodes as well. You'll also want to replace <code>SAFE_RANGE</code> with <code>NEW_SAFE_RANGE</code> so that you wont have any overlapping keycodes</p>
|
|
<p>Then add <code>#include <name.h></code> to all of your keymap.c files. This allows you to use these new keycodes without having to redefine them in each keymap.</p>
|
|
<p>Once you've done that, you'll want to set the keycode definitions that you need to the <code><name>.h</code> file. For instance:</p>
|
|
<pre><code>#ifndef USERSPACE
|
|
#define USERSPACE
|
|
|
|
#include "quantum.h"
|
|
|
|
// Define all of
|
|
enum custom_keycodes {
|
|
KC_MAKE = SAFE_RANGE,
|
|
NEW_SAFE_RANGE //use "NEW_SAFE_RANGE" for keymap specific codes
|
|
};
|
|
|
|
#endif
|
|
</code></pre>
|
|
<p>Now you want to create the <code><name>.c</code> file, and add this content to it:</p>
|
|
<pre><code>#include "<name>.h"
|
|
#include "quantum.h"
|
|
#include "action.h"
|
|
#include "version.h"
|
|
|
|
__attribute__ ((weak))
|
|
bool process_record_keymap(uint16_t keycode, keyrecord_t *record) {
|
|
return true;
|
|
}
|
|
|
|
bool process_record_user(uint16_t keycode, keyrecord_t *record) {
|
|
switch (keycode) {
|
|
case KC_MAKE:
|
|
if (!record->event.pressed) {
|
|
SEND_STRING("make " QMK_KEYBOARD ":" QMK_KEYMAP
|
|
#if (defined(BOOTLOADER_DFU) || defined(BOOTLOADER_LUFA_DFU) || defined(BOOTLOADER_QMK_DFU))
|
|
":dfu "
|
|
#elif defined(BOOTLOADER_HALFKAY)
|
|
":teensy "
|
|
#elif defined(BOOTLOADER_CATERINA)
|
|
":avrdude "
|
|
#endif
|
|
SS_TAP(X_ENTER));
|
|
}
|
|
return false;
|
|
break;
|
|
}
|
|
return process_record_keymap(keycode, record);
|
|
}
|
|
</code></pre>
|
|
<p>This will add a new <code>KC_MAKE</code> keycode that can be used in any of your keymaps. And this keycode will output <code>make <keyboard>:<keymap"></code>, making frequent compiling easier. And this will work with any keyboard and any keymap as it will output the current boards info, so that you don't have to type this out every time.</p>
|
|
<p>Additionally, this should flash the newly compiled firmware automatically, using the correct utility, based on the bootloader settings (or default to just generating the HEX file). However, it should be noted that this may not work on all systems. AVRDUDE doesn't work on WSL, namely (and will dump the HEX in the ".build" folder instead).</p>
|
|
<h2 id="page_Override-default-userspace">Override default userspace</h2>
|
|
<p>By default the userspace used will be the same as the keymap name. In some situations this isn't desirable. For instance, if you use the <a href="Layouts.html">layout</a> feature you can't use the same name for different keymaps (e.g. ANSI and ISO). You can name your layouts <code>mylayout-ansi</code> and <code>mylayout-iso</code> and add the following line to your layout's <code>rules.mk</code>:</p>
|
|
<pre><code>USER_NAME := mylayout
|
|
</code></pre>
|
|
</div>
|
|
|
|
<nav>
|
|
<ul class="Pager">
|
|
<li class=Pager--prev><a href="../Features/Unicode.html">Previous</a></li> <li class=Pager--next><a href="../Keycodes/index.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>
|