Quickstart: Build the Blink sample application

This quickstart shows how to enable application development on an Azure Sphere device and how to build and debug a sample application. It uses the Blink sample, which is part of the Azure Sphere SDK. The Blink sample shows how to access GPIOs and LEDs on the development board.

Prerequisites

The steps in this quickstart assume that:

  • Your Azure Sphere device is connected to your PC
  • You have completed all the steps to install Azure Sphere

Prepare your device for development and debugging

Before you can run the sample applications on your Azure Sphere device or develop new applications for it, you must enable development and debugging on the board. 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. Prepping the device for debugging removes this restriction.

The azsphere device prep-debug command configures the device to accept applications from a PC for debugging and loads the debugging server onto the device. It also assigns the device to a device group that does not allow over-the-air (OTA) application updates. During application development and debugging, you should leave the device in this group so that OTA application updates do not overwrite the application under development.

To prep your device

  1. Make sure that your Azure Sphere device is connected to your PC, and your PC is connected to the internet.

  2. In an Azure Sphere Developer Command Prompt window, type the following command:

    azsphere device prep-debug
    

    You should see output similar to the following:

    Getting device capability configuration for application development.
    Downloading device capability configuration for device ID 'ABCDE082513B529C45098884F882B2CA6D832587CAAE1A90B1CEC4A376EA2F22A96C4E7E1FC4D2AFF5633B68DB68FF4420A5588B420851EE4F3F1A7DC51399ED'.
    Successfully downloaded device capability configuration.
    Successfully wrote device capability configuration file 'C:\Users\user\AppData\Local\Temp\tmpD732.tmp'.
    Setting device group ID 'a6df7013-c7c2-4764-8424-00cbacb431e5' for device with ID 'ABCDE082513B529C45098884F882B2CA6D832587CAAE1A90B1CEC4A376EA2F22A96C4E7E1FC4D2AFF5633B68DB68FF4420A5588B420851EE4F3F1A7DC51399ED'.
    Successfully disabled over-the-air updates.
    Enabling application development capability on attached device.
    Applying device capability configuration to device.
    Successfully applied device capability configuration to device.
    The device is rebooting.
    Installing debugging server to device.
    Installation started.
    Application development capability enabled.
    Successfully set up device 'ABCDE082513B529C45098884F882B2CA6D832587CAAE1A90B1CEC4A376EA2F22A96C4E7E1FC4D2AFF5633B68DB68FF4420A5588B420851EE4F3F1A7DC51399ED' for application development, and disabled over-the-air updates.
    Command completed successfully in 00:00:17.1861625.
    

The device remains enabled for debugging and closed to OTA application updates until you explicitly change it. To disable debugging and allow application updates, use the azsphere device prep-field command.

You can also create your own device group that does not enable OTA application updates. See azsphere device-group create and azsphere device update-device-group for details.

  1. Start Visual Studio 2017 and go to File>New>Project. The templates for Azure Sphere are available in Visual C++>Cross Platform>Azure Sphere. Select Blink Sample for MT3620 RDB (Azure Sphere).

    Azure Sphere templates in Visual Studio

  2. Enter a name and location for the project and select OK.

    The project opens with two windows in the editor: main.c and Mt3620Blink. The MT3620Blink window is a Visual Studio Overview page for the project, which links to information about your device and Azure Sphere application development.

  3. Navigate to the line that tests the value of newButtonState and press F9 to set a breakpoint:

    if (newButtonState == GPIO_Value_Low) {

  4. Ensure that your board is connected to your PC by USB. Then select Remote GDB Debugger from the menu bar or press F5.

    Remote GDB Debugger button

  5. 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 over the air (OTA) by Wi-Fi.

    Tip

    Note the path in the Build output, which indicates the location of the image package on your PC. You'll use the image package later in the Deployment Quickstart.

  6. Press button A. Visual Studio stops at the breakpoint that you set. Open Debug>Windows and select Autos to display the variables that are used in the current and previous statements. Visual Studio populates the call stack and the auto variables after program execution stops at the breakpoint. In the following example, the value of the newButtonState variable is 0, equal to GPIO_Value_Low, which indicates a button press.

    newButtonState value in Autos

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

  8. Select Continue. Execution pauses again at this breakpoint. Now the value of newButtonState variable is 1, equal to GPIO_Value_High, which indicates a button release. Press F9 to remove the breakpoint. Now, each time you press and release Button A, the blink rate changes.

  9. When you are done debugging, select the Stop icon in the menu bar or press Shift+F5.

Next steps

This quickstart showed how to prepare your Azure Sphere device for debugging and how to build and debug an application.

Next, learn how to deploy the application over the air.