Quickstart: Use a device capability model to create an IoT Plug and Play Preview device (Windows)

A device capability model (DCM) describes the capabilities of an IoT Plug and Play device. A DCM is often associated with a product SKU. The capabilities defined in the DCM are organized into reusable interfaces. You can generate skeleton device code from a DCM. This quickstart shows you how to use VS Code on Windows to create an IoT Plug and Play device using a DCM.

Prerequisites

To complete this quickstart, you need to install the following software on your local machine:

Install Azure IoT Tools

Use the following steps to install the Azure IoT Tools for VS Code extension pack:

  1. In VS Code, select the Extensions tab.
  2. Search for Azure IoT Tools.
  3. Select Install.

Install the Azure IoT explorer

Download and install the latest release of Azure IoT explorer from the tool's repository page, by selecting the .msi file under "Assets" for the most recent update.

Get the connection string for your company model repository

You can find your company model repository connection string in the Azure Certified for IoT portal portal when you sign in with a Microsoft work or school account, or your Microsoft Partner ID if you have one. After you sign in, select Company repository and then Connection strings.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Launch Cloud Shell in a new window
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block to copy the code.

  3. Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code.

Prepare an IoT hub

You also need an Azure IoT hub in your Azure subscription to complete this quickstart. If you don't have an Azure subscription, create a free account before you begin. If you don't have an IoT hub, follow these instructions to create one.

Important

During public preview, IoT Plug and Play features are only available on IoT hubs created in the Central US, North Europe, and Japan East regions.

If you're using the Azure CLI locally, first sign in to your Azure subscription using az login. If you're running these commands in the Azure Cloud Shell, you're signed in automatically.

If you're using the Azure CLI locally, the az version should be 2.0.73 or later; the Azure Cloud Shell uses the latest version. Use the az --version command to check the version installed on your machine.

Run the following command to add the Microsoft Azure IoT Extension for Azure CLI to your instance:

az extension add --name azure-cli-iot-ext

Run the following command to create the device identity in your IoT hub. Replace the YourIoTHubName and YourDeviceID placeholders with your own IoT Hub name and a device ID of your choice.

az iot hub device-identity create --hub-name <YourIoTHubName> --device-id <YourDeviceID>

Run the following command to get the device connection string for the device you just registered (note for use later):

az iot hub device-identity show-connection-string --hub-name <YourIoTHubName> --device-id <YourDeviceID> --output table

Run the following command to get the IoT hub connection string for your hub (note for use later):

az iot hub show-connection-string --hub-name <YourIoTHubName> --output table

Prepare the development environment

In this quickstart, you use the Vcpkg library manager to install the Azure IoT C device SDK in your development environment.

  1. Open a command prompt. Execute the following command to install Vcpkg:

    git clone https://github.com/Microsoft/vcpkg.git
    cd vcpkg
    
    .\bootstrap-vcpkg.bat
    

    Then, to hook up user-wide integration, run the following (note: requires admin on first use):

    .\vcpkg.exe integrate install
    
  2. Install Azure IoT C device SDK Vcpkg:

    .\vcpkg.exe install azure-iot-sdk-c[public-preview,use_prov_client]
    

Author your model

In this quickstart, you use an existing sample device capability model and associated interfaces.

  1. Create a pnp_app folder in your local drive. You use this folder for the device model files and device code stub.

  2. Download the device capability model and interface sample files and interface sample and save the files into the pnp_app folder.

    Tip

    To download a file from GitHub, navigate to the file, right-click on Raw, and then select Save link as.

  3. Open pnp_app folder with VS Code. You can view the files with IntelliSense:

    Device capability model

  4. In the files you downloaded, replace <YOUR_COMPANY_NAME_HERE> in the @id and schema fields with a unique value. Use only the characters a-z, A-Z, 0-9, and underscore. For more information, see Digital Twin identifier format.

Generate the C code stub

Now that you have a DCM and its associated interfaces, you can generate the device code that implements the model. To generate the C code stub in VS Code:

  1. With the pnp_app folder open in VS Code, use Ctrl+Shift+P to open the command palette, enter IoT Plug and Play, and select Generate Device Code Stub.

    Note

    The first time you use the IoT Plug and Play CodeGen CLI, it takes a few seconds to download and install automatically.

  2. Choose the SampleDevice.capabilitymodel.json file to use for generating the device code stub.

  3. Enter the project name sample_device. This is the name of your device application.

  4. Choose ANSI C as your language.

  5. Choose Via IoT Hub device connection string as connection method.

  6. Choose CMake Project on Windows as your project template.

  7. Choose Via Vcpkg as the way to include the device SDK.

  8. A new folder called sample_device is created in the same location as the DCM file, and in it are the generated device code stub files. VS Code opens a new window to display these. Device code

Build and run the code

