Developer World Spresense
日本語 中文
Table of Contents

1. Introduction

This section describes how to start working with the Spresense SDK via CLI (Command Line Interface).

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 (64bit)

    • 10 (with MSYS2 console)

    • 11 (with WSL2 console)

  • macOS

    • High Sierra (10.13) or later

Does not support 32bit version OS

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 and install-tools.sh via proxy server, set your proxy server as below.

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

    The version of the GNU Arm Embedded Toolchain (compiler) is updated in the SDKv2.3 and SDKv3.0 releases.

    SDK version GNU Arm Toolchain version

    SDKv3.0 or later

    gcc-arm-none-eabi-10.3-2021.10

    SDKv2.3 or later

    gcc-arm-none-eabi-9-2019-q4-major

    SDK v2.2 or earlier

    gcc-arm-none-eabi-7-2018-q2-update

    If you want to reinstall including the new compiler, get the latest version of install-tools.sh and run install-tools.sh with the -r option.

    bash install-tools.sh -r

    If you want to check the compiler version you have already installed, run arm-none-eabi-gcc -v after source ~/spresenseenv/setup. The version information will be displayed on the last line.

    arm-none-eabi-gcc -v
(snip)
gcc version 10.3.1 20210824 (release) (GNU Arm Embedded Toolchain 10.3-2021.10)

    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
    If you want to update a spresense.git repository that is already downloaded by git clone , please refer to How to get specified Spresense SDK version .

2.2. Setup for Windows 10 (for MSYS2)

  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 and install-tools.sh via proxy server, set your proxy server as below.

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

    The version of the GNU Arm Embedded Toolchain (compiler) is updated in the SDKv2.3 and SDKv3.0 releases.

    SDK version GNU Arm Toolchain version

    SDKv3.0 or later

    gcc-arm-none-eabi-10.3-2021.10

    SDKv2.3 or later

    gcc-arm-none-eabi-9-2019-q4-major

    SDK v2.2 or earlier

    gcc-arm-none-eabi-7-2018-q2-update

    If you want to reinstall including the new compiler, get the latest version of install-tools.sh and run install-tools.sh with the -r option.

    bash install-tools.sh -r

    If you want to check the compiler version you have already installed, run arm-none-eabi-gcc -v after source ~/spresenseenv/setup. The version information will be displayed on the last line.

    arm-none-eabi-gcc -v
(snip)
gcc version 10.3.1 20210824 (release) (GNU Arm Embedded Toolchain 10.3-2021.10)

    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
    If you want to update a spresense.git repository that is already downloaded by git clone , please refer to How to get specified Spresense SDK version .

  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 Windows 11 (for WSL2)

  1. Install WSL2

    Install WSL2 according to the following procedure

    1. Open PowerShell console

    2. Run wsl command to install WSL2.

      wsl --install

      The following command can be used to specify the version of Ubuntu to be installed as WSL2. (The following command is an example of installing Ubuntu 20.04.)

      wsl --install -d Ubuntu-20.04

    3. Open the WSL2 console.

      tools wsl2 ubuntu en

    4. When starting up for the first time, you will be asked to create an account as shown below, and enter a user name and password.

      tools wsl2 create account

    5. Once the account is created and the console opens as shown below, WSL2 setup is complete.

      tools wsl2 shell en

  2. Install development tools

    Open the WSL2 console from start menu, and run following commands.

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

    If you run curl command and install-tools.sh via proxy server, set your proxy server as below.

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

    The version of the GNU Arm Embedded Toolchain (compiler) is updated in the SDKv2.3 and SDKv3.0 releases.

    SDK version GNU Arm Toolchain version

    SDKv3.0 or later

    gcc-arm-none-eabi-10.3-2021.10

    SDKv2.3 or later

    gcc-arm-none-eabi-9-2019-q4-major

    SDK v2.2 or earlier

    gcc-arm-none-eabi-7-2018-q2-update

    If you want to reinstall including the new compiler, get the latest version of install-tools.sh and run install-tools.sh with the -r option.

    bash install-tools.sh -r

    If you want to check the compiler version you have already installed, run arm-none-eabi-gcc -v after source ~/spresenseenv/setup. The version information will be displayed on the last line.

    arm-none-eabi-gcc -v
(snip)
gcc version 10.3.1 20210824 (release) (GNU Arm Embedded Toolchain 10.3-2021.10)

    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
    If you want to update a spresense.git repository that is already downloaded by git clone, please refer to How to get specified Spresense SDK version .

  4. Install USB serial driver

    User must install before connecting Spresense board to the PC.

    Please download and install from below.

2.4. 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 wget (Necessary to build some of NuttX application tools)

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
brew install wget

  4. Install flock (Necessary to build for SDKv3.2.0 or later)

    brew tap discoteq/discoteq
brew install flock

  5. 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 and install-tools.sh via proxy server, set your proxy server as below.

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

    The version of the GNU Arm Embedded Toolchain (compiler) is updated in the SDKv2.3 and SDKv3.0 releases.

    SDK version GNU Arm Toolchain version

    SDKv3.0 or later

    gcc-arm-none-eabi-10.3-2021.10

    SDKv2.3 or later

    gcc-arm-none-eabi-9-2019-q4-major

    SDK v2.2 or earlier

    gcc-arm-none-eabi-7-2018-q2-update

    If you want to reinstall including the new compiler, get the latest version of install-tools.sh and run install-tools.sh with the -r option.

    bash install-tools.sh -r

    If you want to check the compiler version you have already installed, run arm-none-eabi-gcc -v after source ~/spresenseenv/setup. The version information will be displayed on the last line.

    arm-none-eabi-gcc -v
(snip)
gcc version 10.3.1 20210824 (release) (GNU Arm Embedded Toolchain 10.3-2021.10)

    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.

  6. Clone the Spresense SDK with submodule

    git clone --recursive https://github.com/sonydevworld/spresense.git
    If you want to update a spresense.git repository that is already downloaded by git clone , please refer to How to get specified Spresense SDK version .

  7. 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. Example application of "Hello, World!"

