Developer World Spresense
日本語 中文
Table of Contents

This section helps you set up the environment on your computer to:

  1. Install the Spresense Arduino Library.

  2. Set up your computer to run Spresense Arduino Library sketches.

  3. Run a sample application on the Spresense board to test the setup.

1. Supported Operating Systems

The Spresense Arduino Library runs on the following operating systems:

  • Windows 10/11 (64bit version)

  • Linux Ubuntu 16.04 (64bit version) or later

  • Mac OS X 10.12 Sierra or later

Does not support 32bit version OS

2. Prerequisites

  1. Download and install the Arduino IDE for your operating system:

  2. Download and install the USB-to-serial drivers that correspond to your operating system from the following links:

If you use the latest Silicon Labs driver (v11.2.0) in Windows 10/11 environment, USB communication may cause an error and it may fail to flash the program. Please download v11.1.0 from the above URL and install it.

2.1. Linux USB serial port configuration

  • 64bit Linux Ubuntu requires the user to be a member of the dialout group.

    1. Add user to dialout groups.

      sudo usermod -a -G dialout $USER

    2. Logout and login again to use the new settings.

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

You must set up the USB port to be able to upload the built image to the Spresense board.

2.2. macOS High Sierra (10.13) or later

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. Install Spresense Arduino Library

There are two installation methods to choose from:

We recommend installing through the Arduino IDE Board Manager for ease of use. If you are unable to complete installation through this method, you can still install the library using the manual install method.

3.1. Installation through Arduino IDE Board Manager

The following steps will describe how to install the Spresense Arduino Library into the Arduino IDE using the Board Manager.

  1. Start Arduino IDE.

  2. Open the preferences in [File→Preferences].

    tutorial arduino open preferences
    Figure 1. Open preferences

  3. Copy and paste the following URL into the field called Additional Boards Managers URLs:

    https://github.com/sonydevworld/spresense-arduino-compatible/releases/download/generic/package_spresense_index.json

    tutorial arduino preferences add bm url
    Figure 2. Copy this URL and paste it into the Additional Boards Manager URLs field.

  4. Open the Boards Manager [Tools→Board→Boards Manager].

    tutorial arduino open boardmanager
    Figure 3. Open the Boards Manager.

  5. Search for Spresense. Once found in the list, select it and click install. If the package list fails to download, a possible reason is your network connection uses a proxy. To set the proxy, navigate to [File → Preferences → Network].

    The Spresense board package size is above 150 MB. Please be aware of the impact to your network usage limits and charges.
    tutorial arduino boardmanager spresense install
    Figure 4. Search for Spresense, select it and click install.

  6. The Spresense Arduino Library is now installed.

4. Setting up the environment

4.1. Identify the serial port used by Spresense board

Connect your PC to the Spresense main board USB connector and check that the power LED turns on. The serial port driver may install at this point if it has not done so already.

spresense musb connect
Figure 5. Connection to the Spresense main board USB connector with power LED on

4.2. Install Bootloader

  1. Select the Spresense board in the [Tools→Boards→Spresense] menu.
    ([Tools→Boards→Spresense Boards→Spresense] in Arduino IDE 1.8.13 or later)

    tutorial arduino board spresense
    Figure 6. Select the Spresense board

  2. Select the serial port used by Spresense from the menu [Tools→Port]. If there is more than one port see Identify the serial port used by Spresense board for more info.

    tutorial arduino select port
    Figure 7. Select port, this example shows how it looks like in Windows.

  3. If you are using the Spresense board for the first time, or if you are using an updated version of the Spresense Arduino Library, update the boot loader by selecting [Tools→Programmer→Spresense Firmware Updater].

    tutorial arduino select programmer
    Figure 8. Select correct programmer to be able to flash the firmware/boot loader.

  4. Then select [Tools→Programmer→Burn Bootloader].

    tutorial arduino burn bootloader
    Figure 9. Burn bootloader.

  5. Review and accept the EULA by following the dialog.

    tutorial arduino eula dialog
    Figure 10. Accept EULA to load the bootloader binaries.

  6. Once the upload completes, this is how it should look like:

    tutorial arduino fw upload done
    Figure 11. Burn bootloader.

4.3. Build your first sketch to verify installation

  1. You have now finished setting up the board. To verify the setup is correct, copy and paste the following example LED test code into a new sketch:

    void setup() {
    pinMode(LED0, OUTPUT);
    pinMode(LED1, OUTPUT);
    pinMode(LED2, OUTPUT);
    pinMode(LED3, OUTPUT);
}

