IoT | Busbyland - Azure IoT Playground

Run Azure Digital Twins ADT-Explorer in Docker

This post walks you through running the ADT-Explorer tool, part of our Azure Digital Twins solution, in a docker container.

My apologies, but it’s been a while since I blogged. Life’s been getting in the way.

I’ve been doing more and more lately with our Azure Digital Twins solution. The ADT engineering team has a nice visualization tool for visualizing your models, twins, relationships, and query results. One of the biggest challenges for me and my customers, has been getting my environment set up: right version of node, right version of the code, authentication, etc.

Conveniently, the ADT team has some instructions for running the ADT-Explorer tool in a docker container, so you don’t have to worry about the pre-reqs. It generally works great. However, there’s one downside. The ADT-Explorer tool uses the Microsoft.Identity provider, and specifically the DefaultAzureCredential setting to do your authentication. This is usually a great thing, in that it just automatically picks up any cached local azure credentials you may already be logged in with (Azure CLI, VS Code, Visual Studio, ENV vars, etc) and uses them.

The challenge, however, is that ADT-Explorer running in a docker container cannot leverage those local cached credentials. So, what do you do?

The easiest way to handle this is to install the azure cli inside the docker container, do an ‘az login’ in it, and then start ADT explorer. The rest of this post walks you through this. This post assumes you have docker installed on your machine with linux containers enabled.

The first step is to clone the repo with git.


git clone https://github.com/Azure-Samples/digital-twins-explorer

After you do that, navigate to the digital-twins-explorer and create the adt-explorer docker container (Note the dot/period at the end of the command – don’t forget it!)


docker build -t adt-explorer .

So far this follows the instructions provided by the ADT team, but this is where we will deviate. The ADT team provided instructions have you just run the container as-is. However, if you do that, the DefaultAzureCredentials won’t work. Instead, we need to install the azure cli and login into azure before we start the adt-explorer app. The first thing we need to do is run the adt-explorer docker container, but we are going to start in a bash command prompt. Run the following command


docker run -it -p3000:3000 adt-explorer bash

Note that we added ‘bash’ to the end of the command line, to start the container but override the default entrypoint and give us a bash prompt. It should look like this:

Now that we have a prompt, we need to install the azure cli. To install it, run this command


curl -sL https://aka.ms/InstallAzureCLIDeb | bash

This should install the CLI for us. After a successful install, we can now do an ‘az login’ to authenticate to Azure. You will get a ‘code’ to use, and a URL to visit in your browser as shown below

Open your browser, navigate to http://microsoft.com/devicelogin, enter the code, then your azure subscription credentials as shown below

The authentication process will be slightly different for every environment based on your IT department’s set up (i.e. 2-factor auth, etc), but the result should eventually be a successful login

After a successful login, you’ll see a list of your azure subscriptions in the docker container.

Now we can start the adt-explorer app. To do so, run


npm run start

You’ll see this in your container.

You can now open up a browser, navigate to http://localhost:3000. Click on the People icon in the upper right corner, enter your ADT instance URL, and off you go.

Enjoy, and as always, hit me up in the comments if you have any issues.

Azure IoT Edge local and offline dashboards

This post will cover a common ask for customers. How to display, report, or dashboard data locally, even when offline, from Azure IoT Edge

One of the main uses for IoT is to be able to have dashboards and reports showing the latest information off of IoT devices. Often that happens with data sent from the devices to the cloud. In many IoT scenarios, especially in manufacturing, those dashboards also serve the needs of local operators or supervisors in the very plants or locations that supply that IoT data. So often that data “round trips” from the device, up to Azure, then the reports back down to screens at the plant.

But what happens if you need lower latency reporting? Or you lose your Internet connection frequently because your plant is in an area with slow or unreliable connectivity?

A common ask from customer is to, in addition to sending the IoT data to Azure for centralized reporting, ML model training, etc to also have the data ‘reported/dashboarded’ locally. That allows for lower latency display, as well as continued operation in the event of an Internet failure.

To address this need, I’m happy to announce that Azure IoT Global Black Belt counterparts have published guidance and a sample implementation on how to do just this. The sample implementation happens to be a common manufacturing KPI called Overall Equipment Effectiveness (OEE), but could be adapted to many other scenarios such as retail stores, warehouses, etc.

Please check it out at our github repo -> https://github.com/AzureIoTGBB/iot-edge-offline-dashboarding

Enjoy! And, as always, hit me up in the comments if you have questions.

IoT Transformers podcast

So… I did a thing.

My co-workers, Dani Diaz and Deb Oberly, host a very cool podcast called IoT Transformers. They typically host our Azure IoT customers and partners to talk about how they are transforming their businesses with IoT. It’s a great series full of really useful information about these customer’s and partner’s digital transformation journey.

For this most recent episode, they decided to interview me (“Insights from Busbyland” 🙂 ). As one of the founding members of our IoT Global Black Belt team, we talked about changes I’ve seen in the industry, cool projects, and the IoT-related tech I’m most excited about.

I’ve also created a cool circular reference. The podcast references the blog which references the podcast which references the blog which references the podcast………

Anyway, if you have interest, and want to hear my thoughts on IoT and just how horrible my electronically recorded voice is, how many times I say ‘ummm’, and a little southern drawl, check it out. And don’t forget to go back and give the entire series a listen. You won’t regret it.

-Steve

Install IoT Edge on Red Hat Enterprise Linux (RHEL) – 7.x

This post demonstrates how to get Azure IoT Edge to work on Red Hat Enterprise Linux (RHEL)

Hi all. Sorry for the lack of content lately. Between some (minor) personal stuff and the coronavirus stuff with both myself and my customers, it’s been a bit of a goat-rodeo around Busby Manor lately.

Recently I needed to help a customer get IoT Edge installed on a box running Red Hat Enterprise Linux (RHEL). In this case, it was version 7.5, but this should work for other 7.x based versions too.. I think . I’m about as far away from a RHEL expert as you can get.

NOTE: credit for most of this info goes to Justin Dyer, a peer of mine on the Azure IoT pre-sales team!

First off, if you look at the “platform support” documentation for IoT Edge, you’ll notice that RHEL is a “Tier 2” supported platform. That’s a fancy way of saying that either MSFT or someone we know has gotten it working on that platform and it generally works. However, it also means that it is not a “gating” platform for us, meaning it’s not a platform that we test extensively every release on before we release it. In other words, not working on RHEL will not block or gate a release. That’s not because we don’t like it, or don’t want to “tier 1” support it, but rather it’s just one that we haven’t gotten around (yet) to doing all the necessary work to get it fully integrated into our extensive testing platform. We love all Linux! We’ve just prioritized based on how often we run into various platforms in the field with our customers.

Now, with all the caveating out of the way, IoT Edge on RHEL DOES work, and seems to work fine, and we DO provide RPM packages for it whenever we do a release.

Pre-requisites

Ok.. enough pre-amble, let’s jump in. For RHEL, we provide RPM packages that you can install with YUM… The actual IoT Edge install is reasonably straightforward, once you get through the big pre-req, which is container-selinux.

The big issue is that the moby engine (i.e. open source docker) underneath IoT Edge needs a newer version of container-selinux than was installed on RHEL 7.5. We need version 2:2.95 or greater. If you have it already, great – proceed.

If you don’t, you can manually download from here and update. Updating that package will be left as an exercise to the reader (remember: I’m not a RHEL expert, but hopefully you are )

If you are running your own RHEL install, you can skip this next section and jump down to the “Install IoT Edge” section

A note about RHEL on Azure VMs

Most of the testing I did here was on RHEL running in an Azure VM built with our ready-made RHEL images. If you are running it on your own, you can skip this section.

container-selinux is found in the “rhel-7-server-extras-rpms” repo, which our Azure RHEL VMs do not have access to. There are instructions on how to “remove the version lock and install the non-eus repos” in order to get access to it.

But, if you don’t want to read all that, these are the net instructions that you need to run:


sudo rm /etc/yum/vars/releasever

sudo yum --disablerepo='*' remove 'rhui-azure-rhel7-eus'

sudo yum --config='https://rhelimage.blob.core.windows.net/repositories/rhui-microsoft-azure-rhel7.config' install 'rhui-azure-rhel7'

sudo yum install container-selinux

Once those are complete, you can proceed with the “install IoT Edge” section below

Install IoT Edge

Finding the right packages

Before we install IoT Edge, a short note about how to release IOT Edge. For all of the “non-docker-based” parts of the runtime (i.e. ignoring edgeAgent and edgeHub for the moment), there are really four major components of the runtime:

the moby engine: the open-source version of docker, basically
the moby CLI: gives you the ‘docker’ commands
libiothsm: MSFT provided library that implements the security abstraction layer that let’s the edge runtime talk to various security hardware (like TPMS)
iotedged: the IoT Edge “Security Manager”, which is the daemon based part of IoT Edge and really the component that ‘bootstraps’ all the rest of IoT Edge

When we do a ‘release’ (in the github sense of ‘release’) of IoT Edge, we only provide new packages for those components that changed with that release. So, for example, in the 1.0.8 release, we had changes in all four components and you’ll see (under “assets”) new *.deb and *.rpm packages for all of them.

But in 1.0.9, only libiothsm and iotedged changed, so you only see new packages for those two components.

Unfortunately, that complicates the edge install for us, just a little bit. So, for a given IoT Edge release, you need to spelunk a little to get the latest versions. For the moby engine and CLI, you can usually find the latest version on the packages.microsoft.com site. That’s the easier one. For the iot edge components, unfortunately that requires a little more digging. For the release you want to install, say 1.0.9, you have to work backwards through the releases to find the latest one in which we updated the libiothsm and iotedge components, in this case 1.0.8. So, you need to go find those links, under ‘assets’ of each release, and capture the latest URL’s to the libiothsm and iotedge packages.

Sorry about that. The good news is, that’s the hard part.

finally, install iotedge

Ok, finally, we can install IoT Edge.

The first step is to download the packages. Make a folder on your device to hold them, CD into that folder, and then run


wget https://packages.microsoft.com/centos/7/prod/moby-cli-3.0.10%2Bazure-0.x86_64.rpm

wget https://packages.microsoft.com/centos/7/prod/moby-engine-3.0.10%2Bazure-0.x86_64.rpm

wget https://github.com/Azure/azure-iotedge/releases/download/1.0.9/libiothsm-std_1.0.9-1.el7.x86_64.rpm

wget https://github.com/Azure/azure-iotedge/releases/download/1.0.9/iotedge-1.0.9-1.el7.x86_64.rpm

Those URL’s are valid as the ‘latest’ releases of each component as of the 1.0.9 version of IoT Edge. As future versions ship, you’ll need to see if the various components of them have updated, and replace the URI’s appropriately.

Next, we just install IoT Edge components with the following commands (run them one at a time, as they ask a y/n question in the middle):


sudo yum install moby-cli-3.0.10+azure-0.x86_64.rpm

sudo yum install moby-engine-3.0.10+azure-0.x86_64.rpm

sudo rpm -Uhv libiothsm-std_1.0.9-1.el7.x86_64.rpm

sudo rpm -Uhv iotedge-1.0.9-1.el7.x86_64.rpm

Obviously if you had to download newer package names, replace them.

Once those packages finish installing, all you need to do is open config.yaml and add in your connection string or DPS information and restart iotedge with:


sudo systemctl restart iotedge

There you go. Enjoy. As always, if you have issues, feel free to hit me up in the comments!

Azure Device Provisioning Server over MQTT using x509 Certificates

In a previous post, I showed you how to register a device with Azure’s Device Provisioning Server (DPS) over raw MQTT. A reader/commenter asked how the process would differ if we used x.509 certificate based authentication vs. the SAS-token based authentication that the article was based on.

Since it’s inevitable that I’ll run across this in a customer situation, I thought I’d tackle it. Based on the knowledge from the previous article, as well as my article on DPS over the REST APIs, it was pretty straightforward. The process was nearly identical except for a few fields in the connection information, specifically specifying the iothub root cert, the device cert/key, and leaving off the SAS token. I’ll cover the details below.

Generating Certs

The steps for generating the device certificates and creating the enrollment in DPS is the same process as outlined in my DPS over REST API article. Specifically the sections titled “Prep work (aka – how do I generate test certs?)” and “X.509 attestion with individual enrollments- setup”, so I won’t repeat them here… For the screenshots below, I called my enrollment registration id ‘dpstestdev01’.

The only other thing you need is the IoT Root CA cert. This is the Baltimore-based root ca cert from which all the IoT Hub and DPS “server-side” TLS certificates are generated. The client needs this to validate that it is indeed talking to the genuine microsoft endpoint and not a ‘man in the middle’. The easiest way to get this cert, is to open this file from the Azure IoT C SDK, copy everything from (and including) line 23 to (and including) line 43, then strip out the quotes at the beginning and end of each line, and strip off the ‘\r\n’ off the ends. Save the file with a .pem extension. We will call that the “DPS-root-CA” cert.

Client Setup