Old SDK 1.5 Document is here

This section describes the procedure from building to execution of the sample application "Hello, World!".
See the following chapters for details of how to configure and build.

3.1. Configuration instructions

  1. Navigate to the folder where you have stored the cloned Spresense SDK code, and enter the sdk folder:

    cd spresense/sdk

  2. Set the initial SDK configuration:

    tools/config.py examples/hello
If you see a message like WARNING: New loader vX.Y.Z is required, please download and install. in this step, please install a new bootloader with refer Flashing bootloader.

3.2. Build instructions

  1. Build the example image:

    make

In SDKv2.3 or later, parallel build is available with the -j option.

make -j

If you use -j option with no argument, it allows infinite parallel jobs. However, if it doesn’t work correctly due to lack of PC resources, try to limit the number of jobs like make -j2.

A nuttx.spk file will be created in the sdk folder when this step has successfully finished. This file is the final result and can be flashed onto the Spresense board.

3.3. Tutorial to flash SW

Type tools/flash.sh for flashing nuttx.spk into Spresense board.

+ Please refer to USB connection for checking the <port> of the -c option.

+ Example for Linux environment ( <port> = /dev/ttyUSB0)

+

tools/flash.sh -c /dev/ttyUSB0 nuttx.spk
>>> Install files ...
install -b 115200
Install nuttx.spk
|0%-----------------------------50%------------------------------100%|
######################################################################

252480 bytes loaded.
Package validation is OK.
Saving package to "nuttx"
updater# sync
updater# Restarting the board ...
reboot

+ Example for Windows environment ( <port> = COM9)

+

tools/flash.sh -c COM9 nuttx.spk
>>> Install files ...
install -b 115200
Install nuttx.spk
|0%-----------------------------50%------------------------------100%|
######################################################################

252480 bytes loaded.
Package validation is OK.
Saving package to "nuttx"
updater# sync
updater# Restarting the board ...
reboot

+ Example for macOS environment ( <port> = /dev/cu.SLAB_USBtoUART)

+

tools/flash.sh -c /dev/cu.SLAB_USBtoUART nuttx.spk
>>> Install files ...
install -b 115200
Install nuttx.spk
|0%-----------------------------50%------------------------------100%|
######################################################################

252480 bytes loaded.
Package validation is OK.
Saving package to "nuttx"
updater# sync
updater# Restarting the board ...
reboot

On installation completion, the Spresense board will reboot.

If you see a message like WARNING: New loader vX.Y.Z is required, please download and install. in this step, please install a new bootloader with refer Flashing bootloader.

3.4. Run "Hello, World!"

hello example is a simple program that it shows Hello world!! on the console. So you need serial terminal software. You can use any serial terminal software, for example, screen or minicom on Linux and macOS, or PuTTY or Tera Term on Windows.

Table 1. Serial Terminal Configuration

Baudrate

115200

Data Bits

8 bit

Parity Bit

none

Stop Bit

1 bit

Flow Control

none

In this chapter, use screen. If you use Linux, install first.

sudo apt install screen

Run terminal in 115200 baud

screen /dev/ttyUSB0 115200

If nsh> is shown after typing Enter and Esc keys, the Spresense board working properly. nsh> is the command prompt for NuttShell.

NuttShell (NSH)
nsh>

Type hello

NuttShell (NSH)
nsh> hello
Hello, World!!
nsh>
If you want to finsh screen, then press Ctrl+a k. When it asks Really kill this window [y/n], press y.

4. Build method

Old SDK 1.5 Document is here

This chapter describes the structure and build procedure of the Spresense SDK. Spresense SDK uses a build system using GNU Make.

It might be handy to have a local clone of the Spresense SDK while reading this section. The Spresense SDK is be cloned from GitHub.

Cloning Spresense SDK via https:
git clone --recursive https://github.com/sonydevworld/spresense.git

4.1. Configuration

The NuttX kernel and Spresense SDK are configurable to be able to comply with the requirements for specific applications and hardware configurations. The Spresense SDK is using Kconfig to handle the configuration, just as the Linux kernel build system does. Please refer to Development environment to get the Kconfig installation instructions.

The Spresense SDK provides a set of tools: tools/config.py and tools/mkdefconfig.py to handle the system configuration.

Usage of tools/config.py
cd spresense/sdk
tools/config.py -h
usage: config.py [-h] [-k] [-l] [-m] [-q] [-g] [-d DIR] [-v]
                 [-i [config [config ...]]]
                 [<config name> [<config name> ...]]

Configuration tool

positional arguments:
  <config name>         configuration name

optional arguments:
  -h, --help            show this help message and exit
  -k, --kernel          DEPRECATED
  -l, --list            list default configurations. show kernel defconfigs
                        with --kernel.
  -m, --menuconfig      run config in "menuconfig"
  -q, --qconfig         run config in "qconfig"
  -g, --gconfig         run config in "gconfig"
  -d DIR, --dir DIR     change configs directory
  -v, --verbose         verbose messages
  -i [config [config ...]], --info [config [config ...]]
                        show configuration information
Usage of tools/mkdefconfig.py
cd spresense/sdk
tools/mkdefconfig.py -h
usage: mkdefconfig.py [-h] [-k] [-d DIR] [-y] [--all] [--verbose]
                      <config name>

Make default config from current config

positional arguments:
  <config name>      configuration name

optional arguments:
  -h, --help         show this help message and exit
  -k                 DEPRECATED
  -d DIR, --dir DIR  change configs directory
  -y                 overwrite existing defconfig
  --all              DEPRECATED
  --verbose, -v      verbose messages

In the following example tools/config.py tool will load the kconfig-frontends with menuconfig as user interface and load a predefined configuration (described below).

The tools/config.py and tools/mkdefconfig.py scripts depend on the current directory structure so make sure that they run from the sdk directory.

