Sparrow Builder's Guide

In this guide you'll learn how to go beyond the basics, and build custom solutions on top of the Sparrow architecture.

The easiest place to start building is by running the Sparrow Reference Firmware. The reference firmware is open-source, and allows you to tweak your devices' behavior, as well as make entirely new sensors work in your Sparrow systems.

Let's look at how to download, flash, and debug the reference firmware.

Installing Firmware Prerequisites

All the different Sparrow configurations run off the same firmware, which is open source and available on GitHub in the Sparrow Reference Firmware repository .

To start, you'll first need to clone the firmware's repository (making sure to include the --recursive flag).

git clone https://github.com/blues/sparrow-reference-firmware.git --recursive

From there you must additionally install a series of prerequisites.

Option 1: Docker Container (Linux only)

The Sparrow Reference Firmware repository contains a Docker container that includes all of the firmware's prerequisites.

To use the Docker container you must have both Docker, and the the Visual Studio Code “Remote - Containers” installed.

Why is the Docker container only available on Linux?

The Sparrow Reference Firmware's Docker container can compile firmware on Windows, macOS, and Linux.

However, the container only has USB access on Linux, and therefore you can only flash and debug firmware over USB on Linux.

Option 2: Native Installation

To build, flash, and debug the Sparrow Reference Firmware on your development machine locally you'll need to have the following tools natively installed.

Additionally, if you intend to use Visual Studio Code to build and flash firmware (recommended), you must install the following.

With all of these tools installed, next ensure all tools and libraries are in your system path. This may be necessary of all tools, but is especially important for ST-LINK_gdbserver and its shared library dependency, libSTLinkUSBDriver.so (or platform-specific equivalent). You can use the code below to add those libraries to your system path.

Linux:

export PATH=/opt/st/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.9-2020-q2-update.linux64_2.0.0.202105311346/tools/bin:${PATH}
export PATH=/opt/st/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.linux64_2.0.100.202110141430/tools/bin:${PATH}
export PATH=/opt/st/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.100.202109301221/tools/bin:${PATH}
export LD_LIBRARY_PATH=/opt/st/stm32cubeide_1.8.0/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.linux64_2.0.100.202109301221/tools/bin/native/linux_x64:${LD_LIBRARY_PATH}

macOS (set in your ~/.bashrc file or whatever terminal you prefer):

export PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.9-2020-q2-update.macos64_2.0.0.202105311346/tools/bin:$PATH"export PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.9-2020-q2-update.macos64_2.0.0.202105311346/tools/bin:$PATH"
export PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.cubeprogrammer.macos64_2.0.100.202110141430/tools/bin:$PATH"
export PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.macos64_2.0.100.2109301221/tools/bin:$PATH”
export DYLD_LIBRARY_PATH="/Applications/STM32CubeIDE.app/Contents/Eclipse/plugins/com.st.stm32cube.ide.mcu.externaltools.stlink-gdb-server.macos64_2.0.100.202109301221/tools/bin/native/mac_x64:$DYLD_LIBRARY_PATH”

Building, Flashing, and Debugging Firmware

Now that you have the prerequisites in place, let's next look at how you can build, flash, and debug the Sparrow Reference Firmware.

note

Make sure to connect your Sparrow board to your computer via the STLINK-V3MINI using a USB cable before continuing.

Option 1: Visual Studio Code (Recommended)

The easiest way to build, flash, and debug the Sparrow Reference Firmware is within Visual Studio Code.

As a first step, open the sparrow-reference-firmware repository you cloned within the Visual Studio Code editor.

note

If you're on Linux and using the firmware's Docker container, make sure to open the firmware project in its container.

Be sure to attach your Sparrow device to your machine before you launch the development environment, so /dev/bus/usb can be captured by the container.

You can open the firmware project in its container by first clicking the small green box in the lower-left corner of the Visual Studio Code window.

Location of the green button

Next, select “Reopen in Container” from the drop-down menu.

Location of the container menu option

Building

Hotkey: Ctrl + Shift + B (Cmd + Shift + B on macOS)

  1. In the Visual Studio menu (top of screen), click Terminal > Run Build Task...

Flashing

  1. In the Visual Studio menu (top of screen), click Terminal > Run Task...

  2. Next, Sparrow: Flash Firmware Using STM32_Programmer_CLI.

Debugging

Hotkey: Ctrl + Shift + D (Cmd + Shift + D on macOS), or F5.

  1. Within Visual Studio select the Run and Debug menu from the leftmost toolbar.

  2. Press the green “Play” button next to Cortex Debug.

Location of debugging in VS Code

Option 2: STM32CubeIDE

You can also build, flash, and debug Sparrow firmware within STM32CubeIDE. To start, you'll need to open the firmware in the IDE with the following steps.

  1. Open the STM32CubeIDE application.

  2. Navigate to File > Open Projects from File System...

Loading a project in STM32CubeIDE

  1. Press the Directory... button.

  2. Open the hidden folder, .STM32CubeIDE, from your newly cloned firmware repository. (On macOS you may need to type Cmd + Shift + . within the dialog to see hidden files and folders.)

  3. Press the Finish button.

Building

  1. Select the sparrow project in the Project Explorer on the left-side of the IDE.

  2. Click the hammer icon in the toolbar to build “Debug” for project sparrow.

Location of the hammer icon in STM32CubeIDE

Flashing

Before you can install binaries you must first specify a Run Configuration by following the steps below.

  1. Select Run > Run Configurations... from the menu.

  2. From the Run Configurations dialog select STM32 Cortex-M C/C++ Application > sparrow Debug.

  3. All the default values should be correct, so next press the Run button.

Run configuration display in STM32CubeIDE

Once you have specified a Run Configuration, you can then use perform subsequent runs directly from the toolbar. To do so complete the following steps.

  1. Select the sparrow project in the Project Explorer on the left-side of the IDE.

  2. Click the green play icon in the toolbar to debug project sparrow.

Location of the play icon in STM32CubeIDE

Debugging

  1. Select the sparrow project in the Project Explorer on the left-side of the IDE.

  2. Click the bug icon in the toolbar to debug project sparrow.

Location of the bug icon in STM32CubeIDE

Collecting Firmware Logs

If you connect an STLINK-V3MINI to your device, you can use a terminal emulator to view the debugging output on the serial port that appears on your computer.

Connect your computer to your STLINK-V3MINI using a USB A-to-Micro, then connect the STLINK-V3MINI to your device using the Cortex debug connector.

You can use the following settings to configure your logging terminal.

Terminal settings to use

Writing Custom Firmware

Now that you've set everything up, you're ready to start writing custom Sparrow firmware.

For details on next steps, including how to write custom Sparrow applications, check out the Reference Firmware's README on GitHub .

And if you have any questions about what you can do next, feel free to reach out in our community forum .