void loop() {
    digitalWrite(LED0, HIGH);
    delay(100);
    digitalWrite(LED1, HIGH);
    delay(100);
    digitalWrite(LED2, HIGH);
    delay(100);
    digitalWrite(LED3, HIGH);
    delay(1000);

    digitalWrite(LED0, LOW);
    delay(100);
    digitalWrite(LED1, LOW);
    delay(100);
    digitalWrite(LED2, LOW);
    delay(100);
    digitalWrite(LED3, LOW);
    delay(1000);
}

  2. Build and upload the LED test sketch by clicking Upload.

    tutorial arduino upload
    Figure 12. Click Upload.

  3. Wait for the upload to complete.

    tutorial arduino upload example sketch done
    Figure 13. Uploading finished without errors.

  4. Your sketch should run automatically. When the LEDs on the main board are flashing, congratulations! Your setup is now complete!

    • If the LEDs doesn’t flash, press the board reset button or open the serial monitor to start the sketch.

    • You may increase the baud rate to shorten the transfer/upload time. This may not always work depending on what hardware you use (PC, cables etc). A recommendation is to start at the default value and increase the baud rate to test if the transfer still works.

      tutorial arduino select baudrate
      Figure 14. This picture shows the highest possible baud rate. Not guaranteed to work on every setup.

5. Explore further!

Now that you have set up your development environment, you can proceed to run example sketches to explore the features on the board or head over to Spresense Arduino Library Developer Guide to read more.

Spresense specific examples are available from the Arduino IDE at File > Examples > Spresense and on spresense-sketches GitHub repository. You can also run example sketches that work with Arduino Uno though be aware of the hardware differences. Spresense Hardware comparison section contains details of these differences.

6. Appendix

6.1. Check USB serial driver connection

This section shows how to verify the USB serial driver connection for different platforms.

6.1.1. Check USB serial driver connection on Windows

  1. Open Device Manager

  2. Check the COM port number of the Spresense board.

tutorial arduino windows device manager find port
Figure 15. Device manager

6.1.2. Check USB serial driver connection on Ubuntu 64bit

Locate the COM port used to connect the Spresense board.

  1. Open the terminal.

  2. Enter the following command.

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

    In this example ttyUSB0 is the COM port.

6.1.3. Check USB serial driver connection on Mac OS X

Locate the COM port used to connect the Spresense board.

  1. Open the terminal.

  2. Enter the following command.

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

    In this example the COM port for CU command is cu.SLAB_USBtoUART or for tty command tty.SLAB_USBtoUART.

6.2. How to create Spresense Arduino customized package

Spresense provides a solution to create a customized board package and install it in the Arduino IDE in a local environment. You can install a customized package into your Arduino IDE, as well as share it between communities.

Please refer to Installation with offline package via Boards Manager in Arduino IDE for the installation method of the created board package.

6.2.1. About Spresense Arduino board package

The Spresense Arduino board package consists of a pre-built Spresense SDK, a Spresense library wrapped around it for Arduino, and tools for Spresense.

arduino borad manager package detail en
Component File name Details

Spresense Library

spresense-v*...tar.gz

A wrapper library for Arduino on the Spresense SDK. Includes Arduino standard library code, Spresense library code and sample sketches.

Spresense Tools

spresense-tools-v*...tar.gz

Includes tools for creating and writing binaries for Spresense on the Arduino IDE.

Spresense SDK Prebuilt

spresense-sdk-v*...tar.gz

Contains a static archive of the Spresense SDK built for the Arduino IDE.

ARM GCC

gcc-arm-none-eabi-X.Y.Z-*.tar.gz

Includes a toolchain for building your sketches. Basically, the Arduino IDE uses the published toolchain as is, and is not created for local board packages.

By creating these Spresense archives, you can create customized packages that can be installed on the Arduino IDE.

6.2.2. How to create customized package

This section describes how to create a customized package.

You can create customized package by 4 steps as follow:

  • Clone the repository (spresense.git, spresense-arduino-compatible.git)

  • Modify a Spresense SDK codes (spresense.git) or spresense Arduino(spresense-arduino-compatible.git)

  • (If you modify a Spresense SDK) Import the Spresense SDK

  • Create a package (Archive file, Json file)

The following describes how to create a package for each use case.

6.2.2.1. Case of updating the Spresense Arduino Library for adding samples

