Getting Started

This section describes how to install the SPARK Software Development Kit (SDK) virtual environment on a user’s personal computer. Virtual environments are isolated environments that use specific versions of software packages without affecting the rest of the system. They work by creating a separate directory where all the necessary files for the environment are installed. The specific virtual environment is activated by modifying the system’s PATH variable to point to that directory so that commands are executed using the packages installed there rather than the system’s default packages.

The SPARK SDK development environment dependencies are all contained within this virtual environment and can be easily bootstrapped by running a single script.

After following the steps outlined below to install and set up the virtual environment, the user will be ready to start building their own applications. Let’s get started!

Preferred Integrated Development Environment (IDE)

SPARK’s SDK is designed to work with Visual Studio Code (VS Code). This IDE is used internally and can be considered as tested and supported. Other IDEs or source code editors can be utilized provided that they support CMake and micromamba virtual environments.

The use of CMake files and the micromamba virtual environment allows for a more flexible and scalable development process and enables users to access a variety of tools and platforms to build and develop applications using the SPARK SDK.

Warning

Users of a different source code editor or IDE assume the responsibilities of ensuring that it supports CMake and that the necessary plugins or extensions are installed. They will also need to set up a virtual environment using micromamba which is required for building and running applications with the SDK.

Prerequisites

VS Code Extensions

To use the SPARK SDK and its virtual environment with VS Code, certain VS Code extensions need to be installed.

Follow these steps to install the recommended VS Code extensions:

  1. Open the VS Code command palette by pressing Ctrl+Shift+P.

  2. Type Extensions: Show Recommended Extensions and select it from the list.

  3. Install all Workspace Recommendations.

  4. Reload the window by pressing Ctrl+Shift+P and selecting Developer: Reload Window.

Hardware

The example applications provided with the SPARK SDK are written specifically for the SPARK Evaluation Kit (EVK) boards. This means that to run these applications, the user will need at least two EVKs and one ST-Link debug probe (for debugging).

If access to two EVKs is not possible, the user may still use the example applications as a reference for building their own applications. The code will need to be modified for specific hardware configurations, but the overall structure and functionality of the applications are still useful starting points.

In any case, it is recommended to carefully review the documentation and code provided with the SPARK SDK to ensure a clear understanding of how the example applications work and how to adapt them for specific needs.

Windows Long Path Support

The SPARK Virtual Environment requires Windows Long Path support to be enabled. The bootstrap script will attempt to enable this feature automatically, but in some cases, manual intervention may be required. If an error is encountered during the bootstrap process, follow these steps to enable Windows Long Path support. There are two ways to enable long path support in Windows: through Group Policy or the Windows Registry.

Warning

To avoid potential issues with Windows’ maximum path length restriction, it is recommended to unzip the package as close to the root directory as possible. Extracting the files too deeply nested may result in errors.

Through Group Policy

  1. Open the Local Group Policy Editor by typing gpedit.msc in the Start Menu.

  2. Navigate to Computer Configuration\Administrative Templates\System\Filesystem.

  3. Find the setting for Enable Win32 long paths.

  4. Double-click on Enable Win32 long paths to open it.

  5. Choose the Enabled option and apply the changes.

  6. Restart the computer or update the Group Policy by executing gpupdate /force in the command prompt.

Through Windows Registry

During the bootstrap script execution, the Windows Registry key will be checked, and if necessary, the user will be prompted to perform this step automatically. However, if manual intervention is needed or the bootstrap script fails to enable the Windows Registry key, follow these steps.

  1. Open the Registry Editor by typing regedit.msc in the Start Menu.

  2. Navigate to Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem.

  3. Find the LongPathsEnabled registry key and double-click on it.

  4. Change the Value Data to 1.

  5. Exit the Registry Editor

Create the Virtual Environment with VS Code

To initiate the virtual environment and download all dependencies, it’s necessary to create it once by running the VS Code task Create SPARK Environment.

Follow these steps to execute the task:

  1. Open the VS Code command palette by pressing Ctrl+Shift+P.

  2. Type Tasks: Run Task and press Enter.

  3. Select the task Create SPARK Environment.

    Bootstrapping the SPARK Virtual Environment.

    Figure 1: Bootstrapping the SPARK Virtual Environment.

