Developer World Spresense
日本語 中文
Table of Contents

1. Introduction

This chapter explains the installation and setup procedures for developing Spresense SDK applications on Visual Studio Code (hereafter called as VS Code) provided by Microsoft. And also explains how to create a simple sample application. You can learn the basic usage of Spresense SDK using VS Code.

1.1. Function restrictions by user name and folder name

Depending on the user name or folder name, there are restrictions on the functions described in the table below.

Characters included in folders and user names

Toolchain setup

Build configuration

Build the project

Serial monitor

Debugging the main core with ICE

Consisting only of alphanumeric characters.(e.g. SonyTaro)

〇

〇

〇

〇

〇

Includes space character.(e.g. Sony Taro)

×

×

×

〇

×

2. Development environment

You can develop Spresense SDK on Linux/Windows/macOS. Please setup development environment for your appropriate OS.

Supported Operation System

  • Linux (64bit)

    • Ubuntu 16.04 or later

  • Windows

    • 8.1/10

  • macOS

    • High Sierra (10.13) or later

2.1. Setup for Linux

  1. Serial Configuration

    Add user to dialout group

    sudo usermod -a -G dialout <user-name>

    Please logout and login after running the above command.

  2. Install development tools

    wget https://raw.githubusercontent.com/sonydevworld/spresense/master/install-tools.sh
bash install-tools.sh

    If you run wget command via proxy server, set your proxy server as below.

    export https_proxy=http://<your proxy server>:<port number>

    And run this command to activate installed tools.

    source ~/spresenseenv/setup

    This command must run in every terminal window. If you want to skip this step, please add this command in your ${HOME}/.bashrc.

    The tool chain is installed in spresenseenv/usr/bin under the home directory.

  3. Clone the Spresense SDK with submodule

    git clone --recursive https://github.com/sonydevworld/spresense.git

2.2. Setup for Windows

  1. Install MSYS2

    https://www.msys2.org/

  2. Install development tools

    Run MSYS2 MSYS from start menu, and run following commands.

    MSYS2 MinGW 64-bit and MSYS2 MinGW 32-bit is not supported. Please use MSYS2 MSYS. 
    curl -L https://raw.githubusercontent.com/sonydevworld/spresense/master/install-tools.sh > install-tools.sh
bash install-tools.sh

    If you run curl command via proxy server, set your proxy server as below.

    export https_proxy=http://<your proxy server>:<port number>

    And run this command to activate installed tools.

    source ~/spresenseenv/setup

    This command must run in every terminal window. If you want to skip this step, please add this command in your ${HOME}/.bashrc.

    The tool chain is installed in /opt/spresenseenv/usr/bin.

  3. Clone the Spresense SDK with submodule

    git clone --recursive https://github.com/sonydevworld/spresense.git

  4. Install USB serial driver

    User must install before connecting Spresense board to the PC.

    Please download and install from below.

2.3. Setup for macOS

  1. Install development tools provided by Apple

    Open the Teminal and run following command.

    xcode-select --install

  2. Install Python3

    Python.org

  3. Install development tools

    curl -L https://raw.githubusercontent.com/sonydevworld/spresense/master/install-tools.sh > install-tools.sh
bash install-tools.sh

    If you run curl command via proxy server, set your proxy server as below.

    export https_proxy=http://<your proxy server>:<port number>

    And run this command to activate installed tools.

    source ~/spresenseenv/setup

    This command must run in every terminal window. If you want to skip this step, please add this command in your ${HOME}/.bash_profile.

    The tool chain is installed in spresenseenv/usr/bin under the home directory.

  4. Clone the Spresense SDK with submodule

    git clone --recursive https://github.com/sonydevworld/spresense.git

  5. Install USB serial driver

    User must install before connecting Spresense board to the PC.

    Please download and install from below.

    CP210x USB to serial driver for Macintosh OSX

    On High Sierra (10.13) and later, the installation of the driver may be blocked. Please allow this driver from System Preferences Security & Privacy pane. See Apple Technical Note TN2459 "User-Approved Kernel Extension Loading" for more information.

3. Preparing the debugger (For ICE debugging)

3.1. Hardware

3.2. Mounting the SWD connector

Refer to the hardware documentation for how to mount the SWD connector.

