Build a high-level application

Article
08/08/2023

This section describes how to build, package, and deploy an Azure Sphere high-level application.

These instructions use the HelloWorld_HighLevelApp sample application as an example.

Prerequisites

Connect your Azure Sphere device to your computer
Install Azure Sphere

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 az sphere 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.

Make sure that your Azure Sphere device is connected to your computer, and your computer is connected to the internet.
Open a command-line interface using PowerShell, Windows Command Prompt, or Linux command shell.

Enter the following command:

az sphere device enable-development --resource-group <ResourceGroupName> --catalog <CatalogName> --device <DeviceIdValue>

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 az sphere device enable-development command fails, see Troubleshoot Azure Sphere problems for help.

Build and deploy the application in Visual Studio with debugging

Ensure that your device is connected to your PC by USB. In the Set startup item menu, select Azure Sphere App (HLCore) where Azure Sphere App is the name of your current high-level application or press F5.
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 of the image package in the View > Output > Show output from: Build output. You'll use the image ID later in Tutorial: Create a cloud deployment.
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.

Build and deploy the application in Visual Studio without debugging

Ensure that your device is connected to your PC by USB. In the Debug menu, select Start without Debugging or press Ctrl+F5.
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. Sideloading means that the application is delivered directly from the PC over a wired connection, rather than delivered through the cloud.
By default, the Output window shows output from Device Output.

Build and deploy the application in Visual Studio Code with debugging

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.
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 pane shows the result as the image package is deployed to the device. Finally, the Debug Console receives focus and shows debugger output.

Build and deploy the application in Visual Studio Code without debugging

Ensure that your device is connected to your PC by USB. In the Run menu, select Start without Debugging or press Ctrl+F5 to build and run 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.
Wait several seconds for Visual Studio Code to build the application, create an image package, deploy it to the board, and start it. 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. The app starts automatically after it is deployed to the device.

Build the application

To build your application you will need to find the correct compilation tools, headers, and libraries—collectively called the sysroot—on your computer. The Azure Sphere SDK ships with multiple sysroots so applications can target different API sets, as described in Application runtime version, sysroots, and Beta APIs. The sysroots are installed in the Azure Sphere SDK installation folder under Sysroots.

Create or navigate to the directory that will contain the files to be generated during the build process.
If your application depends on another application, mark the applications as partners in their app_manifest.md files.
Add or update the CMakeLists.txt file for your application to call the Azure Sphere CMake functions as necessary.
From your project build directory, at the command prompt, run CMake with the following parameters:
```
cmake --preset <preset-name> <source-path>
```
- --preset <preset-name>
  
  The build configuration preset name as defined in CMakePresets.json.
- --build <cmake-path>
  
  The binary directory that contains the CMake cache. For example, if you run CMake on an Azure Sphere sample, the build command would be cmake --build out/ARM-Debug.
- <source-path>
  
  The path of the directory 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
- Linux
Windows Command Prompt
```
cmake ^
 --preset "ARM-Debug" ^
 "C:\AzSphere\azure-sphere-samples\Samples\HelloWorld\HelloWorld_HighLevelApp"
```
Windows PowerShell
```
cmake `
 --preset "ARM-Debug" `
 "C:\AzSphere\azure-sphere-samples\Samples\HelloWorld\HelloWorld_HighLevelApp"
```
```
cmake \
 --preset "ARM-Debug" \
 ./AzSphere/azure-sphere-samples/Samples/HelloWorld/HelloWorld_HighLevelApp
```
Run Ninja to build the application and create the image package file:
```
ninja -C out/ARM-Debug
```
Ninja places the resulting application and .imagepackage files in the specified directory.

You can also invoke Ninja through CMake with the following command:
```
cmake --build out/<binary-dir>
```
Set <binary-dir> to the binary directory that contains the CMake cache. For example, if you run CMake on an Azure Sphere sample, the build command would be cmake --build out/ARM-Debug.

Deploy the application

Make sure your device has the appDevelopment capability so you can sideload the application and ensure that the debugging server is present. Use the az sphere device enable-development command if necessary.

If your device is already running one or more applications, delete them.
```
az sphere device sideload delete
```
Note that this command deletes all the applications on the device. If you've already deployed an RTApp that is a partner to the high-level app, use the --component-id parameter to specify which application to delete. You can find the component ID of the application in its app_manifest.json file.
Load the image package onto your device by running the az sphere device sideload deploy command and specifying the image package. For example:
```
az sphere device sideload deploy --image-package C:\Users\LocalSamples\HelloWorld\HelloWorld_HighLevelApp\out\ARM-Debug\HelloWorld_HighLevelApp.imagepackage
```
Your application should start running.

You can later stop and restart the application by using the az sphere device app stop --component-id <component-ID> and az sphere device app start --component-id <component ID> commands.