Swan Quickstart

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, C/C++, and CircuitPython using your preferred IDE. Start by choosing one of the following setup options:

• Option #1: VS Code + PlatformIO Extension Instructions (recommended)
• Option #2: STM32CubeIDE Instructions
• Option #3: Arduino IDE Instructions
• Option #4: CircuitPython Instructions

note

If you’re using Swan with a Notecard, make sure to complete the Notecard quickstart after you finish this guide.

Using the VS Code PlatformIO Extension

Using PlatformIO with VS Code can be a friction-free way of getting started with Swan development due to the relatively few configuration steps required. Those who already have STM32CubeIDE and/or Arduino IDE installed may prefer to follow those instructions instead.

Prerequisites

1. 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!

Creating a PlatformIO Project for Swan

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.

   

2. In the provided Project Wizard, give your project a name, choose the "Blues Wireless 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.

   

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, your platformio.ini file will look something like this:

   COPY
   [env:bw_swan_r5]
   platform = ststm32
   board = bw_swan_r5
   upload_protocol = dfu
   framework = arduino
   build_flags = -D PIO_FRAMEWORK_ARDUINO_ENABLE_CDC
   monitor_speed = 115200
   lib_deps = 
     Wire
     blues/Blues Wireless Notecard@^1.3.16

   note

   The above configuration assumes you're connecting to your Swan via USB. If you instead intend to debug your Swan using an STLink programmer like the STLink-V3Mini, you'll want to set your upload_protocol to stlink instead.

Programming Swan (PlatformIO)

To program Swan with PlatformIO, you can use a programmer like the STLINK-V3MINI or program via a USB cable connected to your computer.

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.

   

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.

   warning

   If you are using Windows and encounter a LIBUSB error when uploading firmware via the dfu method, you may have to install a generic USB driver that supports LIBUSB. Download Zadig to install WinUSB and consult this article for more background.

With the STLink-V3Mini

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 to use the serial monitor).

   

4. Plug the Cortex-Debug connector from the STLink-V3Mini into Swan.

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:

   COPY
   #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.

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

   

Debugging with PlatformIO

The PlatformIO documentation includes a helpful set of resources for debugging an STM32. Please note that an STLink programmer like the STLink-V3Mini is required for debugging with Swan.

Using the STM32CubeIDE

1. Download and install STM32CubeIDE and STM32CubeProgrammer if you don't already have them installed. Be sure to follow these installation notes when installing STM32CubeProgrammer.

2. During the STM32CubeIDE configuration, select STM32L4R5ZIYx (STM32L4R5ZIY6TR) as the target device.

   

3. Once you've selected the STM32L4R5ZIY6TR, you'll be able to use STM32CubeIDE as you would for any STMicroelectronics dev kit.

Using the Arduino IDE

Prerequisites

1. Download and install STM32CubeIDE and STM32CubeProgrammer if you don't already have them installed. Be sure to follow these installation notes when installing STM32CubeProgrammer.

Installing STM32duino in the Arduino IDE

1. Add the following URL to the Additional Boards URL in Preferences: https://github.com/stm32duino/BoardManagerFiles/raw/main/package_stmicroelectronics_index.json

   

2. After restarting Arduino, go to the Tools > Boards > Boards Manager... menu option, search for "STM32 MCU based boards", and install version 2.1.0 or greater.

3. Restart Arduino.

Using STM32duino in the Arduino IDE

1. Under Tools > Board, select "STM32 Boards groups", and then "Blues Wireless boards."

   

2. Next, under Tools > Board Part Number, select "Swan R5."

   

3. Lastly, under Tools > USB support (if available), select "CDC (generic 'Serial' supersede U(S)ART)."

Programming Swan (Arduino IDE)

To program Swan in the Arduino IDE, you can use a programmer like the STLINK-V3MINI or program via a USB cable connected to your computer.

Without the STLink-V3Mini

1. Under Tools > Upload method, select "STM32CubeProgrammer (DFU)."

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

   

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.

With the STLink-V3Mini