4.1.1. menuconfig, qconfig, gconfig

Kconfig have a few different user interfaces. To open them to modify the configuration execute tools/config.py with one of the options in the table below.

Table 2. Setup screen options:

Options

-m or - menuconfig

CUI menu selection using the ncurses library

-q or --qconfig

GUI menu selection using the Qt library

-g or --gconfig

GUI menu selection using the gtk library

Depending on what user interface options that where activated when kconfig-frontend was built some of the options might not be available.

4.1.2. Predefined Configuration (defconfig)

The predefined configuration (defconfig) is a predefined combination of settings required when you want to use a certain function. If you want to use a defconfig, specify the defconfig name as the argument of the tools/config.py tool. It is possible to list the available defconfigs by executing the tools/config.py with the -l option.

List all defconfigs example:
tools/config.py -l

Multiple defconfigs can be specified at the same time. If more than one defconfig is specified, the result is a combination of all the defconfigs.

Example of using more than one defconfig:
tools/config.py device/sdcard feature/wifi
Specifying a defconfig when calling tools/config.py will reset/overwrite the current configuration.

If you do not know the contents of defconfig, use the -i or --info option to display the information of the specified defconfig.

./tools/config.py -i device/sdcard
=== device/sdcard ===
[Description]
This configuration contains required options to use SD card slot.

[Differences]
+CXD56_SDIO=y

4.1.3. Save settings

It is possible to save custom settings made by the user.

To save the current SDK settings as <config name> use the following command:
tools/mkdefconfig.py <config name>

In the example above on the Spresense SDK settings will be saved.

If the name specified in <config name> already exists, a confirmation will be displayed asking if you want to overwrite it.

tools/config.py and tools/mkdefconfig.py apply/save to defconfig files in the folder sdk/configs. The defconfig destination folder can be set with the -d or --dir option.

Example of using ../path/to/configs directory to save the <config name> defconfig to:
tools/mkdefconfig.py -d ../path/to/configs <config name>
To use a defconfig in a different path, in this example ../path/to/configs use:
tools/config.py -d ../path/to/configs <config name>

4.2. Build system

To build the SDK, type in the commands in the following example.

tools/config.py default
tools/config.py -m
# Above commands are to configure the SDK settings.
make

In SDKv2.3 or later, parallel build is available with the -j option.

make -j

If you use -j option with no argument, it allows infinite parallel jobs. However, if it doesn’t work correctly due to lack of PC resources, try to limit the number of jobs like make -j2.

If the build succeeds two files will be created in the sdk directory: nuttx and nuttx.spk.

These two files have the following format:

nuttx

ELF format. To be used when loaded with a debugger.

nuttx.spk

A proprietary file packaged to write to the actual machine.

5. Flashing binaries to the Spresense board

This chapter explains how to flash the following binaries:

  • nuttx.spk

  • loader.espk

  • gnss.espk

5.1. USB connection

Connect the Spresense main board to the PC via the USB cable.

spresense musb connect
Figure 1. Main board USB connection

5.1.1. Check the serial port name

SDK tools needs the serial port name for communicate with Spresense board. The serial port name is different on each OS.

  • on Linux

    dmesg | grep "cp21.*attached"
[12220.625979] usb 1-1: cp210x converter now attached to ttyUSB0

    In this case, the port name is /dev/ttyUSB0.

  • on macOS

    ls /dev/{tty,cu}.*
/dev/cu.SLAB_USBtoUART  /dev/tty.SLAB_USBtoUART

    In this case, the port name is /dev/tty.SLAB_USBtoUART.

  • on Windows

    Open Settings > Devices, and Spresense board will be shown in Other devices list like Silicon Labs CP210x USB to UART Bridge (COM3). In this case, the port name is COM3. Alternatively, you can check it from Device Manager.

    tutorial arduino windows device manager find port

    In this case, the port name is COM9.

5.2. Flash the bootloader

Please see Flashing bootloader.

5.3. Flash the user nuttx.spk image

Use the tools/flash.sh script to flash nuttx.spk to Spresense board.

  1. Connect the USB cable from the Spresense main board to your PC.

  2. Check serial port number by using next command.

    dmesg | grep "cp21.*attached"
[12220.625979] usb 1-1: cp210x converter now attached to ttyUSB0

    In this case, Spresense board use /dev/ttyUSB0 for serial connection.

  3. Type tools/flash.sh for flashing nuttx.spk into Spresense board.

    tools/flash.sh -c /dev/ttyUSB0 nuttx.spk
    tutorial nuttx image load
    Figure 2. nuttx.spk flashing

  4. On installation completion, the Spresense board will reboot.

6. Adding a user application

Old SDK 1.5 Document is here

A new user application can be added using the following methods:

  • Using the application template in the sdk/apps/examples directory, or

  • Adding the user application to any other directory.

6.1. Add to the examples

The most straightforward way to quickly get started with developing a custom made user application is to use the hello example.

  1. Copy the whole sdk/apps/examples/hello folder to a directory with a new name.

  2. Replace all hello strings in Makefile,Make.defs, Kconfig,hello_main.c with the new name chosen in step 1.

  3. Change the file name of hello_main.c to an arbitrary file name. (See Example of adding a user application from scratch).

  4. After replacing all the strings, execute make distclean once in the SDK directory.

  5. Perform initial SDK configuration

Enter menuconfig
cd sdk
make distclean
tools/config.py default
make menuconfig
Kconfig menu
Examples --->
  [] My first app example (NEW)
If the Kconfig file have been added or deleted, the config menu menuconfig, can be updated by running make clean in the SDK directory.

Once the new application has been enabled, the SDK is ready to be built by the command:

make

In SDKv2.3 or later, parallel build is available with the -j option.

make -j

If you use -j option with no argument, it allows infinite parallel jobs. However, if it doesn’t work correctly due to lack of PC resources, try to limit the number of jobs like make -j2.

