Skip to content

Latest commit

 

History

History
143 lines (93 loc) · 5.54 KB

iot-pnp-connect-device-c.md

File metadata and controls

143 lines (93 loc) · 5.54 KB
author ms.author ms.service ms.topic ms.date
dominicbetts
dobett
iot-pnp
include
11/20/2020

This quickstart shows you how to build a sample IoT Plug and Play device application, connect it to your IoT hub, and use the Azure IoT explorer tool to view the telemetry it sends. The sample application is written in C and is included in the Azure IoT device SDK for C. A solution builder can use the Azure IoT explorer tool to understand the capabilities of an IoT Plug and Play device without the need to view any device code.

Prerequisites

[!INCLUDE iot-pnp-prerequisites]

You can run this quickstart on Linux or Windows. The shell commands in this quickstart follow the Linux convention for path separators '/', if you're following along on Windows be sure to swap these separators for '\'.

The prerequisites differ by operating system:

Linux

This quickstart assumes you're using Ubuntu Linux. The steps in this quickstart were tested using Ubuntu 18.04.

To complete this quickstart on Linux, install the following software on your local Linux environment:

Install GCC, Git, cmake, and all the required dependencies using the apt-get command:

sudo apt-get update
sudo apt-get install -y git cmake build-essential curl libcurl4-openssl-dev libssl-dev uuid-dev

Verify the version of cmake is above 2.8.12 and the version of GCC is above 4.4.7.

cmake --version
gcc --version

Windows

To complete this quickstart on Windows, install the following software on your local Windows environment:

Download the code

In this quickstart, you prepare a development environment you can use to clone and build the Azure IoT Hub Device C SDK.

Open a command prompt in the directory of your choice. Execute the following command to clone the Azure IoT C SDKs and Libraries GitHub repository into this location:

git clone https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init

Expect this operation to take several minutes to complete.

Build the code

You use the device SDK to build the included sample code:

  1. Create a cmake subdirectory in the root folder of the device SDK, and navigate to that folder:

    cd azure-iot-sdk-c
mkdir cmake
cd cmake

  2. Run the following commands to build the SDK and samples:

    cmake -Duse_prov_client=ON -Dhsm_type_symm_key=ON -Drun_e2e_tests=OFF ..
cmake --build .

Tip

On Windows, you can open the solution generated by the cmake command in Visual Studio 2019. Open the azure_iot_sdks.sln project file in the cmake directory and set the pnp_simple_thermostat project as the startup project in the solution. You can now build the sample in Visual Studio and run it in debug mode.

Run the device sample

[!INCLUDE iot-pnp-environment]

To learn more about the sample configuration, see the sample readme.

To run the sample application in the SDK that simulates an IoT Plug and Play device sending telemetry to your IoT hub:

From the cmake folder, navigate to the folder that contains the executable file and run it:

# Bash
cd iothub_client/samples/pnp/pnp_simple_thermostat/
./pnp_simple_thermostat
REM Windows
cd iothub_client\samples\pnp\pnp_simple_thermostat\Debug
.\pnp_simple_thermostat.exe

Tip

To trace the code execution in Visual Studio on Windows, add a break point to the main function in the pnp_simple_thermostat.c file.

The device is now ready to receive commands and property updates, and has started sending telemetry data to the hub. Keep the sample running as you complete the next steps.

Use Azure IoT explorer to validate the code

After the device client sample starts, use the Azure IoT explorer tool to verify it's working.

[!INCLUDE iot-pnp-iot-explorer.md]

Review the code

This sample implements a simple IoT Plug and Play thermostat device. The model this sample implements doesn't use IoT Plug and Play components. The DTDL model file for the thermostat device defines the telemetry, properties, and commands the device implements.

The device code uses the standard function to connect to your IoT hub:

deviceHandle = IoTHubDeviceClient_CreateFromConnectionString(connectionString, MQTT_Protocol)

The device sends the model ID of the DTDL model it implements in the connection request. A device that sends a model ID is an IoT Plug and Play device:

static const char g_ModelId[] = "dtmi:com:example:Thermostat;1";

...

IoTHubDeviceClient_SetOption(deviceHandle, OPTION_MODEL_ID, modelId)

The code that updates properties, handles commands, and sends telemetry is identical to the code for a device that doesn't use the IoT Plug and Play conventions.

The code uses the Parson library to parse JSON objects in the payloads sent from your IoT hub:

// JSON parser
#include "parson.h"