Introduction

 

Welcome to part 3 of the Avnet Azure Sphere Starter-Kit (Out of Box Demo).  In this follow-up blog, we'll walk through connecting the example Azure Sphere application to an IoT Central Application that we’ll create from scratch.

 

The Starter Kit is available for order here.

 

We've put together three different blogs to showcase the Avnet Azure Sphere Starter Kit and how it can be used for your next IoT project . . .

  • Blog #1: Simple non-connected demo
  • Blog #2: Hands-on connected demo using a generic IoT Hub and Time Series Insights
    • Must complete blog 1 demo before moving on to blog 2
    • Configures IoT Hub and Time Series Insights Azure resources
    • Manipulate the device twin
    • Visualize data using Time Series Insights
  • Blog #3: Hands-on, connected demo using IoT Central (this blog)
    • Must complete blog 1 before moving on to part 3
    • Walks the user though configuring a IoT Central Application to create a custom visualization and device control application

Azure IoT Central

IoT Central is a Software-as-a-Service (SaaS) offering from Microsoft.  Microsoft has made it easy to connect IoT devices and display telemetry data from connected devices.  Additionally, there are some cloud to device (C2D) controls available.  IoT Central Applications are created on-line without any coding necessary; configuration is all driven from the web interface.  This document will walk the user through each step required to create an IoT Central application that interacts with Avnet’s Azure Sphere Reference Design Project.

I’ll make the assumption that you’ve completed the simplified non-connected example.  If not, please go back and complete that demohere. For the IoT Central demo the following prerequisites are required.

 

  • Visual Studio and the Azure Sphere SDK are installed and confirmed working
  • You were able to run the non-connected example without any issues (link)
  • Your device is connected to a Wi-Fi access point and has access to the internet
  • You have an Azure account
    • You can sign up for a free Azure account here

IoT Central Application Features

Our application will have the following features

  • Display X, Y, and Z axis g-force (gravitational force equivalent data label named GForce) measurement from the built in LSM6DSO accelerometer in a graph
  • Display event data generated when user buttons A or B are pressed
  • Allow the user to toggle the User RGB Red, Green, and Blue LEDs from the application
  • Allow the user to toggle the WLAN and APP LEDs from the application
  • Control optional Relay Click relays(2) from the application
  • Display the current firmware version running on the Starter Kit
  • Display the current connected Starter Kit Wi-Fi SSID
  • Display the Wi-Fi AP bssid
  • Display the current Wi-Fi frequency

Implementation Steps

This blog will walk the reader through the following implementation steps

  • Create a custom IoT Central application
  • Create a device template
  • Add g-force telemetry to the Measurements Tab
  • Add Button Press events to the Measurements Tab
  • Add Toggle controls to the Settings Tab
    • RGB LED controls
    • WWAN and APP LED controls
    • Relay Click controls
  • Add Application information to the Properties Tab
    • Application Version
    • Current SSID
    • BSSID
    • Current Wi-Fi Radio Frequency

  That looks like a lot of work, but as you’ll see IoT Central makes is easy to add all these elements.  Let’s get started!

 

Create a IoT Central custom application

The first step is to create the application.  Follow this link to the Azure IoT Central main page.  If prompted to login, use your Azure credentials.  If you don’t have Azure credentials, you can sign up for a free account here.

Once you’re logged into the IoT Central page, you should see a screen similar to the one shown below:

  • Select the “Trial” option for a free 7-day trial.  You can also select the Pay-As-You-Go option; you’ll need an Azure account with a balance or a pay-as-you-go account associated credit card if you choose this option.
  • Select the “Custom Application” option.  The other templates can be good to see how things are done in IoT Central, but for our example a custom application will be easiest.
  • Create a name for your application.  Note that when you type into this box there will be a validation check on the name. Since your application name will also be used for the URL, it must be unique across all of Azure.  If you provide a name that’s already taken, you’ll get an error message stating the issue.
  • Click the “Create” Button

Your application will be provisioned on Azure and you’ll be taken to the main page of your application. 

Here you’ll see the landing page.  The first thing we need to do is to create a “Device Template,” so click on the link at the left side of the page.

Create a device template

A device template is where we’ll define all the information that will be displayed for our device.  By default there are not any templates.  On the “Device Templates” page, find the “+” link at the top right and click.

You’ll be given 4 choices to start your new template. Select the “Custom” square.