After flashing the created nuttx.spk file and restarting the Spresense board, the added application can be executed as a command.

6.1.1. Example of adding a user application from scratch

Kconfig
config EXAMPLES_MYFIRSTAPP
    tristate "My first app example"
    default n
    ---help---
        Enable the my first app example

if EXAMPLES_MYFIRSTAPP

config EXAMPLES_MYFIRSTAPP_PROGNAME
    string "Program name"
    default "myfirstapp"
    ---help---
        This is the name of the program that will be used when the NSH ELF
        program is installed.

config EXAMPLES_MYFIRSTAPP_PRIORITY
    int "My firstapp task priority"
    default 100

config EXAMPLES_MYFIRSTAPP_STACKSIZE
    int "My first app stack size"
    default 2048

endif

Symbols defined with config <symbol> in the Kconfig file can be referred to in the Makefile with the variable CONFIG_ <symbol>.
Option symbols defined in the Kconfig file must be unique in the SDK. If symbols are duplicated, a warning will be displayed when running the configuration tool.
Makefile
-include $(TOPDIR)/Make.defs

PROGNAME  = $(CONFIG_EXAMPLES_MYFIRSTAPP_PROGNAME)
PRIORITY  = $(CONFIG_EXAMPLES_MYFIRSTAPP_PRIORITY)
STACKSIZE = $(CONFIG_EXAMPLES_MYFIRSTAPP_STACKSIZE)
MODULE    = $(CONFIG_EXAMPLES_MYFIRSTAPP)

MAINSRC = myfirstapp_main.c

include $(APPDIR)/Application.mk
PROGNAME

The character string set in this variable becomes the command name
PRIORITY

Sets the task priority
STACKSIZE

Sets the task’s stack size
MODULE

Select application build as a loadable ELF or not
Make.defs
ifneq ($ (CONFIG_EXAMPLES_MYFIRSTAPP),)
CONFIGURED_APPS += myfirstapp
endif
CONFIGURED_APPS

The directory set in this variable is subject to build.

6.2. Add to a different directory

It is possible to store the application outside the Spresense SDK repository. The following steps will explain how to add a directory outside of the repository into the build system.

  1. Create arbitrary directories in the same directory as the SDK.

  2. Copy Makefile, Make.defs and .sdksubdirs from the examples directory.

  3. Add any application in the newly created directory in the same way as described in Add to the examples.

  4. Execute make in the SDK directory.

6.2.1. Example of adding another directory

In this example, the application myfirstapp is placed in a folder called myapps.

File/directory structure after creating the example.
|-- sdk
|-- examples
└-- myapps
    |-- .sdksubdirs
    |-- Make.defs
    |-- Makefile
    └-- myfirstapp
        |-- Kconfig
        |-- Make.defs
        |-- Makefile
        └-- myfirstapp_main.c
myapps/Makefile
MENUDESC = "My Apps"

include $(SDKDIR)/tools/Sdk.mk
MENUDESC

String displayed in the configuration menu

6.3. How to use utility tools

There are utility tools to add your application to the examples and a different directory as mentioned above.

A utility tool to add your application to the examples
tools/mkcmd.py -h
usage: mkcmd.py [-h] [-d BASEDIR] [-v] <app name> [desc]

Create a new application

positional arguments:
  <app name>            New application name
  desc                  Menu description

optional arguments:
  -h, --help            show this help message and exit
  -d BASEDIR, --basedir BASEDIR
                        Base directory to create new application
  -v, --verbose         Verbose messages

This tool create a new application at examples directory.
You can use '-d' option to change application directory, it is a same level
of sdk and examples.
A utility tool to add your application to a different directory
tools/mkapppsdir.py -h
usage: mkappsdir.py [-h] [-s] [-v] <dir name> [desc]

Create a new application directory at the outside of sdk repository

This tool must be run on sdk directory.

positional arguments:
  <dir name>     New application directory name
  desc           Menu description

optional arguments:
  -h, --help     show this help message and exit
  -s, --spresense_home  using spresense home
  -v, --verbose  verbose messages
Run these tools under the sdk directory.

6.3.1. Usage

e.g. Add myfirstapp application to the example
cd spresense/sdk
tools/mkcmd.py myfirstapp "My first app example"
e.g. Create new directory myapps and add myfirstapp application to its directory
cd spresense/sdk
tools/mkappsdir.py myapps "My Apps"
tools/mkcmd.py -d myapps myfirstapp "My first app example"

7. Flashing bootloader

Correct bootloader is required for using Spresense board properly.

  • The bootloader has to be flashed after purchase.

  • It is needed to accept the End User License Agreement before using the Spresense bootloader binary.

A WARNING might be shown when using tools/config.py or tools/flash.sh with bootloader missing. In this case, please flash the Spresense bootloader into the Spresense board.

WARNING: New loader vX.Y.Z is required, please download and install.
         Download URL   : <<Displays the download URL of the appropriate boot loader for your Spresense SDK>>
         Install command:
                          1. Extract loader archive into host PC.
                             ./tools/flash.sh -e <download zip file>
                          2. Flash loader into Board.
                             ./tools/flash.sh -l <<Displays the firmware directory path of the boot loader for your Spresense SDK>> -c <port>

  1. Download the EULA binary zip archive.

    Go to the Download URL in WARNING description which will provide a link to the specific version you need by execute a tools/config.py or tools/flash.sh command, and download it to your PC.

  2. Extract the EULA binary zip on your PC by executing:

    ./tools/flash.sh -e <<Downloaded zip file>>

  3. Flash Spresense bootloader into Spresense board. Make sure the Spresense board is attached to the PC via the USB cable.

    Please refer to USB connection for checking the <port> of the -c option. The following is an execution command example in the Linux / Windows / macOS environment.

    (This is an example when second step of Install command in WARNING description shows ./tools/flash.sh -l /home/user/spresense/firmware/spresense -c <port>.)

    Example for Linux environment ( <port> = /dev/ttyUSB0).

    ./tools/flash.sh -l /home/user/spresense/firmware/spresense -c /dev/ttyUSB0

    Example for Windows environment ( <port> = COM9).

    ./tools/flash.sh -l /home/user/spresense/firmware/spresense -c COM9

    Example for macOS environment ( <port> = /dev/cu.SLAB_USBtoUART).

    ./tools/flash.sh -l /home/user/spresense/firmware/spresense -c /dev/cu.SLAB_USBtoUART

8. Spresense Commands (β version)

Developers can use build-env.sh to enable a these features:

  1. Enable to add a user application to your directory except in Spresense SDK.

  2. Add a Spresense command ( spr-* )

  3. Completion of ./tools/config.py

How to apply

source tools/build-env.sh
This script use a environment variable. If you re-open a terminal, please re-execute it.

8.1. Add user application except in Spresense SDK directory

We can add own application outside of Spresense SDK directory.

sdk user application
Figure 3. Relations of Spresense SDK and application root

As shown in above image, you can create a user application into application root which is independent from Spresense SDK. And you can import other applications which have been created by the same method by copying.

Next commands is for using User application.

  • spr-create-approot

  • spr-set-approot

  • spr-create-app

Description of these commands Please refer to Spresense command for details of these commands.

8.2. Spresense command

Command Functionality

spr-config

For building configuration. The same as ./tools/config.py .

spr-make

For building application. Almost the same as make , but this command can execute everywhere.

spr-create-approot

For creating application root directory that can contain user applications.

spr-set-approot

For setting application root directory.

spr-create-app

For creating skeleton application into applicatno root directory.

spr-go-sdk

For changing current directory to Spresense SDK

spr-go-approot

For changing current directory to application root directory.

8.3. spr-config

spr-config is wrapper command of tools/config.py spr-config can do the configuration required to build the SDK. The functionality is the same as tools/config.py .In addition, this command supports TAB completion , and you can assist key inputs of configuration by inputting the command as follow:

spr-config exam<TAB key>
spr-config examples/he<TAB key>
spr-config examples/hello

Also, by making effective use of this function, you can check the available configurations as follow as shown in the list:

spr-config <TAB key><TAB key>
board/collet                        examples/hello
board/corvo                         examples/helloxx
board/spresense                     examples/jpeg_decode
default                             examples/lcdrw
device/accelerometer                examples/light
device/adc                          examples/lte_awsiot
device/bcm20706                     examples/lte_http_get
device/camera                       examples/lte_lwm2m
device/charger                      examples/lte_mqtt
device/colorsensor                  examples/lte_tls
device/lcd                          examples/lte_websocket
device/lightsensor                  examples/mag
device/magnetometer                 examples/nx
device/pressure                     examples/nxhello

8.4. spr-make

This command has the same function as the Spresense SDK build command make. So it also supports the subcommand buildkernel and so on. And you can also run builds with this command from somewhere other than spresense/sdk .

spr-config --kernel release
spr-config examples/hello
spr-make buildkernel
spr-make

8.5. spr-create-approot

This is a command to create (set) a directory to be used as an application root . Files necessary for building with SDK are also created by this command.

If you create application root at /home/user/myapps , please type commands as follow:

spr-create-approot /home/user/myapps
Creating application directory into /home/user/myapps

After typing the commands, When the above commands are executed, the files necessary for build are created in the directory which will be application root as shown below.

tree /home/user/myapps
/home/user/myapps
├── Application.mk
├── LibTarget.mk
├── Make.defs
└── Makefile

0 directories, 4 files

Applications can be added to the directory created by this command.

The configured application root is restored by executing the following command when switching terminals.

8.6. spr-set-approot

This is a command to switch directories used as application root. The directory to switch must have been created beforehand with the spr-create-approot command.

If you switch to /home/user/myapps as application root, please execute this command:

spr-set-approot /home/user/myapps

8.7. spr-create-app

This is a command to create a new skeleton application. Applications are created in the application root selected by spr-create-approot or spr-set-approot .

If you create an application with the name myapp, please execute tihs command:

spr-create-app myapp
New 'myapp' app successfully created at '/home/user/myapps/myapp'.

When you execute the above command, files required for build are created in application root as follow:

tree /home/user/myapps/myapp
/home/user/myapps/myapp
├── configs
│   └── default-defconfig
├── Kconfig
├── Make.defs
├── Makefile
└── myapp_main.c

1 directory, 5 files

Applications can also be updated by writing a code in <application name> _main.c. With this command, a program file is created as follows, and the program can be described in the myapp_main(int argc, char *argv []) function in follow,

cat /home/user/myapps/myapp/myapp_main.c

#include <sdk/config.h>
#include <stdio.h>

#ifdef CONFIG_BUILD_KERNEL
int main(int argc, FAR char *argv[])
#else
int myapp_main(int argc, char *argv[])
#endif
{
  return 0;
}

Also, the configuration of the created application can be selected as myapp/myapp/default by ./tools/config.py or spr-config.

spr-config <TAB>
...
examples/audio_recorder_pre  examples/mag                 myapp/myapp/default
examples/audio_through       examples/nx
examples/ble_central         examples/nxhello

8.8. spr-go-sdk

This is the command to change current directory to the Spresense SDK. It is used when updating the Spresense SDK repository or using tools.

8.9. spr-go-approot

This is the command to change current directory to the configured application root.

9. Limitations

9.1. Spresense SDK may not be used depending on the folder name/path used

Spresense SDK does not allow filenames and folder names with spaces due to build system restrictions.

If there is a space in the path of the file name or folder name, the configuration or build cannot be performed properly. Please download and use the Spresense SDK in a location with no spaces in the path.

10. Appendix

10.1. How to get specified Spresense SDK version

This section shows how to change Spresense SDK that already downloaded by git clone to specified version.

10.1.1. Clean the repository

You should clean the repository before changing specified SDK version. Please follow the steps below to check the status and clean the repository.