If you are only updating Arduino libraries and sample sketches, you can use published Spresense SDK prebuilt. In this case, you can skip "Import the Spresense SDK".

  1. Clone the spresense-arduino-compatible.git

  2. Modify a spresense-arduino-compatible/Arduino15/packages/SPRESENSE/hardware/spresense/1.0.0 and spresense-arduino-compatible/Arduino15/packages/SPRESENSE/tools/spresense-tools codes.

  3. Creating an archive files and Json file.

    cd spresense-arduino-compatible
make

  4. The process is complete if the following three files have been created.

    ./out/package_spresense_local_index.json
./out/staging/packages/spresense-v*.*.*_local.tar.gz
./out/staging/packages/spresense-tools-v*.*.*_local.tar.gz
6.2.2.2. Case of using a customized Spresense SDK

If you use a customized Spresense SDK, you must import the Spresense SDK. In this case you need to use spresense-arduino-compatible and spresense repository as follow:

  1. Clone the spresense.git

  2. Clone the spresense-arduino-compatible.git

  3. Modify in a spresense/

    If you edit or add a file, that file must be in a build target. Please check a defconfig list in a spresense-arduino-compatible/tools/configs/spresense.conf for confirm build target.

  4. Import the Spresense SDK

    Please use same version of spresense.git and spresense-arduino-compatible.git repository.
    path/to/spresense is the path where spresense.git is cloned.

    • SDK v1.5 or earlier

      cd spresense-arduino-compatible
./tools/prepare_arduino.sh -S path/to/spresense -c spresense -k release -p
./tools/prepare_arduino.sh -S path/to/spresense -c spresense -k debug -p
./tools/prepare_arduino.sh -S path/to/spresense -c spresense_sub -k subcore-release -p
./tools/prepare_arduino.sh -S path/to/spresense -c spresense_sub -k subcore-debug -p

    • SDK v2.0 or later

      cd spresense-arduino-compatible
./tools/prepare_arduino.sh -S path/to/spresense -c spresense -d disable -p
./tools/prepare_arduino.sh -S path/to/spresense -c spresense -d enable -p
./tools/prepare_arduino.sh -S path/to/spresense -c spresense_sub -d disable -p
./tools/prepare_arduino.sh -S path/to/spresense -c spresense_sub -d enable -p

  5. Creating an archive files and Json file.

    cd spresense-arduino-compatible
make

  6. The process is complete if the following four files have been created.

    ./out/package_spresense_local_index.json
./out/staging/packages/spresense-v*.*.*_local.tar.gz
./out/staging/packages/spresense-tools-v*.*.*_local.tar.gz
./out/staging/packages/spresense-sdk-v*.*.*_local.tar.gz
6.2.2.3. Case of changing the configuration of Spresense SDK

If you update a configuration of Spresense SDK, you must import the Spresense SDK. In this case you need to use spresense-arduino-compatible and spresense repository as follow:

  1. Clone the spresense.git

  2. Clone the spresense-arduino-compatible.git

  3. Import the Spresense SDK

    You can change the configuration of the Spresense SDK when importing the SDK.

    Please use same version of spresense.git and spresense-arduino-compatible.git repository.
    If you only want to add the configuration as defconfig, you can update configuration by adding defconfig into spresense-arduino-compatible/tools/configs/spresense.conf without option -M SDK.

    • SDK v1.5 or earlier

      cd spresense-arduino-compatible
./tools/prepare_arduino.sh -S path/to/spresense -c spresense -k release -M SDK -p
<After menuconfig is opened, change the configuration>
./tools/prepare_arduino.sh -S path/to/spresense -c spresense -k debug -M SDK -p
<After menuconfig is opened, change the configuration>

    • SDK v2.0 or later

      cd spresense-arduino-compatible
./tools/prepare_arduino.sh -S path/to/spresense -c spresense -d disable -M SDK -p
<After menuconfig is opened, change the configuration for MainCore>
./tools/prepare_arduino.sh -S path/to/spresense -c spresense_sub -d enable -M SDK -p
<After menuconfig is opened, change the configuration for SubCore>

  4. Creating an archive files and Json file.

    cd spresense-arduino-compatible
make

  5. The process is complete if the following four files have been created.

    ./out/package_spresense_local_index.json
./out/staging/packages/spresense-v*.*.*_local.tar.gz
./out/staging/packages/spresense-tools-v*.*.*_local.tar.gz
./out/staging/packages/spresense-sdk-v*.*.*_local.tar.gz

6.3. Spresense Arduino board package local installation

There are two ways to install Spresense Arduino package locally.