You can leverage any MQTT 3.1.1 client to talk to DPS, however, like in previous articles, I’m going to use MQTT.fx, which is an excellent MQTT GUI tool for ‘manually’ doing MQTT. It allows you to get a really good feel for what’s happening under the covers without writing a bunch of code.

Through a series of screenshots below, I’ll show you my configuration.

The first step is to open Mqtt.Fx, click on the little ‘gear’ button next to the Connect button, and in the bottom right, click on the “+” button to create a new connection. You can call it anything (I called mine ‘dpscert’ in the screenshots below)

This screenshot shows the ‘general’ settings…

The type is MQTT Broker
The broker address is the global DPS endpoint (global.azure-devices-provisioning.net)
The port is the MQTTS (tls) port 8883
The client ID is the ‘registration id’ from DPS, specifically in this instance is the CN/Subject name you used for your device cert when you generated it
the only other change from the defaults is to explicitly choose MQTT version 3.1.1

This screenshot shows the user credentials. For DPS, the user-id is of the form of:

{idScope}/registrations/{registration_id}/api-version=2019-03-31

where {idScope} is the idScope of your DPS instance.

Note that, unlike the SAS-Token case, the password is BLANK for x.509 authentication.

This screenshot is the most important one and the biggest difference from the SAS-Token case.

Make sure you explicitly select TLS version 1.2 (we don’t support older versions)
in our use case, we are using self-signed certificates, so choose that option
For the “CA files”, this the DPS-root-CA cert we captured from github earlier. (the baltimore root cert)
For the Client Certificate file, this is the device certificate we created earlier
For the Client Key file, this is the private key for the device cert that we generated earlier.
Make sure and check the “PEM formatted” checkbox, as that’s the format our certs are in.

All the other tabs are just left default.

Click Ok to close this dialog. Click the “Connect” button to connect to DPS.

From this point on, you subscribe and publish exactly like you did in the previous article and/or as specified in the official DPS documentation here.

Enjoy – and as always, let me know if you run into any issue. Hit me up on Twitter (@BamaSteveB), email (steve.busby ( at ) microsoft.com) or in the comments below.

Azure IoT Device Provisioning Service (DPS) over MQTT

Continuing the theme of “doing things on Azure IoT without using our SDKs”, this article describes how to provision IOT devices with Azure IoT’s Device Provisioning Service over raw MQTT.

Previously, I wrote an article that describes how to leverage Azure IoT’s Device Provisioning Service over its REST API, as well as an article about connecting to IoT Hub/Edge over raw MQTT. Where possible, I do recommend using our SDKs, as they provide a nice abstraction layer over the supported transport protocols and frees you from all that protocol-level detailed work. However, we understand there are times and reasons where it’s just a better fit to do things over the raw protocols.

To support this, the Azure IoT DPS engineering team has documented the necessary technical details to register your device via MQTT. This document may provide enough details for you to figure out how to do it, but since I needed to test it for a customer anyway, I thought I’d capture a real-world example in hopes it can help others.

To make the scenario simpler, I chose to just use symmetric key attestation, but this would still work with any of the attestation methods supported by DPS.

Create individual enrollment

The first step is to create the enrollment in DPS. In the Azure portal, in your DPS instance, from the ‘overview’ tab, grab your Scope ID from the upper right of the ‘overview’ tab as shown below (I’ve blacked out part of my details, for obvious reasons)

Once you have that, copy it somewhere like notepad or equivalent, we’ll use it later. Once we have that, we can create our enrollment. On the left nav, click on “Manage Enrollments” and then “Add Individual Enrollment”. For “Mechanism”, choose Symmetric Key, enter a registration ID of your choosing (for the example further below, I used ‘my-mqtt-dev01’)

Click Save. Then drill back into your enrollment in the portal and copy the “Primary Key” and save it for later use.

Generate SAS token

Once you’ve created the enrollment and gotten the device key, we need to generate a SAS token for authentication to the DPS service. A description of the SAS token, and several code samples for generating one in various languages can be found here. Some of the inputs (discussed below) will be different for DPS versus IoT Hub, but the basic structure of the SAS token is the same.

For my purposes, I used this python code to generate mine:

————-

from base64 import b64encode, b64decode
from hashlib import sha256
from time import time
from urllib import quote_plus, urlencode
from hmac import HMAC

def generate_sas_token(uri, key, policy_name, expiry=3600000000):
ttl = time() + expiry
sign_key = “%s\n%d” % ((quote_plus(uri)), int(ttl))
print(sign_key)
signature = b64encode(HMAC(b64decode(key), sign_key, sha256).digest())

rawtoken = {
‘sr’ : uri,
‘sig’: signature,
‘se’ : str(int(ttl))
}

if policy_name is not None:
rawtoken[‘skn’] = policy_name

return ‘SharedAccessSignature ‘ + urlencode(rawtoken)

uri = ‘[dps URI]’
key = ‘[device key]’
expiry = [SAS token duration]
policy=’registration’

print(generate_sas_token(uri, key, policy, expiry))

——–

where:

[dps URI] is of the form [DPS scope id]/registrations/[registration id]
[device key] is the primary key you saved earlier
[SAS token duration] is the number of seconds you want the token to be valid for
policy is required to be ‘registration’ for DPS SAS tokens

running this code will give you a SAS token that looks something like this (changing a few random characters to protect my DPS):

SharedAccessSignature sr=0ne00055505%2Fregistrations%2Fmy-mqtt-dev01&skn=registration&sig=gMpllKo7qS1VR31vyfsT6JAcc4%2BHIu2gQSyai0Uz0KM%3D&se=1579698526

Now that we have our authentication credentials, we are ready to make our MQTT call.

Example call

The documentation does a decent job of showing the MQTT parameters and flow (read it first!), so I’m not going to repeat that here. What I will show is an example call with screenshots to ‘make it real’. For my testing, I used mqtt.fx, which is a pretty nice little interactive MQTT test client.

Once you download and install it, click on the little lightning bolt to switch from localhost to allow you to create a new connection to an MQTT server.

After that, click on the settings symbol next to the edit box to open the settings dialog that lets you edit the various connection profiles:

On the “Edit Connection Profiles” dialog, in the very bottom left hand corner, click the “+” symbol to create a new connection profile.

Give your connection a name and choose MQTT Broker as the Profile Type

Enter the following settings in the top half of the dialog:

for “Broker Address”, use ‘global.azure-devices-provisioning.net’
for “Broker Port”, use “8883”
for Client ID, enter your registration ID you used in the portal for your device