10.1.1.1. Remove the build objects

Remove the build objects generated by make with the following command.

make distclean
10.1.1.2. Clean the uncommitted files

Use the following command to check the edited contents of the repository that has not been committed.

git status

If there is a file being edited in the repository, it will be displayed as modified or Untracked files as shown below.

On branch master
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   examples/accel/accel_main.c

Untracked files:
  (use "git add <file>..." to include in what will be committed)

	examples/accel/README

no changes added to commit (use "git add" and/or "git commit -a")

In such a case, please commit by git commit the edited contents or use the following command to temporarily save.

git stash
By using git stash pop, you can take back your changes that has been temporarily saved by git shash.

10.1.2. Update git objects

Please follow next commands to update git objects.

(e.g. If you clone repository into /home/user/spresense )

cd /home/user/spresense
git fetch origin
The origin is the remote repository name, which is associated with the <URL> specified by git clone <URL>.

10.1.3. Checkout the specified SDK version

(e.g. If you want to checkout v2.0.2 )

git checkout v2.0.2
git submodule init
git submodule update
If you want to checkout specific branch, please use branch name such like origin/develop in behalf of SDK version.
Once checkout the repository, your modification will be lost. If you want to avoid it, please use git merge to merge changes or create a new branch to save your changes.

10.1.4. If Untracked files: remains after checkout

If you change the major version such like SDK v1.5.1 → v2.0.2 or v2.0.2 → v1.5.1, git status might shows Untracked files: such as next lines.

HEAD detached at v2.0.2
Untracked files:
  (use "git add <file>..." to include in what will be committed)

	externals/nnabla-c-runtime/

nothing added to commit but untracked files present (use "git add" to track)

In such case, please remove untracked files manually.

10.2. How to build SDK for v1.5 and earlier versions

The build method of SDK v1.5 or earlier is shown below.

10.2.1. Example application of "Hello, World!" (old version 1.X)

This section describes the procedure from building to execution of the sample application "Hello, World!".
See the following chapters for details of how to configure and build.

10.2.1.1. Configuration instructions

  1. Navigate to the folder where you have stored the cloned Spresense SDK code, and enter the sdk folder:

    cd spresense/sdk

  2. Set the initial NuttX kernel configuration:

    tools/config.py --kernel release

  3. Set the initial SDK configuration:

    tools/config.py examples/hello
10.2.1.2. Build instructions

  1. Build the NuttX kernel:

    make buildkernel

  2. Build the example image:

    make

A nuttx.spk file will be created in the sdk folder when this step has successfully finished. This file is the final result and can be flashed onto the Spresense board.

10.2.1.3. Tutorial to flash SW

Use the tools/flash.sh script to flash nuttx.spk to Spresense board.

Type tools/flash.sh for flashing nuttx.spk into Spresense board.

tools/flash.sh -c /dev/ttyUSB0 nuttx.spk
>>> Install files ...
install -b 115200
Install nuttx.spk
|0%-----------------------------50%------------------------------100%|
######################################################################

252480 bytes loaded.
Package validation is OK.
Saving package to "nuttx"
updater# sync
updater# Restarting the board ...
reboot

On installation completion, the Spresense board will reboot.

10.2.1.4. Run "Hello, World!"

hello example is a simple program that it shows Hello world!! on the console. So you need serial terminal software. You can use any serial terminal software, screen and minicom for example.

Table 3. Serial Terminal Configuration

Baudrate

115200

Data Bits

8 bit

Parity Bit

none

Stop Bit

1 bit

Flow Control

none

In this chapter, use screen. If you use Linux, install first.

sudo apt install screen

Run terminal in 115200 baud

screen /dev/ttyUSB0 115200

If nsh> is shown after typing Enter and Esc keys, the Spresense board working properly. nsh> is the command prompt for NuttShell.

NuttShell (NSH)
nsh>

Type hello

NuttShell (NSH)
nsh> hello
Hello, World!!
nsh>
If you want to finsh screen, then press Ctrl+a k. When it asks Really kill this window [y/n], press y.

10.2.2. Build method (old version 1.X)

This chapter describes the structure and build procedure of the Spresense SDK. Spresense SDK uses a build system using GNU Make.

It might be handy to have a local clone of the Spresense SDK while reading this section. The Spresense SDK is be cloned from GitHub.

Cloning Spresense SDK via https:
git clone --recursive https://github.com/sonydevworld/spresense.git
10.2.2.1. Configuration

The NuttX kernel and Spresense SDK are configurable to be able to comply with the requirements for specific applications and hardware configurations.. The Spresense SDK is using Kconfig to handle the configuration, just as the Linux kernel build system does. Please refer to Development environment to get the Kconfig installation instructions.

The configuration is divided into two parts:

  • NuttX kernel configuration

  • SDK configuration

The Spresense SDK provides a set of tools: tools/config.py and tools/mkdefconfig.py to handle the configuration of these two systems.

Usage of tools/config.py
cd spresense/sdk
tools/config.py -h
usage: config.py [-h] [-k] [-l] [-m] [-q] [-g] [-d DIR] [-v]
                 [<config name> [<config name> ...]]

Configuration tool

positional arguments:
  <config name>      configuration name

optional arguments:
  -h, --help         show this help message and exit
  -k, --kernel       kernel config
  -l, --list         list default configurations. show kernel defconfigs with
                     --kernel.
  -m, --menuconfig   run config in "menuconfig"
  -q, --qconfig      run config in "qconfig"
  -g, --gconfig      run config in "gconfig"
  -d DIR, --dir DIR  change configs directory
  -v, --verbose      verbose messages
Usage of tools/mkdefconfig.py
cd spresense/sdk
tools/mkdefconfig.py -h
usage: mkdefconfig.py [-h] [-k] [-d DIR] [--all] [--verbose] <config name>

Make default config from current config

positional arguments:
  <config name>      configuration name

