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:
- VS Code + PlatformIO Extension Instructions (recommended)
- STM32CubeIDE Instructions
- Arduino IDE Instructions
- VS Code + Arduino Extension Instructions
- CircuitPython Instructions
In addition, 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.
If you’re using Swan with a Notecard, make sure to complete the Notecard quickstart after you finish this guide.
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.
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!
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 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.
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, yourplatformio.ini
file will look something like this:[env:bw_swan_r5] platform = ststm32 board = bw_swan_r5 upload_protocol = dfu framework = arduino lib_deps = 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
tostlink
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
To program Swan with PlatformIO, you can use a programmer like the STLINK-V3MINI or program via a USB cable connected to your computer.
- In your
platformio.ini
file, setupload_protocol
todfu
. - Plug the Swan into your computer over USB.
- Press and hold the
BOOT
button on the Swan, pressRESET
, then release both buttons to cause the Swan to jump into its bootloader.
- In your
platformio.ini
file, setupload_protocol
tostlink
. - Plug the STLink-V3Mini into your computer over USB.
- Plug the Swan into a power source.
- Plug the Cortex-Debug connector from the STLink-V3Mini into Swan.
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
orshift + 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.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
orstlink
upload_protocol
).
Download and install STM32CubeIDE and STM32CubeProgrammer if you don't already have them installed. Be sure to follow these installation notes when installing STM32CubeProgrammer.
During the STM32CubeIDE configuration, select
STM32L4R5ZIYx
(STM32L4R5ZIY6TR
) as the target device.Once you've selected the
STM32L4R5ZIY6TR
, you'll be able to use STM32CubeIDE as you would for any STMicroelectronics dev kit.
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
- Download and install STM32CubeIDE and STM32CubeProgrammer if you don't already have them installed. Be sure to follow these installation notes when installing STM32CubeProgrammer.
Add the following URL to the Additional Boards URL in Preferences:
https://github.com/stm32duino/BoardManagerFiles/raw/main/package_stmicroelectronics_index.json
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.Restart Arduino.
Under Tools > Board, select "STM32 Boards groups", and then "Blues Wireless boards."
Next, under Tools > Board Part Number, select "Swan R5."
Lastly, under Tools > USB support (if available), select "CDC (generic 'Serial' supersede U(S)ART)."
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.
- Under Tools > Upload method, select "STM32CubeProgrammer (DFU)."
- Plug the Swan into your computer over USB.
- Press and hold the
BOOT
button on the Swan, pressRESET
, then release both buttons to cause the Swan to jump into its bootloader.
- Under Tools > Upload method, select "STM32CubeProgrammer (SWD)."
- Plug the STLink-V3Mini into your computer over USB.
- Plug the Swan into a power source.
- Plug the Cortex-Debug connector from the STLink-V3Mini into Swan.
In the Arduino IDE, use File > New to create a new sketch.
Overwrite the provided boilerplate code with the following to cause the onboard LED to blink repeatedly:
// 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 }
Upload this sketch to the Swan.
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 either the Arduino IDE or Arduino CLI is required for the official VS Code Arduino extension to work properly.
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.
Install the official Arduino extension from Microsoft via the Extensions menu of VS Code.
Install STMCubeIDE and add
STM32_Programmer.sh
andSTM32_Programmer_CLI
to your path.Linux/macOS:
$ 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
Install OpenOCD
Linux:
sudo apt install openocd
macOS:
Homebrew
brew install openocd
MacPorts
sudo port install openocd
Windows:
Download the latest, pre-built version of OpenOCD from the GNU Toolchains page.
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
Open the VS Code command palette with
F1
orshift + cmd/ctrl + P
and type "Arduino: Board Config". Alternatively, click the<Select Board Type>
button in the bottom Status Bar.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.
Now that you have the necessary setup done, it’s time to run your first sketch.
Plug the Swan into your computer over USB.
Press and hold the
BOOT
button on your Swan, pressRESET
, then release both buttons to cause the Swan to jump into its bootloader.Press
F1
orshift + cmd/ctrl + P
and select Arduino: Examples from the dropdown menu.Select Built-in Examples > 01. Basics > Blink from the menu, and a new editor will open.
Press the Upload button in VS Code to upload your sketch to Swan.
The upload process will take several seconds. When it finishes you should see a done uploading message in your terminal output.
You will likely receive the following warning when you first run a sketch.
[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.
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.
An STLink programmer like the STLink-V3Mini is required for debugging with Swan.
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 inlaunch.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...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:
"debugServerPath": "/usr/bin/openocd", "debugServerArgs": "-f interface/stlink.cfg -f target/stm32l4x.cfg",
Windows:
"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`
{ // 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": [] } ] }
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).
Download the latest versions of
tinyuf2-swan_r5.bin
andcircuitpython-swan_r5.uf2
from the Blues Wireless CircuitPython repository.If you haven't already, install the device firmware upgrade utility: dfu-util.
Connect the Swan to your computer via the Micro USB port.
Put your Swan into "boot" mode by holding down the
BOOT
button, pressing and releasing theRESET
button, then releasing theBOOT
button.In a terminal window, navigate to the directory where you downloaded the bootloader files and run the following command to flash the Swan:
dfu-util -s 0x8000000:leave -a 0 -D tinyuf2-swan_r5.bin
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 theRESET
button twice to mount the drive.Drag-and-drop the previously downloaded
circuitpython-swan_r5.uf2
file onto theSWANBOOT
drive. Your Swan will quickly reset and theCIRCUITPY
drive will appear.
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.
VS Code CircuitPython Extension Instructions
Within the CircuitPython extension there are configurations specific to individual boards. These configurations are generated automatically when a new version of the CircuitPython extension is released. Since the Swan is a new board, its config is not yet loaded in the extension, so there are some (temporary) manual steps involved.
Install the CircuitPython extension from the Extensions menu in VS Code.
Find your VS Code installation directory and open up the following file in an editor (your path may differ slightly):
~/.vscode/extensions/joedevivo.vscode-circuitpython-0.1.15/boards/metadata.json
Add the following item to the JSON object:
"vid": "0x30a4", "pid": "0x0002", "product": "Swan R5", "manufacturer": "Blues Wireless",
In that same directory, create the following directories and file:
0x30A4/0x0002/board.pyi
Populate
board.pyi
with the following:from typing import Any """ board Blues Wireless Swan Feather STM32L4R5 https://shop.blues.io/products/swan """ board.A0: Any = ... A1: Any = ... A2: Any = ... A3: Any = ... A4: Any = ... A5: Any = ... VOLTAGE_MONITOR: Any = ... D5: Any = ... D6: Any = ... D9: Any = ... D10: Any = ... D11: Any = ... D12: Any = ... LED: Any = ... D13: Any = ... SDA: Any = ... SCL: Any = ... SCK: Any = ... MISO: Any = ... MOSI: Any = ... TX: Any = ... RX: Any = ... NEOPIXEL: Any = ... SDIO_CLOCK: Any = ... SDIO_COMMAND: Any = ... SDIO_DATA: Any = ... CAN_RX: Any = ... CAN_TX: Any = ... def I2C() -> busio.I2C: """Returns the `busio.I2C` object for the board designated SDA and SCL pins. It is a singleton.""" ... def SPI() -> busio.SPI: """Returns the `busio.SPI` object for the board designated SCK, MOSI and MISO pins. It is a singleton.""" ... def UART() -> busio.UART: """Returns the `busio.UART` object for the board designated TX and RX pins. It is a singleton. The object created uses the default parameter values for `busio.UART`. If you need to set parameters that are not changeable after creation, such as ``receiver_buffer_size``, do not use `board.UART()`; instead create a `busio.UART` object explicitly with the desired parameters."""
Open the
CIRCUITPY
drive with a new VS Code window. Click theChoose a board
option in the bottom Status Bar.In the provided dialog, search for "Swan" and select the "Blues Wireless:Swan R5" option.
Open the
copy.py
file using your preferred editor.Paste in the following code and save the updated
copy.py
file.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)
Depending on your IDE or editor, you may have to reset the device to see the changes. Enjoy your blinking LED!
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
Register | Value |
---|---|
OPTR | 0x08000000 |
PCROP1SR | 0xFFFE0000 |
PCROP1ER | 0xFFFE0000 |
WRP1AR | 0xFF00FF00 |
WRP2AR | 0xFF00FF00 |
PCROP2SR | 0xFFFFFFFF |
PCROP2ER | 0xFFFF0000 |
WRP1BR | 0xFF00FFFF |
WRP2BR | 0xFF00FFFF |
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
Register | Value |
---|---|
OPTR | 0xFFEF98AA |
PCROP1SR | 0xFFFFFFFF |
PCROP1ER | 0xFFFF0000 |
WRP1AR | 0xFF00FFFF |
WRP2AR | 0xFF00FFFF |
PCROP2SR | 0xFFFFFFFF |
PCROP2ER | 0xFFFF0000 |
WRP1BR | 0xFF00FFFF |
WRP2BR | 0xFF00FFFF |
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.
- 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.