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: VS Code + Arduino Extension Instructions
• Option #5: CircuitPython Instructions

Additionally, if you have an STLink programmer like the STLink-V3Mini, you can follow the debugging guide for instructions on how to debug Arduino Swan programs with VS Code.

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
   lib_deps = 
     Wire
     blues/Blues Wireless Notecard@^1.3.13

   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.

   Likewise, if you want serial monitor access on the Swan, you'll want to add the following configuration option:

   build_flags = -D PIO_FRAMEWORK_ARDUINO_ENABLE_CDC

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. Plug the Swan into your computer over USB.
3. Press and hold the BOOT button on the Swan, press RESET, then release both buttons to cause the Swan to jump into its bootloader.

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

   

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. Plug the Swan into your computer over USB.
3. Press and hold the BOOT button on the Swan, press RESET, then release both buttons 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.
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 the VS Code Arduino Extension

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.

2. Installing either the Arduino IDE or Arduino CLI is required for the official VS Code Arduino extension to work properly.

3. Install the STM32 BSP (STM32duino) as described in Installing STM32duino in the Arduino IDE above.

   NOTE: On Windows the Arduino IDE must be installed manually, as opposed to being installed via the Windows App Store.

4. Install the official Arduino extension from Microsoft via the Extensions menu of VS Code.

   

5. Install STMCubeIDE and add STM32_Programmer.sh and STM32_Programmer_CLI to your path.

   Linux/macOS:

   COPY
   $ sudo ln -s /<STM32CubeProgrammer path>/bin/STM32_Programmer.sh -t /usr/local/bin
   $ sudo ln -s /<STM32CubeProgrammer path>/bin/STM32_Programmer_CLI -t /usr/local/bin

   Note: If you’re on macOS the path to the STM32CubeProgrammer is likely /Applications/STMicroelectronics/STM32Cube/STM32CubeProgrammer/STM32CubeProgrammer.app/Contents/MacOs/.

   Windows:

   Add the following location to Path in your system environment variables.

   Example: C:\ST\STM32CubeIDE_1.7.0\STM32CubeIDE\plugins\com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.win32_2.0.0.202105311346\tools\bin

6. Install OpenOCD

   Linux:

   COPY
   sudo apt install openocd

   macOS:

   • Homebrew

     COPY
     brew install openocd

   • MacPorts

     COPY
     sudo port install openocd

   Windows:

   1. Download the latest, pre-built version of OpenOCD from the GNU Toolchains page.

   2. Unzip and add the following location to Path in your system environment variables.

      Example: C:\Program Files (x86)\OpenOCD\OpenOCD-20210729-0.11.0\bin

Configuring VS Code for Swan

1. Open the VS Code command palette with F1 or shift + cmd/ctrl + P and type "Arduino: Board Config". Alternatively, click the <Select Board Type> button in the bottom Status Bar.

   

2. Set the options as follows. Note: Once you select a board, there is often a delay before the rest of the options appear.

   

   Saving the options will either create or update your .vscode/arduino.json file.

   note

   The options above assume 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 need to set your upload method to STM32CubeProgrammer (SWD) instead.

Blink the Onboard LED

Now that you have the necessary setup done, it’s time to run your first sketch.

1. Plug the Swan into your computer over USB.

2. Press and hold the BOOT button on your Swan, press RESET, then release both buttons to cause the Swan to jump into its bootloader.

3. Press F1 or shift + cmd/ctrl + P and select Arduino: Examples from the dropdown menu.

   

4. Select Built-in Examples > 01. Basics > Blink from the menu, and a new editor will open.

   

5. Press the Upload button in VS Code to upload your sketch to Swan.

   

6. The upload process will take several seconds. When it finishes you should see a done uploading message in your terminal output.

   

Build Output

You will likely receive the following warning when you first run a sketch.

COPY
[Warning] Output path is not specified. Unable to reuse previously compiled files. Build will be slower. See README.

