Build a real-time capable application

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.

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

     

     From the dropdown 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. 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 HelloWorld RTApp:

   • Windows
   • Linux

   Windows Command Prompt

   cmake ^
   --preset "ARM-Debug" ^
   "C:\AzSphere\azure-sphere-samples\Samples\HelloWorld\HelloWorld_RTApp_MT3620_BareMetal"
   

   Windows PowerShell

   cmake `
   --preset "ARM-Debug" `
   "C:\AzSphere\azure-sphere-samples\Samples\HelloWorld\HelloWorld_RTApp_MT3620_BareMetal"
   

3. 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.

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

   az sphere device sideload delete
   

5. Deploy the image package that Ninja created:

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

6. 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"
     },
   ...
   

7. Determine which core your app is running on.

   By default, the RTApp is deployed to the first available real-time core on the device; you cannot currently specify a particular core. To find out which core the application is running on, use the az sphere device app command to stop and then restart the application. Supply the component ID for the application in the commands. For example:

   az sphere device app stop --component-id <component id>
   <component id>: App state: stopped
   

   az sphere device app start --component-id <component id>
   <component id>
   App state: running
   Core     : Real-time 0
   

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

   Tick

   Tock