Click on the General ‘tab’ at the bottom. As in the screenshot above, for MQTT Version, uncheck the “Use Default” button and explicitly choose version 3.1.1. Leave other settings on this tab alone.

click on the “User Credentials” tab’

for “User Name”, enter [DPS Scope Id]/registrations/[registration id]/api-version=2019-03-31 (replacing the scope id and registration id with your values)
for “Password”, copy/paste in your SAS token you generated earlier

Move to the SSL/TLS tab. Check the box for “Enable SSL/TLS” and make sure that TLSv1.2 is chosen as the protocol

leave the proxy and LWT tabs alone.

Click Ok to save the settings and return to the main screen

Click on the Connect button and you should get a successful connection (you can verify by looking at the “log” tab)

Once connected, navigate to the “Subscribe” tab. We will set up a subscription on the dps ‘response’ MQTT topic to receive responses to our registration attempts from DPS. On the “Subscribe” tab, enter ‘$dps/registrations/res/#’ into the subscriptions box, choose “QoS1” from the buttons on the right, and click “Subscribe”. You should see an active subscription get set up and waiting on responses.

Click back over on the “Publish” tab and we will make our registration attempt. In the publish edit box, enter $dps/registrations/PUT/iotdps-register/?$rid={request_id}

replace {request_id} with an integer of your choosing (1 is fine to start with). This lets us correlate requests with responses when we get responses back from the service. For example, I entered:

$dps/registrations/PUT/iotdps-register/?$rid=1

in the big edit box beneath the publish edit box, we need to enter a ‘payload’ for the request. For DPS registration requests, the payload takes the form of a JSON document like this: {“registrationId”:”<registration id>”}

for example, for my sample it’s:

{“registrationId”: “my-mqtt-dev01”}

Hit the “Publish button”

Flip back over to the Subscribe tab and you should see on the right hand side of the screen that we’ve received a response from DPS. You should see something like this:

This indicates that DPS is in the process of ‘assigning’ and registering our device to an IoT Hub. This is a potentially long running operation, so to get the status of it, we have to query for that status. To do that, we are going to publish another MQTT message to check on the status. For that, we need the ‘operationId’ from the message we just received. In the screenshot above, mine looks like this:

4.22724a0213a69c4d.9750f5e6-b4c3-4760-9b15-4e74d6120bd1

Copy that ID as we’ll use it in the next step.

To check on the status of the operation, switch back over to the Publish tab and replace the values in the publish edit box with this

$dps/registrations/GET/iotdps-get-operationstatus/?$rid={request_id}&operationId={operationId}

replacing {request_id} with a new request id (2 in my case) and the {operationId} with the operationId you just copied. For example, with my sample values and the response received above, my request looks like this:

$dps/registrations/GET/iotdps-get-operationstatus/?$rid=2&operationId=4.22724a0213a69c4d.9750f5e6-b4c3-4760-9b15-4e74d6120bd1

Delete the JSON in the payload box and click “publish”

Switch back over to the Subscribe tab and you should notice that you’ve received a response to your operational status query, similar to this:

Notice the status of “assigned”, as well as details like “assignedHub” that gives the state of the successful registration and connection details.

If you navigate back over to the azure portal and look at the enrollment record for your device (refresh the page.. you may have to exit and re-enter), you should see something like this:

This indicates that our DPS registration was successful.

In the “real world”, in your application, you’ll make the registration attempt and then poll the operational status until it gets to the state of ‘assigned’. There will be intermediate states while it is being assigned, but doing this manually through a GUI, I’m not fast enough to catch them Smile

Enjoy – and let me know in the comments if you have any questions or issues.

Connect MXChip DevKit to Azure IoT Edge

A customer of mine who is working on an IoT POC to show their management wanted to connect the MXChip Devkit to IoT Hub via IoT Edge. This turned out to be trickier than it should be, as the connection between the MXChip and the IoT Edge box is, like all IoT Hub/Edge connections, TLS-encrypted. So you have to get the MXChip to trust the “tls server” certificate that IoT Edge returns when a client tries to connect. Thanks to some great ground-laying work by Arthur Ma, I wrote a hands-on lab walking you through this scenario. The lab can be found on my team’s github site here

Enjoy, and let me know if you have any problems.

Azure IoT Device Provisioning Service via REST–part 2

This is part 2 of a two part post on provisioning IoT devices to Azure IoT Hub via the Azure IoT Device Provisioning Service (DPS) via its REST API. Part 1 described the process for doing it with x.509 certificate attestation from devices and this part will describe doing it with Symmetric Key attestation.

I won’t repeat all the introduction, caveats, etc. that accompanied part 1, but you may want to take a quick peek at them so you know what I will, and will not, be covering here.

If you don’t fully understand the Symmetric Key attestation options for DPS, I recommend you go read the docs here first and then come back…

Ok, welcome back!

So let’s just jump right in. Similarly to part 1, there will be a couple of sections of ‘setup’, depending on whether you choose to go with Individual Enrollments or Group Enrollments in DPS. Once that is done, and the accompanying attestation tokens are generated, the actual API calls are identical between the two.

Therefore, for the first two sections, you can choose the one that matches your desired enrollment type and read it for the required setup (or read them both if you are the curious type), then you can just jump to the bottom section for the actual API calls.

But, before we start with setup, there’s a little prep work to do.

Prep work (aka – how do I generate the SAS tokens?)

Symmetric Key attestation in DPS works, just like pretty much all the rest of Azure, on the concept of SAS tokens. In Azure IoT, these tokens are typically derived from a cryptographic key tied to a device or service-access level. As mentioned in the overview link above (in case you didn’t read it), DPS have two options for these keys. One option is an individual key per device, as specified or auto-generated in the individual enrollments. The other option is to have a group enrollment key, from which you derive a device-specific key, that you leverage for your SAS token generation.

Generating SAS tokens

So first, let’s talk about and prep for the generation of our SAS tokens, independent of what kind of key we use. The use of, and generation of, SAS tokens is generally the same for both DPS and IoT Hub, so you can see the process and sample code in various languages here. For my testing, I pretty much ~~shamelessly stole~~ re-used the python example from that page, which I slightly modified (to actually call the generate_sas_token method).

from base64 import b64encode, b64decode
from hashlib import sha256
from time import time
from urllib import quote_plus, urlencode
from hmac import HMAC

def generate_sas_token(uri, key, policy_name, expiry=3600):
     ttl = time() + expiry
     sign_key = “%s\n%d” % ((quote_plus(uri)), int(ttl))
     print sign_key
     signature = b64encode(HMAC(b64decode(key), sign_key, sha256).digest())

    rawtoken = {
         ‘sr’ : uri,
         ‘sig’: signature,
         ‘se’ : str(int(ttl))
     }

