Share via

Build and deploy partner applications

  • Article

This section describes how to build, package, and deploy Azure Sphere partner applications.

These instructions use the IntercoreComms sample applications as an example.

Prerequisites

Enable 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 debugging. By default, Azure Sphere devices are "locked"; that is, they do not allow applications under development to be loaded from a PC, and they do not allow debugging of applications. Preparing the device for debugging removes this restriction and loads software required for debugging and unlocks device capabilities .

To debug on the real-time cores, use the az sphere device enable-development command. This command configures the device to accept applications from a PC for debugging and assigns the device to the Development device group, which 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.

On Windows, you must add the --enable-rt-core-debugging parameter, which loads the debugging servers and required drivers for each type of core onto the device.

  1. Log in to Azure Sphere if you haven't already done so:

    az login

  2. Open a command-line interface using PowerShell or Windows Command Prompt with administrator privileges. The --enable-rt-core-debugging parameter requires administrator privilege because it installs USB drivers for the debugger.

  3. Enter the following command:

    az sphere device enable-development --enable-rt-core-debugging  --catalog <CatalogName>  --resource-group <ResourceGroupName>

  4. Close the window after the command completes because administrator privilege is no longer required. As a best practice, you should always use the lowest privilege that can accomplish a task.

If the az sphere device enable-development command fails, see Troubleshoot Azure Sphere problems for help.

Enable 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 debugging. By default, Azure Sphere devices are "locked"; that is, they do not allow applications under development to be loaded from a PC, and they do not allow debugging of applications. Preparing the device for debugging removes this restriction and loads software required for debugging and unlocks device capabilities as described in Device capabilities and communication.

To debug on the real-time cores, use the az sphere device enable-development command. This command configures the device to accept applications from a PC for debugging and assigns the device to the Development device group, which 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.

On Windows, you must add the --enable-rt-core-debugging parameter, which loads the debugging servers and required drivers for each type of core onto the device.

  1. Log in to Azure if you haven't already done so:

    az login

  2. Open a command-line interface using PowerShell, Windows Command Prompt, or Linux command shell with administrator privileges. The --enable-rt-core-debugging parameter requires administrator privilege because it installs USB drivers for the debugger.

  3. Enter the following command:

    az sphere device enable-development --enable-rt-core-debugging

  4. Close the window after the command completes because administrator privilege is no longer required. As a best practice, you should always use the lowest privilege that can accomplish a task.

If the az sphere device enable-development command fails with the following error message, see Troubleshoot Azure Sphere problems for help.

error: The device did not accept the device capability configuration. Please check the Azure Sphere OS on your device is up-to-date using 'az sphere device show-deployment-status'.

Build partner apps with Visual Studio

  1. Ensure that your device is connected to your PC by USB. In the Set startup item menu, select Azure Sphere App (All Cores) where Azure Sphere App is the name of your top-level project or press F5.

    Remote GDB Debugger button

  2. If you are prompted to build the project, select Yes. Visual Studio compiles the partner applications, creates image packages, sideloads them onto the board, and starts them in debug mode. Sideloading means that the applications are delivered directly from the PC over a wired connection, rather than delivered through the cloud.

    Note the paths in the View > Output > Show output from: Build output, which indicates the location of the output image packages on your PC. When you are ready to create a deployment, you will need to know the paths to the image packages.

  3. 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 partner apps with Visual Studio Code

  1. Open the folder containing your partner applications. Visual Studio Code detects the workspace file and asks if you want to open the workspace. Select Open Workspace to open both the real-time application and high-level application at once.

  2. Right-click on either of the two CMakeLists.txt files and select Build All Projects.

  3. Click the Run icon in the Visual Studio Code Activity Bar.

  4. On the pulldown menu that appears at the top of the window on the left side of the screen, select Launch Azure Sphere Apps (gdb)(workspace).

  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 applications, create the image packages, deploy them to the board, and start them in debug mode. You'll see status updates in the Output pane along the way.

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

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

Compile and build the application

To build your applications with the CLI, 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 that 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.

When building with the CLI, first build and deploy the real-time capable application, then build and deploy the high-level application.

Build and deploy the real-time capable application

  1. Navigate to the folder containing your real-time capable application.

  2. Open the app_manifest.json file and verify that the high-level app's component ID is shown in the AllowedApplicationConnections capability.

  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:

    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 IntercoreComms RTApp:

    Windows Command Prompt

    cmake ^
--preset "ARM-Debug" ^
"C:\AzSphere\azure-sphere-samples\Samples\IntercoreComms\IntercoreComms_RTApp_MT3620_BareMetal"

    Windows PowerShell

    cmake `
--preset "ARM-Debug" `
"C:\AzSphere\azure-sphere-samples\Samples\IntercoreComms\IntercoreComms_RTApp_MT3620_BareMetal"

  5. From your project build directory, at the command prompt, 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.

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

  6. Delete any applications that are already deployed to the device:

    az sphere device sideload delete

  7. From your project build directory, at the command prompt, load the image package that Ninja created:

    az sphere device sideload deploy --image-package <path-to-imagepackage>

    The application will start to run soon after it's loaded.

  8. Get the component ID for the image:

    az sphere image-package show --image-package <path-to-imagepackage>

    The command returns all the metadata for the image package. The component ID for the application appears in the Identity section for the Application Image Type. For example:

    ...
  "Identity": {
    "ComponentId": "<component-id>",
    "ImageId": "<image-id>",
    "ImageType": "Application"
  },
...

Build and deploy the high-level application

  1. Navigate to the folder containing your high-level application.

  2. Open the app_manifest.json file and verify that the RTApp's component ID is shown in the AllowedApplicationConnections capability.

  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:

    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 IntercoreComms high-level application.

    Windows Command Prompt

    cmake ^
--preset "ARM-Debug" ^
"C:\AzSphere\azure-sphere-samples\Samples\IntercoreComms\IntercoreComms_HighLevelApp"

    Windows PowerShell

    cmake `
--preset "ARM-Debug" `
"C:\AzSphere\azure-sphere-samples\Samples\IntercoreComms\IntercoreComms_HighLevelApp"

  5. From your project build directory, at the command prompt, 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.

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

  6. From your project build directory, at the command prompt, load the image package that Ninja created:

    az sphere device sideload deploy --image-package <package-name>

    The application will start to run soon after it's loaded.

  7. Get the component ID for the image:

    az sphere image-package show --image-package <path-to-imagepackage>

    The command returns all the metadata for the image package. The component ID for the application appears in the Identity section for the Application Image Type. For example:

      "ComponentId": "<component-ID>",
...
  "Identity": {
    "ComponentId": "<component-id>",
    "ImageId": "<image-id>",
    "ImageType": "Application"
  },
...