Tutorial: Build a high-level application

A high-level application runs on the Azure Sphere OS, uses the Azure Sphere application libraries, and can communicate with the internet and with cloud-based services. See Overview of Azure Sphere applications for basic information about high-level applications.

In this tutorial, you learn how to:

  • Prepare your device for development and debugging
  • Build, run, and debug a high-level application

Prerequisites

Prepare your device for development and debugging

Before you can build a sample application on your Azure Sphere device or develop new applications for it, you must enable development and sideloading. By default, Azure Sphere devices are "locked"; that is, they do not allow applications under development to be loaded from a computer, and they do not allow debugging of applications. Preparing the device for sideloading removes this restriction.

The azsphere device enable-development command configures the device to accept applications for debugging, loads the debugging server onto the device, and assigns the device to a device group that does not allow cloud application updates. During application development and debugging, you should leave the device in this group so that cloud application updates do not overwrite the application under development.

  1. Make sure that your Azure Sphere device is connected to your computer, and your computer is connected to the internet.

  2. Open a command-line interface using PowerShell, Windows command prompt, or Linux command shell.

  3. Enter the following command:

    azsphere device enable-development
    

    You should see output similar to the following:

    Getting device capability configuration for application development.
    Downloading device capability configuration for device ID '<device ID>'.
    Successfully downloaded device capability configuration.
    Successfully wrote device capability configuration file 'C:\Users\user\AppData\Local\Temp\tmpD732.tmp'.
    Setting device group ID 'a6df7013-c7c2-4764-8424-00cbacb431e5' for device with ID '<device ID>'.
    Successfully disabled over-the-air updates.
    Enabling application development capability on attached device.
    Applying device capability configuration to device.
    Successfully applied device capability configuration to device.
    The device is rebooting.
    Installing debugging server to device.
    Deploying 'C:\Program Files (x86)\Microsoft Azure Sphere SDK\DebugTools\gdbserver.imagepackage' to the attached device.
    Image package 'C:\Program Files (x86)\Microsoft Azure Sphere SDK\DebugTools\gdbserver.imagepackage' has been deployed to the attached device.
    Application development capability enabled.
    Successfully set up device '<device ID>' for application development, and disabled over-the-air updates.
    Command completed successfully in 00:00:38.3299276.
    

If the azsphere device enable-development command fails, see Troubleshoot Azure Sphere issues for help.

Build and run the high-level application with Visual Studio Code

This tutorial uses the Azure Sphere Blink template, which is part of the Azure Sphere Extension for Visual Studio Code. The Blink template blinks an LED so you can verify that the Azure Sphere device and tools are installed and set up correctly.

  1. Start Visual Studio Code. Select View > Command palette, and then type Azure Sphere: Generate New Project.

    Command bar in Visual Studio code

  2. Choose Blink from the Templates menu.

    pop-up menu with template names

  3. Visual Studio Code then displays a File Explorer window. Navigate to the folder where you want to place the Blink application. Visual Studio Code creates the Blink folder in your selected location and generates the build files for the Blink application. You should see messages from CMake.

  4. Open the CMakeLists.txt file and change the TARGET_DIRECTORY setting to specify the folder that contains definitions for the hardware you're using. By default, the TARGET_DIRECTORY specifies HardwareDefinitions/mt3620_rbd, which matches the Seeed Azure Sphere MT3620 Development Kit:

    azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "HardwareDefinitions/mt3620_rdb" TARGET_DEFINITION "template_appliance.json")
    

    Several hardware definitions are provided with the template. For example, if you're using a SEEED MT3620 Mini Dev Board, specify HardwareDefinitions/seeed_mt3620_mdb instead.

  5. Press F5 to build and debug the project. If the project has not previously been built, or if files have changed and rebuilding is required, Visual Studio Code will build the project before debugging starts.

  6. Wait several seconds for Visual Studio Code to build the application, create an image package, deploy it to the board, and start it in debug mode. You'll see status updates in the Output pane along the way.

    First, CMake determines whether the application needs to be built. If so, focus shifts to the output window, which displays the output from CMake/Build.

    Next, the output window shows the output from azsphere as it deploys the image package to the device. Finally, the Debug Console receives focus and shows gdb output.

    Tip

    Make a note of the image ID in the Build output. You'll use the image ID later in the Deployment Quickstart.

  7. After a short delay, you should see an LED blink.

  8. Set a breakpoint somewhere in main.c and step through the application, so that you can explore the Visual Studio Code debugging features for Azure Sphere.