The customized package created in the previous chapter can be installed using the Installation with offline package via Boards Manager in Arduino IDE procedure.

6.3.1. Installation with offline package via Boards Manager in Arduino IDE

This is an installation method using the file for the board manager. It can be installed together with other boards of Arduino, so it is a recommended method for those who use multiple boards including Spresense with Arduino IDE.

6.3.1.1. Preparation

The following two types of file are required for installation from the Arduino IDE board manager. Both files are created by the spresense-arduino-compatible repository’s script.

  • Archive file (out/staging)

    • Spresense Library(out/staging/packages/spresense-v*.*.*_local.tar.gz)

    • Spresense Tools(out/staging/packages/spresense-tools-v*.*.*_local.tar.gz)

    • Spresense SDK Prebuilt(out/staging/packages/spresense-sdk-v*.*.*_local.tar.gz)

      Spresense SDK Prebuilt is only required if you have customized the Spresense SDK.

  • Json file(out/package_spresense_local_index.json)

Be sure to use an archive and json files created with make command in spresense-arduino-compatible. If it is created at a different timing, it cannot be installed correctly.(Example: If only the archive file is updated and the old Json file is used, it cannot be installed correctly.)
6.3.1.2. Install steps

  1. Copy archive files into Arduino install directory.

    cp -r spresense-arduino-compatible/out/staging <Arduino15>/
    Arduino package installation path <Arduino15> varies depending on your OS and IDE installation method. Arduino package installation path can be opened by click into File → Preferences → Settings → More preferences can be edited directory in the file on Arduino IDE.

  2. Add a URLs for the official Json file and the local Json file to the Additional Boards Manager URLs.

    https://github.com/sonydevworld/spresense-arduino-compatible/releases/download/generic/package_spresense_index.json
file://<path of the package_spresense_local_index.json>
    Please use the original file path used in your OS as it is for <path of the package_spresense_local_index.json>. If you use the file C:\Users\user\spresense-arduino-compatible\out\package_spresense_local_index.json , the second line of Additional Boards Manager URLs need to be set to file://C:\Users\user\spresense-arduino-compatible\out\package_spresense_local_index.json.
    If you are using Arduino IDE2, please write the file name with file: and 3 slashes like file:///C:\Users\user\spresense-arduino-compatible\out\package_spresense_local_index.json.
    If the official Json file URL is missing, the ARM toolchain will not be installed and you will not be able to use it properly.

  3. Click Tools → Board: → Boards Manager…​ on the Arduino IDE, and search Spresense local Board and click Install.

  4. After the installation, the process is complete if the Spresense local is there in Tools → Boards:.

6.3.2. Manual installation

  1. Download the manual installation board package zip file manual-install-spresense-arduino-"OPERATING_SYSTEM"-latest.zip for your platform from:

  2. Follow the installation instructions for the respective PC platform:

  3. Start Arduino IDE.

  4. Open the preferences in [File→Preferences].

  5. In the Arduino IDE Preferences dialog box, set the following URL in the field called Additional Boards Managers URLs: and close the dialog box. This is to prevent the Arduino Boards Manager UI from removing the Spresense board listing.

    https://github.com/sonydevworld/spresense-arduino-compatible/releases/download/generic/package_spresense_index.json

6.3.2.1. Install Spresense Arduino Library for Windows

Extracting manual-install-spresense-arduino-windows-latest.zip may cause an error, the file path name is too long. Therefore, the procedure described here extracts the zip file to a folder with a short path name such as c:\temp.

  1. Create c:\temp folder and unzip manual-install-spresense-arduino-windows-latest.zip to the folder.

    The packages folder and a package_spresense_index.json file will be under an Arduino15 folder.

    Diagram

  2. Copy these files to Arduino IDE installation folder.

    Open %userprofile%\AppData\Local\Arduino15 folder and copy packages and package_spresense_index.json to the folder.

    Diagram

    In case of Arduino IDE installed from Microsoft Store, the destination folder is different.
    Open %userprofile%\Documents\ArduinoData folder and copy packages and package_spresense_index.json to the folder.

    Diagram

  3. The board package is now installed.

6.3.2.2. Install Spresense Arduino Library for Linux

The following steps assume you have a 64-bit Ubuntu PC and you have stored the downloaded file manual-install-spresense-arduino-linux-latest.zip at ~/Downloads.

  1. If you have not started the Arduino IDE for the first time, start the application and close it. Check that a folder called ~/.arduino15/ exists.

  2. Open the terminal and navigate to the folder where you have stored manual-install-spresense-arduino-linux-latest.zip.

  3. Extract the contents to ~/Downloads.

    cd ~/Downloads