3.3. OpenOCD settings (Ubuntu only)

In the case of Ubuntu, it is necessary to grant the authority to connect to ICE with the following command. Please do it before connecting ICE

sudo cp ~/spresenseenv/usr/contrib/60-openocd.rules /etc/udev/rules.d/
sudo udevadm control --reload

4. Install IDE

Install the Spresense SDK application development environment using the following procedure. As a result, a series of development environment from project creation to debugging is prepared on VS Code.

Please download the necessary tools and Spresense SDK after referring to Development environment in advance.

4.1. Installation of VSCode

  1. Download the VSCode installer from the following site.

    https://code.visualstudio.com/

  2. Run the downloaded installer

    • For Windows

      1. Start the installer (VSCodeUserSetup.exe).

      2. Proceed with installation according to the dialog.

    • For macOS

      1. Unzip the installation file (VSCode-darwin-stable.zip).

      2. Move the unzipped Visual Studio Code to the application.

    • For Ubuntu

      1. Install from the downloaded file (code_1.37.1-xxx.deb) with the following command.

        $ sudo dpkg -i code_1.37.1-xxx.deb

  3. Launch the installed VS Code

    vscode vscode installed en

4.2. Installing the Spresense extension

If you have installed the Spresense Extension α version , please uninstall it. If you do not uninstall, the Spresense extension will not work properly.

  1. Search Spresense on the extension screen.

  2. Spresense VSCode IDE will appear in the list and click on it.

  3. Click Install button on the details displayed on the right side of the window.

    vscode spresense install en

  4. The installation is complete when the message Installation is complete appears as shown in the screen below.

    vscode spresense installed en
    The Spresense VSCode IDE will automatically install these extensions for use with C/C++ for Visual Studio Code and Cortex Debug.

4.2.1. Setting Msys2 Installation Path (Windows only)

In this section, we will set the MSYS2 on VS Code.

  1. Press F1 to display the command palette.

  2. Input spresense msys to filtering commands, and select MSYS2 path(Windows only): Location for Msys install path.

    vscode msys2 search en

  3. When the folder selection screen appears, select the MSYS2 path and click Open.

    vscode msys2 folder en

  4. This completes the environment for developing Spresense applications on VS Code.

5. Create application project

The environment for developing applications using the steps in the previous sections is now ready. This section explains how to actually create on VS Code.

5.1. About the workspace

The workspace is a VS Code function that allows you to manage and share common settings on a single window by combining arbitrary folders.

Also, the folders included in the workspace have a hierarchical relationship, and you can change this hierarchical relationship by moving the folders in the order in which they were added or in the window.

The Spresense VSCode IDE uses a workspace function to provide an environment for application development by combining the Spresense SDK and application projects.

The workspace in Spresense VSCode IDE is as shown below

  1. Spresense SDK folder

  2. Project A folder

  3. Project B folder

  4. Project C folder

The project folder contains the following application programs to be developed.

  • Application commands

    Commands that can be used on the NuttShell console. You can add original commands by creating this program.

  • ASMP worker program

    A program that uses the multi-core feature of Spresense. By creating this program and using it from the above application commands, you can add multi-core applications.

vscode workspace overview en

5.2. Creating a workspace

The workspace described in the previous section can be created using the following procedure.

  1. Click Open folder

    vscode workspace open folder en
    Can also open the folder by selecting window menu File → Open Folder…​.

  2. Specify the location of the downloaded Spresense SDK folder and click Open

    vscode workspace open sdk en

  3. Choose Add Folder to Workspace from File.

    vscode workspace add folder en

  4. Navigate to where you want to create the project folder and create a folder for the project.

  5. Select the created folder and click Add.

    vscode workspace add project folder en

  6. After selecting project folder, Spresense VSCode IDE will setup project folder.

  7. If Spresense setup: Setup complete. is displayed, setup is complete.

    vscode workspace setup en

  8. You can save the created workspace by selecting Save Workspace As from File.

    vscode workspace save en

  9. Choose New Terminal from Terminal.

    vscode terminal open en

  10. Choose working foldder from dialog with message Select current working directory for new terminal(Both will give the same result.).

    vscode terminal select en

  11. Click Allow on the dialog that appears Do you allow this workspace to modify your terminal shell?.

    vscode shell approve en
    If you do not select Allow in this dialog, Spresense VSCode IDE functions such as build and serial terminal display will not work properly.