if policy_name is not None:
rawtoken[‘skn’] = policy_name

return ‘SharedAccessSignature ‘ + urlencode(rawtoken)

uri = ‘[resource_uri]’
key = ‘[device_key]’
expiry = [expiry_in_seconds]
policy=’[policy]’

print generate_sas_token(uri, key, policy, expiry)

the parameters at the bottom of the script, which I hardcoded because I am ~~lazy~~ busy, are as follows:

[resource_uri] – this is the URI of the resource you are trying to reach with this token. For DPS, it is of the form ‘[dps_scope_id]/registrations/[dps_registration_id]’, where [dps_scope_id] is the scope id associated with your DPS instance, found on the overview blade of your DPS instance in the Azure portal, and [dps_registration_id] is the registration_id you want to use for your device. It will be whatever you specified in an individual enrollment in DPS, or can be anything you want in a group enrollment as long as it is unique. Frequently used ideas here are combinations of serial numbers, MAC addresses, GUIDs, etc
[device_key] is the device key associated with your device. This is either the one specified or auto-generated for you in an individual enrollment, or a derived key for a group enrollment, as explained a little further below
[expiry_in_seconds] the validity period of this SAS token in sec… ok, not going to insult your intelligence here
[policy] the policy with which the key above is associated. For DPS device registration, this is hard coded to ‘registration’

So an example set of inputs for a device called ‘dps-sym-key-test01’ might look like this (with the scope id and key modified to protect my DPS instance from the Russians!)

uri = ‘0ne00057505/registrations/dps-sym-key-test01’
key = ‘gPD2SOUYSOMXygVZA+pupNvWckqaS3Qnu+BUBbw7TbIZU7y2UZ5ksp4uMJfdV+nTIBayN+fZIZco4tS7oeVR/A==’
expiry = 3600000
policy=’registration’

Save the script above to a *.py file. (obviously, you’ll need to install python 2.7 or better if you don’t have it to run the script)

If you are only doing individual enrollments, you can skip the next section, unless you are just curious.

Generating derived keys

For group enrollments, you don’t have individual enrollment records for devices in the DPS enrollments, so therefore you don’t have individual device keys. To make this work, we take the enrollment-group level key and, from it, cryptographically derive a device specific key. This is done by essentially hashing the registration id for the device with the enrollment-group level key. The DPS team has provided some scripts/commands for doing this for both bash and Powershell here. I’ll repeat the bash command below just to demonstrate.

KEY=[group enrollment key]
REG_ID=[registration id]

keybytes=$(echo $KEY | base64 –decode | xxd -p -u -c 1000)
echo -n $REG_ID | openssl sha256 -mac HMAC -macopt hexkey:$keybytes -binary | base64

where [group enrollment key] is the key from your group enrollment in DPS. this will generate a cryptographic key that uniquely represents the device specified by your registration id. We can then use that key as the ‘[device_key]’ in the python script above to generate a SAS key specific to that device within the group enrollment.

Ok – enough prep, let’s get to it. The next section shows the DPS setup for an Individual Enrollment. Skip to the section beneath it for Group Enrollment.

DPS Individual Enrollment – setup

The setup for an individual device enrollment for symmetric key in DPS is pretty straightforward. Navigate to the “manage enrollments” blade from the left nav underneath your DPS instance and click “Add Individual Enrollment”. On the ‘Add Enrollment’ blade, for Mechanism, choose “Symmetric Key”, then below, enter in your desired registration Id (and an option device id for iot hub if you want it to be different). It should look similar to the below (click on the pic for a bigger version).

Click Save. Once saved, drill back into the device and copy the Primary Key and remember your registration id, we’ll need both later.

That’s it for now. You can skip to the “call DPS REST APIs” section below, or read on if you want to know how to do this with a group enrollment.

DPS Group Enrollment – setup

The setup for an group enrollment for symmetric key is only slightly more complicated than individual. On the portal side, it’s fairly simple. In the Azure portal, under your DPS instance, on the left nav click on ‘manage enrollments’ and then “Add Group Enrollment”. On the Add Enrollment page, give the enrollment a meaningful name and set Attestation Type to Symmetric Key, like the screenshot below.

Once you do that, click Save, and then drill back down into the enrollment and copy the “Primary Key” that got generated. This is the group key referenced above, from which we will derive the individual device keys.

In fact, let’s do that before the next section. Recall the bash command given above for deriving the device key, below is an example using the group key from my ‘dps-test-sym-group1’ group enrollment above and I’ll just ‘dps-test-sym-device01’ as my registration id

You can see from the picture that the script generated a device-specific key (by hashing the registration id with the group key).

Just like with the individual enrollment above, we now have the pieces we need to generate our SAS key and call the DPS registration REST APIs

call DPS REST APIs

Now that we have everything setup, enrolled, and our device-specific keys ready, we can set up to call the APIs. First we need to generate our SAS tokens to authenticate. Plug in the values from your DPS instance into the python script you saved earlier. For the [device key] parameter, be sure and plug in either the individual device key you copied earlier, or for the group enrollment, make sure and use the derived key you just created and not the group enrollment key.

Below is an example of a run with my keys, etc

the very last line is the one we need. In my case, it was (with a couple of characters changed to protect my DPS):

SharedAccessSignature sr=0ne00052505%2Fregistrations%2Fdps-test-sym-device01&skn=registration&sig=FKOnylJndmpPYgJ5CXkw1pw3kiywt%2FcJIi9eu4xJAEY%3D&se=1568718116

So we now have the pieces we need for the API call.

The CURL command for the registration API looks like this (with the variable parts bolded).

curl -L -i -X PUT -H ‘Content-Type: application/json’ -H ‘Content-Encoding: utf-8’ -H ‘Authorization: [sas_token]‘ -d ‘{“registrationId”: “[registration_id]“}’ https://global.azure-devices-provisioning.net/[dps_scope_id]/registrations/[registration_id]/register?api-version=2019-03-31

where

[sas_token] is the one we just generated
[dps_scope_id] is the one we grabbed earlier from the azure portal
[registration_id] is the the one we chose for our device.
the –L tells CURL to follow redirects
-i tells CURL to output response headers so we can see them
-X PUT makes this a put command
-H ‘Content-Type: application/json’ and –H ‘Content-Encoding: utf-8’ are required and tells DPS we are sending utf-8 encoded json in the body (change the encoding to whatever matches what you are sending)

Above is an example of my call and the results returned.