Enter a name for your template, then click on the “Create” button.

The next page shows your new template.  The template is empty.  So let’s build it out! 

We’ll add Telemetry data first, so click on the “+ New Measurement” link.

Add Telemetry to the Measurements Tab

On this page you can add different things to your template. Telemetry, State or Events.  The first thing we’ll do is configure some telemetry items, so click on the “Telemetry” square.

This is where we define all the properties for a new Telemetry item.  We’re going to add the X G-Force component to the measurement data graph.  To do this we just need to fill out the form. 

  • Display Name: The name of the telemetry item to add (anything you want)
  • Field Name: Enter the “key” name of the {“key”: value} key pair telemetry data.  The sample Azure Sphere application uses “gX” for the X g-force component, so we enter “gX” in this field.
  • Units: Anything you want, but it should represent the units of your telemetry data, in our case milli-g-force so “mG”
  • Min/Max Value:  Use these fields to add bounds to your graph.  You should select values that are close to what you expect the maximum and minimum values to be.  That way your graph will not have too much empty space or allow your data to be off the graph.  We'll set our limits in the range (-1500, 1500)
  • Decimal Places: How many decimal places to show on your graph, I selected to display 3 decimal places of accuracy.
  • Color: Select the color you want for this telemetry item

That’s all there is to add telemetry data.  The critical piece is that you need to know what key:value pairs your application is sending up.  Once you fill out the form, click on the “Save” button at the top of the form. 

Next we need to add Telemetry entries for the Y and Z components.  Use the table below and your new knowledge to verify the X configuration and to add the Y and Z telemetry pieces.

Display Name

Field Name

Units

Minimum Value

Maximum Value

Decimal Places

X-GForce

gX

g

-1500

1500

1

Y-GForce

gY

g

-1500

1500

1

Z-GForce

gZ

g

-1500

1500

1

 

The application is also sending up angular rate data in units of mill degrees per second (mdps), and pressure in units of hPa.  The table below shows additional telemetry items you could add if you wanted.

Display Name

Field Name

Units

Minimum Value

Maximum Value

Decimal Places

X-Angular Rate

aX

mdps

-120

120

1

Y-Angular Rate

aY

mdps

-120

120

1

Z-Angular RateaZmdps-1201201
PressurepressurehPa90011002

 

After entering the GForce telemetry measurements, your screen should look similar to the picture below.

You may notice data showing up in the graph already.  This data is being generated by a Simulated Device. Whenever you create a new Device Template in IoT Central it will auto generate a simulated device, and that device will start to send random data within the min/max bounds you defined in the new measurement configurations.

The next thing we want to add to our Measurement Tab is some Event Data. 

Add Button Press events to the Measurements Tab

 

The example application will send button press telemetry whenever button A or button B is pressed.  We can display these events on our measurements Tab.  Starting back at the Device Template, click on the “+ New Measurement” link again.  This time we want to add an “Event Type.”

This form is where we define the properties for an event.  We’re going to add an event for a button press.  When the user presses button A on the starter kit we’ll see an indication (event) along the bottom of the Measurements Tab.

  • Display Name: The name of the event, it can be anything you want.
  • Field Name: Just like with the Telemetry entry, this is the key in the key value pair for this data.  Enter “buttonA” in this field.
  • Default Severity: Error, Warning, or Information.  I selected “Information.”

Hit the “Save” button after you entered information into all the fields.

We also have a second button that we’ll monitor from the starter kit.  Use the table below to review the information for button A and to add a button B Event to your application.

Display Name

Field Name

Default Severity

Button A Pressed

buttonA

Information

Button B Pressed

buttonB

Information

 

After both events are added your Measurements Tab should look similar to the picture below.

Add Toggle controls to the Settings Tab

Next we’ll jump over to the Settings Tab.  This is where you can add controls to change things on the Azure Sphere Starter Kit.  We saw with the Measurements Tab that we could add telemetry data as long as we knew the name of the Key in the Key: Value pair telemetry data.  The settings page does not use telemetry data, but instead uses Digital Device Twin data.  Each IoT device connected to Azure has a digital twin stored in the cloud.  Here’s the Microsoft documentation on device twins: link

What we need to understand for this exercise is that each device twin has two sections or JSON objects. The desired properties object and the reported properties object.  Things in the cloud can change desired properties to request changes on the device. IoT devices will receive this cloud to device (C2D) message, implement the change, whatever it is, and then send a reported properties update device to cloud (D2C) message informing Azure of the change.

