Test the protocol availability of your Azure IoT Hub

Yesterday I discovered this little gem on Github. This NodeJS tool is advertised as:

“This tool is provided to help diagnose issues with a device connecting to Azure IoT Hubs.”

What it basically does, is calling your IoT Hub and trying to make a connection using Ping, AMQP, AMQP-WS, HTTPS and MQTT. It just checks the availability.

This is the outcome of a typical call:

I can think of calling your service once or more times every day, to check the availability.

What do I have to do for this to get it running?

Usage is pretty simple, the documentation and deployment are easy. Just run:

npm install -g iothub-diagnostics

Now you have the tooling on your machine. Run the service using:

iothub-diagnostics HostName=[name of the IoT Hub].azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=[Shared Access key of iothubowner]

Note: this is basically “iothub-diagnostics [connection string]”

And that will do the job. You will get your fancy outcome of the call.

Note: the Ping is optional. If this is not supported by your device or network, the rest of the logic is still executed.

How useful?

But wait…

This would be perfect when installing a new client device. If this was a tool to check the connectivity of that device, I would like to fill in a device connection string.

But… I have to provide the connection string of the IoT Hub Owner or an identical policy…

But exposing the IoTHubOwner policy in a non-cloud environment is not recommended!!!

In the end, I tried to call the same functionality with the other (standard policies) but they all failed. Thus I can recommend to create an extra policy and to use that:

Note: Only the ‘Registry read’, ‘Registry write’ and ‘Service connect’ permissions are needed. The ‘Device connect’ permission is not needed.


During my tests, I encountered some errors (I had to check the permissions). But sometimes exceptions were thrown but after a rerun, these were not shown again. And a few times, the tool just encountered starvation, nothing happened after an error. Maybe we were waiting for a time-out?

So run the same test a few more times when you encounter an exception…


This is a simple but effective tool to check the connectivity of the different protocols available on your IoTHub. Unfortunately, this tool is configured from the perspective of the server, not from the device point of view.