Working with the IoT Hub using Azure Command Line Interface (CLI 2.0)

In my previous blog, I introduced you to the Azure Command Line Interface (CLI). We ended with creating a resource group just to show how easy it is to create it using nothing more than the command line.

From there, large parts of Azure are available using the CLI, including the IoT Platform.

In this blog, we dive deeper into the world of CLI and we will see how easy it is to manage devices. The tag line is ‘Connect, monitor, and control millions of IoT assets’. Let’s start with just one…

So let’s proceed where we left at the previous blog, let’s create an IoT Hub inside the newly created resource group.

This is part two of a series of blogs regarding the Azure CLI:

1. Getting started with Azure Command Line Interface 2.0
2. Working with the IoT Hub using Azure Command Line Interface
3. Azure CLI made easy. Using the shell

Creating a new IoT Hub

Creating a new IoT Hub can be done in one line. Here we create a new IoT Hub called test-ih, and it’s a free version (with a limitation of 8000 messages each day):

az iot hub create --resource-group cli-rg --output json --name test-ih --sku F1

After a while (this call is blocking) we get a response. The IoT Hub is created and the response is a JSON message containing information about the state and settings of the hub.

Note: If you have a free version already in your resource group, change F1 into S1 (I can not recommend S2 or S3 for testing purposes due to the costs).

Checking out a connection string

If we want to use the newly created IoT Hub for another resource or external tooling (like the Device Explorer), we need a connection string:

az iot hub show-connection-string --name test-ih --policy-name iothubowner --key primary

Again, we get a response within a few seconds:

{
  "connectionString": "HostName=test-ih.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey=[key]"
}

This is the connection string for the ‘iothubowner’ policy. It’s also possible to check and manipulate all available policies using “az iot hub policy list” and “az iot hub policy create”.

Quota’s and Metrics

We created a Free edition of an IoT Hub. Let’s check what we can do with this version:

az iot hub show-quota-metrics --name test-ih

We can see that we can send 8000 messages each day and create a maximum of 500 devices.

[
  {
    "currentValue": 0,
    "maxValue": 8000,
    "name": "TotalMessages"
  },
  {
    "currentValue": 0,
    "maxValue": 500,
    "name": "TotalDeviceCount"
  }
]

Counting devices

How many devices are there already?

az iot device list --hub-name test-ih

The response is a bit disappointing, just an empty array:

"[]"

No devices are added yet, let’s add one.

Adding a device

We name our new device ‘testdevice’:

az iot device create --hub-name test-ih --device-id testdevice

Once it’s created, we get a response:

{
  "authentication": {
    "symmetricKey": {
      "primaryKey": "[key 1]",
      "secondaryKey": "[key 2]"
    },
    "x509Thumbprint": {
      "primaryThumbprint": null,
      "secondaryThumbprint": null
    }
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Disconnected",
  "connectionStateUpdatedTime": "0001-01-01T00:00:00",
  "deviceId": "testdevice",
  "etag": "MA==",
  "generationId": "636245727968771480",
  "lastActivityTime": "0001-01-01T00:00:00",
  "status": "enabled",
  "statusReason": null,
  "statusUpdatedTime": "0001-01-01T00:00:00"
}

As you can see, we get quite a lot of information about the device, include the keys to access this device, the status and the number of messages sent from cloud to the device.

If we ask for the list of devices again, we get the same information as shown above, in the response array. The metrics of the IoT Hub will change also.

We can request the same information again using:

az iot device show --hub-name test-ih --device-id testdevice

Send a D2C ping, acting like the device; Device to Cloud (D2C) messages

We can send a message to the IoT Hub, acting it’s coming from the actual device:

az iot device message send --hub-name test-ih --device-id testdevice

Notice that the response is a void. No error message returned means a message is sent. We can see this ‘Ping from Azure CLI’ in Device explorer:

Note: we do not have to provide device credentials, only the device name. And this is called a ping because we did not provide an actual message. We can provide a custom message:

az iot device message send --hub-name test-ih --device-id testdevice --data "{"text": "hello"}"

Here, a JSON message is sent and received in the IoT Hub:

Cloud to Device (C2D) messages

It’s also possible to check if there are C2D messages available for the device in the IoT Hub. These are commands for the device which are not picked up yet by the device:

az iot device message receive --hub-name test-ih --device-id testdevice

note: the response will arrive in just a few seconds. It should be possible to extend the waiting window to eg. 300 seconds using an extra attribute ‘–lock-timeout 300’ but I noticed no extra delay.

I just sent a message using the device explorer:

So the response looks like:

{
  "ack": "full",
  "correlationId": "",
  "data": "test c2d message",
  "deliveryCount": "0",
  "enqueuedTime": "4/2/2017 11:09:59 AM",
  "expiry": "",
  "lockToken": "131f24b3-1d48-4938-8997-d3fab216a631",
  "messageId": "59c77165-c380-4a87-a025-9b40381e1b72",
  "sequenceNumber": "1",
  "to": "/devices/testdevice/messages/deviceBound",
  "userId": ""
}

As you can see, the ‘test c2d message’ message is found. And eg. the MQTT path of the message is shown (the ‘to’ field).

Note: The response is NOT an array. If there are multiple C2D messages, you only get one. Repeat this request multiple times to get all messages. And even if there are multiple messages queued, it’s still possible to receive ‘nothing’…

This request must be treated as a ‘peek’ action. Although we have seen the message, it’s still available for the actual device. If we want to accept this message as received, we have to accept it.

These C2D messages have a unique lock token. Fill the token into the next request:

az iot device message complete  --device-id testdevice --hub-name test-ih  --lock-token 131f24b3-1d48-4938-8997-d3fab216a631

Again, a void answer will be returned if the request succeeds. The message is now treated as accepted by the original device and is removed from the queue.

Conclusion

Again, the CLI can be very handy to manipulate Azure in general and the IoT Hub and it’s devices specifically.

 

Advertentie