qmk_firmware/static/Hardware/AVR_Processors.html
2018-05-07 21:02:24 -07:00

255 lines
22 KiB
HTML

<!DOCTYPE html>
<html class="no-js" lang="en">
<head>
<title>AVR Processors - 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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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 Nav__item--open has-children'><a href="../Hardware/index.html" class="folder"><i class="Nav__arrow">&nbsp;</i>Hardware</a><ul class='Nav'><li class='Nav__item Nav__item--active'><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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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">&nbsp;</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="../Hardware/index.html">Hardware</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="../Hardware/AVR_Processors.html">AVR Processors</a></h1>
<span class="EditOn">
<a href="https://github.com/qmk/qmk_firmware/blob/master/docs/04_Hardware/02_AVR_Processors.md" target="_blank">
Edit on GitHub </a>
</span>
</div>
<div class="s-content">
<ul class="TableOfContents">
<li>
<p><a href="#page_Keyboards-with-AVR-Processors">Keyboards with AVR Processors</a></p>
<ul class="TableOfContents">
<li>
<p><a href="#page_Adding-Your-AVR-Keyboard-to-QMK">Adding Your AVR Keyboard to QMK</a></p>
</li>
<li>
<p><a href="#page_section_3"><code>readme.md</code></a></p>
</li>
<li>
<p><a href="#page_section_4"><code>&lt;keyboard&gt;.c</code></a></p>
</li>
<li>
<p><a href="#page_section_5"><code>&lt;keyboard&gt;.h</code></a></p>
</li>
<li>
<p><a href="#page_section_6"><code>config.h</code></a></p>
<ul class="TableOfContents">
<li>
<p><a href="#page_Hardware-Configuration">Hardware Configuration</a></p>
</li>
<li>
<p><a href="#page_Keyboard-Matrix-Configuration">Keyboard Matrix Configuration</a></p>
</li>
<li>
<p><a href="#page_Backlight-Configuration">Backlight Configuration</a></p>
</li>
<li>
<p><a href="#page_Other-Configuration-Options">Other Configuration Options</a></p>
</li>
</ul>
</li>
<li>
<p><a href="#page_section_11"><code>rules.mk</code></a></p>
<ul class="TableOfContents">
<li>
<p><a href="#page_MCU-Options">MCU Options</a></p>
</li>
<li>
<p><a href="#page_Bootloader-Size">Bootloader Size</a></p>
<ul class="TableOfContents">
<li>
<p><a href="#page_Teensy-2-0-Bootloader-Example">Teensy 2.0 Bootloader Example</a></p>
</li>
<li>
<p><a href="#page_Teensy-2-0-Bootloader-Example-2">Teensy 2.0++ Bootloader Example</a></p>
</li>
<li>
<p><a href="#page_Atmel-DFU-Loader-Example">Atmel DFU Loader Example</a></p>
</li>
</ul>
</li>
<li>
<p><a href="#page_Build-Options">Build Options</a></p>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<h1 id="page_Keyboards-with-AVR-Processors">Keyboards with AVR Processors</h1>
<p>This page describes the support for for AVR processors in QMK. AVR processors include the atmega32u4, atmega32u2, at90usb1286, and other processors from Atmel Corporation. AVR processors are 8-bit MCU's that are designed to be easy to work with. The most common AVR processors in keyboards have on-board USB and plenty of GPIO for supporting large keyboard matrices. They are the most popular MCU for use in keyboards today.</p>
<p>If you have not yet you should read the <a href="../Reference/Keyboard_Guidelines.html">Keyboard Guidelines</a> to get a sense of how keyboards fit into QMK.</p>
<h2 id="page_Adding-Your-AVR-Keyboard-to-QMK">Adding Your AVR Keyboard to QMK</h2>
<p>QMK has a number of features to simplify working with AVR keyboards. For most keyboards you don't have to write a single line of code. To get started run the <code>util/new_project.sh</code> script:</p>
<pre><code>$ util/new_project.sh my_awesome_keyboard
######################################################
# /keyboards/my_awesome_keyboard project created. To start
# working on things, cd into keyboards/my_awesome_keyboard
######################################################
</code></pre>
<p>This will create all the files needed to support your new keyboard, and populate the settings with default values. Now you just need to customize it for your keyboard.</p>
<h2 id="page_section_3"><code>readme.md</code></h2>
<p>This is where you'll describe your keyboard. Please follow the <a href="../Reference/Documentation_Templates.html#keyboard-readmemd-template">Keyboard Readme Template</a> when writing your <code>readme.md</code>. You're encouraged to place an image at the top of your <code>readme.md</code>, please use an external service such as <a href="http://imgur.com" class="Link--external">Imgur</a> to host the images.</p>
<h2 id="page_section_4"><code>&lt;keyboard&gt;.c</code></h2>
<p>This is where all the custom logic for your keyboard goes. Many keyboards do not need to put anything at all in here. You can learn more about writing custom logic in <a href="../Reference/Custom_Code.html">Custom Quantum Functions</a>.</p>
<h2 id="page_section_5"><code>&lt;keyboard&gt;.h</code></h2>
<p>This is the file you define your <a href="../Features/Layouts.html">Layout Macro(s)</a> in. At minimum you should have a <code>#define LAYOUT</code> for your keyboard that looks something like this:</p>
<pre><code>#define LAYOUT( \
k00, k01, k02, \
k10, k11 \
) { \
{ k00, k01, k02 }, \
{ k10, KC_NO, k11 }, \
}
</code></pre>
<p>The first half of the <code>LAYOUT</code> pre-processor macro defines the physical arrangement of keys. The second half of the macro defines the matrix the switches are connected to. This allows you to have a physical arrangement of keys that differs from the wiring matrix.</p>
<p>Each of the <code>k__</code> variables needs to be unique, and typically they follow the format <code>k&lt;row&gt;&lt;col&gt;</code>.</p>
<p>The physical matrix (the second half) must have a number of rows equaling <code>MATRIX_ROWS</code>, and each row must have exactly <code>MATRIX_COLS</code> elements in it. If you do not have this many physical keys you can use <code>KC_NO</code> to fill in the blank spots.</p>
<h2 id="page_section_6"><code>config.h</code></h2>
<p>The <code>config.h</code> file is where you configure the hardware and feature set for your keyboard. There are a lot of options that can be placed in that file, too many to list there. For a complete overview of available options see the <a href="../Reference/Config_Options.html">Config Options</a> page.</p>
<h3 id="page_Hardware-Configuration">Hardware Configuration</h3>
<p>At the top of the <code>config.h</code> you'll find USB related settings. These control how your keyboard appears to the Operating System. If you don't have a good reason to change you should leave the <code>VENDOR_ID</code> as <code>0xFEED</code>. For the <code>PRODUCT_ID</code> you should pick a number that is not yet in use.</p>
<p>Do change the <code>MANUFACTURER</code>, <code>PRODUCT</code>, and <code>DESCRIPTION</code> lines to accurately reflect your keyboard.</p>
<pre><code>#define VENDOR_ID 0xFEED
#define PRODUCT_ID 0x6060
#define DEVICE_VER 0x0001
#define MANUFACTURER You
#define PRODUCT my_awesome_keyboard
#define DESCRIPTION A custom keyboard
</code></pre>
<p>{% hint style='info' %}
Note: On Windows and macOS the <code>MANUFACTURER</code>, <code>PRODUCT</code>, and <code>DESCRIPTION</code> fields will be displayed in the list of USB devices. On Linux these values will not be visible in <code>lsusb</code>, since Linux takes that information from the list published by the USB-IF.
{% endhint %}</p>
<h3 id="page_Keyboard-Matrix-Configuration">Keyboard Matrix Configuration</h3>
<p>The next section of the <code>config.h</code> file deals with your keyboard's matrix. The first thing you should set is the matrix's size. This is usually, but not always, the same number of rows and columns as the physical key arrangement.</p>
<pre><code>#define MATRIX_ROWS 2
#define MATRIX_COLS 3
</code></pre>
<p>Once you've defined the size of your matrix you need to define which pins on your MCU are connected to rows and columns. To do so simply specify the names of those pins:</p>
<pre><code>#define MATRIX_ROW_PINS { D0, D5 }
#define MATRIX_COL_PINS { F1, F0, B0 }
#define UNUSED_PINS
</code></pre>
<p>The number of <code>MATRIX_ROW_PINS</code> entries must be the same as the number you assigned to <code>MATRIX_ROWS</code>, and likewise for <code>MATRIX_COL_PINS</code> and <code>MATRIX_COLS</code>. You do not have to specify <code>UNUSED_PINS</code>, but you can if you want to document what pins are open.</p>
<p>Finally, you can specify the direction your diodes point. This can be <code>COL2ROW</code>, <code>ROW2COL</code>, or <code>CUSTOM_MATRIX</code>.</p>
<pre><code>#define DIODE_DIRECTION COL2ROW
</code></pre>
<h3 id="page_Backlight-Configuration">Backlight Configuration</h3>
<p>By default QMK supports backlighting on pins <code>B5</code>, <code>B6</code>, and <code>B7</code>. If you are using one of those you can simply enable it here. For more details see the <a href="../Features/Backlight.html">Backlight Documentation</a>.</p>
<pre><code>#define BACKLIGHT_PIN B7
#define BACKLIGHT_LEVELS 3
#define BACKLIGHT_BREATHING
#define BREATHING_PERIOD 6
</code></pre>
<p>{% hint style='info' %}
You can use backlighting on any pin you like, but you will have to do more work to support that. See the <a href="../Features/Backlight.html">Backlight Documentation</a> for more details.
{% endhint %}</p>
<h3 id="page_Other-Configuration-Options">Other Configuration Options</h3>
<p>There are a lot of features that can be configured or tuned in <code>config.h</code>. You should see the <a href="../Reference/Config_Options.html">Config Options</a> page for more details.</p>
<h2 id="page_section_11"><code>rules.mk</code></h2>
<p>You use the <code>rules.mk</code> file to tell QMK what files to build and what features to enable. If you are building around an atmega32u4 you can largely leave these defaults alone. If you are using another MCU you may have to tweak some parameters.</p>
<h3 id="page_MCU-Options">MCU Options</h3>
<p>These options tell the build system what CPU to build for. Be very careful if you change any of these settings, you can render your keyboard inoperable.</p>
<pre><code>MCU = atmega32u4
F_CPU = 16000000
ARCH = AVR8
F_USB = $(F_CPU)
OPT_DEFS += -DINTERRUPT_CONTROL_ENDPOINT
</code></pre>
<h3 id="page_Bootloader-Size">Bootloader Size</h3>
<p>The bootloader is a special section of your MCU that allows you to upgrade the code stored on the MCU. Think of it like a Rescue Partition for your keyboard. If you are using a teensy 2.0, or a device like the Ergodox EZ that uses the teensy bootloader you should set this to <code>512</code>. Most other bootloaders should be set to <code>4096</code>, but <code>1024</code> and <code>2048</code> are other possible values you may encounter.</p>
<h4 id="page_Teensy-2-0-Bootloader-Example">Teensy 2.0 Bootloader Example</h4>
<pre><code>OPT_DEFS += -DBOOTLOADER_SIZE=512
</code></pre>
<h4 id="page_Teensy-2-0-Bootloader-Example-2">Teensy 2.0++ Bootloader Example</h4>
<pre><code>OPT_DEFS += -DBOOTLOADER_SIZE=1024
</code></pre>
<h4 id="page_Atmel-DFU-Loader-Example">Atmel DFU Loader Example</h4>
<pre><code>OPT_DEFS += -DBOOTLOADER_SIZE=4096
</code></pre>
<h3 id="page_Build-Options">Build Options</h3>
<p>There are a number of features that can be turned on or off in <code>rules.mk</code>. See the <a href="../Reference/Config_Options.html#feature-options">Config Options</a> page for a detailed list and description.</p>
</div>
<nav>
<ul class="Pager">
<li class=Pager--prev><a href="../Hardware/index.html">Previous</a></li> <li class=Pager--next><a href="../Hardware/Drivers.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>