The user should now be able to select an application for compilation and any terminal opened within VS Code will have the environment automatically activated.

Note

If the virtual environment fails to activate after running the VS Code task, follow these steps to manually activate it using the micromamba extension:

  1. Reload the window by pressing Ctrl+Shift+P and selecting Developer: Reload Window.

  2. Open the VS Code command palette by pressing Ctrl+Shift+P.

  3. Search for Micromamba: activate environment and choose it from the list.

  4. Reload the window once more by pressing Ctrl+Shift+P and selecting Developer: Reload Window.

Attention

If an error occurs during the process, it might be required to manually enable Windows Long Path Support.

Bootstrap the Virtual Environment Manually (optional)

In the event that creating the virtual environment outside VS Code is necessary, follow these steps depending on the operating system.

  1. Open a Command Prompt or PowerShell in the project’s root directory.

  2. Run the bootstrap script by typing:

    $ .\script\bootstrap.bat

  1. Open a terminal in the project’s root directory.

  2. If not already installed, install the curl command-line tool using your Linux distribution’s package manager.

  3. Run the bootstrap script by typing:

    $ source ./script/bootstrap.sh
Bootstrapping the SPARK Virtual Environment.

Figure 2: Bootstrapping the SPARK Virtual Environment.

Activate the Virtual Environment Without VS Code (optional)

There might be cases where activating the environment outside of VS Code is necessary. Follow these steps depending on the operating system.

Using Command Prompt

  1. Open a Command Prompt in the project’s root directory.

  2. Execute the activation script by typing:

    $ .\script\activate.bat

Using PowerShell

  1. Open PowerShell in the project’s root directory.

  2. Execute the activation script by typing:

    $ .\script\activate.ps1

At this point, the virtual environment is activated in the current terminal session.

  1. Open a terminal in the project’s root directory.

  2. Execute the activation script by typing:

    $ source ./script/activate.sh

At this point, the virtual environment is activated in the current terminal session.

Building Applications

With the SPARK Virtual Environment created, the next step is to build the applications. Follow these steps.

  1. Open the VS Code command palette by pressing Ctrl+Shift+P.

  2. Type CMake: Select Configure Preset and press Enter.

  3. Select the desired preset.

  4. Open the VS Code command palette again and choose CMake: Delete Cache and Reconfigure..

  5. Open the VS Code command pallete a final time and choose CMake: Clean Rebuild.

The applications will build as binaries and the progress can be viewed in the Output terminal.

Viewing the Terminal

Every application features a terminal output that displays important information such as real-time SWC link and application statistics. Live statistics viewed through a terminal emulator allow developers to monitor the behavior and performance of the application during runtime. Once an application is built and flashed on the target device, follow these steps depending on the operating system to view the terminal output.

PuTTY is recommended for Windows users.

  1. Install PuTTY from the official website.

  2. Identify the device’s serial port and open it with PuTTY.

Hint

To help identify the device’s COM port number:

  1. Unplug the device (if already connected).

  2. Open the Device Manager and view the Ports (COM & LPT) device category. Note which devices are already listed.

  3. Plug the device and wait for the Device Manager to refresh the list.

  4. The device and its COM port should be added to the previously viewed list.

Minicom is recommended for Linux users. Here is the procedure for Debian-based distributions:

  1. In a terminal, install Minicom.

    $ sudo apt update
$ sudo apt install minicom

  2. Identify the device’s serial port and run minicom.

    $ sudo dmesg
$ sudo minicom -D /dev/<serial_port>

    Hint

    Superuser privileges are not required to run minicom if appropriate udev rules have been added to grant the necessary permissions to access the devices.

Note

The EVKs use the USB Communication Device Class standard and do not require a particular configuration as opposed to UART for example.

Time to Explore

The user is ready to explore and build new applications or port the example applications onto new hardware. It is recommended to start by reviewing the documentation and code provided with the SPARK SDK as well as by experimenting with the example applications to gain a better understanding of how the platform works.

From there, the user can begin building their own applications using the SPARK SDK or modify the example applications to meet their specific needs.

The possibilities are endless, and we’re excited to see the creations that will emerge from our platform!