Build and run the high-level application with Visual Studio

This tutorial uses the Azure Sphere Blink template, which is part of the Azure Sphere Extension for Visual Studio. The Blink template blinks an LED so you can verify that the Azure Sphere device and tools are installed and set up correctly.

  1. If you are new to Visual Studio, consider the Quickstart or Guided Tour to learn about navigating and using it.

  2. Open Visual Studio and select Create a new project. In the Search box, type 'azure sphere' to get a list of Azure Sphere templates. Choose Azure Sphere Blink from the list.

  3. Enter a name and location for the project, and then select Create.

  4. Open the CMakeLists.txt file and change the TARGET_DIRECTORY setting to specify the folder that contains definitions for the hardware you're using. By default, the TARGET_DIRECTORY specifies HardwareDefinitions/mt3620_rbd, which matches the Seeed Azure Sphere MT3620 Development Kit:

    azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "HardwareDefinitions/mt3620_rdb" TARGET_DEFINITION "template_appliance.json")
    

    Several hardware definitions are provided with the template. For example, if you're using a SEEED MT3620 Mini Dev Board, specify HardwareDefinitions/seeed_mt3620_mdb instead.

  5. In Visual Studio, select View > Output to display the Output window.

  6. Ensure that your device is connected to your PC by USB. In the Set startup item menu, select GDB Debugger (HLCore) or press F5.

    Remote GDB Debugger button

  7. If you are prompted to build the project, select Yes. Visual Studio compiles the application, creates an image package, sideloads it onto the board, and starts it in debug mode. Sideloading means that the application is delivered directly from the PC over a wired connection, rather than delivered through the cloud.

    Note the image ID in the View > Output > Show output from: Build output, which indicates the image ID of the image package. You'll use the image ID later in Tutorial: Create a cloud deployment.

  8. By default, the Output window shows output from Device Output. To see messages from the debugger, select Debug from the Show output from: dropdown menu. You can also inspect the program disassembly, registers, or memory through the Debug > Windows menu.

  9. When you run the program, you should see an LED blink.

Download the sample application

You can download the HelloWorld application as follows: :

  1. Point your browser to Microsoft Samples Browser.
  2. Type "Azure Sphere" in the Search box.
  3. Select Azure Sphere - Hello World from the search results.
  4. Select Download ZIP.
  5. Open the downloaded file and extract to a local directory.

Build the sample

