Skip to content

Project Setup: VS Code

Jump to bottom Edit New page
Jamie Smith edited this page Jan 31, 2024 · 36 revisions

This page will show you how to take an existing Mbed CE project and develop it using the VS Code IDE.

Note that VS Code can develop locally, or over an SSH connection to a remote host, or over a connection to Windows Subsystem for Linux if you use it.

Setting Up VS Code

  1. If you don't have VS Code, you'll need to install it per the instructions here. Open it, and go through the getting started wizard according to your preferences.
  2. If connecting to a remote workspace, connect to it now and open the folder with your project.
  3. Go to the Extensions menu on the left, then search for and install the following extensions. If connected to a remote workspace, make sure to install the extensions for the remote host as well.
    • C/C++
    • Better C++ Syntax (recommended addon for C/C++)
    • CMake Tools (allows building CMake projects)
    • CMake (syntax higlighting for CMake)
    • Cortex-Debug (allows VS Code to connect to an embedded GDB server).
      • NOTE: If you have GDB 8 instead of a newer version (common in older GNU ARM toolchains) you will need to install version 1.4.4 of this extension, future versions dropped support for it.

Loading your Project

  1. First, make sure the Python requirements for the project are installed. Open a terminal in the project root and run python3 -m pip install -r mbed-os/tools/requirements.txt (use python instead of python3 on Windows)
    • On recent Debian/Ubuntu versions, pip can no longer install packages to the system interpreter. On these systems, you should use xargs sudo apt-get install -y < mbed-os/tools/requirements.apt.txt to install the needed python packages via apt instead.
  2. Go to File > Open Folder, and browse to the root directory of the Mbed project
  3. Click Yes to the trust dialog

image

  1. Close the "Would you like to configure CMake project" popup on the bottom right, we'll be doing this manually.
  2. Click on the bottom bar where it says "No Kit Selected". Then, choose "[Unspecified]" from the menu (the Mbed build scripts will find the compilers).

image

  1. If the project does not already have a cmake-variants.yaml file, you will need to create one. Note that in VSCode, cmake-variants.yaml needs to live in your project's root directory.
    1. This file does two things: (1) it lists the build types (develop, debug, release) that the project can be built as, and (2) it also supplies the CMake options for each Mbed target that you want to build for. Here's a template for you to use:
buildType:
  default: Develop
  choices:
    Develop:
      short: Develop
      long: Emit debug information but also optimize
      buildType: Develop
    Debug:
      short: Debug
      long: Emit debug information and don't optimize
      buildType: Debug
    Release:
      short: Release
      long: Optimize generated code
      buildType: Release
board:
  default: YOUR_MBED_TARGET
  choices:
    YOUR_MBED_TARGET:
      short: YOUR_MBED_TARGET
      settings:
        MBED_TARGET: YOUR_MBED_TARGET
        UPLOAD_METHOD: YOUR_UPLOAD_METHOD

Just replace YOUR_MBED_TARGET with your Mbed target name (e.g. LPC1768 or NUCLEO_L452RE_P), and replace YOUR_UPLOAD_METHOD with your upload method name (e.g. MBED or OPENOCD).

  • Note: if you created a custom target in custom_targets.json, your custom target must be all capitalized.

Later on, if you want your project to support multiple different Mbed targets, you can add them as entries in the board: section in this file.

  1. Add this line to .vscode/settings.json:
    "cmake.buildDirectory": "${workspaceFolder}/build/${variant:board}-${variant:buildType}",

Without this setting, switching between targets requires to clean the build dir and starts always a build all. By using this setting, each variant has its own build dir.

  1. Now, select your variant. Use Ctrl-Shift-P and find CMake: Select Variant. Then choose the variant you want. I'd recommend starting with the Develop one for general use.

image image

  1. If all goes well, you should see the CMake project successfully configure and load. If not, you may need to double-check the toolchain setup guide to make sure everything is set up OK.

NOTE: When working with Mbed projects, "CMake: Delete Cache and Reconfigure" is your friend if things break. If your project did not find the compilers successfully, or things moved on the disk, or you're getting other errors, make it your first recourse to try this option.

Building and Flashing Code

  1. To choose your build target, use Ctrl-Shift-P and find "CMake: Set Build Target". Then, choose the target you want from the list. Just like on the command line, targets starting with flash- will upload a program to your Mbed board, while others just build the code.

image

  1. Start a build, either by pressing the Build button on the bottom toolbar or by pressing F7. The code should compile!

Debugging

  1. First, if you haven't already, you will need to make sure the project is configured to use an upload method that supports debugging. Read about upload methods on the Upload Methods page, and select a method to use using the UPLOAD_METHOD: option in cmake-variants.yaml.
  2. Once this is done, if you go to the "Run and Debug" pane on the left, you should see a list of launch configurations at the top. Simply select your application and press the play button. If all goes well, you should be dropped into a debug session in the application!

Using WSL (Windows Subsystem for Linux)

Developing in WSL works great, especially with the current feature update 22H2 in Windows 10 or 11. Earlier Versions had problems with USB, now it is even possible to have Linux GUI on the Windows desktop. One big advantage is the much faster compiling speed.

General WSL documentation starts here: https://docs.microsoft.com/en-us/windows/wsl/about

To setup the development environment, there are a few steps neccessary:

  • connect VSCode to your WSL instance, this will install a VSCode server automatically

grafik

  • install the gcc toolchain from arm Developer site: https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads
  • install python modules as described in the command line tools setup
  • install cmake, use a current Linux x86_64 version from cmake.org: https://cmake.org/download/
  • install ccache with 'apt-get install ccache'
  • install git with 'apt-get install git'
  • for using STLink, a full installaton of STM32CubeIDE is neccessary. Even if only the gdbserver is needed, it is part of this package.

When VSCode is connected to WSL, install cmake-tools and other desired extensions like gitlens also in VSC under WSL. Then it is important to use the filesystem in WSL, so copy/clone projects into your home directory in WSL. There you will have the benefit of the faster filesystem, which makes compiling about 5 times faster.

To use USB debuging hardware, the USB device must be attached to the Linux VM. There is a bridge 'usbipd', and a few steps to follow: https://learn.microsoft.com/en-us/windows/wsl/connect-usb

Add a custom footer
Add a custom sidebar
Clone this wiki locally