1. Under Tools > Upload method, select "STM32CubeProgrammer (SWD)."

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 to use the serial monitor).

   

4. Plug the Cortex-Debug connector from the STLink-V3Mini into Swan.

Blink the Onboard LED

1. In the Arduino IDE, use File > New to create a new sketch.

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

   COPY
   // 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. Upload this sketch to the Swan.

Using CircuitPython

Prerequisites

1. Download the latest versions of tinyuf2-swan_r5.bin and circuitpython-swan_r5.uf2 from the Blues Wireless CircuitPython repository.

2. If you haven't already, install the device firmware upgrade utility: dfu-util.

Installation

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

2. Put your Swan into "boot" mode by holding down the BOOT button, pressing and releasing the RESET button, then releasing the BOOT button.

   

3. In a terminal window, navigate to the directory where you downloaded the bootloader files and run the following command to flash the Swan:

   COPY
   dfu-util -s 0x8000000:leave -a 0 -D tinyuf2-swan_r5.bin

4. In a few seconds, a new drive called SWANBOOT will appear.

   note

   If you have previously installed the bootloader but don't see the SWANBOOT drive appear, simply press and release the RESET button twice to mount the drive.

5. Drag-and-drop the previously downloaded circuitpython-swan_r5.uf2 file onto the SWANBOOT drive. Your Swan will quickly reset and the CIRCUITPY drive will appear.

Choosing an IDE

The beauty of working with CircuitPython on the Swan is that you interact directly with the source Python files on the CIRCUITPY drive. Virtually any IDE or text editor can be used to add, edit, and delete these files.

However, if you want to interact with the on-device REPL or view terminal output, you'll want to use a tool specific to CircuitPython development. Traditional Python editors such as Mu and Thonny are great for programming CircuitPython on the Swan. Likewise, VS Code with the CircuitPython extension is another popular option (noting some additional configuration required below).

Consult the recommended editors resource from Adafruit for more information about choosing an editor.

Blink the Onboard LED

1. Open the copy.py file using your preferred editor.

2. Paste in the following code and save the updated copy.py file.

   COPY
   import board
   import digitalio
   import time
   
   led = digitalio.DigitalInOut(board.LED)
   led.direction = digitalio.Direction.OUTPUT
   
   while True:
      led.value = True
      time.sleep(0.5)
      led.value = False
      time.sleep(0.5)

3. Depending on your IDE or editor, you may have to reset the device to see the changes. Enjoy your blinking LED!

Recover Swan (STM32L4R5)

We discovered an SWD configuration error was present in older versions of the ST Board Support Package (BSP) for the Arduino IDE. The configuration error would occasionally cause corruption of the Option Bytes in the FLASH registers. Below we outline the steps required to repair the Option Bytes of the Swan.

note

The configuration error was resolved in the Arduino BSP, STM32 MCU based boards, version 2.3.0.

Hardware Setup

1. Connect the STLink Debugger to the Swan with the included ribbon cable and your computer via USB
2. Apply power to the Swan via the micro USB port and plug into your computer (or other USB power source)

Update with STM32CubeProgrammer (GUI)

Invalid FLASH Registers

When the Option Byte registers get into this state, the STM32L4R5 will no longer execute firmware or allow programming.

Fortunately, the STM32L4R5 can be recovered using the STM32CubeProgrammer, by updating the following FLASH registers (in the [REG] tab) to the following values:

Valid FLASH Registers

After updating the option bytes, the STM32L4R5 can now be programmed using the STM32CubeProgrammer and execute firmware. Once you have updated the ST BSP, the device can be debugged and programmed normally via SWD again.

Update with STM32_Programmer_CLI

1. Apply the following commands in order:

   COPY
   STM32_Programmer_CLI --connect port=SWD --optionbytes RDP=0xBB
   STM32_Programmer_CLI --connect port=SWD --optionbytes RDP=0xAA
   STM32_Programmer_CLI --connect port=SWD --optionbytes nRST_STOP=1 IWDG_SW=1 IWDG_STOP=1 IWDG_STDBY=1 WWDG_SW=1 DBANK=1 nBOOT1=1 SRAM2_PE=1 SRAM2_RST=1 nSWBOOT0=01 PCROP1_STRT=0x1FFFF PCROP1_END=0x10000 WRP1A_STRT=0xFF WRP1A_END=0 WRP1B_STRT=0xFF WRP1B_END=0
   STM32_Programmer_CLI --connect port=SWD --optionbytes PCROP_RDP=1