Items on the Settings Tab leverage device twins.  Let’s jump in and create some settings controls.  Make sure you’re still in the Device Template section and click on the Settings Tab.

You can see that there are a few options for things you can add to the Settings Tab.  We’re going to use the “Toggle” control, but feel free to play with the other items.

Click on the “Toggle” link.

The Configure Toggle form opens.

  • Display Name: The name or label for this toggle control. This can be anything you want.
  • Field Name: This is the name of the key from the device twin that will be used to send the on/off or actually true/false data to the IoT device.  In our case, the application implemented this control using the key userLedRed.
  • On Display Text: Text next to the slider describing its on state. This can be anything you want.
  • Off Display Text: Text next to the slider describing its off state. This can be anything you want.
  • Initial Value: What do you want the default state of this slider to be?

Once you have all the fields filled in, click on the “Save” link at the top of the form.

We have a total of 7-sliders to configure.  Use the table below to confirm the settings for userRedLed and to see how to configure the remaining 6-sliders.

Display Name

Field Name

On Display Text

Off Display Text

Initial Value

Red LED

userLedRed

ON

OFF

Off

Green LED

userLedGreen

ON

OFF

Off

Blue LED

userLedBlue

ON

OFF

Off

WLAN LED

wifiLed

ON

OFF

Off

APP LED

appLed

ON

OFF

Off

Relay #1

clickBoardRelay1

ON

OFF

Off

Relay #2

clickBoardRelay2

ON

OFF

Off

 

Once you create all the new sliders, they will be all over the screen.  You can use your mouse to drag them around the screen to organize them anyway you like.  The screen shot below shows all my sliders configured and organized.  I also added a few Labels to help users understand what each group is for.

 

 

Add Application information to the Properties Tab

Next we’ll jump over to the Properties Tab.  A property is data about the device that the user can’t change.  Like items on the Settings Tab, we’ll utilize device twin key:value pairs to read property data from the IoT device.  These items are different from the device twin settings items because there is not any code in the Azure Sphere implementation to “catch” desired properties for the these items.  This is a one-way path, where Azure Sphere sends reported properties to the cloud.  Adding these items is similar to what we’ve been doing already.  Make sure you’re still in the Device Template section and click on the Properties Tab.

Click on the “Properties Tab”, then "Device Property." That will bring up the “Device Property” form.

When the form comes up, enter the following information

  • Display Name: The label for the property.
  • Field Name: Similar to a control on the “Settings Page,” we input the name of the key of the key: value pair that contains the property we want to display.
  • Data Type: Select the data type that represents the data in your key : value pair.  We’ll select text since we’re reading a string.

Once you have all the required fields filled in click on the “Save” button at the top of the form.

We have a total of 4 properties that we want to display on the “Properties Tab.”  Use the table below to verify the information you used for the Application Version and to create additional property fields.

Display Name

Field Name

Data Type

Application Version

versionString

Text

Current Wi-Fi SSID

ssid

Text

Wi-Fi Radio BSSID

bssid

Text

Current Wi-Fi Frequency (MHz)

freq

Text

 

After you have all the properties configured, your screen should look similar to the picture below. Note I arranged my properties and added two labels to help organize the data.

And that’s all there is to creating a IoT Central Application.  Once you’re comfortable with all the controls and how things work, you can create a new application in 30 minutes or less!  So we have our application, the next thing to do is to provision our device to allow it to connect to our new shiny application.  But before we go there . . .

Bonus Material on IoT Central and digital device twins

When we looked at device twins in the IoT Hub example, we kept it simple.  Desired and Reported properties were represented a simple key: value pairs.  For example . . .

 

Device twins for the IoT Hub example

The format for digital twins is flexible.  As long as the data is valid JSON and all applications that use the digital twin data understand the format, it can be whatever you want.  IoT Central implements digital twins in a way to allow the application to provide user feedback when making changes from the settings tab.  The settings tab will display a status update under the slider to help the user see that the change was requested and that the change was acknowledged by the IoT device.  If you look at the device application code, you'll see that the only difference between the IoT Hub application and the IoT Central application is how we handle device twin messages.

 

