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.

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

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

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.

   

   warning

   Version 0.4.6 of the official Arduino extension contains major bugs that stop many Arduino features from working. If you’re experiencing problems with the extension, try downgrading to version 0.4.4.

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!

Additional Information

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