Note two things.. One is the operationId. DPS enrollment in an IoT Hub is a (potentially) long running operation, and thus is done asynchronously. So to see the status of your IoT Hub provisioning, we’ll need to poll for status. I’ll get to that in a minute. The second thing is the “status” field, which begins in the ‘assigning’ status.

The next API call we need to make is get the status. You’ll basically do this in a loop until you either get a success or failure status. The valid status values for DPS are:

assigned
– the return value from the status call will indicate what IoT Hub the device was assigned to
assigning
disabled
– the device enrollment record is disabled in DPS, so we can’t assigned
failed
– assignment failed. There will be an errorCode and errorMessage returned in an registrationState record in the returned JSON to indicate what failed.
unassigned – ummm.. no clue.

To make the afore-mentioned status call, you need to copy the operationId from the return status above. The CURL command for that call is (with variables bolded):

curl -L -i -X GET -H ‘Content-Type: application/json’ -H ‘Content-Encoding: utf-8’ -H ‘Authorization: [sas_token]’ https://global.azure-devices-provisioning.net/[dps_scope_id]/registrations/[registration_id]/operations/[operation_id]?api-version=2019-03-31

use the same sas_token and registration_id as before and the operation_id you just copied.

A successful call looks like this:

Unfortunately, I’m not a fast enough copy/paste-r to catch it in a status other than ‘assigned’ (DPS is just too fast for me). But you can try this all programmatically or in a script to do it.

Viola

That’s it. Done. You can check the status of your registration in the azure portal and see that the device was assigned.

enjoy, and as always, if you have questions or even suggested topics (remember, it has to be complex, technical, and not well covered in the docs), hit me up in the comments

Azure IoT Device Provisioning Service via REST–part 1

This will be a two-part article on how to provision IoT devices using Microsoft’s Azure IoT Device Provisioning Service, or DPS, via its REST API. DSP is part of our core IoT platform. It gives you an global-scale solution for near zero touch provisioning and configuration of your IoT Devices. We make the device-side provisioning pretty easy with nice integration with our open-source device SDKs.

With that said, one of our core design tenants for our IoT platform is that, while they do make life easier for you in most instances, you do not have to use our SDKs to access any of our services, whether that’s core IoT Hub itself, IoT Edge, or in this case, DPS.

I recently had a customer ask about invoking DPS for device registration from their field devices over the REST API. For various reasons I won’t dive deep in, they didn’t want to use our SDKs and preferred the REST route. The REST APIs for DPS are documented, but.. well.. we’ll just say “not very well” and leave it at that……..

ahem……..

anyway..

So I set out to figure out how to invoke device registration via the REST APIs for my customer and thought I would document the process here.

Ok, enough salad, on to the meat of the post.

First of all, this post assumes you are already familiar with DPS concepts have maybe even played with it a little. If not, review the docs here and come back. I’ll wait……….

Secondly, in case you didn’t notice the “part 1” in the title, because of the length, this will be a two-part post. The first half will show you how to invoke DPS registration over REST for the x.509 certificate attestation use cases, both individual and group enrollments, and part 2 will show for the Symmetric Key attestation use cases.

NOTE- but what about TPM chip-based attestation?, you might ask.. Well, I’m glad you asked! Using a TPM-chip for storing secrets and working with any IoT device is a best practice that we highly recommend! with that said, I’m not covering it for three reasons, 1) the process will be relatively similar to the other scenarios, 2) despite it being our best practice, I don’t personally have any customers today it (shame on us all!) and 3) I don’t have an IoT device right now that has a TPM to test with

One final note – I’m only covering the registration part from the device side. There are also REST APIs for enrolling devices and many other ‘back end’ processes that I’m not covering. This is partially because the device side is the (slightly) harder side, but also because it’s the side that is more likely to need to be invoked over REST for constrained devices, etc.

Prep work (aka – how do I generate test certs?)

The first thing we need f0r x.509 certificate attestation is, you guess it, x.509 certificates. There are several tools available out there to do it, some easy, and some requiring an advanced degree in “x.509 Certificate Studies”. Since I don’t have a degree in x.509 Certificate Studies, I chose the easy route. But to be clear, I just picked this method, but any method that can generate valid x.509 CA and individual certs will work.

The tool I chose is provided by the nice people who write and maintain our Azure IoT SDK for Node.js. This tool is specifically written to work/test with DPS, so it was ideal. Like about 50 other tools, it’s a friendly wrapper around openssl. Instructions for installing the tool are provided in the readme and I won’t repeat them here. Note that you need NodeJs version 9.x or greater installed for it to work.

For my ‘dev’ environment, I used Ubuntu running on Windows Subsystem for Linux (WSL) (man, that’s weird for a 21-year MSFT veteran to say), but any environment that can run node and curl will work.

Also, final note about the cert gen scripts.. these are scripts for creating test certificates… please.. pretty please.. don’t use them for production. If you do, Santa will be very unhappy with you!

In the azure portal, I’ll assume you’ve already set up a DPS instance. At this point, on the DPS overview blade, note your scope id for your instance (upper right hand side of the DPS Overview blade), we’ll need it here in a sec. From here on out, I’ll refer to that as the [dps_scope_id]

The next two sections tell you how to create and setup the certs we’ll need for either the Individual or Group Enrollments. Once the certs are properly setup, the process for making the API calls are the same, so pick the one of the next two sections that apply to you and go (or read them both if you are really thirsty for knowledge!)

x.509 attestation with Individual Enrollments – setup

Let’s start with the easy case, which is x.509 attestation with an Individual Enrollment. The first thing I want to do is to generate some certs.

For my testing, using the create_test_cert tool to create a root certificate, and a device certificate for my individual enrollment, using the following two commands.

node create_test_cert.js root “dps-test-root”

node create_test_cert.js device “dps-test-device-01” “dps-test-root”

The tool creates the certificates with the right CN/subject, but when saving the files, it drops the underscores and camel-cases the name. I have no idea why. Just roll with it. Or feel free to create a root cert and device cert using some other tool. The key is to make the subject/CN of the device cert be the exact same thing you plan to make your registration id in DPS. They HAVE to match, or the whole thing doesn’t work. For the rest of the article, I will refer to the registration id as [registration_id]

so my cert files look like this…. (click on the pic to make it larger)

Back in the Azure portal, under “Manage enrollments” on the left nav, click on “Add Individual Enrollment”. On the “Add Enrollment” blade, leave the default of “X.509” for the Mechanism. On the “Primary Certificate .pem or .cer file”, click on the folder and upload/choose the device certificate you generated earlier (in my case, it’s dpsTestRoot_cert.pem).