The graphics below show some of the digital twin details for my device.  There are three things I want to point out.

  1. The desired property object is not a simple key: value pair.
  2. The reported properties for the static items in our implementation ARE simple key: value pairs.  See the ssid, freq, bssid, and versionString keys.
  3. The reported properties for the slider controls on our settings tab are objects with three different elements
    1. Value: The value for this item, in the capture the value is false
    2. Status: This field communicates to IoT central what happened when the device tried to make the requested change.  In this case we report "completed."  I've never found any documentation on this implementation, but I have tried to send "failed" and the interface reported the a status of "Item could not sync" or something similar.
    3. DesiredVersion: This represents the requested version that the reported status is responding to .  Each desired property will include an associated message version, this version is captured and echoed back in the reported response.

 

There is a tool called iotc-explorer that will allow you to monitor telemetry messages and dump the device twin for IoT Central applications here

Provision Devices in IoT Central

There are multiple ways to provision devices into IoT Central.  The easiest way if you’re only dealing with one device is to add it manually and use a connection string.  If you need to connect 25 or 1,000,000 devices there are provisioning services that you can leverage.  Since we’re only connecting a single device, I’ll provide details for manually provisioning a device.

Add the device to IoT Central

To manually add a device to IoT Central, navigate to the Device Explorer by clicking on Device Explorer à AvnetStarterKit (1.0.0).

Once you’re in the Device Explorer you’ll see the simulated device that was automatically created for you and no other devices listed.

Add a new “Real” device by clicking on the “+” link and selecting “Real.”

This will open the “Create New Device” form. 

  • Device ID: Leave this set to the default. 
  • Device Name: This field is pre-populated with the device template name and the device ID.   I like to change it to something friendly. 

Click the “Create” button.

Once created, you’ll be taken to the new devices main page.  There’s nothing interesting here yet, because our device is not yet connected to the application.  The next step is to generate the connection string.

Connection String

To generate the connection string we’ll use a tool called dps-keygen. This is a simple command line tool where you provide specific information about your IoT Central application and your device, and the tool generates a connection string that your application can use to connect to IoT Central.

There are a few steps to get the connection string

Install the dps-keygen utility

From Windows Powershell execute the command > npm i -g dps-keygenYou should see output similar to the picture below:

Find the required data in IoT Central

Navigate to your “real” device and click on the Connect link at the top right.

The “Device Connection” dialog box contains all the details we need to use the dps-keygen utility. We need Scope ID, Device ID, and Primary Key.  Notice that Microsoft provides a link at the right side to copy the contents into the copy/paste buffer.

Generate the connection string

Back in Windows PowerShell use the dsp-keygen utility to generate the connection string.  The command is

>dps-keygen -si: <scope ID> -di: <device ID> -dk: <device primary shared key>

Using my device details it looks like this:

My connection string is: HostName=iotc-0d18b636-6088-4bcb-b654-3f7758baf097.azure-devices.net;DeviceId=0f22da28-d345-4035-a813-cff4ed607cd3;SharedAccessKey=YL7s89qZJBfQhUpurwXfN2g7pUXc24FuxG+YWVi5PZI=

What did this utility do? dps-keygen used my scope ID to determine the hostname for my application.  It then concatenated the hostname, device ID, and shared access key into the connection string.

Modify the Azure Sphere source code

Now let’s go back to Visual Studio.  If it’s not open, go ahead and launch the Visual Studio application and open the “AvnetStarterKitReferenceDesign” project.  Visual Studio keeps a list of recent projects, your project should be found in that list.

 

Remember in the simple non-connected application we discussed the three different build configurations:

  1. No cloud connectivity.  This is the simplest configuration.  The application runs and you can monitor sensor data from the Visual Studio debug window.
  2. IoT Hub connectivity.  This configuration requires an Azure IoT Hub and an IoT Hub connection string.  Once we have the Hub configured and the application connecting to the IoT Hub, we’ll walk through how to provision a Time Series Insights (TSI) application to visualize the sensor data and control GPIOs on the board from the cloud.
  3. IoT Central connectivity.  This configuration leverages Microsoft’s IoT Central SaaS product.  IoT Central provides a simple interface that allows users to visualize telemetry and to control connected devices.

For this example we’ll enable the IoT Central configuration.

  • Open the build_options.h file
  • On line #5 remove the “//” comment characters to enable the #define IOT_CENTRAL_APPLICATION configuration.
  • If you completed blog #2, make sure to comment out line #8 that defines the IOT_HUB_APPLICATION.  If both of these are enabled, you'll see a build error stating the issue.

