---
title: Using PlatformIO with Cygnet
description: Learn about using PlatformIO with Cygnet.
source_url: https://dev.blues.io/feather-mcus/cygnet/using-platformio-with-cygnet/
canonical_url: https://dev.blues.io/feather-mcus/cygnet/using-platformio-with-cygnet/
markdown_url: https://dev.blues.io/feather-mcus/cygnet/using-platformio-with-cygnet.md
---

# Using PlatformIO with Cygnet

Using [PlatformIO](https://platformio.org/) with [VS Code](https://code.visualstudio.com/) is a friction-free way of getting started with Cygnet development due to the relatively few configuration steps required.

## Install Prerequisites

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

```bash
(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.

```bash
(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`.

```bash
sudo usermod -aG plugdev $USER
```

**Using Cygnet with Notecarrier CX**

Notecarrier CX includes an onboard STM32L433 microcontroller (the same MCU used on Blues Cygnet). When programming the Cygnet MCU, set the DIP switch next to the USB-C connector to `HST`. If changing the switch from `NC` to `HST`, fully power down the Notecarrier CX and then power it back on to apply the change.

![dip switch on Notecarrier CX](https://dev.blues.io/images/quickstart/cygnet/cx-dip.jpg?v=9bc4224b)

1. Install [Visual Studio Code](https://code.visualstudio.com/) (if you haven't done so already).

2. Install the [PlatformIO IDE extension](https://marketplace.visualstudio.com/items?itemName=platformio.platformio-ide) via the Extensions menu of VS Code.

   ![VS Code PlatformIO Extension](https://dev.blues.io/images/quickstart/swan/vscode-platformio-extension.png?v=00b6b783)

*Note that all other requirements like STM32duino, OpenOCD, and dfu-util will be installed automatically by PlatformIO when needed!*

## Create a Project

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](https://dev.blues.io/images/quickstart/swan/vscode-platformio-new-project.png?v=15848eb1)

2. In the provided **Project Wizard**, give your project a name, choose the "Blues Cygnet" 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](https://dev.blues.io/images/quickstart/cygnet/vscode-platformio-wizard.png?v=078aefdb)

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](https://docs.platformio.org/en/latest/projectconf/index.html) for complete details.

   To develop on the Cygnet with the Notecard, replace your generated `platform.ini` file with this:

   ```cpp
   [env:blues_cygnet]
   platform = ststm32
   board = blues_cygnet
   upload_protocol = stlink
   framework = arduino
   build_flags = -D PIO_FRAMEWORK_ARDUINO_ENABLE_CDC
   monitor_speed = 115200
   lib_deps =
     Wire
     blues/Blues Wireless Notecard
   ```

   > **Warning:**
   >
   > The above configuration assumes you're connecting to your Cygnet via an STLink programmer like the [STLINK-V3MINI](https://shop.blues.com/products/stlink-v3mini?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link). If you instead intend to program your Cygnet using only a USB cable, you'll need to set your `upload_protocol` to `dfu` and follow these instructions to force the Cygnet to jump into its bootloader:
   >
   > Press and hold the `BOOT` button on the Cygnet, press and release `RESET`, then release `BOOT` every time you want to upload firmware.

## Flash Firmware

To program Cygnet, it is recommended you use a programmer like the [STLINK-V3MINI](https://shop.blues.com/products/stlink-v3mini?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link). However, you may also program Cygnet via a USB cable connected directly from it to your computer.

### Programming Cygnet *with* the STLINK-V3MINI (Recommended)

1. In your `platformio.ini` file, set `upload_protocol` to `stlink`.

2. Plug the STLINK-V3MINI into your computer over USB.

3. Plug the Cygnet into a power source (e.g. a LiPo battery or your computer via USB).

   **NOTE:** If you want to see Serial output from the Cygnet, you need to either use a USB cable as the power source or [customize your sketch](https://dev.blues.io/feather-mcus/serial-logging-with-stlink.md) to use the STLINK-V3MINI for Serial output.

4. Plug the Cortex-Debug connector from the STLINK-V3MINI into the Cygnet.

   ![cygnet to stlink](https://dev.blues.io/images/quickstart/cygnet/cygnet-stlink.jpg?v=f89f4cd9)

5. Skip to the [**Blink the Onboard LED**](#blink-the-onboard-led) instructions below.

### Programming Cygnet *without* the STLINK-V3MINI

1. In your `platformio.ini` file, set `upload_protocol` to `dfu`.

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

   ![cygnet micro usb](https://dev.blues.io/images/quickstart/cygnet/cygnet-usb-c.jpg?v=7732bd57)

3. Press and hold the `BOOT` button on the Cygnet, press and release `RESET`, then release `BOOT` to cause the Cygnet to jump into its bootloader. **IMPORTANT:** This sequence must be performed each time you want to upload new firmware to the Cygnet!

4. Proceed to the **Blink the Onboard LED** instructions below.

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

   ```cpp
   #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 Cygnet.

   > **Warning:**
   >
   > Did your firmware upload fail with a `libusb` error? This is not specific to Cygnet, but rather with programming any STM32 board.
   >
   > **Windows:** Install a generic USB driver that supports `libusb`. Download [Zadig](https://zadig.akeo.ie/) to install "WinUSB" and [consult this article](https://www.hanselman.com/blog/how-to-fix-dfuutil-stm-winusb-zadig-bootloaders-and-other-firmware-flashing-issues-on-windows) for more information.
   >
   > **macOS on Apple Silicon:** The appropriate `libusb` package must be installed for the Apple Silicon architecture:
   >
   > - Install via [MacPorts](https://www.macports.org/) with `port install libusb`
   >
   > - Install via [Homebrew](https://brew.sh/) with `brew install libusb`
   >
   > - Installing ST's [STM32CubeIDE](https://www.st.com/en/development-tools/stm32cubeide.html) should also fix the issue, as it installs `libusb` as part of its setup.

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](https://dev.blues.io/images/quickstart/cygnet/vscode-platformio-serial-monitor.png?v=a01aca43)

## Debugging with PlatformIO

Using a programmer like the [STLINK-V3MINI](https://shop.blues.com/products/stlink-v3mini?utm_source=dev-blues\&utm_medium=web\&utm_campaign=store-link) with PlatformIO allows you to set breakpoints in code and use "step out", "step over", and "step into" commands to debug your firmware while it's actively running on the Cygnet.

1. In your `platformio.ini` file, add a line to set the debugging tool you are using: `debug_tool = stlink`.

2. Set a breakpoint on a line of code by clicking to the left of any line number in your sketch (with code) and adding a red dot. This is a breakpoint where the execution of the program will halt and allow you to debug.

   ![platformio set breakpoint](https://dev.blues.io/images/quickstart/swan/swan-debug-breakpoint.png?v=2cd03d65)

3. Press `F5`, or press the play button in VS Code's "Run and Debug" tab, to compile and deploy the sketch to your Cygnet. The **Debug Console** will open and allow you to step through your code line-by-line, watch variables, and view memory usage.

   ![platformio debug console](https://dev.blues.io/images/quickstart/swan/swan-debug-output.png?v=ab6a1416)