Scaling an IoT deployment? Join our webinar on May 28th where we dive into real-world scaling pain points and how to overcome them.

Blues Developers
What’s New
Resources
Blog
Technical articles for developers
Newsletter
The monthly Blues developer newsletter
Terminal
Connect to a Notecard in your browser
Developer Certification
Get certified on wireless connectivity with Blues
Webinars
Listing of Blues technical webinars
Blues.comNotehub.io
Shop
Docs
Button IconHelp
Notehub StatusVisit our Forum
Button IconSign In
Sign In
Sign In
Docs Home
What’s New
Resources
Blog
Technical articles for developers
Newsletter
The monthly Blues developer newsletter
Terminal
Connect to a Notecard in your browser
Developer Certification
Get certified on wireless connectivity with Blues
Webinars
Listing of Blues technical webinars
Blues.comNotehub.io
Shop
Docs
Quickstart
Cell+WiFi Quickstart
LoRaWAN Quickstart
Starnote Quickstart
Wireless for Arduino Opta Quickstart
Notecard Quickstart
Notecard LoRa Quickstart
Cygnet Quickstart
Swan Quickstart
Install PrerequisitesCreate a ProjectFlash FirmwareDebugging with PlatformIONext Steps
Mojo Quickstart
Sparrow Quickstart
homechevron_rightDocschevron_rightQuickstartchevron_rightSwan Quickstart

Swan Quickstart

Watch a video of this tutorial

The Swan Development Board is a fully-featured board that provides access to the rich feature set of the onboard STM32L4 chip. We selected the STMicroelectronics chip because of its industry-leading technology, as well as its rich tooling and developer experience.

All together, the Swan empowers all developers, from IoT newcomers to industry experts.

This guide will help you start developing on the Swan with Arduino, using PlatformIO.

Using the VS Code PlatformIO Extension

Using PlatformIO with VS Code is a friction-free way of getting started with Swan development due to the relatively few configuration steps required.

Those who already have STM32CubeIDE or Arduino IDE installed may prefer to follow the guides on Using STM32CubeIDE with Swan or Using Arduino IDE with Swan instead.

Install Prerequisites

Linux only setup required for accessing the device in DFU mode and virtual COM port.
  1. Create a /etc/udev/rules.d/ rule for the device in DFU mode.
