الملاحظات

Build a real-time capable application

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

You can use Visual Studio, Visual Studio Code, or the command line (CLI) to develop and debug real-time capable applications (RTApps) in much the same way as high-level applications.

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 the RTApp using Visual Studio Code

To build an RTApp:

  1. In Visual Studio Code, open the HelloWorld_RTApp_MT3620_BareMetal folder in your clone of the Azure Sphere samples repo. If you're prompted to select a kit, choose "Do not use a kit."

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

  3. The connected terminal emulator should display output from the application. The program sends the following words at one-second intervals:

    Tick

    Tock

    Note

    Visual Studio Code provides Intellisense, but it won't automatically update when you modify CMakeLists.txt. You need to run the CMake: Delete Cache and Reconfigure command to refresh Intellisense. The CMake targets view can be found in the CMake extension view on the left bar.

Build the RTApp using Visual Studio

To build an RTApp:

  1. In Visual Studio, select File > CMake and navigate to the folder that contains the sample.

  2. If CMake generation does not start automatically, select the CMakeLists.txt file.

  3. In Visual Studio, View > Output > Show output from: CMake output should show the messages CMake generation started. and CMake generation finished.

  4. On the CMake menu (if present), select Build All. If the menu is not present, open Solution Explorer, right-click the CMakeLists.txt file, and select Build. The output location of the Azure Sphere application appears in the Output window.

  5. Press F5 to deploy the application.

  6. The connected terminal emulator should display output from the application. The program sends the following words at one-second intervals:

    Tick

    Tock

    Note

    • Visual Studio provides Intellisense for Azure Sphere RTApps by gathering data from its CMake cache. Visual Studio updates the cache whenever the CMakeLists.txt or CMakeSettings.json file in the RTApp changes.

    • By default, Visual Studio uses the Folder view. If you prefer a logical view of the CMake project, you can change to the CMake Targets view. In Solution Explorer, select the folder toggle icon:

      Toggle between Solution and Folder views

      From the drop-down menu, select CMake Targets View.

    • The application might begin executing before OpenOCD makes a connection. As a result, breakpoints set early in the code might be missed. A simple workaround for this is to delay the start of the app until OpenOCD connects.

      1. Insert the following code at the beginning of the application entry point RTCoreMain. This will cause the application to enter and remain in a while loop until variable f is set to true.

          volatile bool f = false;
  while (!f) {
    // empty.
  }

      2. Press F5 to start the app with debugging and then break into execution.

      3. In the Locals debug pane, change the value of f from zero to one.

      4. Step through the code as normal.

Build RTApp using the CLI

The instructions that follow assume you're using CMake. If you prefer to build on the command line without using CMake, you can determine the appropriate compiler and linker options by looking at the AzureSphereToolchainBase.cmake and AzureSphereRTCoreToolchain.cmake files, which are installed with the Azure Sphere SDK.

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

  2. Create or navigate to the directory that will contain the build and .imagepackage files that will be generated during the build process. For example, to create and open a new directory called "buildfiles" you would enter the following commands at the command line:

    mkdir buildfiles

    cd buildfiles

  3. 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 HelloWorld 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\HelloWorld\HelloWorld_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\HelloWorld\HelloWorld_RTApp_MT3620_BareMetal"

Log output from an RTApp

Each real-time core on the MT3620 has a dedicated UART that is intended for logging output. The real-time cores can also access the ISU UARTs. The MT3620 RDB exposes only the TX pin, which you can use to display log output from the application. Other hardware may expose this differently, or not at all. To see the log output, set up your hardware to display this output as described in the quickstart. The dedicated UART doesn't require the Uart application manifest requirement; however, it shouldn't be used for purposes other than logging output for an RTApp.

Develop with partner apps

When you load an application onto the Azure Sphere device, the Azure Sphere deployment tools by default delete all existing applications. To prevent this from happening when you develop applications that communicate with each other, you need to mark the applications as partners. When you deploy one of the applications, its partners will not be deleted. See Mark applications as partners for details.

Troubleshooting

If you encounter problems, see Troubleshooting real-time capable applications.