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.

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

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

Add active user to plugdev group in /etc/group.

sudo usermod -aG plugdev $USER

Install Visual Studio Code (if you haven't done so already).
Install the PlatformIO IDE extension via the Extensions menu of VS Code.

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

Create a Project

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.
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.
At this point, PlatformIO may need to install a variety of software dependencies. Please be patient as installation may take some time!
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.6
```
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)

In your platformio.ini file, set upload_protocol to stlink.
Plug the STLINK-V3MINI into your computer over USB.
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.
Plug the Cortex-Debug connector from the STLINK-V3MINI into the Swan.
Skip to the Blink the Onboard LED instructions below.

Programming Swan without the STLINK-V3MINI

In your platformio.ini file, set upload_protocol to dfu.
Connect the Swan's Micro USB port to your computer with a USB cable.
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!
Proceed to the Blink the Onboard LED instructions below.

Blink the Onboard LED

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

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
}

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.
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).

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.

In your platformio.ini file, add a line to set the debugging tool you are using: debug_tool = stlink.
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.
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.

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:

~~Use the Notecard to Send Data~~
~~Set Up Your Microcontroller~~
Build Your First IoT App With Blues
Send Data to Your Cloud

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