optional arguments:
  -h, --help         show this help message and exit
  -k                 save kernel configuration
  -d DIR, --dir DIR  change configs directory
  --all              Save SDK and kernel configuration with same name
  --verbose, -v      verbose messages

In the following example tools/config.py tool will load the kconfig-frontends with menuconfig as user interface and load a predefined configuration (described below).

This tool is used for both for the NuttX kernel and Spresense SDK configuration. Selecting what target to configure is done by extra option switches on the command line when executing the tools/config.py script. The -k or --kernel option will affect the NuttX kernel configuration. When the tools/config.py script is called without any switch the Spresense SDK configuration is affected.

e.g.
cd spresense/sdk
tools/config.py -k -m
The tools/config.py and tools/mkdefconfig.py scripts depend on the current directory structure so make sure that they run from the sdk directory.
menuconfig, qconfig, gconfig

Kconfig have a few different user interfaces. To open them to modify the configuration execute tools/config.py with one of the options in the table below.

Table 4. Setup screen options:

Options

-m or - menuconfig

CUI menu selection using the ncurses library

-q or --qconfig

GUI menu selection using the Qt library

-g or --gconfig

GUI menu selection using the gtk library

Depending on what user interface options that where activated when kconfig-frontend was built some of the options might not be available.

Predefined Configuration (defconfig)

The predefined configuration (defconfig) is a predefined combination of settings required when you want to use a certain function. If you want to use a defconfig, specify the defconfig name as the argument of the tools/config.py tool. It is possible to list the available defconfigs by executing the tools/config.py with the -l option.

List all defconfigs example:
tools/config.py -l

Multiple defconfigs can be specified at the same time. If more than one defconfig is specified, the result is a combination of all the defconfigs.

Example of using more than one defconfig:
tools/config.py board/spresense device/sdcard
Specifying a defconfig when calling tools/config.py will reset/overwrite the current configuration.
Save settings

It is possible to save custom settings made by the user.

To save the current SDK settings as <config name> use the following command:
tools/mkdefconfig.py <config name>

In the example above on the Spresense SDK settings will be saved, but not the NuttX kernel settings. To save the NuttX kernel settings the -k option has to be used. Use the -k option or the --all option. If you specify the --all option, the current settings of both the SDK and the kernel are saved with the specified name.

tools/mkdefconfig.py -k <config name>

or

tools/mkdefconfig.py --all <config name>
If the name specified in <config name> already exists, a confirmation will be displayed asking if you want to overwrite it.

tools/config.py and tools/mkdefconfig.py apply/save to defconfig files in the folder sdk/configs. The defconfig destination folder can be set with the -d or --dir option.

Example of using ../path/to/configs directory to save the <config name> defconfig to:
tools/mkdefconfig.py -d ../path/to/configs <config name>
To use a defconfig in a different path, in this example ../path/to/configs use:
tools/config.py -d ../path/to/configs <config name>

Changing the defconfig directory is also supported when using the -k option.

10.2.2.2. Build system
The build system is divided into two parts:

  • NuttX kernel

  • Spresense SDK

Each of these two need to be built separately. Starting the build must be done from the sdk directory in both cases.

Diagram
Figure 4. Build workflow
Building the NuttX kernel

To build the NuttX kernel, type the commands in the following example. Before the build is started, the NuttX kernel have to be configured.

Configure the NuttX kernel via menuconfig:
cd spresense/sdk
tools/config.py -k release
tools/config.py -k -m
# Above commands are to configure the NuttX kernel settings.
make buildkernel
Configure the NuttX kernel with default settings:
cd spresense/sdk
make buildkernel KERNCONF=release
If the settings of the NuttX kernel haven’t been changed or if the source have not been modified, then the NuttX kernel doesn’t have to be rebuilt.
Building the SDK

To build the SDK, type in the commands in the following example. Just as in the NuttX kernel case, the configuration have to be set prior starting the build.

tools/config.py default
tools/config.py -m
# Above commands are to configure the SDK settings.
make

If the build succeeds two files will be created in the sdk directory: nuttx and nuttx.spk.

These two files have the following format:

nuttx

ELF format. To be used when loaded with a debugger.

nuttx.spk

A proprietary file packaged to write to the actual machine.

10.2.3. Adding a user application (old version 1.X)

A new user application can be added using the following methods:

  • Using the application template in the examples directory, or

  • Adding the user application to any other directory.

10.2.3.1. Add to the examples

The most straightforward way to quickly get started with developing a custom made user application is to use the hello example.

  1. Copy the whole hello folder to a directory with a new name.

  2. Replace all hello strings in Makefile,Make.defs, Kconfig,hello_main.c with the new name chosen in step 1.

  3. Change the file name of hello_main.c to an arbitrary file name. (See Example of adding a user application from scratch).

  4. After replacing all the strings, execute make clean once in the SDK directory.

  5. Enter menuconfig, your new custom made example application should be listed under examples.

Enter menuconfig
cd sdk
make clean
tools/config.py -m
Kconfig menu
Examples --->
  [] My first app example (NEW)
If the Kconfig file have been added or deleted, the config menu menuconfig, can be updated by running make clean in the SDK directory.

Once the new application has been enabled, the SDK is ready to be built by the command:

make

After flashing the created nuttx.spk file and restarting the Spresense board, the added application can be executed as a command.

Example of adding a user application from scratch
Kconfig
config EXAMPLES_MYFIRSTAPP
bool "My first app example"
default n
---help---
    Enable the my first app example

if EXAMPLES_MYFIRSTAPP

config EXAMPLES_MYFIRSTAPP_PROGNAME
string "Program name"
default "myfirstapp"
depends on BUILD_KERNEL
---help---
    This is the name of the program that will be used when the NSH ELF
    program is installed.

config EXAMPLES_MYFIRSTAPP_PRIORITY
int "My firstapp task priority"
default 100

config EXAMPLES_MYFIRSTAPP_STACKSIZE
int "My first app stack size"
default 2048

