Using STM32Cube VS Code Extension with Swan

STM32CubeIDE for Visual Studio Code is STMicroelectronics' official extension pack for VS Code. It brings project creation, a CMake build, and ST-LINK debugging for STM32 devices into the editor. Paired with STM32CubeMX, it is a good fit for writing STM32Cube firmware for Swan without leaving VS Code.

This guide covers generating a project for Swan's microcontroller in STM32CubeIDE for Visual Studio Code, and how to build, flash, and step debug the result in VS Code.

Install Prerequisites

1. Install the latest version of Visual Studio Code (if you haven't done so already). The extension pack requires version 1.94.2 or later.

2. Open the Extensions view in the Activity Bar, search for STM32, and install STM32CubeIDE for Visual Studio Code, published by STMicroelectronics.

   

   This is an extension pack, so installing it also pulls in the component extensions it depends on: the project manager, the CMake build integration, the ST-LINK and J-Link debug adapters, clangd, the register and RTOS views, and a serial monitor.

3. Windows/Linux, only if using an ST-LINK: Install the ST-LINK host support your platform needs. Click the STM32Cube (butterfly) icon that the extension adds to the Activity Bar and look at the STM32Cube Resources section:

   • Windows: select Install ST-Link USB drivers and run the installer it downloads. This needs administrator privileges, which is why the extension cannot do it for you on first run.

   • Linux: select Install ST-Link udev rules. That entry covers the probe; the DFU and virtual COM port rules above cover the target, so you want both.

4. The first time you create or build a project, the extension downloads the command-line tools it needs (the compiler toolchain, CMake, Ninja, and the GDB servers) through its bundle manager.

5. Next, download and install STM32CubeMX. You configure Swan's clocks and peripherals there and generate the HAL code the project is built on.

   warning

   Install classic STM32CubeMX, not STM32CubeMX2. STM32CubeMX2 targets ST's newer HAL2 series, starting with STM32C5; Swan's STM32L4R5 is a HAL1 device and is not among the series it supports.

   AI Tip

   STMicroelectronics does not ship a conventional installer on every platform. The Windows download is an ordinary .exe wizard, but the macOS download is a .tar.gz holding an installer .app that Gatekeeper quarantines, and the Linux download is a bare installer binary you have to mark executable yourself. The exact filename changes with every release and CPU architecture, so an AI agent is the quickest way to get commands that match the file you actually downloaded.

   Promptcontent_copyCopy

   I downloaded STM32CubeMX from STMicroelectronics and ended up with an archive named <your-downloaded-filename>. There is no ordinary installer inside it. Walk me through installing it on my machine, with exact shell commands: how to extract the archive, how to make the installer runnable — including any macOS Gatekeeper quarantine or Linux execute-permission steps — and how to confirm afterward that it installed.

   Install it to the default location. The STM32CubeIDE for Visual Studio Code extension only auto-detects STM32CubeMX at the paths below, so tell me if the installer puts it anywhere else:

   • macOS: /Applications/STMicroelectronics/STM32CubeMX.app
   • Linux: ~/STM32CubeMX/STM32CubeMX
   • Windows: C:\Program Files\STMicroelectronics\STM32Cube\STM32CubeMX\STM32CubeMX.exe

6. Optional. Install STM32CubeProgrammer if you plan to flash Swan over USB in DFU mode. Be sure to follow these installation notes when installing it.

Create a Project

There is no CMSIS board definition for Swan, so you configure the project against Swan's microcontroller — the STM32L4R5ZIY6TR — and then apply any Swan-specific configuration you need to below.

1. Click the STM32Cube (butterfly) icon in the Activity Bar and select Launch STM32CubeMX in the STM32Cube Key Actions section.

2. In STM32CubeMX, choose File > New Project, then select STM32L4R5ZIY6TR from the part selector and click Start Project.

   

3. Configure what you need in Pinout & Configuration, if anything. To follow the blink example below, set PE2 to GPIO_Output.

4. Open the Project Manager tab. Give the project a name and location, and set Toolchain/IDE to CMake. This is the setting that makes the output readable by VS Code.

5. Click Generate Code. You may have to download additional dependencies.

6. Return to VS Code and open the generated folder with File > Open Folder. The extension will detect your STM32Cube project and configure the tooling.

7. Select the CMake preset Debug when prompted. CMake then runs its configure step and writes the build files to build/Debug.

You now have a CMake project carrying the STM32L4 HAL under Drivers/STM32L4xx_HAL_Driver, an stm32l4xx_hal_conf.h, a linker script matched to Swan's 2MB of flash and 640KB of RAM, and a main.c with generated initialization code.

note

Keep the .ioc file that STM32CubeMX writes into the project. Reopening it in STM32CubeMX and regenerating is how you add peripherals later, and it preserves anything you write between the USER CODE BEGIN and USER CODE END markers.

Swan-Specific Configuration

Because the project targets the bare microcontroller rather than a Swan board definition, a few defaults do not match Swan's hardware.

Here are a few things worth knowing:

• USB requires its own supply rail. VDDUSB is fed by a separate 3.3V regulator rather than by VDD, so USB peripherals need PWR_CR2 USV enabled (HAL_PWREx_EnableVddUSB()) before they will work.

• PE6 (DISCHRG) must be open drain, with no pull-up or pull-down. This pin discharges the switchable 3.3V output rail; the default push-pull GPIO configuration violates the board's design note. PE4 (nEN_3V3_OUT) enables that same rail.

• Do not connect PB2 (BOOT1) to VDD.

• PA13 (SWDIO) and PA14 (SWCLK) are the two pins SWD needs. Repurposing either as GPIO will cost you SWD access, and with it the extension's ability to flash and debug.

• PA15 (JTDI) and PB3 (JTDO/TRACESWO) are JTAG pins, and STM32CubeMX may reserve them by default. Two-wire SWD does not need either, so you can release both for GPIO and keep flashing and debugging — but freeing PB3 gives up SWO trace output. PB4 is wired to USART1_CTS through a 0Ω resistor.

• LED_BUILTIN is PE2, and USER_BTN is PC13.

• Feather analog pins do not map to the ports you might assume: A4 and A5 are PC4 and PC5, and the two DAC outputs are PA4 (D10) and PA5 (D13). See Pin Information in the Swan Datasheet for the full mapping.

Blink the Onboard LED

To confirm the toolchain end to end, blink PE2. If you set it to GPIO_Output in STM32CubeMX's Pinout view, the generated MX_GPIO_Init() already configures the pin — so the only code you add is the loop, between the USER CODE BEGIN WHILE and USER CODE END WHILE markers in Core/Src/main.c:

/* USER CODE BEGIN WHILE */
while (1) {
  HAL_GPIO_TogglePin(GPIOE, GPIO_PIN_2);
  HAL_Delay(1000);
  /* USER CODE END WHILE */
}

note

If you'd rather configure the pin in code than in the Pinout view, do it after MX_GPIO_Init() instead:

COPY

__HAL_RCC_GPIOE_CLK_ENABLE();

GPIO_InitTypeDef led = {0};
led.Pin = GPIO_PIN_2;
led.Mode = GPIO_MODE_OUTPUT_PP;
led.Pull = GPIO_NOPULL;
led.Speed = GPIO_SPEED_FREQ_LOW;
HAL_GPIO_Init(GPIOE, &led);

warning

Keep additions inside the USER CODE markers. STM32CubeMX overwrites everything outside them the next time you regenerate.

Build and Flash Firmware

Swan has no on-board debugger, so flashing and step debugging from VS Code require an STLINK-V3MINI (or another SWD-capable ST-LINK probe) connected to Swan's Cortex-Debug connector. You can flash over USB with Swan's DFU bootloader instead, which requires no probe, but the extension's debugger cannot attach that way. We'll cover both paths here.

Build

You can now build your project with the CMake Tools integration the extension pack installs: click the Build button in the CMake view, use the build item in the status bar, or run CMake: Build from the Command Palette.

The build writes its artifacts to the preset's directory — build/Debug for the Debug preset — including the .elf the debugger flashes and the .hex, .bin, and .map files. To switch between Debug and Release, run CMake: Select Configure Preset from the Command Palette.

Flash with an STLINK-V3MINI (Recommended)

The extension flashes as part of starting a debug session: the ST-LINK GDB server downloads the built .elf to Swan, then hands control to GDB.

1. Plug the STLINK-V3MINI into your computer over USB.

2. Plug Swan into a power source — a LiPo battery, or your computer over USB.

   note

   If you want to see serial output from Swan over its own USB port, power it from a USB cable rather than a battery. Alternatively, use the STLINK-V3MINI for serial output and keep everything on one cable.

3. Plug the Cortex-Debug connector from the STLINK-V3MINI into Swan.

   

4. Open the Run and Debug view (shift + cmd/ctrl + D) and click Run and Debug. If VS Code asks which debug probe you are using, select the Launch ST-Link GDB Server option.

   After your project is built and uploaded to the Swan press F5 and you should see the onboard LED flash.

note

To keep a configuration you can edit and commit, click create a launch.json file in the Run and Debug view. The .vscode folder holding it must sit at the root of the project. A working Swan configuration looks like this:

COPY

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "stlinkgdbtarget",
      "request": "launch",
      "name": "Swan: Launch ST-Link GDB Server",
      "origin": "snippet",
      "cwd": "${workspaceFolder}",
      "preBuild": "${command:st-stm32-ide-debug-launch.build}",
      "runEntry": "main",
      "imagesAndSymbols": [
        {
          "imageFileName": "${command:st-stm32-ide-debug-launch.get-projects-binary-from-context1}"
        }
      ]
    }
  ]
}

