Tutorial: Build a high-level application

• Install CMake and Ninja for Windows or for Linux.

• Install Visual Studio Code for Windows or for Linux.
• Install CMake and Ninja for Windows or for Linux.

• Install Azure Sphere extension for Visual Studio.

Build and run the high-level application with Visual Studio Code

This tutorial uses the Azure Sphere Blink template, which is part of the Azure Sphere Extension for Visual Studio Code. The Blink template blinks an LED so you can verify that the Azure Sphere device and tools are installed and set up correctly.

1. Start Visual Studio Code. Select View > Command palette, and then type Azure Sphere: Generate New Project.

   

2. Choose Blink from the Templates menu.

   

3. Visual Studio Code then displays a File Explorer window. Navigate to the folder where you want to place the Blink application. Visual Studio Code creates the Blink folder in your selected location and generates the build files for the Blink application. You should see messages from CMake.

4. Open the CMakeLists.txt file and change the TARGET_DIRECTORY setting to specify the folder that contains definitions for the hardware you're using. By default, the TARGET_DIRECTORY specifies HardwareDefinitions/mt3620_rbd, which matches the Seeed Azure Sphere MT3620 Development Kit:

   azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "HardwareDefinitions/mt3620_rdb" TARGET_DEFINITION "template_appliance.json")
   

   Several hardware definitions are provided with the template. For example, if you're using a SEEED MT3620 Mini Dev Board, specify HardwareDefinitions/seeed_mt3620_mdb instead.

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 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 pane, which displays the output from CMake/Build.

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

   Tip

   Make a note of the location of your image package, as you will need it when you create a deployment. You should see a message such as "Build files written to <path>" in the Output window, where <path> is the full path to your Blink application's build folder, typically ending in "out\ARM-Debug" or "out/ARM-Debug".

7. After a short delay, you should see an LED blink.

8. Set a breakpoint somewhere in main.c and step through the application, so that you can explore the Visual Studio Code debugging features for Azure Sphere.

Build and run the high-level application with Visual Studio

This tutorial uses the Azure Sphere Blink template, which is part of the Azure Sphere Extension for Visual Studio. The Blink template blinks an LED so you can verify that the Azure Sphere device and tools are installed and set up correctly.

1. If you are new to Visual Studio, consider the Quickstart or Guided Tour to learn about navigating and using it.

2. Open Visual Studio and select Create a new project. In the Search box, type 'azure sphere' to get a list of Azure Sphere templates. Choose Azure Sphere Blink from the list.

3. Enter a name and location for the project, and then select Create.

4. Open the CMakeLists.txt file and change the TARGET_DIRECTORY setting to specify the folder that contains definitions for the hardware you're using. By default, the TARGET_DIRECTORY specifies HardwareDefinitions/mt3620_rbd, which matches the Seeed Azure Sphere MT3620 Development Kit:

   azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "HardwareDefinitions/mt3620_rdb" TARGET_DEFINITION "template_appliance.json")
   

   Several hardware definitions are provided with the template. For example, if you're using a SEEED MT3620 Mini Dev Board, specify HardwareDefinitions/seeed_mt3620_mdb instead.

5. In Visual Studio, select View > Output to display the Output pane.

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

   

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

   Tip

   Make a note of the location of your image package, as you will need it when creating a deployment. You should see a message such as "Output file is at: <path>" in the output in View > Output > Show output from: Build, where <path> is the full path to your Blink application's build folder, typically ending in "out/ARM-Debug".

8. By default, the Output pane 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.

9. When you run the program, you should see an LED blink.

Download the sample application

You can download the HelloWorld application as follows: :

1. Point your browser to Microsoft Samples Browser.
2. Type "Azure Sphere" in the Search box.
3. Select Azure Sphere - Hello World from the search results.
4. Select Download ZIP.
5. Open the downloaded file and extract to a local directory.

Build the sample

To create the build and .imagepackage files for the HelloWorld_HighLevelApp sample application, follow these steps.

1. Update the sample to target your hardware, if necessary. By default, the samples target hardware that follows the MT3620 reference board design (RDB), such as the MT3620 Development Kit from Seeed Studios. Additional target hardware definitions for the sample applications are available in the HardwareDefinitions directory of the Azure Sphere Samples repo. For example, the hardware definition files for the Avnet MT3620 Starter Kit are in the HardwareDefinitions/avnet_mt3620_sk subdirectory.

   • Open CMakeLists.txt and update the TARGET_DIRECTORY parameter in the azure_target_hardware_definition function to point at the subdirectory for your hardware. For example:

     azsphere_target_hardware_definition(${PROJECT_NAME} TARGET_DIRECTORY "../../../HardwareDefinitions/avnet_mt3620_sk" TARGET_DEFINITION "sample_appliance.json")
     

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

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

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

Run the sample

1. If your device is already running an application, delete the application:

   azsphere device sideload delete
   

2. Change to the directory that contains the build and .imagepackage files created previously.

3. Load the image package onto your device by running the azsphere device sideload deploy command and specifying the image package. For example:

   • Azure Sphere CLI
   • Azure Sphere classic CLI

   azsphere device sideload deploy --image-package HelloWorld_HighLevelApp.imagepackage
   

   This command loads the image package and starts the application. You should see an LED blink.

   Tip

   Note the path of the image package. You'll use the image package later in the Deployment Quickstart.

Debug the sample

1. Change to the directory that contains the build and .imagepackage files created previously.

2. Get the component ID if you don't already have it:

   • Azure Sphere CLI
   • Azure Sphere classic CLI

   azsphere image-package show --image-package HelloWorld_HighLevelApp.imagepackage
   

1. If the application is running, stop it and then restart it with the --debug-mode option:

   • Azure Sphere CLI
   • Azure Sphere classic CLI

   azsphere device app stop --component-id <ComponentId>
   

   azsphere device app start --debug-mode --component-id <ComponentId>
   

You should see:

 <ComponentId>
 App state   : debugging
 GDB port    : 2345
 Output port : 2342
 Core        : High-level

1. Use a terminal client to establish a Telnet or raw TCP connection to read the output stream from the process. Specify 192.168.35.2 as the IP address and 2342 as the port.

2. Open a command-line interface using PowerShell or a standard command prompt on Windows, or command shell on Linux, and pass the .out app binary from your build as a parameter. This will enable full source code debugging.

   • Windows
   • Linux

   Windows Command Prompt

   "C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\gcc\arm-poky-linux-musleabi-gdb" HelloWorld_HighLevelApp.out
   

   Windows PowerShell

   & "C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\*sysroot*\tools\gcc\arm-poky-linux-musleabi-gdb" HelloWorld_HighLevelApp.out
   

   Note

   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.

3. Set the remote debugging target to IP address 192.168.35.2 on port 2345:

   target remote 192.168.35.2:2345

4. Run any other gdb commands you choose. For example, the following commands set a breakpoint upon entry to main() and then continue execution after the breakpoint, respectively.

   break main
   

   c
   

   For more information about debugging with gdb, see GDB: The GNU Project Debugger or one of the other numerous sources on the subject.