Rate this page
- ★★
- ★★
- ★★
- ★★
- ★★
Can we improve this page? Send us feedbackRate this page
- ★★
- ★★
- ★★
- ★★
- ★★
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.
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.
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.
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.
To build, flash, and debug the Sparrow Reference Firmware on your development machine locally you’ll need to have the following tools natively installed.
CMake (must be v3.14 or greater)
Make
A terminal Program (choose one)
(OPTIONAL) GNU ARM toolchain (also packaged with STM32CubeIDE)
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”
Now that you have the prerequisites in place, let’s next look at how you can build, flash, and debug the Sparrow Reference Firmware.
Make sure to connect your Sparrow board to your computer via USB before continuing.
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.
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.
Next, select “Reopen in Container” from the drop-down menu.
Hotkey: Ctrl
+ Shift
+ B
(Cmd
+ Shift
+ B
on macOS)
In the Visual Studio menu (top of screen), click Terminal > Run Task...
Next, Sparrow: Flash Firmware Using STM32_Programmer_CLI.
Hotkey: Ctrl
+ Shift
+ D
(Cmd
+ Shift
+ D
on macOS), or F5
.
Within Visual Studio select the Run and Debug menu from the leftmost toolbar.
Press the green “Play” button next to Cortex Debug.
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.
Open the STM32CubeIDE application.
Navigate to File > Open Projects from File System...
Press the Directory... button.
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.)
Press the Finish button.
Select the sparrow project in the Project Explorer on the left-side of the IDE.
Click the hammer icon in the toolbar to build “Debug” for project sparrow.
Before you can install binaries you must first specify a Run Configuration by following the steps below.
Select Run > Run Configurations... from the menu.
From the Run Configurations dialog select STM32 Cortex-M C/C++ Application > sparrow Debug.
All the default values should be correct, so next press the Run button.
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.
Select the sparrow project in the Project Explorer on the left-side of the IDE.
Click the green play icon in the toolbar to debug project sparrow.
Select the sparrow project in the Project Explorer on the left-side of the IDE.
Click the bug icon in the toolbar to debug project sparrow.
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.
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.