The top half of my “Add Enrollment” blade looks like this (everything below it is default)

I chose to leave the IoT Hub Device ID field blank. If you want your device ID in Hub to be something different than your registration id (which is the CN/subject name in your cert), then you can enter a different name here. click SAVE to save your enrollment and we are ready to go.

x.509 attestation with Group Enrollments – setup

Ok, if you’re reading this section, you are either a curious soul, or decided to go with the group enrollment option for x.509 attestation with DPS.

With the umbrella of group enrollment, there are actually two different options for the ‘group’ certificate, depending on whether or not you want to leverage a root CA certificate or an intermediate certificate. For either option, for test purposes, we’ll go ahead and generate our test certificates. The difference will primarily be which one we give to DPS. In either case, once the certificate is in place, we can authenticate and register any device that presents a client certificate signed by the CA certificate that we gave to DPS. For details of the philosophy behind x.509 authentication/attestation for IoT devices, see this article.

For this test, I generated three certificates, a root CA cert, an intermediate CA cert (signed by the root), and an end IoT device certificate, signed by the intermediate CA certificate. I used the following commands to do so.

node create_test_cert.js root “dps-test-root”

this generated my root CA certificate

node create_test_cert.js intermediate “dps-test-intermediate” “dps-test-root”

this generated an intermediate CA certificate signed by the root CA cert I just generated

node ../create_test_cert.js device “dps-test-device-01” “dps-test-intermediate”

this generated a device certficate for a device called “dps-test-device-01” signed by the intermediate certificate above. So now I have a device certificate that ‘chains up’ through the intermediate to the root.

At this point, you have the option of either setting up DPS with the root CA certificate, or the Intermediate Certificate for attesting the identity of your end devices. The setup process for each option is slightly different and described below.

Root CA certificate attestation

For Root CA certificate attestation, you need to upload the root CA certificate that you generated, and then also provide proof of possession of the private key associated with that root CA certificate. That is to keep someone from impersonating the holder of the public side of the root CA cert by making sure they have the corresponding private key as well.

The first step in root CA registration is to navigate to your DPS instance in the portal and click “Certificates” in the left-hand nav menu. Then click “Add”. In the Add Certificate blade, give your certificate a name that means something to you and click on the folder to upload our cert. Once uploaded, click Save.

At that point, you should see your certificate listed in the Certificates blade with a status of “unverified”. This is because we have not yet verified that we have the private key for this cert.