The workspace has been created.

5.3. Adding application commands

This section describes how to add a program for application commands to the created project folder.

Application commands are NuttShell commands that run on Spresense. If the application command name is gps_watch, the following commands can be used.

NuttShell (NSH) NuttX-7.22
nsh> gps_watch
<<Out put logs while executing command>>

Let’s take a look at how to add it.

  1. Right click on the project folder.

    vscode tree menu open en

  2. Select Spresense: Create application command from the menu.

    vscode tree application command open en

  3. A dialog for entering the application command name will appear. Enter the name of the command you want to add and type the key ENTER.

    vscode tree application command name en

  4. If the program file has been added as shown below, the process is complete. (Ex. name is gps_watch)

    vscode tree application command finished en

5.3.1. About added files

File(Folder)

Content

gps_watch

Folder containing the command program

gps_watch_main.c

Main source code for command program

Make.defs

Makefile for building commands

Makefile

Makefile for building commands

Application.mk

Files that make commands in the project folder available to Spresense

LibTarget.mk

File to archive the program

Make.defs

Makefile for building the entire project

Makefile

Makefile for building the entire project

5.4. Adding ASMP worker program

This section explains how to add a program for ASMP worker to the created project folder. An ASMP worker is a sub-core program in a multi-core program.

  1. Right click on the project folder.

  2. Select Spresense: Create ASMP worker program from the menu.

    vscode tree asmp worker open en

  3. In the ASMP worker name dialog box that appears, enter the name of the ASMP worker you want to create and type ENTER.

    ASMPワーカー名を入力

  4. Click Yes to create a sample application if you want to creata on a dialog Do you want to create a sample application to use new worker?.

    vscode tree asmp create app en

  5. If the program file has been added as shown below, the process is complete. ( This is an example when the worker name is set hello and Yes to create a sample application.)

    vscode tree asmp finished en

5.4.1. About added files

File(Folder)

Content

hello_worker

Folder containing worker program

hello_worker.c

Worker main source file

Makefile

Makefile for building workers

include

Header file folder shared with main core application

hello

Folder containing sample application for workers

6. Build configuration

In the previous section, we added applications and ASMP workers to the project folder. In order to build these programs properly, it is necessary to configure the build according to the function.

This section describes the configuration required for build and the procedure.

First, the build configuration is divided into two parts.

  • Kernel configuration

    This is the configuration of NuttX a Realtime OS used in Spresense SDK . Configure OS level settings for programs that run on Spresense.

    For normal use, save with the default settings.

  • SDK configuration

    Configuration of features specific to Spresense SDK. Audio, camera, GPS, and other features that run on Spresense are configured here. You can also configure the Examples application and system tools here.

Keyword completion and parsing syntax functions provided by Microsoft’s C/C++ extension will not work correctly unless this configuration is complete. Be sure to complete the configuration before creating the program.

The functions of the configuration save menu are as follows.

Menu

Function

New

You can select a preset configuration provided by Spresense SDK.

Save

Save the build configuration with the set contents.

Load

Open the saved backup configuration file.

Save as

Save the settings to any location. Since it is saved separately from the configuration file used for the build, it is not reflected in the build.

6.1. Kernel configuration

  1. Type a key F1 to display the command palette.

    vscode command palette en

  2. Enter the filter word spresense kernel config to narrow down the command.

  3. Choose Spresense: Kernel config.

    vscode kernel config select en

  4. Select the project to be configured.

    vscode kernel config folder en
    If another 'Kernel config' or 'SDK config' is already open, please close it beforehand. Only one config window can be open at a time.

  5. Wait for showing configuration items.

    vscode kernel config prepare en
    vscode kernel config view en

  6. Make the necessary settings and click Save.

  7. Configuration has been saved. is displayed, kernel configuration is complete.

    It may take some time to save depending on the environment. Please wait for a completion message.
    vscode kernel config save en

  8. Close the configuration.