You use the Vcpkg package to build the generated device code stub. The application you build simulates a device that connects to an IoT hub. The application sends telemetry and properties and receives commands.

  1. Create a cmake subdirectory in the sample_device folder, and navigate to that folder:

    mkdir cmake
    cd cmake
    
  2. Run the following commands to build the generated code stub (replacing the placeholder with the directory of your Vcpkg repo):

    cmake .. -G "Visual Studio 16 2019" -A Win32 -Duse_prov_client=ON -Dhsm_type_symm_key:BOOL=ON -DCMAKE_TOOLCHAIN_FILE="<directory of your Vcpkg repo>\scripts\buildsystems\vcpkg.cmake"
    
    cmake --build .
    

    Note

    If you are using Visual Studio 2017 or 2015, you need to specify the CMake generator based on the build tools you are using:

    # Either
    cmake .. -G "Visual Studio 15 2017" -Duse_prov_client=ON -Dhsm_type_symm_key:BOOL=ON -DCMAKE_TOOLCHAIN_FILE="{directory of your Vcpkg repo}\scripts\buildsystems\vcpkg.cmake"
    # or
    cmake .. -G "Visual Studio 14 2015" -Duse_prov_client=ON -Dhsm_type_symm_key:BOOL=ON -DCMAKE_TOOLCHAIN_FILE="{directory of your Vcpkg repo}\scripts\buildsystems\vcpkg.cmake"
    

    Note

    If cmake can't find your C++ compiler, you get build errors when you run the previous command. If that happens, try running this command at the Visual Studio command prompt.

  3. After the build completes successfully, run your application, passing the IoT hub device connection string as a parameter.

    .\Debug\sample_device.exe "<YourDeviceConnectionString>"
    
  4. The device application starts sending data to IoT Hub.

    Device app running

Validate the code

Publish device model files to model repository

To validate the device code with Azure IoT Explorer, you need to publish the files to the model repository.

  1. With the pnp_app folder open in VS Code, use Ctrl+Shift+P to open the command palette, type and select IoT Plug & Play: Submit files to Model Repository.

  2. Select SampleDevice.capabilitymodel.json and EnvironmentalSensor.interface.json files.

  3. Enter your company model repository connection string.

    Note

    The connection string is only required the first time you connect to the repository.

  4. In VS Code output window and notification, you can check that the files have been published successfully.

    Note

    If you get errors on publishing the device model files, you can try use command IoT Plug and Play: Sign out Model Repository to sign out and go through the steps again.

Use the Azure IoT explorer to validate the code

  1. Open Azure IoT explorer. You see the App configurations page.

  2. Enter your IoT Hub connection string and select Connect.

  3. After you connect, you see the Devices overview page.

  1. To add your company repository, select Settings, then + Add module definition source, then Company repository. Add your company model repository connection string, and select Save and Connect.

  2. Back on the Devices overview page, find the device identity you created previously. With the device application still running in the command prompt, check that the device's Connection state in Azure IoT explorer is reporting as Connected (if not, hit Refresh until it is). Select the device to view more details.

  3. Expand the interface with ID urn:<YOUR_INTERFACE_NAME>:EnvironmentalSensor:1 to see the IoT Plug and Play primitives - properties, commands, and telemetry. The interface name that will appear is the name you put in when authoring your model.

  1. Select the Telemetry page and hit Start to view the telemetry data the device is sending.

  2. Select the Properties (non-writable) page to view the non-writable properties reported by the device.

  3. Select the Properties (writable) page to view the writable properties you can update.

  4. Expand property name, update with a new name and select Update writable property.

  5. To see the new name show up in the Reported Property column, select the Refresh button on top of the page.

  6. Select the Commands page to view all the commands the device supports.

  7. Expand the blink command and set a new blink time interval. Select Send command to call the command on the device.

  8. Go to the simulated device command prompt and read through the printed confirmation messages, to verify that the commands have executed as expected.

Clean up resources

If you plan to continue with additional IoT Plug and Play articles, you can keep and reuse the resources you used in this quickstart. Otherwise, you can delete the resources you created in this quickstart to avoid additional charges.

You can delete both the hub and registered device at once by deleting the entire resource group with the following command for Azure CLI. (Don't use this, however, if these resources are sharing a resource group with other resources you have for different purposes.)

az group delete --name <YourResourceGroupName>

To delete just the IoT hub, run the following command using Azure CLI:

az iot hub delete --name <YourIoTHubName>

To delete just the device identity you registered with your IoT hub, run the following command using Azure CLI:

az iot hub device-identity delete --hub-name <YourIoTHubName> --device-id <YourDeviceID>

You may also want to remove the cloned sample files from your development machine.

Next steps

In this quickstart, you learned how to create an IoT Plug and Play device using a DCM.

To learn more about DCMs and how to create your own models, continue to the tutorial: