qmk_firmware/isp_flashing_guide.html

75 lines
129 KiB
HTML
Raw Normal View History

<!DOCTYPE html>
<html lang="en-US" dir="ltr">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>ISP Flashing Guide | QMK Firmware</title>
<meta name="description" content="Documentation for QMK Firmware">
<meta name="generator" content="VitePress v1.1.3">
<link rel="preload stylesheet" href="/assets/style.No8zk9aC.css" as="style">
<script type="module" src="/assets/app.BMmz1pUL.js"></script>
<link rel="preload" href="/assets/inter-roman-latin.Di8DUHzh.woff2" as="font" type="font/woff2" crossorigin="">
<link rel="modulepreload" href="/assets/chunks/framework.DyMmIvSC.js">
<link rel="modulepreload" href="/assets/chunks/theme.jODogfN6.js">
<link rel="modulepreload" href="/assets/isp_flashing_guide.md.BiuBpOKX.lean.js">
<script id="check-dark-mode">(()=>{const e=localStorage.getItem("vitepress-theme-appearance")||"auto",a=window.matchMedia("(prefers-color-scheme: dark)").matches;(!e||e==="auto"?a:e==="dark")&&document.documentElement.classList.add("dark")})();</script>
<script id="check-mac-os">document.documentElement.classList.toggle("mac",/Mac|iPhone|iPod|iPad/i.test(navigator.platform));</script>
</head>
<body>
<div id="app"><div class="Layout" data-v-5d98c3a5><!--[--><!--]--><!--[--><span tabindex="-1" data-v-0f60ec36></span><a href="#VPContent" class="VPSkipLink visually-hidden" data-v-0f60ec36> Skip to content </a><!--]--><!----><header class="VPNav" data-v-5d98c3a5 data-v-ae24b3ad><div class="VPNavBar has-sidebar top" data-v-ae24b3ad data-v-ccf7ddec><div class="wrapper" data-v-ccf7ddec><div class="container" data-v-ccf7ddec><div class="title" data-v-ccf7ddec><div class="VPNavBarTitle has-sidebar" data-v-ccf7ddec data-v-ab179fa1><a class="title" href="/" data-v-ab179fa1><!--[--><!--]--><!--[--><!--[--><!--[--><img class="VPImage dark logo" src="/qmk-logo-dark.svg" alt data-v-8426fc1a><!--]--><!--[--><img class="VPImage light logo" src="/qmk-logo-light.svg" alt data-v-8426fc1a><!--]--><!--]--><!--]--><span data-v-ab179fa1>QMK Firmware</span><!--[--><!--]--></a></div></div><div class="content" data-v-ccf7ddec><div class="content-body" data-v-ccf7ddec><!--[--><!--]--><div class="VPNavBarSearch search" data-v-ccf7ddec><!--[--><!----><div id="local-search"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><span class="vp-icon DocSearch-Search-Icon"></span><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"><kbd class="DocSearch-Button-Key"></kbd><kbd class="DocSearch-Button-Key">K</kbd></span></button></div><!--]--></div><nav aria-labelledby="main-nav-aria-label" class="VPNavBarMenu menu" data-v-ccf7ddec data-v-7f418b0f><span id="main-nav-aria-label" class="visually-hidden" data-v-7f418b0f>Main Navigation</span><!--[--><!--[--><a class="VPLink link VPNavBarMenuLink" href="./" tabindex="0" data-v-7f418b0f data-v-9c663999><!--[--><span data-v-9c663999>Home</span><!--]--></a><!--]--><!--]--></nav><!----><div class="VPNavBarAppearance appearance" data-v-ccf7ddec data-v-e6aabb21><button class="VPSwitch VPSwitchAppearance" type="button" role="switch" title="Switch to dark theme" aria-checked="false" data-v-e6aabb21 data-v-d1f28634 data-v-1d5665e3><span class="check" data-v-1d5665e3><span class="icon" data-v-1d5665e3><!--[--><span class="vpi-sun sun" data-v-d1f28634></span><span class="vpi-moon moon" data-v-d1f28634></span><!--]--></span></span></button></div><div class="VPSocialLinks VPNavBarSocialLinks social-links" data-v-ccf7ddec data-v-0394ad82 data-v-7bc22406><!--[--><a class="VPSocialLink no-icon" href="https://reddit.com/r/olkb" aria-label target="_blank" rel="noopener" data-v-7bc22406 data-v-eee4e7cb><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 50 50" width="50px" height="50px"><path d="M 29 3 C 28.0625 3 27.164063 3.382813 26.5 4 C 25.835938 4.617188 25.363281 5.433594 25 6.40625 C 24.355469 8.140625 24.085938 10.394531 24.03125 13.03125 C 19.234375 13.179688 14.820313 14.421875 11.28125 16.46875 C 10.214844 15.46875 8.855469 14.96875 7.5 14.96875 C 6.089844 14.96875 4.675781 15.511719 3.59375 16.59375 C 1.425781 18.761719 1.425781 22.238281 3.59375 24.40625 L 3.84375 24.65625 C 3.3125 26.035156 3 27.488281 3 29 C 3 33.527344 5.566406 37.585938 9.5625 40.4375 C 13.558594 43.289063 19.007813 45 25 45 C 30.992188 45 36.441406 43.289063 40.4375 40.4375 C 44.433594 37.585938 47 33.527344 47 29 C 47 27.488281 46.6875 26.035156 46.15625 24.65625 L 46.40625 24.40625 C 48.574219 22.238281 48.574219 18.761719 46.40625 16.59375 C 45.324219 15.511719 43.910156 14.96875 42.5 14.96875 C 41.144531 14.96875 39.785156 15.46875 38.71875 16.46875 C 35.195313 14.433594 30.800781 13.191406 26.03125 13.03125 C 26.09375 10.546875 26.363281 8.46875 26.875 7.09375 C 27.164063 6.316406 27.527344 5.757813 27.875 5.4375 C 28.222656 5.117188 28.539063 5 29 5 C 29.460938 5 29.683594 5.125 30.03125 5.40625 C 30.378906 5.6875 30.785156 6.148438 31.3125 6.6875 C 32.253906 7.652344 33.695313 8.714844 36.09375 8.9375 C 36.539063 11.238281 38.574219 13 41 13 C 43.75 13 46 10.75 46 8 C 46 5.25 43.75 3 41 3 C 38.605469 3 36.574219 4.710938 36.09375 6.96875 C 34.3125 6.796875 33.527344 6.109375 32.75 5.3125 C 32.300781 4.851563 31.886719
<span class="line"><span></span></span>
<span class="line"><span>Reading | ################################################## | 100% 0.00s</span></span>
<span class="line"><span></span></span>
<span class="line"><span>avrdude: Device signature = 0x1e9587 (probably m32u4)</span></span>
<span class="line"><span>avrdude: NOTE: &quot;flash&quot; memory has been specified, an erase cycle will be performed</span></span>
<span class="line"><span> To disable this feature, specify the -D option.</span></span>
<span class="line"><span>avrdude: erasing chip</span></span>
<span class="line"><span>avrdude: reading input file &quot;Caterina-Micro.hex&quot;</span></span>
<span class="line"><span>avrdude: writing flash (32730 bytes):</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Writing | ################################################## | 100% 11.58s</span></span>
<span class="line"><span></span></span>
<span class="line"><span>avrdude: 32730 bytes of flash written</span></span>
<span class="line"><span>avrdude: verifying flash memory against Caterina-Micro.hex:</span></span>
<span class="line"><span>avrdude: load data flash data from input file Caterina-Micro.hex:</span></span>
<span class="line"><span>avrdude: input file Caterina-Micro.hex contains 32730 bytes</span></span>
<span class="line"><span>avrdude: reading on-chip flash data:</span></span>
<span class="line"><span></span></span>
<span class="line"><span>Reading | ################################################## | 100% 10.33s</span></span>
<span class="line"><span></span></span>
<span class="line"><span>avrdude: verifying ...</span></span>
<span class="line"><span>avrdude: 32730 bytes of flash verified</span></span>
<span class="line"><span></span></span>
<span class="line"><span>avrdude: safemode: Fuses OK (E:CB, H:D8, L:FF)</span></span>
<span class="line"><span></span></span>
<span class="line"><span>avrdude done. Thank you.</span></span></code></pre></div><h3 id="setting-the-fuses" tabindex="-1">Setting the Fuses <a class="header-anchor" href="#setting-the-fuses" aria-label="Permalink to &quot;Setting the Fuses&quot;"></a></h3><p>This is a slightly more advanced topic, but may be necessary if you are switching from one bootloader to another (for example, Caterina to Atmel/QMK DFU on a Pro Micro). Fuses control some of the low-level functionality of the AVR microcontroller, such as clock speed, whether JTAG is enabled, and the size of the section of flash memory reserved for the bootloader, among other things. You can find a fuse calculator for many AVR parts <a href="https://www.engbedded.com/conffuse/" target="_blank" rel="noreferrer">here</a>.</p><div class="warning custom-block"><p class="custom-block-title">WARNING</p><p>Setting incorrect fuse values, in particular the clock-related bits, may render the MCU practically unrecoverable without high voltage programming (not covered here)! Make sure to double check the commands you enter before you execute them.</p></div><p>To set the fuses, add the following to the <code>avrdude</code> command:</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>-U lfuse:w:0xXX:m -U hfuse:w:0xXX:m -U efuse:w:0xXX:m</span></span></code></pre></div><p>where the <code>lfuse</code>, <code>hfuse</code> and <code>efuse</code> arguments represent the low, high and extended fuse bytes as listed in the <a href="#hardware">Hardware</a> section.</p><div class="tip custom-block"><p class="custom-block-title">TIP</p><p>You may get a warning from <code>avrdude</code> that the extended fuse byte does not match what you provided when reading it back. If the second hex digit matches, this can usually be safely ignored, because the top four bits of this fuse do not actually exist on many AVR parts, and may read back as anything.</p></div><h2 id="creating-a-production-firmware" tabindex="-1">Creating a &quot;Production&quot; Firmware <a class="header-anchor" href="#creating-a-production-firmware" aria-label="Permalink to &quot;Creating a &quot;Production&quot; Firmware&quot;"></a></h2><p>For mass production purposes, it is possible to join the bootloader and QMK firmware together into a single file, due to the way the <a href="https://en.wikipedia.org/wiki/Intel_HEX" target="_blank" rel="noreferrer">Intel Hex format</a> works:</p><ol><li>Open the QMK firmware and bootloader <code>.hex</code> files in a text editor.</li><li>Remove the last line of the QMK firmware (which should be <code>:00000001FF</code> - this is just an &quot;end of file&quot; marker).</li><li>Paste the contents of the bootloader <code>.hex</code> file onto a new line at the end of the QMK firmware file, with no empty lines between.</li><li>Save it as a new file, for example <code>&lt;keyboard&gt;_&lt;keymap&gt;_production.hex</code>.</li></ol><p>You can then ISP flash this combined firmware instead, which allows you to skip the extra step of flashing the QMK firmware over USB.</p><h2 id="flashing-stm32duino-bootloader" tabindex="-1">Flashing STM32Duino Bootloader <a class="header-anchor" href="#flashing-stm32duino-bootloader" aria-label="Permalink to &quot;Flashing STM32Duino Bootloader&quot;"></a></h2><p>As mentioned above, <em>most</em> supported STM32 devices already possess a USB DFU bootloader which cannot be overwritten, however the ROM bootloader in the STM32F103 used on the Bluepill is not USB capable. In this case an ST-Link V2 dongle is required to upload the STM32Duino bootloader to the device. These can be readily purchased for relatively cheap on eBay and other places.</p><p>This bootloader is a descendant of the Maple bootloader by Leaflabs, and is compatible with dfu-util.</p><h3 id="software-1" tabindex="-1">Software <a class="header-anchor" href="#software-1" aria-label="Permalink to &quot;Software&quot;"></a></h3><p>
<span class="line"><span> version: V2J37S7</span></span>
<span class="line"><span> serial: 2C1219002B135937334D4E00</span></span>
<span class="line"><span> flash: 65536 (pagesize: 1024)</span></span>
<span class="line"><span> sram: 20480</span></span>
<span class="line"><span> chipid: 0x0410</span></span>
<span class="line"><span> descr: F1xx Medium-density</span></span></code></pre></div><p>If the reported <code>chipid</code> is <code>0x0410</code>, everything is working. If it is <code>0x0000</code>, check your wiring, and try swapping the <code>SWDIO</code> and <code>SWCLK</code> pins, as some ST-Link dongles may have incorrect pinouts.</p><p>Next, run the following command:</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>st-flash --reset --format binary write &lt;path-to-bootloader&gt; 0x08000000</span></span></code></pre></div><p>where <code>&lt;path-to-bootloader&gt;</code> is the path to the bootloader <code>.bin</code> file above. You can run this command from the directory you downloaded it to, so that you can simply pass in the filename.</p><p>If all goes well, you should get output similar to the following:</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>st-flash 1.7.0</span></span>
<span class="line"><span>2022-03-08T12:16:30 INFO common.c: F1xx Medium-density: 20 KiB SRAM, 64 KiB flash in at least 1 KiB pages.</span></span>
<span class="line"><span>file generic_boot20_pc13.bin md5 checksum: 333c30605e739ce9bedee5999fdaf81b, stlink checksum: 0x0008e534</span></span>
<span class="line"><span>2022-03-08T12:16:30 INFO common.c: Attempting to write 7172 (0x1c04) bytes to stm32 address: 134217728 (0x8000000)</span></span>
<span class="line"><span>2022-03-08T12:16:30 INFO common.c: Flash page at addr: 0x08000000 erased</span></span>
<span class="line"><span>2022-03-08T12:16:30 INFO common.c: Flash page at addr: 0x08000400 erased</span></span>
<span class="line"><span>2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08000800 erased</span></span>
<span class="line"><span>2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08000c00 erased</span></span>
<span class="line"><span>2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001000 erased</span></span>
<span class="line"><span>2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001400 erased</span></span>
<span class="line"><span>2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001800 erased</span></span>
<span class="line"><span>2022-03-08T12:16:31 INFO common.c: Flash page at addr: 0x08001c00 erased</span></span>
<span class="line"><span>2022-03-08T12:16:31 INFO common.c: Finished erasing 8 pages of 1024 (0x400) bytes</span></span>
<span class="line"><span>2022-03-08T12:16:31 INFO common.c: Starting Flash write for VL/F0/F3/F1_XL</span></span>
<span class="line"><span>2022-03-08T12:16:31 INFO flash_loader.c: Successfully loaded flash loader in sram</span></span>
<span class="line"><span>2022-03-08T12:16:31 INFO flash_loader.c: Clear DFSR</span></span>
<span class="line"><span> 8/ 8 pages written</span></span>
<span class="line"><span>2022-03-08T12:16:31 INFO common.c: Starting verification of write complete</span></span>
<span class="line"><span>2022-03-08T12:16:31 INFO common.c: Flash written and verified! jolly good!</span></span>
<span class="line"><span>2022-03-08T12:16:31 WARN common.c: NRST is not connected</span></span></code></pre></div><p>Otherwise, if you receive an <code>Unknown memory region</code> error, run the following command to unlock the STM32F103:</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>openocd -f interface/stlink.cfg -f target/stm32f1x.cfg -c &quot;init; reset halt; stm32f1x unlock 0; reset halt; exit&quot;</span></span></code></pre></div><p>Then re-plug the ST-Link and try again.</p><p>After all of this, unplug the Bluepill from the ST-Link and connect it to USB. It should now be ready to flash using dfu-util, the QMK CLI or Toolbox.</p></div></div></main><footer class="VPDocFooter" data-v-39a288b8 data-v-09de1c0f><!--[--><!--]--><!----><nav class="prev-next" data-v-09de1c0f><div class="pager" data-v-09de1c0f><a class="VPLink link pager-link prev" href="/hand_wire" data-v-09de1c0f><!--[--><span class="desc" data-v-09de1c0f>Previous page</span><span class="title" data-v-09de1c0f>Hand Wiring Guide</span><!--]--></a></div><div class="pager" data-v-09de1c0f><a class="VPLink link pager-link next" href="/pr_checklist" data-v-09de1c0f><!--[--><span class="desc" data-v-09de1c0f>Next page</span><span class="title" data-v-09de1c0f>PR Checklist</span><!--]--></a></div></nav></footer><!--[--><!--]--></div></div></div><!--[--><!--]--></div></div><!----><!--[--><!--]--></div></div>
<script>window.__VP_HASH_MAP__=JSON.parse("{\"changelog_20200229.md\":\"DNsowwM1\",\"changelog_20200530.md\":\"Dk-vRpTQ\",\"changelog_20220226.md\":\"BWO5r_ec\",\"changelog_20210227.md\":\"BWOtCaeS\",\"changelog_20220827.md\":\"DjPthqDk\",\"changelog_20240225.md\":\"B4-WrXj6\",\"changelog_20200829.md\":\"CoqrOffn\",\"capabilities.md\":\"DgKwcj5n\",\"changelog_20210529.md\":\"CR1YNfZX\",\"cli_configuration.md\":\"CGSB128P\",\"cli_development.md\":\"3xFA2OvS\",\"drivers_gpio.md\":\"C5PvyJVh\",\"features_swap_hands.md\":\"DOhgGQf9\",\"configurator_troubleshooting.md\":\"BxGLPT8G\",\"changelog_20211127.md\":\"ClUawWkq\",\"api_development_overview.md\":\"Dcey4ntL\",\"features_rgblight.md\":\"O1OG9fO_\",\"changelog_20231126.md\":\"D2Ok5QAf\",\"features_sequencer.md\":\"DkgqNCsQ\",\"changelog_20210828.md\":\"DNbHIuuM\",\"mod_tap.md\":\"C7wRKLcf\",\"features_os_detection.md\":\"DZKTWvSd\",\"changelog_20220528.md\":\"BX3CCY1Z\",\"drivers_spi.md\":\"tJVeIT7e\",\"drivers_uart.md\":\"BNBs-m3h\",\"api_overview.md\":\"0FPaUsMb\",\"drivers_ws2812.md\":\"D9E3Wb-Y\",\"easy_maker.md\":\"DAfbIK4w\",\"flashing.md\":\"BSZF2RCy\",\"faq_build.md\":\"DL_WezA1\",\"getting_started_docker.md\":\"mz6HE4Bl\",\"faq_debug.md\":\"DuThValw\",\"getting_started_github.md\":\"OYq7IT7B\",\"faq_general.md\":\"BC3pFw4U\",\"getting_started_introduction.md\":\"BOJreqSs\",\"faq_misc.md\":\"qGrhOTu4\",\"getting_started_make_guide.md\":\"BjUuEnSh\",\"feature_eeprom.md\":\"a0eoTZm7\",\"hand_wire.md\":\"CcI1spCv\",\"hardware_drivers.md\":\"BUnx48D9\",\"feature_layers.md\":\"8GwBUTZN\",\"feature_layouts.md\":\"qcy8hNMO\",\"hardware_keyboard_guidelines.md\":\"CJevsanE\",\"how_a_matrix_works.md\":\"JINKbCuX\",\"how_keyboards_work.md\":\"CB7z8ocb\",\"changelog_20221126.md\":\"DpbrnXeC\",\"index.md\":\"B4QYzvHE\",\"features_hd44780.md\":\"15K40o_e\",\"features_st7565.md\":\"MoajNurJ\",\"keycodes_magic.md\":\"CGO3hgMm\",\"configurator_architecture.md\":\"DEFTvTlS\",\"changelog_20240526.md\":\"DAmAEDG5\",\"drivers_serial.md\":\"qxjytVdM\",\"features_stenography.md\":\"Bb_IhUGl\",\"isp_flashing_guide.md\":\"BiuBpOKX\",\"features_programmable_button.md\":\"D332w_PT\",\"keycodes.md\":\"CINWVdmy\",\"keycodes_basic.md\":\"CHIeCvwn\",\"keycodes_us_ansi_shifted.md\":\"Cs78SDfM\",\"features_key_lock.md\":\"IjFq9dYs\",\"cli_tab_complete.md\":\"ChaxfzYo\",\"features_pointing_device.md\":\"DP6-XwL6\",\"features_unicode.md\":\"CsON-fJH\",\"api_docs.md\":\"CRoD6CbL\",\"feature_advanced_keycodes.md\":\"CX8dJkY-\",\"changelog_20230226.md\":\"Cg0AYxIn\",\"drivers_flash.md\":\"DhWcHp8S\",\"features_tri_layer.md\":\"DdnBVinw\",\"features_oled_driver.md\":\"D9wJVdL1\",\"features_digitizer.md\":\"DGIGZFVx\",\"newbs.md\":\"-YYNd3dT\",\"newbs_building_firmware.md\":\"DnVUK9it\",\"features_repeat_key.md\":\"C3eWDUWn\",\"newbs_building_firmware_workflow.md\":\"DpLVwA7x\",\"unit_testing.md\":\"u3fgbGUj\",\"newbs_external_userspace.md\":\"pD9Lc-a5\",\"feature_converters.md\":\"DFKin1io\",\"features_auto_shift.md\":\"B9HLt3QM\",\"changelog_20190830.md\":\"Drtq3lMy\",\"features_autocorrect.md\":\"DHRDcuho\",\"feature_debounce_type.md\":\"CUrSp0Iy\",\"contributing.md\":\"KzcJdv8r\",\"features_backlight.md\":\"D7R4FkYo\",\"features_bluetooth.md\":\"CiAjl875\",\"features_bootmagic.md\":\"CeNSUsBQ\",\"api_development_environment.md\":\"EhJClb9f\",\"features_caps_word.md\":\"BDQGM0-x\",\"features_combo.md\":\"C-GfDyXJ\",\"features_tap_dance.md\":\"CKLVpnIn\",\"features_command.md\":\"Byl9YoT7\",\"features_haptic_feedback.md\":\"DS8CmC7e\",\"newbs_building_firmware_configurator.md\":\"yyo-1QDE\",\"features_dip_switch.md\":\"DtBOdc98\",\"features_dynamic_macros.md\":\"CrJ1vhBA\",\"arm_debugging.md\":\"BH-H2Ukz\",\"features_secure.md\":\"BX7jFvW5\",\"features_encoders.md\":\"DMlIJGGa\",\"features_joystick.md\":\"CW0gZHec\",\"capabilities_inc.md\":\"Ca9zpMce\",\"drivers_i2c.md\":\"Cuj87reB\",\"breaking_changes.md\":\"BtdqWQlY\",\"breaking_changes_history.md\":\"CkzdD6x8\",\"features_key_overrides.md\":\"rVTP6kn9\",\"features_wpm.md\":\"BYf-Xc1H\",\"changelog_20230528.md\":\"nX9R48zP\",\"features_audio.md
</body>
</html>