unzip manual-install-spresense-arduino-linux-latest.zip
rm -rf ~/.arduino15/packages/SPRESENSE
cp -rfv ~/Downloads/Arduino15/* ~/.arduino15/
rm -rf ~/Downloads/Arduino15

  4. The board package is now installed.

6.3.2.3. Install Spresense Arduino Library for Mac OS X

The following steps assume you have stored the downloaded file manual-install-spresense-arduino-macosx-latest.zip at ~/Downloads.

  1. If you have not started the Arduino IDE for the first time, start the application and close it. Check that a folder called ~/Library/Arduino15 exists.

  2. Open the terminal and navigate to the folder where you have stored manual-install-spresense-arduino-macosx-latest.zip.

  3. Extract the contents to ~/Library/.

    cd ~/Downloads
unzip manual-install-spresense-arduino-macosx-latest.zip -d ~/Library/

  4. The board package is now installed.

6.4. How to install the pre-release version of Spresense Arduino board package

We have started pre-release of Spresense Arduino board package which is under development since 2021. This section describes how to install the pre-release package.

By installing the pre-release package, you’ll be the first to try out the latest features!

6.4.1. How to download the pre-release version

Pre-release versions are available at the following page. For each release, updates history and pre-release packages are available for you to install into your Arduino IDE.

https://github.com/SPRESENSE/spresense-arduino-compatible/releases

You can find a list of packages by clicking on Assets on the page.

The following 4 files are to be downloaded for installation.

  • package_spresense_beta_index.json: Package configuration file

  • spresense-beta.tar.gz: Archive containing libraries for Audio/GNSS/Camera, etc.

  • spresense-tools-beta.tar.gz: Archive containing tools for building sketches and writing them to the Spresense board.

  • spresense-sdk-beta.tar.gz: Archive containing the pre-built Spresense SDK

The above pre-release package is a set of four files. You cannot install a combination of different versions.

6.4.2. How to install pre-release package

The downloaded pre-release package can be installed from the Board Manager of the Arduino IDE in the following 3 steps.

6.4.2.1. Copy the download package

  1. Open File → Preferences → Settings　in the Arduino IDE

  2. Click on the path to the file listed under the text " More preferences can be edited directory in the file " to open the Arduino15 (Windows/macOS cases) or .arduino15 (Ubuntu case) directory.

    arduino preference path link en

  3. Create a directory staging, and inside it, create a directory packages.

  + Arduino15 (or .arduino15)
  └──+ staging
     └─── packages
If you have already installed any board in the Board Manager, these directory has already been created.

  1. Copy the 4 files you downloaded into the packages directory you created.

  + Arduino15 (or .arduino15)
  └───+ staging
      └───+ packages
          ├── package_spresense_beta_index.json
          ├── spresense-beta.tar.gz
          ├── spresense-sdk-beta.tar.gz
          └── spresense-tools-beta.tar.gz
6.4.2.2. Specify the Board Manager URL

  1. Open File → Preferences → Settings　in the Arduino IDE

  2. Add the following 2 lines to the Additional Boards Manager URLs.

https://github.com/sonydevworld/spresense-arduino-compatible/releases/download/generic/package_spresense_index.json
file://<The path to the copied package_spresense_beta_index.json>

The format of the copied package_spresense_beta_index.json path will match the file path in your OS.

Windows example(for Arduino IDE)

file://C:\Users\{username}\AppData\Local\Arduino15\staging\packages\package_spresense_beta_index.json

Windows example(for Arduino IDE2)

file:///C:\Users\{username}\AppData\Local\Arduino15\staging\packages\package_spresense_beta_index.json

macOS example

file:///Users/{username}/Library/Arduino15/staging/packages/package_spresense_beta_index.json

Ubuntu example

file:///home/{username}/.arduino15/staging/packages/package_spresense_beta_index.json

The following is an example on a Windows environment. Replace Username with your user name.

arduino prerelease additionalurl
6.4.2.3. Running the installation in the Board Manager

  1. Open Tools → Board → Boards Manager…​　in the Arduino IDE

  2. Search the Spresense

  3. Install the Spresense beta Board

    arduino prerelease install en

  4. When the message version 999.999.999 INSTALLED is displayed, installation is complete.

    arduino prerelease install done en

  5. Select Tools → Board → Spresense Boards (beta) → Spresense (beta) to use the package you have installed

    arduino prerelease board selection en