(echo '# DFU (Internal bootloader for STM32 MCUs)';  echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE="0664", GROUP="plugdev"') | sudo tee /etc/udev/rules.d/49-stdfu-permissions.rules > /dev/null
  1. Create a /etc/udev/rules.d/ rule for the device's virtual COM port.
(echo '# Virtual COM Port for STM32 MCUs'; echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="5740", MODE="0664", GROUP="plugdev"') | sudo tee /etc/udev/rules.d/49-stvcp-permissions.rules > /dev/null
  1. Add active user to plugdev group in /etc/group.
sudo usermod -aG plugdev $USER
  1. Install Visual Studio Code (if you haven't done so already).

  2. Install the PlatformIO IDE extension via the Extensions menu of VS Code.

    VS Code PlatformIO Extension

Note that all other requirements like STM32duino, OpenOCD, and dfu-util will be installed automatically by PlatformIO when needed!

Create a Project

  1. Open the PlatformIO extension by clicking on the PlatformIO logo in the menu bar. Next, click the "Open" option under the "PIO Home" menu and finally "New Project" to create a new PlatformIO project.

    open platformio extension in vs code

  2. In the provided Project Wizard, give your project a name, choose the "Blues Swan R5" as your board, and choose "Arduino Framework" as your framework. You can also override the default location where your project files will be saved.

    platformio project wizard

  3. At this point, PlatformIO may need to install a variety of software dependencies. Please be patient as installation may take some time!

  4. Once dependency installation is complete, your platformio.ini file will open. This file allows you to configure deployment options and manage project libraries. Consult the PlatformIO documentation for complete details.

    To develop on the Swan with the Notecard, replace your generated platform.ini file with this:

    [env:blues_swan_r5]
    platform = ststm32
    board = blues_swan_r5
    upload_protocol = stlink
    framework = arduino
    build_flags = -D PIO_FRAMEWORK_ARDUINO_ENABLE_CDC
    monitor_speed = 115200
    lib_deps =
      Wire
      blues/Blues Wireless Notecard@^1.6.5
    warning

    The above configuration assumes you're connecting to your Swan via an STLink programmer like the STLINK-V3MINI . If you instead intend to program your Swan using only a USB cable, you'll need to set your upload_protocol to dfu and follow these instructions to force the Swan to jump into its bootloader:

    Press and hold the BOOT button on the Swan, press and release RESET, then release BOOT every time you want to upload firmware.

Flash Firmware

To program Swan, it is recommended you use a programmer like the STLINK-V3MINI . However, you may also program Swan via a USB cable connected directly from it to your computer.

Programming Swan with the STLINK-V3MINI (Recommended)

  1. In your platformio.ini file, set upload_protocol to stlink.

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

  3. Plug the Swan into a power source (e.g. a LiPo battery or your computer via USB).

    NOTE: If you want to see Serial output from the Swan, you need to either use a USB cable as the power source or customize your sketch to use the STLINK-V3MINI for Serial output.

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

    swan to stlink

  5. Skip to the Blink the Onboard LED instructions below.

Programming Swan without the STLINK-V3MINI

  1. In your platformio.ini file, set upload_protocol to dfu.

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

    swan micro usb

  3. Press and hold the BOOT button on the Swan, press and release RESET, then release BOOT to cause the Swan to jump into its bootloader. IMPORTANT: This sequence must be performed each time you want to upload new firmware to the Swan!

  4. Proceed to the Blink the Onboard LED instructions below.

Blink the Onboard LED

  1. In VS Code, open the src/main.cpp file in your PlatformIO project.

  2. Overwrite the provided boilerplate code with the following to cause the onboard LED to blink repeatedly:

    #include <Arduino.h>
    
    // the setup function runs once when you press reset or power the board
    void setup()
    {
      // initialize digital pin LED_BUILTIN as an output.
      pinMode(LED_BUILTIN, OUTPUT);
    }
    
    // the loop function runs over and over again forever
    void loop()
    {
      digitalWrite(LED_BUILTIN, HIGH); // turn the LED on (HIGH is the voltage level)
      delay(1000);                     // wait for a second
      digitalWrite(LED_BUILTIN, LOW);  // turn the LED off by making the voltage LOW
      delay(1000);                     // wait for a second
    }
  3. Press F1 or shift + cmd/ctrl + P to open the VS Code Command Pallette. Choose "PlatformIO: Build" to build the program or "PlatformIO: Upload" to build and upload the program to your Swan.

    warning

    Did your firmware upload fail with a libusb error? This is not specific to Swan, but rather with programming any STM32 board.

    Windows: Install a generic USB driver that supports libusb. Download Zadig to install "WinUSB" and consult this article for more information.

    macOS on Apple Silicon: The appropriate libusb package must be installed for the Apple Silicon architecture:

    • Install via MacPorts with port install libusb

    • Install via Homebrew with brew install libusb

    • Installing ST's STM32CubeIDE should also fix the issue, as it installs libusb as part of its setup.

  4. Lastly, you can open the PlatformIO Serial Monitor by clicking on the appropriate icon on the bottom menu in VS Code. Note that when the serial monitor opens, you may need to choose the device you are connecting to (this will vary depending on your OS and whether you are using the dfu or stlink upload_protocol).

    platformio serial monitor

Debugging with PlatformIO

Using a programmer like the STLINK-V3MINI with PlatformIO allows you to set breakpoints in code and use "step out", "step over", and "step into" commands to debug your firmware while it's actively running on the Swan.

  1. In your platformio.ini file, add a line to set the debugging tool you are using: debug_tool = stlink.

  2. Set a breakpoint on a line of code by clicking to the left of any line number in your sketch (with code) and adding a red dot. This is a breakpoint where the execution of the program will halt and allow you to debug.

    platformio set breakpoint

  3. Press F5, or press the play button in VS Code's "Run and Debug" tab, to compile and deploy the sketch to your Swan. The Debug Console will open and allow you to step through your code line-by-line, watch variables, and view memory usage.

    platformio debug console

Next Steps

Congratulations! You've configured your Swan and flashed new firmware to it using VS Code, PlatformIO, and Arduino.

If you're following the Blues Quickstart, next we recommend building your first IoT app:

  1. Use the Notecard to Send Data
  2. Set Up Your Microcontroller
  3. Build Your First IoT App With Blues
  4. Send Data to Your Cloud

At any time, if you find yourself stuck, please reach out on the community forum .

Can we improve this page? Send us feedback
© 2025 Blues Inc.
© 2025 Blues Inc.
TermsPrivacy
Notecard Disconnected
Having trouble connecting?

Try changing your USB cable as some cables do not support transferring data. If that does not solve your problem, contact us at support@blues.com and we will get you set up with another tool to communicate with the Notecard.

Advanced Usage

The help command gives more info.

Connect a Notecard
Use USB to connect and start issuing requests from the browser.
Try Notecard Simulator
Experiment with Notecard's latest firmware on a Simulator assigned to your free Notehub account.

Don't have an account? Sign up