🌡️  Monitor legacy analog systems with TinyML, Edge Impulse, and Blues Wireless. Learn more in our webinar on May 26th!

Search
Documentation Results
End of results
Community Results
End of results
Support
Blues.io
Notehub.io
Shop
Sign In
Search
Documentation Results
End of results
Community Results
End of results
Support
Blues.io
Notehub.io
Shop
×
HomeQuickstart
Notecard Quickstart
Swan QuickstartUsing the VS Code PlatformIO ExtensionUsing the STM32CubeIDEUsing the Arduino IDEUsing the VS Code Arduino ExtensionDebugging Arduino with VS CodeUsing CircuitPythonRecover Swan (STM32L4R5)Next Steps
Rate this page  
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★

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:

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

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.

    VS Code PlatformIO Extension

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.

    open platformio extension in vs code

  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.

    platformio project wizard

  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:

    [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 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:

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

    platformio serial monitor

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.

    select `STM32L4R5ZIY6TR`

  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

Linux only setup required for accessing the device in DFU mode and virtual COM port.
  1. 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
  2. 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
  3. Add active user to plugdev group in /etc/group.

    sudo usermod -aG plugdev $USER

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

    Update ArduinoIDE preferences

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

    Select STM32 Board

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

    Select STM32 Board Part

  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:

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

    VS Code Arduino Extension

  5. Install STMCubeIDE and add STM32_Programmer.sh and STM32_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

  6. Install OpenOCD

    Linux:

    sudo apt install openocd

    macOS:

    • Homebrew

      brew install openocd
    • MacPorts

      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.

    Open board dialog in VS Code

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

    Update board config options in VS Code

    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.

    Arduino: Examples is now in the VS Code dropdown

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

    Arduino: Examples menu with Blink highlighted

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

    Upload button in VS Code

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

    Done uploading message in VS Code

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

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.

    VSCode Arduino Launch JSON Bug Workaround

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

    VSCode Arduino Launch JSON Bug

    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:

    "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": []
            }
        ]
    }
  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.

    boot and reset buttons on swan

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

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.

  1. Install the CircuitPython extension from the Extensions menu in VS Code.

  2. 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
  3. Add the following item to the JSON object:

    "vid": "0x30a4", "pid": "0x0002", "product": "Swan R5", "manufacturer": "Blues Wireless",
  4. In that same directory, create the following directories and file:

    0x30A4/0x0002/board.pyi
  5. 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."""
  6. Open the CIRCUITPY drive with a new VS Code window. Click the Choose a board option in the bottom Status Bar.

  7. In the provided dialog, search for "Swan" and select the "Blues Wireless:Swan R5" option.

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.

    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

RegisterValue
OPTR0x08000000
PCROP1SR0xFFFE0000
PCROP1ER0xFFFE0000
WRP1AR0xFF00FF00
WRP2AR0xFF00FF00
PCROP2SR0xFFFFFFFF
PCROP2ER0xFFFF0000
WRP1BR0xFF00FFFF
WRP2BR0xFF00FFFF

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:

STM32CubeProgrammer REG Menu

FLASH Registers

RegisterValue
OPTR0xFFEF98AA
PCROP1SR0xFFFFFFFF
PCROP1ER0xFFFF0000
WRP1AR0xFF00FFFF
WRP2AR0xFF00FFFF
PCROP2SR0xFFFFFFFF
PCROP2ER0xFFFF0000
WRP1BR0xFF00FFFF
WRP2BR0xFF00FFFF

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.

Can we improve this page? Send us feedbackRate this page
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
© 2022 Blues Inc.Terms & ConditionsPrivacy
blues.ioTwitterLinkedInGitHubHackster.io
Disconnected
Disconnected
Having trouble connecting?

Try changing your Micro USB cable as some cables do not support transferring data. If that does not solve your problem, contact us at support@blues.com and we will get you set up with another tool to communicate with the Notecard.

Connect a NotecardClick 'Connect' and select a USB-connected Notecard to start issuing requests from the browser.