6.2. SDK configuration

  1. Type a key F1 to display the command palette.

    vscode command palette en

  2. Enter the filter word spresense sdk config to narrow down the command.

  3. Choose Spresense: SDK config.

    vscode sdk config select en

  4. Select the project to be configured.

    vscode sdk config folder en
    If another 'Kernel config' or 'SDK config' is already open, please close it beforehand. Only one config window can be open at a time.

  5. Wait for showing configuration items.

    vscode sdk config prepare en
    vscode sdk config view en

  6. Click New to open the New Configuration menu.

    vscode sdk config new en
    vscode sdk config new open en

  7. Select the required preset configration for device and function and click OK.

    vscode sdk config new select en

  8. Make the necessary settings and click Save.

  9. Configuration has been saved. is displayed, SDK configuration is complete.

    It may take some time to save depending on the environment. Please wait for a completion message.
    vscode sdk config save en

7. Update source codes and create new files

In the previous section, configuration such as setting of functions used in the application was performed.

This section explains how to update the program of the actually created project and how to add program files.

7.1. Updating program files

  1. Press the Explorer button to display the project file list.

    vscode editor view en

  2. Double-click the file you want to edit.

    vscode editor open en

  3. Write the code you want to add on the opened file.

    vscode editor editing en
    vscode editor edited en
The keyword completion list is displayed by the C/C++ extension. This keyword completion list is displayed based on the configuration set in the previous section. Even when it is not displayed, it can be displayed by typing a key Ctrl + Space(may be assigned to another key depending on the environment. For details, see Keyboard shortcuts).
If the keyword completion list is not displayed correctly, the C/C++ extension database may not have been created correctly. In that case, please run the command C/C++: Rescan Workspace and C/C++: Reset IntelliSense Database.

7.2. Adding program files

  1. Right-click on the folder you want to add.

  2. Choose New File from menu.

    vscode editor new file en

  3. Enter the file name.

    vscode editor new file creaed en
It is automatically included in the build target by adding .c and .cxx files.

8. Build the project

Up to the previous section, you have created a project, added a program, and configured it.

This section explains how to build the created program into a binary that can be flash into Spresense.

Like the configuration, the build consists of two parts.

  • Kernel build

    Build the NuttX kernel of Spresense SDK. Since various functions are included, it takes considerable time. (Depending on your environment, it may take over ten minutes.)

    There is no need to build again unless you change the kernel configuration or source code.

  • Application build

    Build Spresense-specific functions provided by Spresense SDK and create nuttx.spk file. If you have added ASMP workers, it will be built in this step.

8.1. Build the kernel

  1. Right click on the project folder you want to build.

    vscode build kernel menu open en

  2. Click Spresense: Kernel build.

    vscode build kernel menu select en

  3. Wait until the kernel build is complete.

    vscode build kernel start en

  4. If the task completes normally as shown below, the kernel build is complete.

    vscode build kernel finished en

8.2. Building the application

  1. Right click on the project folder you want to build.

    vscode build apps menu open en

  2. Click Spresense: Application build.

    vscode build apps menu select en

  3. The application build will start, so wait for it to complete.

    vscode build apps start en

  4. If the task is completed normally as shown below, the application build is complete.

    vscode build apps finished en

9. Flashing the application into Spresense board and Check operation

In the previous sections, we explained everything from creating a project to creating a binary that is flashing into Spresense.

This section describes the procedure from flashing the actually created binary to Spresense to checking the operation.

9.1. Setting the serial port

  1. Connect the PC and Spresense via USB.

  2. Type a F1 key to display the command palette.

    vscode serial port menu open en

  3. Input spresense serial port to narrow down the command.

  4. Choose Spresense: Serial port selection.

    vscode serial port menu select en

  5. Choose serial port for Spresense from list.

    vscode serial port select en

9.2. Installing the boot loader

To use the functions of Spresense and Spresense VSCode IDE, you need to install the latest boot loader. Otherwise, Spresense and Spresense VSCode IDE will not work properly.

This section explains the boot loader installation procedure.

