الملاحظات

Build and deploy partner applications

  • مقالة
  • قراءة خلال 11 دقائق

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 as described in Device capabilities and communication.

To debug on the real-time cores, use the azsphere 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:

    azsphere 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:

    azsphere 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 azsphere 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 azsphere 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:

    azsphere 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:

    azsphere 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 azsphere 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 'azsphere 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 from azsphere 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. Create or navigate to the project build directory for your real-time capable 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

  4. Open a command-line interface using PowerShell, Windows command prompt, or Linux command shell. Navigate to your project build directory.

  5. 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)\<path to SDK>\CMakeFiles\AzureSphereRTCoreToolchain.cmake. For Linux, specify /opt/azurespheresdk/CMakeFiles/AzureSphereRTCoreToolchain.cmake.

    • -DARM_GNU_PATH

      Set this parameter to the path to the directory on your machine that contains arm-none-eabi-gcc, and not the path to the compiler itself. If you are using the GNU Tools from Visual Studio, the ARM_GNU_PATH path would be in the 2019\edition\Linux\gcc_arm\bin subfolder of your Visual Studio installation, rather than the path in the example.

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

    Windows Command Prompt

    cmake ^
-G "Ninja" ^
-DCMAKE_TOOLCHAIN_FILE="C:\Program Files (x86)\Microsoft Azure Sphere SDK\CMakeFiles\AzureSphereRTCoreToolchain.cmake" ^
-DARM_GNU_PATH:STRING="C:\Program Files (x86)\GNU Arm Embedded Toolchain\9 2020-q2-update\bin" ^
-DCMAKE_BUILD_TYPE="Debug" ^
"C:\AzSphere\azure-sphere-samples\Samples\IntercoreComms\IntercoreComms_RTApp_MT3620_BareMetal"

    Windows PowerShell

    cmake `
-G "Ninja" `
-DCMAKE_TOOLCHAIN_FILE="C:\Program Files (x86)\Microsoft Azure Sphere SDK\CMakeFiles\AzureSphereRTCoreToolchain.cmake" `
-DARM_GNU_PATH:STRING="C:\Program Files (x86)\GNU Arm Embedded Toolchain\9 2020-q2-update\bin" `
-DCMAKE_BUILD_TYPE="Debug" `
"C:\AzSphere\azure-sphere-samples\Samples\IntercoreComms\IntercoreComms_RTApp_MT3620_BareMetal"

  6. From your project build directory, at the command prompt, run ninja to build the application and create the image package file.

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

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

    azsphere device sideload delete

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

    azsphere device sideload deploy --image-package <path-to-imagepackage>

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

  9. Get the component ID for the image:

    azsphere 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:

    Image package metadata:
Section: Identity
Image Type:           Application
Component ID:         <component id>
Image ID:             <image id>

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. Create or navigate to the project build directory for your high-level application. This is the directory that will contain the build .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

  4. Open a command-line interface using PowerShell, Windows command prompt, or Linux command shell. Navigate to your project build directory.

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

    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\IntercoreComms\IntercoreComms_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\IntercoreComms\IntercoreComms_HighLevelApp"

  6. From your project build directory, at the command prompt, run ninja to build the application and create the image package file.

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

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

    azsphere device sideload deploy --image-package <package-name>

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

  8. Get the component ID for the image:

    azsphere 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:

    Image package metadata:
  Section: Identity
    Image Type:           Application
    Component ID:         25025d2c-66da-4448-bae1-ac26fcdd3627
    Image ID:             49d3cb5b-0300-4e1f-904d-b730c7933c3f