2. Verify the option byte values by displaying them to the command prompt

   COPY
   STM32_Programmer_CLI --connect port=SWD --optionbytes displ

3. Compare the response to the following...

   COPY
   UPLOADING OPTION BYTES DATA ...
   
     Bank          : 0x00
     Address       : 0x40022020
     Size          : 20 Bytes
   
   ██████████████████████████████████████████████████ 100%
   
     Bank          : 0x01
     Address       : 0x40022044
     Size          : 16 Bytes
   
   ██████████████████████████████████████████████████ 100%
   
   
   OPTION BYTES BANK: 0
   
      Read Out Protection:
   
        RDP          : 0xAA (Level 0, no protection)
   
      BOR Level:
   
        BOR_LEV      : 0x0 (BOR Level 0, reset level threshold is around 1.7 V)
   
      User Configuration:
   
        nRST_STOP    : 0x1 (No reset generated when entering Stop mode)
        nRST_STDBY   : 0x0 (Reset generated when entering Standby mode)
        nRST_SHDW    : 0x0 (Reset generated when entering the Shutdown mode)
        IWDG_SW      : 0x1 (Software independant watchdog)
        IWDG_STOP    : 0x1 (IWDG counter active in stop mode)
        IWDG_STDBY   : 0x1 (IWDG counter active in standby mode)
        WWDG_SW      : 0x1 (Software window watchdog)
        BFB2         : 0x0 (Dual-bank boot disable)
        DBANK        : 0x1 (Dual bank mode with 64 bits data)
        nBOOT1       : 0x1 (Boot from system memory when BOOT0=1)
        SRAM2_PE     : 0x1 (SRAM2 parity check disable)
        SRAM2_RST    : 0x1 (SRAM2 is not erased when a system reset occurs)
        nSWBOOT0     : 0x1 (BOOT0 taken from PH3/BOOT0 pin)
        nBOOT0       : 0x1 (BOOT0 = 0, boot from system memory when nSWBOOT0=1 and main flash is empty,otherwise, boot from main flash memory)
   
      PCROP Protection (Bank 1):
   
        PCROP1_STRT  : 0x1FFFF  (0x80FFFF8)
        PCROP1_END   : 0x10000  (0x8080000)
        PCROP_RDP    : 0x1 (PCROP zone is erased when RDP is decreased)
   
      Write Protection (Bank 1):
   
        WRP1A_STRT   : 0xFF  (0x80FF000)
        WRP1A_END    : 0x0  (0x8000000)
        WRP1B_STRT   : 0xFF  (0x80FF000)
        WRP1B_END    : 0x0  (0x8000000)
   
   OPTION BYTES BANK: 1
   
      PCROP Protection  (Bank 2):
   
        PCROP2_STRT  : 0x1FFFF  (0x81FFFF8)
        PCROP2_END   : 0x10000  (0x8180000)
   
      Write Protection (Bank 2):
   
        WRP2A_STRT   : 0xFF  (0x81FF000)
        WRP2A_END    : 0x0  (0x8100000)
        WRP2B_STRT   : 0xFF  (0x81FF000)
        WRP2B_END    : 0x0  (0x8100000)

If you are still experiencing difficulties, please contact Blues Support.

note

Recovery documentation created based on original Blues forum post.

Next Steps

• Full Swan documentation
• STM32 Arduino Board Support Package
• VS Code Marketplace: PlatformIO Extension
• Swan on CircuitPython.org

If you're using your Swan with a Notecard, make sure you've completed the Notecard quickstart, and then check out the Notecard + Swan sensor tutorial. The sensor tutorial walks you through capturing sensor data with your Swan, and sending that data to the cloud using the Notecard.