Change Device Properties with IoT Hub Direct Methods

1 hour
  • 3 Learning Objectives

About this Hands-on Lab

The primary purpose for an Azure IoT hub is to be somewhere the devices, or “things,” can send telemetry. But did you know it can talk *back* to the things as well? Standard Tiers of Azure IoT Hub allow for cloud-to-device communication. One of the options by which we can communicate from our backend applications to our devices is by using direct methods. Direct methods are used for communications that require immediate confirmation of the result and are often used for interactive control of devices.

In this hands-on lab, we will create a device in a preprovisioned Azure IoT hub and then use a Node.js application to simulate the physical device. As our device sends telemetry information back to the IoT hub, we will use a feature in the Azure portal to send a direct method to the device, forcing it to change the interval by which it provides telemetry.

Learning Objectives

Successfully complete this lab by achieving the following learning objectives:

Register a Device in Azure IoT Hub
  1. Open the link for this lab in an incognito or InPrivate browser window.
  2. Enter the credentials assigned to this lab (they will be different from the credentials you see in the solution video; each student gets a unique lab session and credentials).
  3. Navigate to the only IoT Hub already deployed and register a device. Name the device whatever you choose.
  4. Copy the Primary Connection String from the device to a text document.

    Tip: Make sure you copy the Primary Connection String and not just the Primary Key.

Configure and Run Simulated Device in Cloud Shell
  1. Launch Cloud Shell from within the Azure Portal, choosing the "Bash" environment in order to use Azure CLI.
  2. When prompted to initialize storage for Cloud Shell, select Advanced settings and add the storage account and file share. Note that the storage account name must be universally unique. You might want to use the random characters at the beginning of the resource group name as a part of your storage account name.
  3. Install the Azure IoT extension for Azure CLI:
    az extension add --name azure-iot
  4. Download the sample Node.js application by cloning the Git repository, below. This sample application acts as a simulated device. it includes a method that handles the direct method call from the hub or another backend application.
    git clone https://github.com/Azure-Samples/azure-iot-samples-node.git 
  5. Change to the directory for the Device Twin lab:
    cd azure-iot-samples-node/iot-hub/Quickstarts/simulated-device-2
  6. Install the Node dependencies for the sample application:
    npm install
  7. In the top menu of the Cloud Shell terminal window, select the curly brackets icon to open the editor. Navigate to this directory: azure-iot-samples-node/iot-hub/Quickstarts/simulated-device-2

    Note: Make sure you are in the right directory. There are duplicate files with the same names in other directories — but with different code.

  8. Open SimulatedDevice.js, and find the connectionString variable, near the top of the code. Replace the value assigned to that variable with the device connection string you copied in the first objective.

    Tip: Make sure the value is wrapped in single quotes.

  9. You now need to find the name of the method name that you can use to send a remote command using a direct method in the Azure IoT Hub.

    Hints:

    • The purpose of the method is to change the interval by which telemetry is sent. It currently defaults to 1 second.
    • There are no parameters on the method.
    • You are looking for a handler of the direct method call from the backend application. The code does not directly expose the method.
  10. Once you find the method, copy and paste it into a text document for use later.
  11. Save your changes.

    Tip: Look for the "…" in the upper right of the editor window to save changes.

  12. Back in the command prompt, run the following command to launch the application and run your simulated device:
    node SimulatedDevice.js

If the device has successfully connected to the hub, you will see telemetry flowing in the terminal window.

Execute a Direct Method on the Simulated Device
  1. Leave the terminal window open and the simulated device running in a big enough pane to see the telemetry flowing.
  2. Return to the device registration you created in the Azure portal, and execute a direct method on the device, using the method name you found in the code. Recall the purpose of the method is to change the telemetry interval from the default of 1 second, so the payload for the method is the digit 5.
  3. Verify that the messages in the terminal have slowed down substantially.
  4. Execute the direct method again, using 0.5 for the payload.
  5. Verify that the messages in the terminal have sped up substantially.
  6. Feel free to try other values.
  7. When you are done, you can stop the code from running by returning to the terminal and executing CTRL-C.

    Tip: Suppose the direct method name you found in the code was runMe, then you would use runMe for the method name and the digit 5 for the payload — not runMe(5).

Additional Resources

You have recently been hired by Railtronics, a monitoring company that works with rail carriers to automate the monitoring and management of station equipment and facilities. They have decided to use Azure IoT to develop a solution that manages environmental temperature and humidity on sensors in both public areas, as well as enclosed equipment housing.

You've been tasked with a proof-of-concept of the solution around cloud-to-device communication. You already have some experience running simulated devices, and you need to show that you can use direct methods from within the Azure Portal to remotely manage devices. In order to complete the lab, you will need to scan the code on the simulated device to find the method that handles a direct method call from the backend.

If you get stuck, feel free to check out the solution video or the lab guide. Good luck!

Tools

You will be using the Azure CLI to perform most of the tasks in this lab. You can access the CLI by using Azure Cloud Shell via the Azure portal.

Node.js Application

We will be using the sample IoT Node.js application to simulate the IoT device application. You do not need prior experience with Node.js. Follow the instructions in the lab objectives.

WARNING: Be Prepared for UI Changes

Given the fluid nature of Microsoft cloud tools, you may experience user interface (UI) changes that were made following the development of this hands-on lab that do not match up with lab instructions. When any such changes are brought to our attention, we will attempt to update the content accordingly. However, if changes occur, students will have to adapt to the changes and work through them in the hands-on labs as needed.

What are Hands-on Labs

Hands-on Labs are real environments created by industry experts to help you learn. These environments help you gain knowledge and experience, practice without compromising your system, test without risk, destroy without fear, and let you learn from your mistakes. Hands-on Labs: practice your skills before delivering in the real world.

Sign In
Welcome Back!

Psst…this one if you’ve been moved to ACG!

Get Started
Who’s going to be learning?