Install the boot loader the first time you use it or when the SDK version is updated.

  1. Type a F1 key to display the command palette.

    vscode bootloader open en

  2. Input spresense bootloader to narrow down the command and choose Spresense: Flash bootloader.

    vscode bootloader select en

  3. Click OK on dialog that showing the message To install the bootloader, you must download the bootloader archive with a web browser…​..

    Download the boot loader from the web site.
    vscode bootloader web confirm en

  4. As the web browser opens, download according to the instructions on the page.

    vscode bootloader webpage1 en
    vscode bootloader webpage2 en

  5. Click on the dialog box to confirm the continuation of the installation.

    vscode bootloader zip confirm en

  6. In the file dialog that appears, select the downloaded ZIP file.

    vscode bootloader zip open en

  7. After selecting the ZIP file, the boot loader installation will begin.

    vscode bootloader flash start en

  8. If the task is completed normally as shown below, the installation of the boot loader is complete.

    vscode bootloader flash finished en

9.3. Flashing build binaries

  1. Right click on the project folder you want to build.

    vscode flash open en

  2. Click Spresense: Build and Flash.

    vscode flash select en

  3. The application build will start and wait for completion.

    vscode flash build en
    You can also skip the previous section’s command Spresense: Application build by using this command.

  4. As soon as the build is over, flashing to Spresense will start.

    vscode flash start en
    If you are creating an ASMP worker, it will be written at this time.

  5. After flashing to Spresense, the serial terminal will open.

    vscode serial terminal open en

9.4. Operation check

  1. Enter the command name created on the open serial terminal and type the Enter key.

  2. The command execution result is displayed.

    vscode serial terminal hello en
    vscode serial terminal asmp en

10. Debugging the main core with ICE

In the previous section, the built binary was flashing to Spresense’s Flash memory to check operation.

This section explains how to load the built binary directly into Spresense SRAM and check (debug) the operation.

You can debug by setting a break at a specified location and stopping the program at the specified location, or by writing a Watch statement and stopping at the specified condition.

Pleasae check Preparing the debugger (For ICE debugging) to connect ICE debugger, in advance.

10.1. Setting Break points

  1. Open the source code where you want to set the Break point (eg: if you want to set it on the 6th line).

    vscode debug break point en

  2. Click the left edge of the line you want to set (next to the left of the line number) and mark it red.

    vscode debug break point set en

This completes the setting of the Break point.

10.2. Starting Debug

  1. Click the debug icon from the icon on the left of the window.

    vscode debug open en

  2. elect the debug menu for the created project from the debug configuration list.

    vscode debug select en

  3. Click the Start debugging button.

    vscode debug start button en

  4. Wait for the completion of the debugging process.

    vscode debug prepare en

  5. When the debug control button icon changes as shown below, the preparation is complete.

    vscode debug started en
    At the start of debugging __start(void), a Break is performed.

  6. Click Continue on the icon above and Spresense will start running.

    vscode debug executed en

  7. When processing that passes through the set break point (eg: command execution), the break will occur at the set point.

    vscode debug breaking en

  8. Click Continue button again to release from Break.

    vscode debug continue en

11. Troubleshooting

This section explains the problems that may occur when using VS Code and how to deal with them by category. See here if the VS Code does not work well.

11.1. Setup

11.1.1. Terminal does not open correctly (Windows)

In Windows environment, VS Code uses MSYS2 bash as a terminal. If this bash does not open and PowerShell or cmd (command prompt) opens as shown in the following figure, the terminal settings of the workspace may not be reflected correctly. In that case, try the following steps:

  • Allow terminal shell changes

    For Visual Studio Code Version 1.37.1 or earlier

    1. Press F1 to open the command palette.

    2. Type terminal allow to narrow down the command and select Terminal: Allow to Workspace Shell Configuration.

    For Visual Studio Code Version 1.38.0 or later

    1. Press F1 to open the command palette.

    2. Type terminal manage to narrow down the command and select Terminal: Manage Workspace Shell Permissions.

    3. Select Allow Workspace Shell Configuration from list.

  • Reopen the workspace

    1. Select File → Close Workspace from window menu.

    2. Select File → Open Workspace…​ from window menu.

    3. Open the saved workspace file.

    4. Waiting to display Spresense setup: Setup complete.

11.2. Build a project

11.2.1. Build does not progress

If the build does not proceed, the load on your PC may have increased, or there may be a problem with the terminal settings. Check the terminal status by following the steps below.

  1. Select Terminal → New Terminal from window menu.

  2. Run the`echo ${SHELL}` command on the terminal opened in the previous step.

  3. If the result is not /bin/bash or /usr/bin/bash, perform the Terminal does not open correctly (Windows).