Quickstart: Connect a sample IoT Plug and Play Preview device application to IoT Hub (Java)

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 information it sends to the hub. The sample application is written in Java, and is provided as part of the Azure IoT Samples for Java collection. A solution developer 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.

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.

Prerequisites

To complete this quickstart, you need Java SE 8 on your development machine. You also need to install Maven 3.

For details on how to get set up with these, see Prepare your development environment in the Microsoft Azure IoT device SDK for Java.

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.

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.

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

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 prepare a development environment you can use to clone and build the Azure IoT Samples for Java.

Open a terminal window in the directory of your choice. Execute the following command to clone the Azure IoT Samples for Java GitHub repository into this location:

git clone https://github.com/Azure-Samples/azure-iot-samples-java

This operation may take several minutes to complete.

Build the code

You use the cloned sample code to build an application simulating a device that connects to an IoT hub. The application sends telemetry and properties and receives commands.

  1. In a local terminal window, go to the folder of your cloned repository and navigate to the /azure-iot-samples-java/digital-twin/Samples/device/JdkSample folder. Then run the following command to install the required libraries and build the simulated device application:

    mvn clean install -DskipTests
    
  2. Configure the device connection string:

    set DIGITAL_TWIN_DEVICE_CONNECTION_STRING=<YourDeviceConnectionString>
    

Run the device sample

Run a sample application to simulate an IoT Plug and Play device that sends telemetry to your IoT hub. To run the sample application, use the following command:

java -jar environmental-sensor-sample\target\environmental-sensor-sample-with-deps.jar

You see messages saying that the device is connected, performing various setup steps, and waiting for service updates, followed by telemetry logs. This indicates that the device is now ready to receive commands and property updates, and has begun sending telemetry data to the hub. Keep the sample running as you complete the next steps.

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 ensure the tool can read the interface model definitions from your device, select Settings. In the Settings menu, On the connected device may already appear in the Plug and Play configurations; if it does not, select + Add module definition source and then On the connected device to add it.

  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:java_sdk_sample:EnvironmentalSensor:1 to reveal the interface and IoT Plug and Play primitives—properties, commands, and telemetry.

  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've learned how to connect an IoT Plug and Play device to an IoT hub. To learn more about how to build a solution that interacts with your IoT Plug and Play devices, see: