Quickstart: Install the Azure Sphere SDK for Linux

You can install the Azure Sphere SDK on a computer running the Linux operating system to develop, deploy, and debug Azure Sphere applications.

Prerequisites

The Azure Sphere SDK installation requires the following prerequisites:

  • A computer running Ubuntu 20.04 LTS or 18.04 LTS
  • Linux sudo permission.
  • An internet connection or a way to transfer files from a computer that has an internet connection to your computer. For more information, see Install the SDK without an internet connection.

Add required Linux packages

Before you run the SDK installation script, you need to add required Linux packages to your computer if they are not already installed. Enter the following lines in a Linux terminal. You may omit packages that are already installed.

sudo apt-get update

sudo apt-get install -y net-tools curl

Install the Azure Sphere SDK

Follow these steps:

  1. Download the install script.

  2. Navigate to the folder into which you downloaded the compressed file and extract the contents. The .tar.gz contains the install_azure_sphere_sdk.sh file.

  3. Enable execution of the install script with this command:

    chmod +x install_azure_sphere_sdk.sh

  4. Run the install script. It asks questions and then installs the SDK.

  5. During installation, the script displays messages similar to these:

    The SDK tarball signature is valid. The fingerprint of the key used is:`
    
    Primary key fingerprint: <hexadecimal>
    

    Navigate to Microsoft's public-key fingerprint site and verify that the hexadecimal fingerprint value displayed during installation matches matches the Microsoft Public Key Fingerprint that is shown on the page. Do not proceed if the two fingerprints don't match.

    Installing CLI v2 (Beta).
    This release contains the new azsphere CLI v2 (Beta), which adds new functionality including autocompletion of commands, scriptable output, browser-based authentication, and simplified object identification.
    
    Choose 'Yes' to use the CLI v2 (Beta) as your default CLI. The classic CLI will remain available as 'azsphere_v1'. If you choose 'No', you can still try the azsphere CLI v2 (Beta) using 'azsphere_v2'. See https://aka.ms/AzureSphereLinuxCLIversion for more details.
    Do you want to use the new azsphere CLI v2 (Beta) (Y/N) y
    

    Select Y to set CLI v2 Beta as your default CLI or N to set CLI v1 as your default CLI.

  6. When the installation completes, you must log out and log back into your desktop session or login shell to initialize the CLI.

After installation, the azsphere command is on the PATH and the new udev rules for your device are at /etc/udev/rules.d/.

The script installs the SDK to /opt/azurespheresdk and the toolchains to /opt/azurespheresdk/Sysroots/sysroot-version/tools, where sysroot-version identifies a sysroot against which the SDK supports app development.

The installer installs both the Azure Sphere CLI v1 and the Azure Sphere CLI v2 Beta versions of the CLI. You don't need to uninstall the current version because the installation will update any existing version. Azure Sphere CLI v1 is installed in ./install_path/Tools and Azure Sphere CLI v2 Beta is installed in ./install_path/Tools_v2. For more information on beta version of the CLI, see Azure Sphere CLI v2 Beta.

On Linux, you can run Azure Sphere CLI v2 Beta from a terminal using azsphere_v2 and azsphere if it was selected as the default CLI during the installation.

After installing the CLI for the first time, check that it's installed and you've got the correct version by running azsphere show-version.

Set up a device connection

The Azure Sphere SDK for Linux sets up the required networking settings to allow communication with the attached device. Connect your device to your computer by USB and then run the following script as sudo:

sudo /opt/azurespheresdk/DeviceConnection/azsphere_connect.sh

You must supply the full path to the script because sudo replaces the PATH variable before a call. You can also supply the following PATH alternative:

sudo $(which azsphere_connect.sh).

If you haven't run azsphere_connect.sh and attempt to run an azsphere command that communicates with a local device, you will be prompted to run the script.

Important

You must run this script whenever you reboot the machine or detach and reattach the device.

udev rules

The Azure Sphere SDK specifies udev rules for your computer's device information. The SDK creates a new group called azsphere and adds the currently logged-in user to the group. The udev rule grants ownership of USB devices matching the Azure Sphere device description. After you install the SDK and reboot your computer, you will not need to use sudo for device recovery or ARM Cortex-M4 debugging.

The azsphere group is added in order to grant permissions using the udev rule. Do not modify the group manually.

Install the SDK without an internet connection

If you don't have an internet connection on the computer on which you're installing the SDK, you need to download three files to a computer that is connected to the internet and transfer them to the installation computer.

Download these three files:

On the installation computer, navigate to the folder into which you downloaded the compressed file and extract the contents. The .tar.gz contains the install_azure_sphere_sdk.sh file.

Enable execution of the install script with this command:

chmod +x install_azure_sphere_sdk.sh

Run the install script using sudo. Include the -i parameter to specify the path to the SDK and the -k parameter to specify the path to the key. Your command should be similar to this:

sudo ./install_azure_sphere_sdk.sh -i [pathtopackage]/[sdkbundle] -k [pathtokey]/microsoft.asc

A notification is displayed which allows you to set Azure Sphere CLI v1 or Azure Sphere CLI v2 Beta as the preferred default CLI version. Type Yes to choose Azure Sphere CLI v2 Beta or type No to use Azure Sphere CLI v1. If you type No, you can still try the azsphere CLI v2 (Beta) using 'azsphere_v2'.

Set up your development environment

You can develop Azure Sphere apps on Linux using either Visual Studio Code or the command-line interface (CLI). No matter which you use, you'll need to install CMake and Ninja on your development machine, if you don't already have them.

To install CMake and Ninja, use the following command:

sudo apt install cmake ninja-build

Note

Do not install cmake or ninja using snap.

If you want to use Visual Studio Code as your development environment, you need to install it and the Azure Sphere Extension.

  1. Use the links in Download Visual Studio Code to install Visual Studio Code, if you haven't already done so.

  2. Install the Azure Sphere Extension from the Extension Marketplace, or in Visual Studio Code, search for Azure Sphere in the Extension Marketplace and install it.

  3. After installation, you should see Azure Sphere, C/C++, and CMake Tools extensions in the ENABLED Extensions pane in the Visual Studio Code IDE.

When installation is complete, the Readme page for the extension will open. The Readme page provides useful information about Visual Studio Code configuration and requirements, and is updated along with the extension. You can view the Readme page any time by opening the Extensions pane and selecting Azure Sphere.

After installation, configure Visual Studio Code with the path to the Azure Sphere SDK installation directory:

  1. In the File menu select Preferences > Settings > Extensions > AzureSphere.

  2. Under Azure Sphere: Sdk Path, ensure that the path to the Azure Sphere SDK installation directory is /opt/azurespheresdk.

Next steps