In this post, we’ll talk about how to use your mobile phone to test Azure IoT Hub PaaS solution features, including telemetry routing, twin updates and direct method execution, Automatic Device Management (ADM), and Auto-provisioning through the Device Provisioning Service (DPS). Read on!
Accelerate your career in cloud
When it all comes together…
Do you remember the first time you snapped in the last track in a train layout and watched the locomotive make its inaugural lap? Or maybe it was the first time you stepped out of the practice room and harmonized with 50 other musicians? How about the first time you were one of three ball players who executed a perfect double-play? Even popping in that last piece of a jigsaw puzzle is pretty satisfying.
When it all comes together, it’s a magic moment. And you can experience such magic early on in your Internet of Things (IoT) projects.
Simulated devices in code or in a web interface are all well and good, but there’s just nothing like holding a physical device in your hand, and watching it connect and send telemetry to an IoT solution in the cloud. Your smartphone and an Azure IoT Hub can deliver the goods.
Microsoft provides documentation and tutorials that describe how to connect your phone to Azure IoT Central, Microsoft’s SaaS option for IoT. However, it just feels a bit like a product demo versus a genuine development tool. There’s a place for that, but the IoT Plug and Play app makes so much more available to IoT developers.
Read on and we’ll explore how to set up and use this app on your phone to test Azure IoT Hub PaaS solution features, including:
- Telemetry routing
- Twin updates and direct method execution
- Automatic Device Management, (ADM)
- Auto-provisioning through the Device Provisioning Service (DPS)
For purposes of these test scenarios, I assume that you know how to build solutions around the various features I’ve selected for testing. If you don’t, this is my chance to plug my course and associated labs: AZ-220 – Microsoft Certified: Azure IoT Developer Specialty, where you can learn how to employ these features as a part of preparing for the AZ-220 Azure certification exam.
Set Up IoT Plug and Play on your Phone and Test Telemetry Routing
Before you can test more advanced solutions, you need to install Iot Plug and Play on your IOS or Android mobile device and familiarize yourself with its features by making a simple connection to your Azure IoT Hub.
You should perform these tests in a non-production environment.
Note that my illustrations of hub resources are all in the Azure portal, but you can use Azure CLI or custom code to execute your tests.
Set up a Route and a Device in Azure IoT Hub
- If you do not already have a hub set up for testing, use the Azure portal or Azure CLI to set up a basic hub, leaving most defaults in place. Choose the Free tier or the S1 Standard tier (the default), with one unit. Do not choose the Basic tier, as it will not allow you to perform all of the tests.
- In your hub a route with an Azure Storage queue endpoint. Make sure the hub fallback route is enabled.
- Add a device to your hub, using symmetric key authentication (the default), and leave all other defaults in place.
- Copy the device’s primary connection string (not the connection key), and email it or airdrop it to your phone. (Yes, I know that symmetric key authentication is not a best practice for production, and emailing a key is an even worse idea. You should do all of this work in a non-production environment and tear down the test resources when you are done.)
Install and Connect a Device to your Hub
- In the app store for your phone, find and install IoT Plug and Play. If prompted, give it broad access to other features on your phone in order to enable the most telemetry and other features.
- When you first open the app, you should be on a welcome screen. If not, click on the Settings “cog” icon in the upper right corner and choose Registration.
- We won’t be using the QR code, but select Scan QR Code, when prompted.
- Below the scanning window, choose “connect manually”
- Under “How would you like to connect?”, select Iot Hub device connection string. Paste in the connection string you copied to your phone.
- Select Connect and wait several seconds.
- Your IoT device will connect to the hub and start pumping telemetry in the form of an accelerometer and a gyroscope (motion detectors), a magnetometer, which gives you a heading or a digital compass, a barometer reading, a geolocation, and even a battery level. The battery level is there to show you that telemetry can come in the form of sensor readings, but it can also be data about the state of the device, as well.
- Navigate to the storage account queue you set up on your IoT hub route to verify that data is flowing from your device to your desired destination. Magic!
- Keep your device connected to the hub for the remainder of the other tests. Depending on how your phone is configured, you may need to re-connect at some point. The symmetric key is saved, so you won’t need to perform that set-up, again.
Test Twin Updates and Direct Method Execution
The IoT Plug and Play device simulator includes handlers for both twin updates as well as direct method execution, such as changing the delivery interval or turning on the phone flashlight.
Perform Device Twin Updates
- With your device/phone connected to the hub, navigate to the device details on the hub and select Device Twin to access the twin JSON. Take a look at the “device_info” section of the “reported” properties. Note that the “readOnlyProp” property has a value of “editable,” which is sort of confusing. Just ignore how the property is named; this is the property you can use to test twin updates in both directions: In desired properties from the hub backend, and in reported properties from the device.
- On your device/phone select Properties at the bottom of the screen and edit the “Editable property” to whatever string you want and select Send. I changed it to “I edited this.”
- Back on the device twin in the hub, refresh the twin. Under device info, the value still says “editable” because that’s the configuration at time of connection. But below that, you can see that the readOnlyProp, now says, “I edited this.” Or whatever string you used. Magic.
- Let’s go the other direction. In the twin JSON, under desired properties, put a comma after the “$version” property and add (or copy-paste from reported properties) the “readOnlyProp” key-value pair. Change the value to something else. I used “Chango-Presto.”
- Save the change on the device twin. Note that the system will probably “beautify” your JSON and even move around the property you just added.
- Don’t blink. By the time you are back on your device/phone, the editable property on the device has probably already changed to reflect the device twin change from the hub.
- Back on the hub, refresh the device twin, and you will see that the reported property is now sync’d with the device. Magic.
Execute a Direct Method
- With your device/phone connected to the hub, navigate to the device details on the hub and select Direct Method.
- Under Method Name enter “lightOn”
- In the Payload enter:
- Select Invoke Method at the top left of the panel, and look at your phone. Don’t look directly into the light that is now flashing. That might ruin the magic — just a little bit.
Test Automatic Device Management (ADM)
This is not a tutorial for Automatic Device Management, so I am assuming that you know the basics for setting up an ADM configuration. This test is very much like the twin updates test.
1. In your ADM configuration, target your phone/device by picking one of the “device_info” properties under “reported” properties. I chose the “manufacturer” key-value pair. If you are using an Android phone, you will obviously need to work with the key-value pairs you have available.
2. In the configuration, add a desired property of “readOnlyProp” and assign a string to it. I chose, “Changed by ADM.”
3. Save your configuration and navigate to the device twin. You should see the new desired property in your device twin almost right away. Refresh if you don’t.
4. In Azure IoT, the reported properties are updated by the device. If the device has already connected and applied the ADM configuration by the time you navigate to the twin, it is also possible that the reported property will have already changed, too. If not, check your phone/device properties to see the “Editable property” change to “Changed by ADM.” Then, refresh the twin in the hub until you see the reported property change. Can your heart take much more magic? Let’s find out; one more test.
Test Auto-Provisioning through the Device Provisioning Service (DPS)
This is not a tutorial for the DPS, so I am assuming that you know the basics for setting up an enrollment in the DPS.
- In the hub, set up an instance of the Device Provisioning Service (DPS), and make sure your test IoT hub is linked to the DPS.
- Add an enrollment group, using symmetric key for the attestation mechanism. An individual enrollment is fine, too, but I used an enrollment group for the illustrations.
- Copy the primary key from the enrollment group details and email it or airdrop it to your phone. I will repeat what I said earlier: I know that symmetric key authentication is not a best practice for production, and emailing a key is an even worse idea. You should do all of this work in a non-production environment and tear down the test resources when you are done.
- From the DPS Overview section, collect the ID Scope and transfer it to your phone by email or airdrop or whatever means works for you.
- On your device/phone, select the Settings “cog” in the upper right, and choose Registration to get back to the registration details. Clear out the “IoT Hub device connection string” and switch to the “Enrollment group information” option.
- Enter a device ID. It can be any string you want — just make sure it is different from the device name/ID you tested earlier, when connecting directly to the hub.
- Paste in the ID Scope string you collected from the DPS metadata, and for the SAS key, paste in the primary key you copied from the enrollment group.
- Select Connect. This will take slightly longer than the previous connection because the device first enrolls with the DPS, and then the DPS auto-provisions the device in the hub device registry.
- Once you see telemetry flowing, check the DPS enrollment group to see that your “new” device is a member of the enrollment group. Then navigate to the hub, and check under Devices to see that your device has been auto-provisioned on that hub. One test, twice the magic. We should quit while we are ahead.
Tear down your test resources
Don’t forget to clean up your test environment. To quickly guard against accidental or malicious connections using those pesky symmetric keys you used, delete the device registrations in the hub and delete the enrollment group (or individual enrollment) you created. Better yet, delete the hub and the DPS for full coverage. It wouldn’t hurt to uninstall the IoT Plug and Play app to be doubly sure. You saw how easy it is to install it again.
Learn more about IoT and Azure
For more information on a few more features of the IoT Plug and Play app, such as file upload and logging, check the Microsoft documentation here: Azure IoT Phone App. And if you’d like to learn more about how to build IoT solutions in Azure, check out my course, AZ-220 – Microsoft Certified: Azure IoT Developer Specialty.
WATCH: Post-COVID DevOps: Accelerating the Future
How has COVID affected — or even accelerated — DevOps best practices for engineering teams? Watch this free, on-demand panel discussion with DevOps leaders as we explore DevOps in a post-COVID world.