endif

Symbols defined with config <symbol> in the Kconfig file can be referred to in the Makefile with the variable CONFIG_ <symbol>.
Option symbols defined in the Kconfig file must be unique in the SDK. If symbols are duplicated, a warning will be displayed when running the configuration tool.
Makefile
-include $ (TOPDIR) / Make.defs
-include $ (SDKDIR) /Make.defs

# My first app built-in application info

CONFIG_EXAMPLES_MYFIRSTAPP_PRIORITY? = SCHED_PRIORITY_DEFAULT
CONFIG_EXAMPLES_MYFIRSTAPP_STACKSIZE? = 2048

APPNAME = myfirstapp
PRIORITY = $ (CONFIG_EXAMPLES_MYFIRSTAPP_PRIORITY)
STACKSIZE = $ (CONFIG_EXAMPLES_MYFIRSTAPP_STACKSIZE)

# My first app Example

ASRCS =
CSRCS =
MAINSRC = myfirstapp_main.c

CONFIG_EXAMPLES_MYFIRSTAPP_PROGNAME? = Myfirstapp $ (EXEEXT)
PROGNAME = $ (CONFIG_EXAMPLES_MYFIRSTAPP_PROGNAME)

include $ (APPDIR) /Application.mk
APPNAME

The character string set in this variable becomes the command name
PRIORITY

Sets the task priority
STACKSIZE

Sets the task’s stack size
Make.defs
ifeq ($ (CONFIG_EXAMPLES_MYFIRSTAPP), y)
CONFIGURED_APPS + = myfirstapp
endif
CONFIGURED_APPS

The directory set in this variable is subject to build.
10.2.3.2. Add to a different directory

It is possible to store the application outside the Spresense SDK repository. The following steps will explain how to add a directory outside of the repository into the build system.

  1. Create arbitrary directories in the same directory as the SDK.

  2. Copy LibTarget.mk,Makefile, Make.defs and Application.mk from the examples directory.

  3. Change the path of the archive in LibTarget.mk.

  4. Change the path of the archive in Application.mk.

  5. Change the file name of the BIN variable in Makefile to the same file name as the file name changed with LibTarget.mk.

  6. Add any application in the newly created directory in the same way as described in Add to the examples.

  7. Execute make in the SDK directory.

Example of adding another directory

In this example, the application myfirstapp is placed in a folder called myapps.

File/directory structure after creating the example.
|-- sdk
|-- examples
└-- myapps
    |-- Application.mk
    |-- LibTarget.mk
    |-- Make.defs
    |-- Makefile
    └-- myfirstapp
        |-- Kconfig
        |-- Make.defs
        |-- Makefile
        └-- myfirstapp_main.c
myapps/LibTarget.mk
# Change directory from examples to myapps
# Change the archive name from libexamples to libmyapps

$(SDKDIR)$(DELIM)..$(DELIM)myapps$(DELIM)libmyapps$(LIBEXT): context
	$(Q) $(MAKE) -C $(dir $@) TOPDIR="$(TOPDIR)" SDKDIR="$(SDKDIR)" $(notdir $@)

lib$(DELIM)libmyapps$(LIBEXT): $(SDKDIR)$(DELIM)..$(DELIM)myapps$(DELIM)libmyapps$(LIBEXT)
	$(Q) install $< $@

EXTLIBS += lib$(DELIM)libmyapps$(LIBEXT)
DELIM

Path delimiter (\ for Windows, / for Linux).
LIBEXT

Library file extension (.a).
myapps/Makefile
MENUDESC = "My Apps"

BIN = libmyapps$(LIBEXT)  # libexamples -> libmyapps

include $(SDKDIR)/Makefile.ext
MENUDESC

String displayed in the configuration menu
myapps/Application.mk (snippet)
ifeq ($(WINTOOL),y)
  BIN = "${shell cygpath -w $(APPDIR)$(DELIM)libmyapps$(LIBEXT)}" # libexamples -> libmyapps
  INSTALL_DIR = "${shell cygpath -w $(BIN_DIR)}"
else
  BIN = $(APPDIR)$(DELIM)libmyapps$(LIBEXT) # libexamples -> libmyapps
  INSTALL_DIR = $(BIN_DIR)
endif

ROOTDEPPATH = --dep-path .

VPATH =

all: .built
.PHONY: clean preconfig depend distclean
.PRECIOUS: $(APPDIR)/libmyapps$(LIBEXT) # libexamples -> libmyapps
10.2.3.3. How to use utility tools

There are utility tools to add your application to the examples and a different directory as mentioned above.

A utility tool to add your application to the examples
tools/mkcmd.py -h
usage: mkcmd.py [-h] [-d BASEDIR] [-v] <app name> [desc]

Create a new application

positional arguments:
  <app name>            New application name
  desc                  Menu description

optional arguments:
  -h, --help            show this help message and exit
  -d BASEDIR, --basedir BASEDIR
                        Base directory to create new application
  -v, --verbose         Verbose messages

This tool create a new application at examples directory.
You can use '-d' option to change application directory, it is a same level
of sdk and examples.
A utility tool to add your application to a different directory
tools/mkapppsdir.py -h
usage: mkappsdir.py [-h] [-s] [-v] <dir name> [desc]

Create a new application directory at the outside of sdk repository

This tool must be run on sdk directory.

positional arguments:
  <dir name>     New application directory name
  desc           Menu description

optional arguments:
  -h, --help     show this help message and exit
  -s, --spresense_home  using spresense home
  -v, --verbose  verbose messages
Run these tools under the sdk directory.
Usage
e.g. Add myfirstapp application to the example
cd spresense/sdk
tools/mkcmd.py myfirstapp "My first app example"
e.g. Create new directory myapps and add myfirstapp application to its directory
cd spresense/sdk
tools/mkappsdir.py myapps "My Apps"
tools/mkcmd.py -d myapps myfirstapp "My first app example"