Flash without an STLINK-V3MINI

Swan's DFU bootloader lets you flash over USB with no probe attached. The extension has no DFU flashing command, so use STM32CubeProgrammer for this path (and note that you cannot step debug this way).

1. Connect Swan's Micro USB port to your computer with a USB cable.

   

2. Press and hold the BOOT button, press and release RESET, then release BOOT to jump into the bootloader. This sequence must be repeated before every upload.

3. In STM32CubeProgrammer, select USB as the connection type and flash the .elf or .hex from your build directory. If you flash a raw .bin instead, set the start address to 0x08000000, since a .bin carries no address information of its own.

Step Debugging

With an STLINK-V3MINI attached, you can set breakpoints and step through firmware while it runs on Swan.

1. Set a breakpoint by clicking to the left of a line number in main.c. A red dot marks the line where execution will halt.

2. Press F5, or click Run and Debug in the Run and Debug view, to build, flash, and break at main.

3. When execution halts, step through your code with VS Code's step over, step into, and step out commands, and inspect state in the surrounding views.

Beyond the standard VS Code debug views, the extension pack adds several that are useful on Swan:

• Peripherals: read and write the STM32L4R5's peripheral registers by name, which is the fastest way to confirm a CubeMX clock or GPIO configuration actually took effect.

• STM32Cube Live Watch: watch global variables update while the target is running, without halting it. Right-click a variable and choose Add expression to Live Watch window.

• STM32Cube Fault Status Registers: decode a HardFault into its cause and location.

• Memory and Disassembly: inspect memory regions and the generated assembly.

• RTOS views: thread, queue, and call-stack views for FreeRTOS and ThreadX.

note

Breakpoints in assembly files are off by default. To enable them, open Settings (cmd/ctrl + ,), search for Allow Breakpoints, and check Allow Breakpoints in any file.

Viewing Serial Output

The extension pack includes a serial monitor, so you can read log output in the same window you build and debug in. Open the Serial Monitor panel, select the port, set the baud rate to match your firmware, and connect.

Swan gives you two ways to produce that output:

1. Over the STLINK-V3MINI's virtual COM port. Swan routes LPUART1 to the probe's VCP on PG7 (TX0) and PG8 (RX0), so a single cable carries both SWD and console output. Enable LPUART1 and assign it to those two pins, then print with HAL_UART_Transmit(). See Serial Logging With STLINK for the wiring details and the tradeoffs.

2. Over Swan's own Micro USB port, using the USB device peripheral in CDC mode. Remember that VDDUSB is on a separate rail — call HAL_PWREx_EnableVddUSB() during initialization or the port will never enumerate.