The process for verifying that we have the private key for this cert involves having DPS generate a “verification code” (a cryptographic alphanumeric string” and then we will take that string and, using our root CA certificate, create a certificate with the verification code as the CN/Subject name and then sign that certificate with the private key of the root CA cert. This proves to DPS that we possess the private key. To do this, click on your newly uploaded cert. On the Certificate Details page, click on the “Generate Verification Code” button and it will generate a verification code as shown below.

Copy that code. Back on the box that you are using to generate the certs, run this command to create the verification cert.

create_test_cert.js verification [–ca root cert pem file name] [–key root cert key pem file name] [–nonce nonce]

where –ca is the path to your root CA cert you uploaded, –key is the path to it’s private key, and–nonce is the verification code you copied from the portal, for example, in my case:

node ../create_test_cert.js verification –ca dpsTestRoot_cert.pem –key dpsTestRoot_key.pem –nonce 07F9332E108C7D24283FB6B8A05284E6B873D43686940ACE

This will generate a cert called “verification_cert.pem”. Back on the azure portal on the Certificates Detail page, click on the folder next to the box “Verification Certificate *.pem or *.cer file” and upload this verification cert and click the “Verify” button.

You will see that the status of your cert back on the Certificates blade now reads “Verified” with a green check box. (you may have to refresh the page with the Refresh button to see the status change).

Now click on “Manage enrollments” on the left-nav and click on “Add enrollment group”. Give it a meaningful name for you, make sure that “Certificate Type” is “CA Certificate” and choose the certificate you just verified from the drop-down box, like below.

Click Save

Now you are ready to test your device cert. You can skip the next section and jump to the “DPS registration REST API calls” section

Intermediate CA certificate attestation

If you decided to go the Intermediate CA certificate route, which I think will be the most common, luckily the process is a little easier than with a root CA certificate. In your DPS instance in the portal, under “Manage enrollments”, click on Add Enrollment Group”. Make sure that Attestation Type is set to “Certificate” and give the group a meaningful name. Under “Certificate Type”, choose “Intermediate Certificate” and click on the folder next to “Primary Certificate .pem or .cer file” and upload the Intermediate Certificate we generated earlier. For me, it looks like this..

click Save and you are ready to go to the next section to try to register a device cert signed by your Intermediate Certificate.

The DPS registration REST API calls

Ok, so the moment you’ve all been waiting (very patiently) for…

As mentioned previously, now that the certs have all been created, uploaded, and setup properly in DPS, the process and the API calls from here on out is the same regardless of how you set up your enrollment in DPS.

For my testing, I didn’t want to get bogged down in how to make HTTP calls from various languages/platforms, so I chose the most universal and simple tool I could find, curl, which is available on both windows and linux.

The CURL command for invoking DPS device registration for x.509 individual enrollments with all the important and variable parameters in []’s..

curl -L -i -X PUT –cert ./[device cert].pem –key ./[device-cert-private-key].pem -H ‘Content-Type: application/json’ -H ‘Content-Encoding: utf-8’ -d ‘{“registrationId”: “[registration_id]“}’ https://global.azure-devices-provisioning.net/[dps_scope_id]/registrations/[registration_id]/register?api-version=2019-03-31

That looks a little complicated, so let’s break each part down

-L : tells curl to follow HTTP redirects
– i : tells curl to include protocol headers in output. Not strictly necessary, but I like to see them
-X PUT : tells curl that is an HTTP PUT command. Required for this API call since we are sending a message in the body
–cert : this is the device certificate that we, as a TLS client, want to use for client authentication. This parameter, and the next one (key) are the main thing that makes this an x.509-based attestation. This has to be the same cert you registered in DPS
–key : the private key associated with the device certificate provided above. This is necessary for the TLS handshake and to prove we own the cert
-H ‘Content-Type: application/json’ : required to tell DPS we are posting up JSON content and must be ‘application/json’
-H ‘Content-Encoding: utf-8’ : required to tell DPS the encoding we are using for our message body. Set to the proper value for your OS/client (I’ve never used anything other than utf-8 here)
-d ‘{“registrationId”: “[registration_id]”}’ : the –d parameter is the ‘data’ or body of the message we are posting. It must be JSON, in the form of “{registrationId”:”[registration_id”}. Note that for CURL, I wrapped it in single quotes. This nicely makes it where I don’t have to escape the double quotes in the JSON
Finally, the last parameter is the URL you post to. For ‘regular’ (i.e not on-premises) DPS, the global DPS endpoint is global.azure-devices-provisioning.net, so that’s where we post. https://global.azure-devices-provisioning.net/[dps_scope_id]/registrations/[registration_id]/register?api-version=2019-03-31. Note that we have to replace the [dps_scope_id] with the one you captured earlier and [registration_id] with the one you registered.

you should get a return that looks something like this…

The next API call we need to make is get the status. You’ll basically do this in a loop until you either get a success or failure status. The valid status values for DPS are:

- assigned
  – the return value from the status call will indicate what IoT Hub the device was assigned to
- assigning
- disabled
  – the device enrollment record is disabled in DPS, so we can’t assigned
- failed
  – assignment failed. There will be an errorCode and errorMessage returned in an registrationState record in the returned JSON to indicate what failed.
- unassigned – ummm.. no clue.

To make the afore-mentioned status call, you need to copy the operationId from the return status above. The CURL command for that call is:

curl -L -i -X GET –cert ./dpsTestDevice01_cert.pem –key ./dpsTestDevice01_key.pem -H ‘Content-Type: application/json’ -H ‘Content-Encoding: utf-8’ https://global.azure-devices-provisioning.net/[dps_scope_id]/registrations/[registration_id]/operations/[operation_id]?api-version=2019-03-31

where [dps_scope_id] and [registration_id] are the same as above, and [operation_id] is the one you copied above. The return will look something like this, keeping in mind the registrationState record will change fields based on what the returned status was.

Unfortunately, I’m not a fast enough copy/paste-r to catch it in a status other than ‘assigned’ (DPS is just too fast for me). But you can try this all programmatically or in a script to do it.

Ta-Da!

That’s it. You can navigate back to DPS, drill in on your device, and see the results

Enjoy – and as always, hit me up with any questions in the comments section.

Monitor IoT Edge connectivity with Event Grid

Hi! Long time, no see. It’s been a few months since I posted here. I won’t bore you with the many “I’ve been busy” excuses (but I have!). Anyway, enough assuaging my guilt over not having shared with you guys in a while. Let’s get to why you came here (since google.com probably sent you)

One of the frequent questions we get related to any IoT device, but especially IoT Edge is “how do I know if my IoT device/edge is up and running and talking to IoT Hub?” I was recently researching this topic for a customer and ran across some cool stuff. I even did a quick little sample/demo I’ll share at the bottom involving IoT Edge and Microsoft Teams.

IoT Edge/Hub and Event Grid

As you may know, IoT Hub integrates with Azure Event Grid. Azure Event Grid is a fully managed event routing service that uses a publish-subscribe model. Event Grid integrates with a bunch of Azure Services (a pic is on that link above), including IoT Hub. As shown from the list below, stolen from that same link, IoT Hub publishes several event types to Event Grid.

Microsoft.Devices.DeviceCreated – Published when a device is registered to an IoT hub.
Microsoft.Devices.DeviceDeleted – Published when a device is deleted from an IoT hub.
Microsoft.Devices.DeviceConnected – Published when a device is connected to an IoT hub.
Microsoft.Devices.DeviceDisconnected – Published when a device is disconnected from an IoT hub.
Microsoft.Devices.DeviceTelemetry – Published when a device telemetry message is sent to an IoT hub

Note that Device Connected and Device Disconnected events will be raised when the devices connect or disconnect. That can be an explicit connection and disconnection, or a disconnect after a certain number of missed ‘heartbeats’, meaning the device or network may have committed seppuku (not to be confused with Sudoku) . You can set Event Grid subscriptions to these events and then respond however you want to (Logic Apps, Azure Functions, Text, Email, etc)

So, what about IoT Edge?

Ok, Steve, but google sent me here because I searched for information about monitoring IoT *Edge*connectivity. If it pleases the court, are you going to talk about that any time soon?

Yes! The reason this is relevant to IoT Edge is that the connection/disconnection events not only work for IoT end-devices, but it also works for IoT Edge modules! So, leveraging that, you can tell if any of your IoT Edge modules disconnect and don’t reconnect (did they crash?) or also if the IoT Edge runtime itself loses connectivity (crash? network issue?) by looking for those events for the $edgeHub and $edgeAgent modules.

Ok skippy, prove it!

Fine! I will… The IoT Hub/Event Grid teams have a nice little example of using the integration between IoT Hub and Event Grid to persistently track the status of your device connectivity in a CosmosDB database, via a LogicApps. It will have a record for all of your devices, and their last connect/disconnect time. It’s a pretty nice little sample and could be the beginning of a connectivity monitoring solution You can build a UI, have it pull the status from CosmosDB, etc.

Check it out if you have the time or inclination.

However, I was too ~~lazy~~ busy to create a CosmosDB, stored procedure, UI, etc. So I took the quicker way out. I created a Channel in Microsoft Teams and, each time a device/module connected or disconnected, I just post a message to the channel.

I basically followed that article and all the pieces of it, except everywhere it referenced the stored procedure and CosmosDB, I just instead leveraged the built-in LogicApps connector for Microsoft Teams, which is super-easy to use.

The result is shown below. I have a raspberry pi running IoT Edge sitting on my desk. It has a SenseHat accessory in top of it and was running a module that I wrote that talks to it (uncreatively named “sensehat” – they don’t pay me enough for naming creativity). At about 10:55 local time, I reached over the yanked the power plug out of the raspberry pi. 2-3 minutes later (after some missed heartbeats), viola, I got a post to my Teams channel telling me that both my module (sensehat) as well as the Edge runtime ($edgeHub and $edgeAgent) had disconnected. (rpihat2 is the device name for my IoT Edge device)

(full disclosure – I made ZERO effort to make the message look pretty)

I could just as easily, via LogicApps again, have leveraged SendGrid, Twilio, etc to send me email alerts, TXTs, or whatever for these events. If you do use Microsoft Teams, you can set alerts on the Channel when new events are posted too. If you use the mobile app, you even get push notifications.

I didn’t write step-by-step instructions for doing this, as I hope it’s not too hard to follow the Azure IoT team’s cool instructions above and just substitute Teams/SendGrid/Twilio, etc for the output.. but feel free to let me know if I need to do step-by-step.

Leave a comment and let me know if this, or any of my other content, is useful (or if you need/want step-by-step instructions)

Enjoy,

–Steve