Spresense SDK
1. Spresense SDK Getting Started Guide
This section describes how to start working with the Spresense SDK.
1.1. Prerequisite
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
1.1.1. Setup for Linux
Serial Configuration
Add user to dialout group
$ sudo usermod -a -G dialout <user-name>
Please logout and login after running the above command.
Install development tools
$ wget
$ bash install-tools.sh
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.
Clone the Spresense SDK with submodule
$ git clone --recursive
1.1.2. Setup for Windows
Install MSYS2
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 > install-tools.sh
$ bash install-tools.sh
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.
Clone the Spresense SDK with submodule
$ git clone --recursive
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 Windows 7/8/8.1
CP210x USB to serial driver (v10.1.3) for Windows 10
1.1.3. Setup for macOS
Install development tools provided by Apple
Open the Teminal and run following command.
$ xcode-select --install
Install Python3
Python.org
Install development tools
$ curl -L > install-tools.sh
$ bash install-tools.sh
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.
Clone the Spresense SDK with submodule
$ git clone --recursive
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.
1.2. USB connection
Connect the Spresense main board to the PC via the USB cable.
Figure 1. Main board USB connection
1.2.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
Use /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.
1.3. Setting Up the Spresense SDK
1.3.1. Build instructions
Navigate to the folder where you have stored the cloned Spresense SDK code, and enter the sdk folder:
$ cd spresense/sdk
Set the initial NuttX kernel configuration:
$ tools/config.py --kernel release
Set the initial SDK configuration:
$ tools/config.py examples/hello
Build the example image:
$ make buildkernel
$ 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. See Tutorial to flash SW for details.
1.4. Tutorial to flash SW
1.4.1. Flash the bootloader
The correct bootloader is required for the Spresense board to function.
Bootloader informationThe bootloader has to be flashed the very first time the board is used.
You have to accept the End User License Agreement to be able to download and use the Spresense bootloader binary.
A WARNING message (example shown below) may be shown when using tools/config.py or tools/flash.sh if the bootloader is missing. In this case you have to flash the Spresense bootloader onto the Spresense board.
WARNING: New loader v1.0.003 is required, please download and install.
Download URL :
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 /home/user/mySpresense/spresense/firmware/spresense -c <port>
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, and download it to your PC.
Extract EULA binary zip in your PC by executing:
$ ./tools/flash.sh -e spresense-binaries-vx.x.x.zip
Flash Spresense bootloader into Spresense board.
Execute the command that is shown in WARNING description. (In this example <port> is /dev/ttyUSB0):
$ ./tools/flash.sh -l ../firmware/spresense -c /dev/ttyUSB0
Finish.
On installation completion, the Spresense board will reboot.
1.4.2. Flash the user nuttx.spk image
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.
1.5. 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 1. Serial Terminal ConfigurationBaudrate / 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>
Spresense board will reboot every time you open the serial terminal.2. Sample Application of GPS(GNSS)
This chapter shows the operation procedure of GPS(GNSS) sample application.
2.1. Build & Flash
Move to the folder where you cloned the Spresense SDK, and enter the sdk folder name:
$ cd spresense/sdk
Set up the NuttX kernel configuration
$ tools/config.py --kernel release
Set up the SDK configuration To enable the gnss example application, select examples/gnss.
$ tools/config.py examples/gnss
Please refer to How to configure for details on the configuration.
Build the example image:
$ make buildkernel
$ make
Please refer to How to build for details on the build.
A nuttx.spk file will be created in the sdk folder after make has successfully finished.
Just the same as Hello World example, flash the nuttx.spk to Spresense with tools/flash.sh.
$ tools/flash.sh -c /dev/ttyUSB0 nuttx.spk
When flashing the board is completed the board is restarted automatically.
2.2. GPS operation confirmation
Loading nuttx.spk to Spresense, you can run the GNSS program.
Open the serial terminal.
$ minicom -D /dev/ttyUSB0 -b 115200 -s
Execute gnss command, the gnss is a built-in application. The following text will be displayed:
Figure 2. GNSS startup log
If positioning is not available, you see this message:
> No Positioning Data
And the time is displayed that is from 0 o’clock count up when GNSS start.
If the Spresense can receive GPS signals from the satellites (clear view to the sky etc), the time in UTC will be displayed in approximately 1 minute, and the GPS position in approximately 3 minutes.
> Hour:9, minute:13, sec:20, usec:559
> LAT 35.25.6303
> LNG 139.22.1986
Similar text as shown above is displayed, and latitude and longitude can be read.
3. Sample Application of Audio Player
This chapter shows the operation procedure of the sample application of Audio Player.
3.1. Build & Flash
Move to the folder where you cloned the Spresense SDK, and enter the sdk folder name:
$ cd spresense/sdk
Set up the NuttX kernel configuration
$ tools/config.py --kernel release
Set up the SDK configuration To enable the audio_player example application, select examples/audio_player .
$ tools/config.py examples/audio_player
Please refer to How to configure for details on the configuration.
Build the example image:
$ make buildkernel
$ make
Please refer to How to build for details on the build.
A nuttx.spk file will be created in the sdk folder after make has successfully finished.
Just the same as Hello World example, flash the nuttx.spk to Spresense with tools/flash.sh .
$ tools/flash.sh -c /dev/ttyUSB0 nuttx.spk
When flashing the board is completed the board is restarted automatically.
For Audio Player, it is necessary to load the DSP binary for decode. You can choose to place the DSP binary on either a SD card or SPI-Flash. Here is how to load from the SD card.
Specify the path of DSP binary in the application code ( audio_player_main.cxx ). In audio_player_main.cxx , it is specified by DSPBIN_PATH .
#define DSPBIN_PATH "/mnt/sd0/BIN"
This code select SD card.
If you want to use SPI-flash, please specify /mnt/spif/BIN . Also, if you specify null, it will be the default path set in Config.
This /mnt/sd0/BIN becomes BIN/ under the root directory when it is read by the PC.
Create this directory and place the DSP for the required codec here.
When you want decode MP3 files,
select MP3DEC under spresense/sdk/modules/audio/dsp/
Write the music file you want to play simultaneously to the SD card. audio_player_main.cxx is specified in AUDIOFILE_ROOTPATH .
#define AUDIOFILE_ROOTPATH "/mnt/sd0/AUDIO"
Therefore, when read on the PC, under AUDIO/ under the root directory, please place the audio files you want to play. It can also be placed in subdirectories.
About this sample
The current Audio Player sample is playing a simple PlayList. So, specify the location and file name of the playlist file and play music files. In audio_player_main.cxx , specify the path with PLAYLISTFILE_PATH and the file name is specified in PLAY_LIST_NAME .
#define PLAYLISTFILE_PATH "/mnt/sd0/PLAYLIST"#define PLAY_LIST_NAME "TRACK_DB.CSV"
Therefor, when read on the PC, under PLAYLIST/ under the root directory, Create a file called TRACK_DB.CSV .
For the contents of TRACK_DB.CSV , see README.txt under spresense/sdk/modules/audio/playlist/ .
You can play music by preparing all of them.
3.2. Operation check of Audio Player
When this nuttx.spk is loaded to the actual machine, the Audio Player program is executed.
Open the serial terminal as you did in the Hello sample.
$ minicom -D /dev/ttyUSB0 -b 115200 -s
When you run the player app that was builtin,
Figure 3. The log of music playback.
The log is displayed and the audio is played back.
If an error occurs, refer to Error Information of Audio SubSystem.
4. Sample application of Audio Recorder
This chapter shows the operation procedure of the sample application of Audio Recorder.
See Audio Recorder Functions for code structure, data flow, API reference etc.4.1. Build & Flash
Move to the folder where you cloned the Spresense SDK, and enter the sdk folder name:
$ cd spresense/sdk
Set up the NuttX kernel configuration
$ tools/config.py --kernel release
Set up the SDK configuration
To enable the audio_recorder example application, select examples/audio_recorder .
$ tools/config.py examples/audio_recorder
By doing this configuration, settings for audio_recorder will be made.
Among them, the following items can be changed as needed. Please do not change the other configuration.
[SDK audio] <= Y
[Audio Recorder] <= Y
[DSP imange mount path] <= /mnt/sd0/BIN (1)
1 / This is the default location for DSP binary in SD card. If /mnd/spif/BIN is set, the default path is SPI-flash.
Please refer to How to configure for details on the configuration.
If you want to use your own signal processing for recording audio, set counfiguration of Preprocess as follow.
In AudioRecorder sample, you can perform your own signal processing on the recorded audio.
If you want to do this you need to enable [Use preprocess] in the config menu.
Open the config menu.
$ tools/cofig.py -m
Check [Use preprocess] .
[Examples]
[Audio recorder example]
[Use preprocess] <= Y (1)
1 / Enable Preprocess
For more information on Preprocess , please refer to SDK Developer Guide Set preprocess.
Do builds
$ make buildkernel
$ make
Please refer to How to build for details on the build.
A nuttx.spk file will be created in the sdk folder after make has successfully finished.
Just the same as Hello World example, flash the nuttx.spk to Spresense with tools/flash.sh .
$ tools/flash.sh -c /dev/ttyUSB0 nuttx.spk
When flashing the board is completed the board is restarted automatically.
For Audio Recorder, it is necessary to load the DSP binary for encoding. You can choose to place the DSP binary on either an SD card or SPI-Flash. Here is how to load from the SD card.
Specify the path of DSP binary in the application code. In audio_recorder_main.cxx , it is specified by DSPBIN_PATH .
#define DSPBIN_PATH "/mnt/sd0/BIN"
This code selects the SD card.
If you want to use SPI-flash, please specify /mnt/spif/BIN . Also, if you specify null, it will be the default path set in Config.
This /mnt/sd0/BIN becomes BIN/ under the root directory when it is read by the PC.
Create this directory and place the DSP for the required codec here.
When you want to encode MP3 files,
select MP3ENC under spresense/sdk/modules/audio/dsp/
The combinations of Codec type and DSP binary for other encoding are shown in the table below.
Codec / DSP Binary
MP3 / MP3ENC
LPCM / SRC
Also, if Preprocess is used, place the Preprocess binaries on the SD card too.
The binary is PREPROC under spresense/examples/audio_recorder/worker/src .
In this sample application, PREPROC includes a simple RCfilter by default.
If you want to customize your own signal processing etc., please refer to here.
The recorded audio is put on the SD card. The recording path is also set by the macro value in the application code (audio_recorder_main.cxx).
The macro on audio_recorder_main.cxx is RECFILE_ROOTPATH , please change the application code as needed.
#define RECFILE_ROOTPATH "/mnt/sd0/REC"
If it is this, it will be recorded on the SD card.
4.2. Operation check of Audio Recorder
When this nuttx.spk is loaded to the actual machine, the Audio Player program is executed.
Open the serial terminal as you did in the Hello sample.
$ minicom -D /dev/ttyUSB0 -b 115200 -s
When you run the recorder app that was builtin,
Figure 4. The log of sound recording.
The log is displayed and the audio is recording.
Recorded audio can be played back on a PC. At that time, there is an audio file in REC/ under the SD card root directory.
If an error occurs, refer to Error Information of Audio SubSystem.
4.3. About customizing of DSP binary (PREPROC)
this chapter shows how to customize the DSP binary (PREPROC).
4.3.1. Step 1. Edit the code of PREPROC
Describes the code structure of PREPROC and the editing location.
The code is divided into two parts: the part to edit the user and the part provided as a framework.
user-edited code
It is a code that users should edit mainly.
It can make unique signal processing by editing these codes.+
The DSP code is in the worker directory, which has the userproc directory.
The user writes signal processing only in the userproc directory, and other things basically do not need to be changed.
Since main.cpp provides startup processing and data communication control with Main CPU, do not change it.
Figure 5. The structure of source code
main.cpp
Startup processing and DSP communication processing are written. There is no need to edit.
userproc_command.h
It is a header file that defines the communication command with DSP.
Describe your necessary parameters in this file.
userproc.h
The header file of user code.
userproc.cpp
The sourace file of user code.
Write or call signal processing to this file.
APIs are provided for user code
userproc.cpp provides a framework for Init , Exec , Flush , Set commands.
The user code can support the processing in DSP by writing the unique contents.
Describes the process that the user should write.
(* By default, an RC filter is included as a sample.)
This framework assumed that the state transition inside DSP like in the figure below.
Figure 6. the state transition in DSP
Program the process by each command as following flow.
DSP starts when AUDCMD_SETRECORDERSTATUS is called.
Set necessary parameters (number of channels, bit length, etc.) with the Init command.
When recording starts, the captured audio data is periodically sent to the DSP with the Exec command, so it can do a unique filter processing.