Next we need to hardcode the connection string for out IoT device.

    • Open connection_strings.h and paste the connection string you generated with the dps-keygen tool inside the “”.  The entry in my file looks like this:

Remember in the first blog I stated that the Azure Sphere device is locked down?  Well here’s a case where the device needs explicit permission to connect to a specific external server.  If you don’t tell the OS about external servers you want to connect to, then the OS will not allow any traffic to your server.  Take a look at our connection string. Notice that the first part of the string contains a FQDN hostname, in my case, the hostname is “iotc-0d18b636-6088-4bcb-b654-3f7758baf097.azure-devices.net” 

  • Open the app_manifest.json file.  This file is located outside the other folders in your Solution Explorer window, usually at the very bottom of the list.
  • Find the “AllowedConnections” entry and paste the hostname from your connection string into the field with a set of “” around the text.  If you already have a FQDN for your IoT Hub example, you can replace this FQDN, or add to the list by comma separating the two entries.

To review.  The modifications we made to the source code . . .

  1. We enabled the IOT_CENTRAL_APPLICATION define in build_options.h
  2. We verified that #define IOT_HUB_APPLICATION is commented out in build_options.h
  3. We added our connection string to the connection_strings.h file
  4. We added our hostname string to the “AllowedConnection” entry in the app_manifest.json file

We should be ready to build the IoT Hub configuration!

Build and run the application

To compile, link and load the application onto your Starter Kit, you just need to click on the “Remote GDB Debugger” button in the toolbar.

You’ll see the build process run and a popup box stating that Visual Studio is starting the application. If you look at the output window, you should see something similar to the text below.

Let's review this output . . .

Updating device twin:

This output is showing that the application is sending device twin updates.  You can see in the output that these updates are sent as JSON {key: value} pairs.

IOTHUB_CLIENT_CONNECTION_OK

This output shows that our device has connected to our IoT Hub.  If you don't see your device connect to the IoT Hub, please review the Troubleshooting Azure IoT Hub Connection Issues blog entry.

Updating device twin:

This output is generated because the IoT Central application is sending down device twin desired properties that align with the toggle controls we added to the Settings Tab in IoT Central. You'll notice that there is an entry for each item we added.  For each item, we receive the message, validate that we understand the "key" and then do something based on the "value" of the key: value pair.  Next we send up a device twin update to inform the IoT Central application that we did indeed make the requested change.

Sending telemetry:

This output shows the telemetry data we’re sending to Azure.  As with the device twin update message, we’re sending JSON key: value pairs. To send telemetry, you just need a valid JSON structure.  The IoT Hub will collect this data and simply pass it on to any services that subscribe to the IoT Hub. 

 

  Did you know?
  • Click Boards
    • There are over 650 different Click Boards available that can be used on the Avnet Starter Kit

 

IoT Central

Now that our application is running on the Avnet Starter Kit, let's open our IoT Central application.  The first thing we need to do is to find our device.

  • Navigate to your IoT Central web site
  • Click on "Device Explorer"
  • Click on your template
  • Click on your device

This opens up the main page for your device and will default to the "Measurements" Tab.  The graphic below shows my device.  Note I was spinning my Avnet Starter Kit around to generate this data.  You can see the telemetry from the LSM6DSO device and the button press events on this page.

Now click on the Settings Tab

  • Change one or more of the sliders and click the "Update" button at the top of the page.  The application on the device will receive the device twin desired object and make the appropriate changes.

Next lets look at the Properties Page.  Click on the Properties Tab.

 

Here we can see the properties that my device sent up to IoT Central

 

 

 

Below is a short video showing the IoT Central application in action.

 

 

Review

 

That concludes the demo, what did we learn?

  • How to create a IoT Central application from scratch
  • How to generate a IoT Central connection string
  • How IoT Central uses JSON objects for device twin data
  • How to configure the sample application to connect to IoT Central
  • How to use IoT Central to view telemetry data
  • How to use IoT Central to change device settings

 

Avnet Azure Sphere Starter Kit

 

Remember that the Avnet Azure Sphere Starter can help you jumpstart your next IoT Project.  Azure Sphere is the easy button for IoT Security, and the Avnet Starter Kit makes it easy to connect hundreds of different sensors and I/O devices for your prototyping needs.  Prototype on your Starter Kit, then migrate your project to the Certified Azure Sphere Module in your final design.

 

Order your Starter Kit today: Link