Visual Studio Code (VS Code) is an open-source code editor that supports many different programming languages.
Using a full-featured editor such as VS Code provides many advantages over a plain text editor, such as:
The purpose of this page is to document how to set up VS Code for developing QMK Firmware.
This guide covers how to configure everything needed on Windows and Ubuntu 18.04
Before starting, you will want to make sure that you have all of the build tools set up, and QMK Firmware cloned. Head to the Newbs Getting Started Guide to get things set up, if you haven't already.
Git for Windows (This link will prompt to save/run the installer)
Git LFS (Large File Support) and Check daily for Git for Windows updates.Use Visual Studio Code as Git's default editorUse Git from Git Bash only option, since that's the option that you should use here.Choosing HTTPS transport backend, either option should be fine.Checkout as-is, commit Unix-style line endings option. QMK Firmware uses Unix style commits.This software is needed for Git support in VS Code. It may be possible to not include this, but it is much simpler to just use this.
Git Credential Manager for Windows (Optional)
This software provides better support for Git by providing secure storage for git credentials, MFA and personal access token generation.
This isn't strictly needed, but we would recommend it.
This part is super simple. However, there is some configuration that we need to do to ensure things are configured correctly.
Now, we will set up the MSYS2 window to show up in VSCode as the integrated terminal. This has a number of advantages. Mostly, you can control+click on errors and jump to those files. This makes debugging much easier. It's also nice, in that you don't have to jump to another window.
Click File > Preferences > > Settings
Click on the {} button, in the top right to open the settings.json file.
Set the file's content to:
{\n "terminal.integrated.profiles.windows": {\n "QMK_MSYS": {\n "path": "C:/QMK_MSYS/usr/bin/bash.exe",\n "env": {\n "MSYSTEM": "MINGW64",\n "CHERE_INVOKING": "1"\n },\n "args": ["--login"]\n }\n },\n\n "terminal.integrated.cursorStyle": "line"\n }If there are settings here already, then just add everything between the first and last curly brackets and separate the existing settings with a comma from the newly added ones.
TIP
If you installed MSYS2 to a different folder, then you'll need to change the path for terminal.integrated.shell.windows to the correct path for your system.
Hit Ctrl-` (Grave) to bring up the terminal or go to View > Terminal (command workbench.action.terminal.toggleTerminal). A new terminal will be opened if there isn‘t one already.
This should start the terminal in the workspace's folder (so the qmk_firmware folder), and then you can compile your keyboard.
No, really, that's it. The paths needed are already included when installing the packages, and it is much better about detecting the current workspace files and parsing them for IntelliSense.
There are a number of extensions that you may want to install:
Restart once you've installed any extensions.
Using the standard compile_commands.json database, we can get the VS code clangd extension to use the correct includes and defines used for your keyboard and keymap.
qmk generate-compilation-database -kb <keyboard> -km <keymap> to generate the compile_commands.json.clangd: Download Language Server and select it when it appears. Note that this only needs to be done once on clangd extension installation, if it didn't already ask to do so.clangd: Restart Language Server and select it when it appears.Now you're ready to code QMK Firmware in VS Code!
...and a Black Magic Probe.
Visual Studio Code has the ability to debug applications, but requires some configuration in order to get it to be able to do so for ARM targets.
This documentation describes a known-working configuration for setting up the use of a Black Magic Probe to debug using VS Code.
It is assumed that you've correctly set up the electrical connectivity of the Black Magic Probe with your MCU. Wiring up NRST, SWDIO, SWCLK, and GND should be enough.
Install the following plugin into VS Code:
A debugging target for the MCU for your board needs to be defined, and can be done so by adding the following to a .vscode/launch.json file:
{\n // Use IntelliSense to learn about possible attributes.\n // Hover to view descriptions of existing attributes.\n // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387\n "version": "0.2.0",\n "configurations": [\n {\n "name": "Black Magic Probe (OneKey Proton-C)",\n "type": "cortex-debug",\n "request": "launch",\n "cwd": "${workspaceRoot}",\n "executable": "${workspaceRoot}/.build/handwired_onekey_proton_c_default.elf",\n "servertype": "bmp",\n "BMPGDBSerialPort": "COM4",\n "svdFile": "Q:\\\\svd\\\\STM32F303.svd",\n "device": "STM32F303",\n "v1": false,\n "windows": {\n "armToolchainPath": "C:\\\\QMK_MSYS\\\\mingw64\\\\bin"\n }\n }\n ]\n}You'll need to perform some modifications to the file above in order to target your specific device:
"name": Can be anything, but if you're debugging multiple targets you'll want something descriptive here."cwd": The path to the QMK Firmware repository root directory -- if using the .vscode directory existing in the qmk_firmware git repository, the default above should be correct"executable": The path to the elf file generated as part of the build for your keyboard -- exists in <qmk_firmware>/.build"BMPGDBSerialPort": The COM port under Windows, or the /dev/... path for Linux/macOS. Two serial port devices will be created -- the Black Magic Probe debug port is usually the first. If it doesn't work, try the second."svdFile": [Optional] The path to the SVD file that defines the register layout for the MCU -- the appropriate file can be downloaded from the cmsis-svd repository"device": The name of the MCU, which matches the <name> tag at the top of the downloaded svd file."armToolchainPath": [Optional] The path to the ARM toolchain installation location on Windows -- under normal circumstances Linux/macOS will auto-detect this correctly and will not need to be specified.WARNING
Windows builds of QMK Firmware are generally compiled using QMK MSYS, and the path to gdb's location (C:\\\\QMK_MSYS\\\\mingw64\\\\bin) needs to be specified under armToolchainPath for it to be detected. You may also need to change the GDB path to point at C:\\\\QMK_MSYS\\\\mingw64\\\\bin\\\\gdb-multiarch.exe in the VSCode Cortex-Debug user settings: 
Optionally, the following modifications should also be made to the keyboard's rules.mk file to disable optimisations -- not strictly required but will ensure breakpoints and variable viewing works correctly:
# Disable optimisations for debugging purposes\nLTO_ENABLE = no\nOPT = g\nDEBUG = 3At this point, you should build and flash your firmware through normal methods (qmk compile ... and qmk flash ...).
Once completed, you can:
VS Code's debugger will then start executing the compiled firmware on the MCU.
At this stage, you should have full debugging set up, with breakpoints and variable listings working!
', 51); const _hoisted_52 = [ _hoisted_1 ]; function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { return openBlock(), createElementBlock("div", null, _hoisted_52); } const other_vscode = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); export { __pageData, other_vscode as default };