You can eliminate this warning by specifying a directory of your choosing in your .vscode/arduino.json (i.e. add key/value pair "output": ".build/GenL4"). You can ignore the warning, but if you do your builds will be slower, as Arduino uses that folder to cache build assets.

note

When debugging, if you haven’t specified an output folder the extension will create a .build/GenL4 folder on your behalf. Interestingly, even if you have specified an output folder, the extension will still create a GenL4 folder nested under the output folder, regardless.

Debugging Arduino with VS Code

note

An STLink programmer like the STLink-V3Mini is required for debugging with Swan.

1. In the Debug Panel, click the "create a launch.json file" link to add an Arduino entry in your launch.json configuration.

   NOTE: At the time of writing, there is a bug in the Arduino VS Code extension that requires you to NOT have an .ino file as the active tab to generate an Arduino entry in launch.json.

   

   Arduino appears in the dropdown menu when an .ino file is NOT the active tab...

   

   Arduino option not available in dropdown menu when an .ino file is the active tab...

2. Once .vscode/launch.json has been created you will need to modify the following lines of the Arduino configuration, keeping in mind the path to your installation of OpenOCD may be different:

   Linux/macOS:

   COPY
   "debugServerPath": "/usr/bin/openocd",
   "debugServerArgs": "-f interface/stlink.cfg -f target/stm32l4x.cfg",

   Windows:

   COPY
   "debugServerPath": "C:\\Program Files (x86)\\OpenOCD\\OpenOCD-20210729-0.11.0\\bin\\openocd.exe",
   "debugServerArgs": "-f interface\\stlink.cfg -f target\\stm32l4x.cfg",

   Full text of generated Arduino `.vscode/launch.json`

   COPY
   {
       // Use IntelliSense to learn about possible attributes.
       // Hover to view descriptions of existing attributes.
       // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Arduino",
               "type": "arduino",
               "request": "launch",
               "program": "${file}",
               "cwd": "${workspaceFolder}",
               "MIMode": "gdb",
               "targetArchitecture": "arm",
               "miDebuggerPath": "",
               "debugServerPath": "",
               "debugServerArgs": "",
               "customLaunchSetupCommands": [
                   {
                       "text": "target remote localhost:3333"
                   },
                   {
                       "text": "file \"${file}\""
                   },
                   {
                       "text": "load"
                   },
                   {
                       "text": "monitor reset halt"
                   },
                   {
                       "text": "monitor reset init"
                   }
               ],
               "stopAtEntry": true,
               "serverStarted": "Info\\ :\\ [\\w\\d\\.]*:\\ hardware",
               "launchCompleteCommand": "exec-continue",
               "filterStderr": true,
               "args": []
           }
       ]
   }

3. Once configured, you can set breakpoints in VS Code and use the VS Code debug pane to step through your Arduino programs.

   note

   If you are able to start debugging but your breakpoints are not being hit, try disconnecting the Swan from your computer and instead powering it externally with a LiPo battery (and the STLink programmer remaining the only device connected to your computer).

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 to your computer via the Micro USB port.

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)

Occasionally, when flashing firmware with the STLINK-V3MINI using the Arduino IDE via SWD, the Option Bytes in the FLASH registers will become invalid.

Example of invalid register values:

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:

FLASH Registers

After updating the option bytes, the STM32L4R5 can now be programmed using the STM32CubeProgrammer and execute firmware. However, this state is unstable and the STM32L4R5 will likely return to the bad state the next time you try to flash using the Arduino IDE via SWD.

However, immediately programing the STM32L4R5 using the Arduino IDE via DFU will often stabilize the device settings. Afterward, the device can be debugged and programmed normally via SWD again.

Next Steps

• Full Swan documentation
• STM32 Arduino Board Support Package
• VS Code Marketplace: PlatformIO Extension
• VS Code Marketplace: Arduino 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.