IoT Hub from the Command Line

If you’re like me, in other words old enough to have spent large periods of time working at a command prompt, then you’ll always be looking for command line tools to get things done.

If you’re like me and spending lots of time doing things with IoT Hub, then wouldn’t it be nice to have a command line tool for that.

I spend time in the Azure Portal and using tools like Device Explorer to manage devices and check connectivity but was looking for a CLI for these tasks when I came across iothub-explorer.

iothub-explorer is a Node.js application so before you can have a play you’ll need to head on over to Node.js website and download it if you don’t have it installed.

You use the node package manager (npm) to install the command line interface tool.

npm install -g iothub-explorer@latest

This will install it globally so you’ll be able to have a good play from your command prompt of choice, I like to use PowerShell.

If you want to examine the dependencies, just issue the following from a command prompt.

npm list -g --depth=1

This will list all the things that are also installed as part of iothub-explorer.

iothub-explorer@1.0.8
  ├── azure-event-hubs@0.0.2
  ├── azure-iot-common@1.0.8
  ├── azure-iot-device@1.0.8
  ├── azure-iothub@1.0.10
  ├── bluebird@3.4.1
  ├── colors-tmpl@1.0.0
  ├── nopt@3.0.6
  ├── prettyjson@1.1.3
  └── uuid@2.0.2

If you run iothub-explorer on its own or with the help command line argument you get a list of supported commands.

iothub-commandsSo as you can see you can do an awful lot with this tool.

The easiest way of having a play from a PowerShell command line is to store your connection string in a variable.

$conn = [YOUR CONNECTION STRING]

You can then start a new session with your IoT Hub by simply logging in to it.

iothub-explorer login $conn

By default this gives you a session lasting one hour. If you need a longer period the command has a –-duration argument that takes the number of seconds you need.

Once you’re logged in you’re live to interact with your IoT Hub in lots of the same ways you can from Device Explorer, except this time from the command line which is pretty cool, and of course scriptable!

If you want to take a look at the devices you currently have registered just get a list. Since you previously logged in you don’t need to provide the connection string, so think of all the key strokes you’ll have left.

iothub-explorer list

This returns all the information about each device, but again there is a handy command line argument to limit the level of information, just use -–display and comma separate the properties you want. The argument is used in a few places, so I’d suggest issuing without, taking a look at what there is and then just grabbing what you need in future.

iothub-explorer list --display="deviceId, connectionState"

If you just want a single device use “get” instead of “list” and use the deviceId.

You can also create devices (for instance by including some JSON that defines your device) and retrieve a SAS token for a device.

If you’re really interested in checking how IoT Hub works then the most interesting commands allow monitoring of events sent by a device, and also sending cloud-to-device messages directly. To top even that though, you can also monitor the feedback queue and check for acknowledgement messages from the device which is very cool.

So how do we do that?

First let’s take a look at monitoring events from devices. You’ll need a console application to send messages to your device, that’s just boilerplate code and I’ve covered that to a degree before so I’ll not repeat that here. Once you’ve hooked that up and are sending messages, monitoring from the command line is simple.

iothub-explorer $conn monitor-events [deviceId]

You’ll notice we need to pass the connection string this time, this is one command that still requires it, but I assume that will change in a later version.

Once issued, the command just waits until messages are received at the device endpoint.

iothub-monitor.png

For simulating messages send to a device from the cloud you’ll need another console application that is pretending to be a device in a receive loop. Again that’s boilerplate that I’ve covered before.

You’ll need the console application running because the whole point is to check that messages are received and an acknowledgement is sent. For this one you need 2 PowerShell command windows and don’t forget to set the connection string in the new window.

In one window issue the following and it’ll pause listening to the feedback queue on the IoT Hub.

iothub-explorer retrieve

You can add an argument, –messages=n where n is the number of messages it’ll wait to receive before stopping, otherwise it’ll just wait until you quit.

In the other window, you need to send a message to the cloud endpoint for the device which will then be received by the console application. You’ll want to request an acknowledgement, after all that is what we’re trying to show here!

For the purpose of ease, I’ve gone and created a message variable containing some simple JSON that I’m sending.

iothub-explorer send [deviceId] $msg --ack=full

So in this we’ve requested a full acknowledgement.

iothub-send.png

You’ll notice we get a message ID, this is what we use to see the feedback message.

iothub-receive.png

So we can see we have the same ID so we can correlate these two events which is pretty amazing.

You can see with a simple command line tool we are able interact with IoT Hub and monitor events from devices, and both send messages to a device from the cloud and receive feedback when that message has been received by the device.

I love iothub-explorer, I can see me using this all the time.

I hope you enjoy using it as much as I do!

Leave a Reply

Your email address will not be published. Required fields are marked *