To create the build and .imagepackage files for the HelloWorld_HighLevelApp sample application, follow these steps.

  1. Create or navigate to the project build directory for your high-level application. This is the directory that will contain the .imagepackage files that will be generated during the build process. For example, to create and open a new directory called "build" you would enter the following commands:

    mkdir build
    cd build
    
  2. Update the sample to target your hardware, if necessary. By default, the samples target hardware that follows the MT3620 reference board design (RDB), such as the MT3620 Development Kit from Seeed Studios. Additional target hardware definitions for the sample applications are available in the HardwareDefinitions directory of the Azure Sphere Samples repo. For example, the hardware definition files for the Avnet MT3620 Starter Kit are in the HardwareDefinitions/avnet_mt3620_sk subdirectory.

    • Open CMakeLists.txt and update the TARGET_DIRECTORY parameter in the azure_target_hardware_definition function to point at the subdirectory for your hardware. For example:

      azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "../../../HardwareDefinitions/avnet_mt3620_sk" TARGET_DEFINITION "sample_appliance.json")
      
  3. Open a command-line interface using PowerShell, Windows command prompt, or Linux command shell. Navigate to your project build directory.

  4. From your project build directory, at the command prompt, run CMake with the following parameters:

    • -G

      Set this parameter to "Ninja" to indicate that CMake should use the Ninja generator to create the build files, as Ninja will be used to complete the build.

    • -DCMAKE_TOOLCHAIN_FILE

      Set this parameter to the path to the compiler tool chain file on your machine. For Windows, the CMAKE_TOOLCHAIN_FILE should point to C:\Program Files (x86)\Microsoft Azure Sphere SDK\CMakeFiles\AzureSphereRTCoreToolchain.cmake. For Linux, specify /opt/azurespheresdk/CMakeFiles/AzureSphereRTCoreToolchain.cmake.

    • -DAZURE_SPHERE_TARGET_API_SET

      Set this parameter to the desired Azure Sphere API set to use. In the example it is set to "latest-lts", which selects the latest set of APIs designated for long-term support.

    • -DCMAKE_BUILD_TYPE

      Set this parameter to the build type. Possible values are Debug and Release.

    • The final parameter is the path to the directory on your machine that contains the source files for the sample application. In the example the Azure Sphere samples repository was downloaded to a directory called AzSphere.

      CMake parameters are separated by spaces. The line continuation character (^ for Windows command line, \ for Linux command line, or ` for PowerShell) can be used for readability but is not required.

    The following examples show the CMake commands for the Hello World high-level app.

    Windows Command Prompt

    cmake ^
     -G "Ninja" ^
     -DCMAKE_TOOLCHAIN_FILE="C:\Program Files (x86)\Microsoft Azure Sphere SDK\CMakeFiles\AzureSphereToolchain.cmake" ^
     -DAZURE_SPHERE_TARGET_API_SET="latest-lts" ^
     -DCMAKE_BUILD_TYPE="Debug" ^
     "C:\AzSphere\azure-sphere-samples\Samples\HelloWorld\HelloWorld_HighLevelApp"
    

    Windows PowerShell

    cmake `
     -G "Ninja" `
     -DCMAKE_TOOLCHAIN_FILE="C:\Program Files (x86)\Microsoft Azure Sphere SDK\CMakeFiles\AzureSphereToolchain.cmake" `
     -DAZURE_SPHERE_TARGET_API_SET="latest-lts" `
     -DCMAKE_BUILD_TYPE="Debug" `
     "C:\AzSphere\azure-sphere-samples\Samples\HelloWorld\HelloWorld_HighLevelApp"
    
  5. Run ninja to build the application and create the image package file.

    ninja
    

When troubleshooting, especially after making any changes to your CMake commands, delete your entire build and try again.

Run the sample

  1. If your device is already running an application, delete the application:

    azsphere device sideload delete
    
  2. Change to the directory that contains the build and .imagepackage files created previously.

  3. Load the image package onto your device by running the azsphere device sideload deploy command and specifying the image package. For example:

    azsphere device sideload deploy --image-package HelloWorld_HighLevelApp.imagepackage
    

    This command loads the image package and starts the application. You should see an LED blink.

    Tip

    Note the path of the image package. You'll use the image package later in the Deployment Quickstart.

Debug the sample

  1. Change to the directory that contains the build and .imagepackage files created previously.

  2. Get the component ID if you don't already have it:

    azsphere image-package show --image-package HelloWorld_HighLevelApp.imagepackage
    

  1. If the application is running, stop it and then restart it with the --debug-mode option:

    azsphere device app stop --component-id <ComponentId>
    
    azsphere device app start --debug-mode --component-id <ComponentId>
    

You should see:

 <ComponentId>
 App state   : debugging
 GDB port    : 2345
 Output port : 2342
 Core        : High-level
  1. Use a terminal client to establish a Telnet or raw TCP connection to read the output stream from the process. Specify 192.168.35.2 as the IP address and 2342 as the port.

  2. Open a command-line interface using PowerShell or a standard command prompt on Windows, or command shell on Linux, and pass the .out app binary from your build as a parameter. This will enable full source code debugging.

    Windows Command Prompt

    "C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\gcc\arm-poky-linux-musleabi-gdb" HelloWorld_HighLevelApp.out
    

    Windows PowerShell

    & "C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\gcc\arm-poky-linux-musleabi-gdb" HelloWorld_HighLevelApp.out
    
  3. Set the remote debugging target to IP address 192.168.35.2 on port 2345:

    target remote 192.168.35.2:2345

  4. Issue whatever other gdb commands you choose. For example, the following commands set a breakpoint upon entry to main() and then continue execution after the breakpoint, respectively.

    break main
    
    c
    

    For more information about debugging with gdb, see GDB: The GNU Project Debugger or one of the other numerous sources on the subject.

Next steps

You've built a high-level application to run on your Azure Sphere device. You may want to modify it now. Hardware definitions describes how to edit a hardware definition JSON file and re-generate the associated header file.

Next, learn how to deploy your high-level application from the cloud.

See also

Visit the Azure Sphere Gallery, a collection of inspirational, unmaintained, and reusable Azure Sphere scripts, utilities, and functions.