IoT Suite - Remote Monitoring - Adding Live and Simulated Devices
Introduction
IoT Hub is the next big thing after Event Hub, providing authentication per device, and two-way messaging from one unified end point.
IoT Suite is a tool to quickly spin up all the components you need to provide a complete IoT solution.
You can find a complete break down of all the components that IoT Suite creates here : IoT Suite - Under The Hood - Remote Monitoring
This document looks closer at just device creation, both real devices and simulated devices. Rules and actions are not covered here.
Components
Azure IoT Hub
IoT Hub is a very different service from both Service Bus and Event Hub. IoT Hub can scale to millions of devices, and provides built-in "per-device authentication", libraries for most common devices, and two-way messaging from a single end point. Wth IoT Hub, you must first register your device, and provide or obtain unique keys and generated ids that help protect your connection and avoid "spoofing".
How to register your device
To create a device, you must first register your chosen device id with event hub, which will create the device's unique Generation Id, and Primary and Secondary Keys. You can create and send the Primary and Secondary keys if you prefer, but the Generation Id is created by IoT Hub.
To register a device, you can use the RegistryManager and AddDeviceAsync method, which returns the new IoT Hub device, with Generation Id and keys.
Registry Manager is available from NuGet, if you search for "Microsoft.Azure.Devices", but [at time of writing] you also need to tick the "show prereleases" checkbox to show it.
At this point, using the data you get back from device registration and the sample code, you can start sending data to IoT Hub from the device. However it will not be listed by the website, because it has not been added to the application database, as explained next.
Azure DocumentDb
This is the place IoT Suite uses for device provisioning and rules, look-ups for the website and simulated devices web jobs. The Web App application data.
To add your new device to that demo website, you simply need to add a document to the DocumentDb resource that was created for the application.
Below is the content of a document for one of the simulated devices which IoT Suite creates:
{
"DeviceProperties": {
"DeviceID": "SampleDevice004_217",
"HubEnabledState": true,
"CreatedTime": "2015-12-14T22:28:24.720717Z",
"DeviceState": "normal",
"UpdatedTime": "2015-12-22T19:58:02.2369042Z",
"Manufacturer": "Contoso Inc.",
"ModelNumber": "MD-996",
"SerialNumber": "SER5102",
"FirmwareVersion": "1.96",
"Platform": "Plat-99",
"Processor": "i3-7340",
"InstalledRAM": "36 MB",
"Latitude": 47.659159,
"Longitude": -122.141515
},
"Commands": [
{
"Name": "PingDevice",
"Parameters": null
},
{
"Name": "StartTelemetry",
"Parameters": null
},
{
"Name": "StopTelemetry",
"Parameters": null
},
{
"Name": "ChangeSetPointTemp",
"Parameters": [
{
"Name": "SetPointTemp",
"Type": "double"
}
]
},
{
"Name": "DiagnosticTelemetry",
"Parameters": [
{
"Name": "Active",
"Type": "boolean"
}
]
},
{
"Name": "ChangeDeviceState",
"Parameters": [
{
"Name": "DeviceState",
"Type": "string"
}
]
}
],
"CommandHistory": [],
"IsSimulatedDevice": 1,
"Version": "1.0",
"ObjectType": "DeviceInfo",
"IoTHub": {
"MessageId": null,
"CorrelationId": null,
"ConnectionDeviceId": "SampleDevice004_217",
"ConnectionDeviceGenerationId": "635857281044650363",
"EnqueuedTime": "0001-01-01T00:00:00",
"StreamId": null
},
"id": "3cd6862c-0d80-4674-8b21-42537csebfd3"
}
"DeviceProperties/DeviceID", "IoTHub/ConnectionDeviceId" and "id" can all be the same, the name of your new device. That last "id" is the document id. IoT Suite generates a GUID for this id when it first creates the simulated devices for the demo. This is just to ensure these and new devices added via the Web App are unique documents in the database.
"IoTHub/ConnectionDeviceGenerationId" is the number you got back from device registration, as explained above.
"IsSimulatedDevice" is a Boolean one or zero. One obviously meaning this device is simulated.
How to add a device to the monitoring Web App
Adding a new device to the example that IoT Suite created just requires one new file [as shown above] to be created in DocumentDb.
The Azure Portal has features built in to browse and manage documents, including adding a new one.
Here is a screenshot of the document above copied and pasted into a new document, with the red bits changed for my new device:
Save your new document into the database and reload your website. You should now find your new device listed. You should see it on the map and be able to select it.
If you have connected a device, telemetry should start to appear in the history charts and any commands you added should be available.
Azure Table Storage
If you want your device to be a simulated device, using the existing web job example provided in the sample code, you need to add it to the Table Storage account that IoT Suite creates for this purpose.
Each component created by IoT Suite is just an example of how you can wire up your IoT solution. Table Storage is the best solution for a simple key/value store. It is cheap and scales easily to millions of rows (devices), whilst still being very fast to query.
As mentioned above, there is a "IsSimulatedDevice" flag in the device document, in DocumentDb, the "**ConnectionDeviceGenerationId" **is also needed by the simulator to pass through IoT Hub. However, DocumentDb could potentially be millions of rows, so running queries for the IsSimulatedDevice flag of each document could be slow, compared to using a look-up table as demonstrated by ths IoT Suite example.
How to add a simulated device
To make your new device come to simulated life, you simply need to add a row to the DeviceList Table Storage service.
This cannot be done from within the Azure Portal, but it can be done manually using Visual Studio.
If the Table Storage account you added does not show in your Azure Server Explorer, you can right click and "Attach External Storage", as shown below:
This will bring up a form that will generate the connection string needed to connect to the various storage resources. The first two connection methods generate the endpoints for you, but if they don't work, you can add them manually with the third option, as shown below:
The account key, and the end points are all shown in Azure Portal, when you click the key icon, as shown below:
The Connection Strings section contains the full text that can be copied from, and it should match your generated connection string n the preview window shown before.
With this new storage account attached, you can now view and add/edit/delete the rows of data that define which devices are simulated, as shown below:
The last device listed was added manually using the + icon shown above. This brings up a form for manually entering the new row,. You must enter your device id as PartitionKey, and the namespace for the project as RowKey.
Then you must add an extra row called "Key" and use the Primary or Secondary Key you obtained or supplied, when registering your device with IoT Hub, as explained at the start.
And that's it!
In a few minutes, you should see data showing for the new simulated device, in the Web App:
