Create a Smart Device

In this exercise, you create a basic smart device using the C# language and the Universal Windows Application (UWP) template. By using this template, the solution can run locally on your desktop providing you a simulator, and it can be deployed to an SBC running Windows 10 IoT.

Requirements for this exercise:

• Windows 10 Operating System

• Visual Studio 2015 with Update 3

• Windows 10 SDK

• Windows 10 Core IoT Visual Studio Templates

• Azure IoT SDK

Note You can clone the Azure IoT SDK from https://github.com/Azure/azure-iot-sdks .

Before we dive into the device project, you need to create UWP versions of two key libraries so that you can leverage them in your microcontroller software: DeviceModels and MessageModels. If you have completed the exercises in Chapter 2, you will have a version of these libraries that target .NET 4.6 and are used by the cloud-hosted services. The code for the UWP versions of these libraries is already part of the code repository. These next steps will create the build definitions and allow you to add them to your NuGet package feed.

1. Create a new build definition using the Build NuGet Package template you created in Chapter 2 (see Figure 4-17).

   

   Figure 4-17. Create a build definition from the template

2. Fill out the build definition settings for the MessageModelUWP solution as shown in Table 4-1. This solution has been provided as part of the reference implementation repo.

   Table 4-1. Build MessageModelUWP NuGet Package Build Definition

   NuGet Installer Settings
   Path to solution	Models/Message/UWP/MessageModels.sln
   Path to NuGet.Config	nuget.config
   NuGet arguments	-outputdirectory packages
   NuGet version	3.5
   MSBuild Settings
   Path to solution	models/Message/UWP/MessageModels.sln
   Configuration	debug
   NuGet Packager
   Path to CSProj	modelsMessageUWPMessageModelsMessageModels.csproj
   Package Folder	nugets
   Include referenced projects	Yes (checked)
   Configuration to package	debug
   NuGet Publisher
   Path to NuPkg	nugets/Message*.nupkg
   Feed type	Internal
   Internal feed URL	[URL to your package feed]
   NuGet Version	3.5

3. Save the build definition. Create another build definition for the DeviceModelsUWP solution using the same settings. Queue the two new build definitions to add these NuGet packages to your feed.

4. Create a project in Visual Studio called SmartDevice using the Blank App (Universal Windows) template (see Figure 4-18).

   

   Figure 4-18. Create a Windows universal app project

   You will be presented with a dialog box that informs you the target version and minimum version of Windows 10 that will be supported by the project (see Figure 4-19). Select the defaults.

   

   Figure 4-19. New universal Windows project

5. After the project has finished initializing, right-click on the References node in the Solution Explorer and select Manage NuGet Packages from the menu.

   Select NuGet.org as the package source location and search for Azure.Devices. Add a reference to the Microsoft.Azure.Devices.Client NuGet package. Also add a reference to the Newtonsoft.Json NuGet package.

   Select your NuGet feed as the package source and add a reference to the DeviceModelUWP and MessagesModelUWP NuGet packages that you just created. When complete, your solution references should appear as depicted in Figure 4-20.

   

   Figure 4-20. SmartDevice references

6. Open the MainPage.xaml.cs file and add these using statements at the top.

   using Microsoft.Azure.Devices.Client;
   using brt.Models.Message;
   using brt.Models.Device;
   using Newtonsoft.JSON;

   You will need a unique ID for your smart device. We registered several devices using the Bootstrap utility in Chapter 2. You can use the Device Explorer utility that is part of the Azure IoT SDK to look up a registered device Id in IoT Hub to use for your smart device.

   Tip The Device Explorer can be found in the C# IoT SDK azure-iot-sdk-csharp oolsDeviceExplorer folder.

7. Open the Device Explorer solution in another instance of Visual Studio and run the app (see Figure 4-21).

   

   Figure 4-21. Device Explorer

   Enter the connection string to your instance of IoT Hub on the Configuration tab and click the Update button. Navigate to the Management tab and click List (see Figure 4-22).

   

   Figure 4-22. Device Explorer listing devices in IoT Hub

   Select a device and then right-click and choose to copy the data for the selected device. Paste that information into Notepad so that you can access the unique ID to use as the smart device serial number.

   You will also need your API Management hostname and developer key to initialize the properties that define device identity. You can retrieve those settings from the API Management Developer portal.

8. Add the following class variables to the MainPage class in your UWP solution. Use the device ID that you copied from the Device Explorer to use as the device serial number. Update the API URIs to use your APIM hostname and subscription key.

   // Device Identity
   private const string DeviceSerialNumber = "[device-id]";                            
   private const string DeviceApi = "https://[your-apim-
       host].azure-api.net/dev/v1/device/manifests/id/" + DeviceSerialNumber;
   private const string SubscriptionKey =
       "subscription-key=[your-apim-devkey] ";
   private static Manifest _deviceManifest;
   private static DeviceClient _deviceClient;
                                                                                                                             
   // Thread Management
   private static Task _heartbeatTask;
   private static Task _telemetryTask;

9. Open the MainPage.xaml file and add a MainPage_OnLoaded() event handler to the <Page> element. The handler is defined in the XAML file and the function is generated in the MainPage.xaml.cs file.

   <Page
   ...
       Loaded="MainPage_OnLoaded">
   ...
   </Page>

10. Add the async keyword to the method signature of MainPage_OnLoaded().

    private async void MainPage_OnLoaded(
      object sender, RoutedEventArgs e)
    {
      throw new System.NotImplementedException();
    }

11. In the Mainpage.Xaml file, replace the <Grid> element section with this XAML code:

    <Grid Background="{ ThemeResource
        ApplicationPageBackgroundThemeBrush}">
      <Grid.RowDefinitions>
         <RowDefinition Height="50*"/>
         <RowDefinition Height="50*"/>
      </Grid.RowDefinitions>
    
      <TextBlock Grid.Row="0"
                 HorizontalAlignment="Center"
                 VerticalAlignment="Center"
                 FontSize="24">
          Windows 10 IoT Device
      </TextBlock>
      <StackPanel Grid.Row="1" Margin="10,10,10,10">
      <TextBox x:Name="Status"
               Margin="10"
               IsReadOnly="True"
               TextAlignment="Center" />
      </StackPanel>
    </Grid>

12. Add two private static method stubs for the code that will handle the background messaging threads.

    private static void StartHeartbeat()
    {
    }
    
    private static void StartTelemetry()
    {
    }

13. Add a private static method called GetDeviceManifest() that invokes the Device API to retrieve the device manifest.

    private static async Task<Manifest> GetDeviceManifest()                            
    {
      var client = new HttpClient();
      var uriBuilder = new UriBuilder(DeviceApi)
      {
        Query = SubscriptionKey
      };
      var json = await client.GetStringAsync(uriBuilder.Uri);                        
      var deviceManifest =                        
        JsonConvert.DeserializeObject<Manifest>(json);                        
      return deviceManifest;
    }

14. Replace the body of the MainPage_OnLoaded() event handler with this code.

    Status.Text = "Main Page Loaded";
    
    // get the device manifest
    _deviceManifest = await GetDeviceManifest();                            
    
    try
    {
      // connect to IoT Hub
      _deviceClient = DeviceClient.Create(                        
        _deviceManifest.Hub,
        AuthenticationMethodFactory
          .CreateAuthenticationWithRegistrySymmetricKey(
            _deviceManifest.SerialNumber,
            _deviceManifest.Key.PrimaryKey),
        TransportType.Amqp);
    
       Status.Text = $"{_deviceManifest.SerialNumber}
         Connected to Azure IoT Hub";
    }
    catch (Exception connectionErr)
    {
         Status.Text = connectionErr.Message;
    }
    
    StartHeartbeat();
    StartTelemetry();

    This code will invoke the Device API to retrieve the device manifest and connect to IoT Hub using properties of the device manifest. If successful, a status message is displayed on the application user interface.

    To implement the heartbeat message pattern, we will start a background task and within that task continuously send heartbeat messages based on the cadence setting, which is defined as an extension property in the device manifest. The heartbeat message is defined in the MessageModelsUWP library. It is a simple message that contains an acknowledgement string, the device serial number, and the longitude and latitude of the device.

15. Add the following code to the body of the StartHeartbeat() method.

    var cadence = Convert.ToInt32(                            
        _deviceManifest.Extensions["heartbeat"]);                        
    
    _heartbeatTask = Task.Factory.StartNew(async () =>                            
    {
      while (true)
      {
        // create a heartbeat message                                                                              
        var heartbeat = new Heartbeat
        {
          Ack =
           $"{_deviceManifest.SerialNumber} is functioning",
          Longitude = _deviceManifest.Longitude,
          Latitude = _deviceManifest.Latitude,
          DeviceId = _deviceManifest.SerialNumber
        };
    
        var json = JsonConvert.SerializeObject(heartbeat);
    
        var message = new Message(
            Encoding.ASCII.GetBytes(json));
    
        await _deviceClient.SendEventAsync(message);                        
    
        await Task.Delay(cadence);              
      }
    });

16. To test your smart device, start the Device Explorer utility, select the Data tab, and begin monitoring for messages arriving from your device by selecting its ID from the drop-down.

    Start your Smart Device application . It will begin sending a heartbeat message every 30 seconds (see Figure 4-23).

    

    Figure 4-23. Smart device sending heartbeat messages

    At this point we do not have any connected sensors. We will simulate taking a temperature with an expected range of values between 60 and 70. These readings will be sent more often than heartbeat messages. We will use the SimpleSensorReading class as defined in the MessageModelsUWP library. Like the heartbeat message, it will contain the device serial number and the longitude and latitude. In addition, it will contain a floating point reading for the simulated temperature.

17. Add the following code to the StartTelemetry() method.

    var cadence = Convert.ToInt32(                            
      _deviceManifest.Extensions["telemetry"]);                        
    
    var random = new Random();
    
    _telemetryTask = Task.Factory.StartNew(async () =>
    {
      while (true)
      {
        // the temperature will be simulated
        // it will be a value between 60 and 70
         var sensorReading = new SimpleSensorReading                        
         {
           Longitude = _deviceManifest.Longitude,
           Latitude = _deviceManifest.Latitude,
           DeviceId = _deviceManifest.SerialNumber,
           Reading = random.Next(60, 70)                        
           };
    
        var json =
          JsonConvert.SerializeObject(sensorReading);
    
        var message = new Message(
          Encoding.ASCII.GetBytes(json));
    
        await _deviceClient.SendEventAsync(message);                        
    
        await Task.Delay(cadence);              
      }
    });

18. Run the Smart Device application and review the incoming messages in IoT Hub using the Device Explorer. You should see multiple telemetry messages arriving and an occasional heartbeat (see Figure 4-24).

    

    Figure 4-24. Heartbeat and telemetry arriving in IoT Hub

Deploy Your Smart Device APP to an SBC

Now that we have a functioning Smart Device simulator application, we can deploy it to an SBC. In this exercise, you will update your Smart Device app to use a temperature sensor attached to a Qualcomm DragonBoard. Note that this exercise is not a requirement for going through the other exercises in the book. It is provided here for completeness.

Note To do this exercise, you need a Qualcomm DragonBoard and the 96Boards Linker Starter Kit.

To purchase a Qualcomm DragonBoard, visit https://www.arrow.com/en/products/dragonboard410ciotsdk/arrow-development-tools .

To purchase the 96Board Linker Starter Kit, visit https://www.arrow.com/en/products/96boards-starter-kit/linksprite-technologies-inc .

The requirements for this exercise are as follows:

• DragonBoard 410c

• 96Boards Linker Starter Kit

• DragonBoard Update Utility for Windows 10 IoT

• Windows 10 IoT Core OS for DragonBoard

• USB mouse

• USB keyboard

• HDMI display and cable

• Mini-USB to USB cable

Note Download the DragonBoard Update utility at https://developer.qualcomm.com/hardware/dragonboard-410c/tools .

Download Windows 10 IoT Core for DragonBoard at https://www.microsoft.com/en-us/download/details.aspx?id=50038 .

To enable your PC for device development, you need to configure Developer Mode. Follow the instructions at https://msdn.microsoft.com/windows/uwp/get-started/enable-your-device-for-development to configure your PC.

The DragonBoard 410c is a single-board computer built around a Qualcomm® Snapdragon™ 400 series processor. It features advanced processing power, Wi-Fi, Bluetooth, and GPS, all packed into a board the size of a credit card. Based on the 64-bit capable Snapdragon 410E processor, the DragonBoard 410c is designed to support Linux- or Windows-based software development (see Figure 4-25).

Figure 4-25. DragonBoard 410c overview

1. Set up your hardware as depicted in Figure 4-26. The DragonBoard is connected to an HDMI display and to your development laptop using a mini-USB cable. There is also a USB mouse and USB keyboard attached to the DragonBoard.

   

   Figure 4-26. DragonBoard setup

   Note It is recommended that whenever you make changes to the hardware configuration of the board, that you power down the DragonBoard and remove the power cable.

2. Flash the DragonBoard with the Windows 10 Core IoT operating system.

   • Plug the HDMI adapter, the USB keyboard, and mouse into the DragonBoard.

   • Use the mini-USB to USB adapter to connect the board to your PC.

   Note The detailed instructions on how to flash the DragonBoard using the DragonBoard Update Utility and Windows 10 IoT Core are located at https://developer.microsoft.com/en-us/windows/iot/Docs/GetStarted/dragonboard/GetStartedStep1.htm .

   Once the device has been flashed and connected to your wireless network, you can manage the device using the Windows Device portal. The Windows Device portal is an application that is part of Windows 10 IoT Core and is running locally on the DragonBoard. This application is accessible from your PC by using a browser and navigating to the home page of the application running on the device. You will need the IP address of your device on you network. The DragonBoard home screen will display the device IP address, as shown in Figure 4-27.

   

   Figure 4-27. DragonBoard home screen

3. Using a browser, navigate to http://[deviceIP]:8080 and log in to the device portal using the default username and password:

   Username: Administrator
   Password: p@ssw0rd.

   Using this application, you can manage the device name, administrator password, and many other features of the device by navigating through the menu on the left side of the user interface (see Figure 4-28).

   

   Figure 4-28. Windows device portal

   All the Linker kit sensors can be added to the DragonBoard through the Linker mezzanine card. The Linker mezzanine card has eight connectors supporting Analog, UART, I2C, and GPIO, and two channels of analog input using the MCP3004 ADC chip. There are bidirectional voltage-level translators, which allow for low-voltage bidirectional translation between any of the 1.2-V,1.5-V, 1.8-V, 2.5-V, 3.3-V, and 5-V voltage nodes. It is compatible with 3.3V or 5V modules and makes connecting peripherals easy. You can select the appropriate voltage by placing a jumper on the JP9 voltage selector. We will be using the mezzanine in 5-V mode as that is what is required by the sensors we are going to attach.

4. Power down the device and remove the keyboard and mouse. Set the voltage to 5V using the JP9 jumper, as shown in Figure 4-29.

   

   Figure 4-29. Set the voltage jumper to 5V

5. Stack the mezzanine board on top of the DragonBoard and carefully insert the general-purpose I/O (GPIO) prongs into the GPIO connectors on the DragonBoard (see Figure 4-30).

   

   Figure 4-30. Before and after stacking the mezzanine

6. Attach the red LED sensor and the thermal sensor as shown in Figure 4-31.

   • Using an adapter cable, attach one end to the red LED module and the other to the connector labeled DC2 on the Linker mezzanine.

   • Using a second adapter cable, attach one end to the thermal sensor and the other to the connector labeled ADC1 on the Linker mezzanine.

   

   Figure 4-31. Sensors attached

7. Attach the keyboard, mouse, and HDMI monitor to the power cable. You are now ready to test the full hardware configuration.

8. Add a reference to the Windows IoT Extensions for UWP to your Smart Device solution. This library will provide high-level classes for working with single-board computers.

   Right-click on the References node in the Solution Explorer and select Add Reference. Select Universal Windows ➤ Extensions in the left menu. Check the box next to the Windows IoT Extensions for the UWP for version 10.0.14393 and then click OK (see Figure 4-32).

   

   Figure 4-32. Add a reference to the Windows IoT extensions

9. Add the following using statements at the top of the MainPage.xaml.cs file:

   using Windows.Devices.Gpio;
   using Windows.Devices.Spi;
   using Windows.Devices.Enumeration;

10. Add the following private variables to the MainPage class. These are used to connect and communicate with the general-purpose I/O (GPIO) interface and the serial peripheral interface (SPI) bus.

    // GPIO
    private static GpioPinValue _value;
    private const int LedPin = 13;
    private static GpioPin _led;
    
    // SPI
    private static byte[] _readBuffer =
        new byte[3] { 0x00, 0x00, 0x00 };
    private static byte[] _writeBuffer =
        new byte[3] { 0x01, 0x80, 0x00 };
    private const string SpiControllerName = "SPI0";
    private const int SpiChipSelectLine = 0;
    private static SpiDevice _spiDisplay;

11. Add a private static method to initialize the GPIO. The GPIO interface will be used to turn the red LED on and off.

    private static void InitGPIO()
    {
      _led = GpioController.GetDefault().OpenPin(LedPin);
      _led.Write(GpioPinValue.Low);
      _led.SetDriveMode(GpioPinDriveMode.Output);
    }

12. Add an asynchronous private static method to turn the LED on and off. This is done by setting the value of the LED pin location to high (on), sleeping for some number of milliseconds, and then setting the pin to low (off). This will cause the LED light to blink on and then off.

    public static async void BlinkLED(int duration)
    {
      _led.Write(GpioPinValue.High);
      await Task.Delay(duration);
      _led.Write(GpioPinValue.Low);
    }

13. Add a private static method to initialize the SPI. The SPI will be used to communicate with the temperature sensor using the analog-to-digital converter on the mezzanine board.

    private static async void InitSPI()
    {
      try
      {
        var settings =
          new SpiConnectionSettings(SpiChipSelectLine)
        {
          ClockFrequency = 500000,
          Mode = SpiMode.Mode0
        };
    
        var spiAqs = SpiDevice.GetDeviceSelector(
          SpiControllerName);
        var deviceInfo = await
          DeviceInformation.FindAllAsync(spiAqs);
    
        _spiDisplay = await SpiDevice.FromIdAsync(
          deviceInfo[0].Id, settings);
      }
      catch (Exception ex)
      {
        throw new Exception("SPI Initialization Failed", ex);
      }
    }

14. Add a private static helper method to convert the byte array returned from the sensor into a floating-point value.

    public static double ConvertToDouble(byte[] data)
    {
      int result = 0;
      int i = Convert.ToInt32("1100000000", 2);
      result = (data[1] << 8) & i;
      result |= (data[2] & 0xff);
      return result;
    }

15. Update the StartTelemetry() method to use the SPI interface to read the temperature sensor and set that as the temperature reading of the simple sensor message. This replaces the use of the random number generator.

    // get the temperature setting from the sensor
    _spiDisplay.TransferFullDuplex(                            
      _writeBuffer, _readBuffer);                        
    
    // convert the value to Fahrenheit
    var temperature = ConvertToDouble(_readBuffer);                            
    temperature = (((temperature * 5.0) /                            
      (1023 - 0.5)) * 100);                        
    
    var sensorReading = new SimpleSensorReading
    {
      Longitude = _deviceManifest.Longitude,
      Latitude = _deviceManifest.Latitude,
      DeviceId = _deviceManifest.SerialNumber,
      Reading = temperature                        
    };

16. Add a call to the BlinkLED() method right after sending the temperature message to IoT Hub. Pass in a value of 500ms for the duration of the blink.

    await _deviceClient.SendEventAsync(message);
    BlinkLED(500);                            

17. Update the start of the MainPage_OnLoaded() method to call the GPIOInit() and SPIInit() methods.

    Status.Text = "Main Page Loaded";
    InitGPIO();
    Status.Text = "GPIO Initialized";
    InitSPI();
    Status.Text = "SPI Initialized";

    That’s it. We are now ready to test our smart device.

18. To deploy the application to the device, set the Build Target to ARM and then select Remote Machine, as shown in Figure 4-33.

    

    Figure 4-33. Configure Visual Studio to build and deploy a solution to a remote device

    The first time you do this Visual Studio will request the IP address of the device. Provide the IP address from the DragonBoard home screen, as shown in Figure 4-34, and click Select.

    

    Figure 4-34. Setting the IP address of your SBC in Visual Studio

19. Run the application using the Visual Studio debugger. The applications will be built and deployed to your DragonBoard. You will see the UI on your HDMI display and you can track the incoming heartbeat and temperature messages on your PC using the Device Explorer utility, as shown in Figure 4-35.

    

    Figure 4-35. DragonBoard sending heartbeat and temperature sensor messages to IoT Hub

    Note You can use Visual Studio to set breakpoints and do remote debugging using this configuration.

Modify the Team Simulators

The Real-Time Business reference implementation is a multi-tenant solution. It provides a common set of platform services that can be used by many customers at the same time, providing secure access to data for each customer.

In our scenario, each company has defined groups of employees called teams, where each member of the team is connected to the cloud using a sensor-enabled vest. Companies can monitor biometric readings from individual employees, which are then routed to advanced analytics services to identify exhaustion and stress levels and provide real-time data visualization, alerts, and notifications.

The reference implementation provides three console applications for simulating the teams. Each application simulates a connected team of 15 employees from these pseudo-companies:

• WigiTech: A Massachusetts-based technology company that sensor-enables its factory floor workers who work in and around dangerous machinery.

• Tall Towers: A utility services company that sensor-enables its field engineers to monitor for exhaustion and stress as they climb towers atop skyscrapers in downtown New York.

• The Complicated Badger: A Chicago-based trucking company that specializes in moving large, dangerous cargo and monitors its drivers for alertness.

The reference implementation includes a microservice called Simulation that provides data to drive the analytics. The sample data is made up of 4200 biometric reading records (containing several biometric sensor readings) for each of 15 individuals resulting in a total of 63K data records. Each simulator application uses this same data set. Therefore, if you run all three simulators at the same time, you will be simulating a total of 45 employees from three different companies.

Each simulator upon startup uses the Registry API and the Device API to retrieve a profile and a device manifest for each teammate. Next it starts a background thread for each teammate. Within that thread, it retrieves a simulation data record and, using the user profile, manifest, and simulation data record, constructs a message and sends it to the Azure IoT Hub. The fields in the message are outlined in the following code snippet.

UserId = teammate.Profile.id,
DeviceId = teammate.Manifest.SerialNumber,
Longitude = teammate.Manifest.Longitude,
Latitude = teammate.Manifest.Latitude,
Status = SensorStatus.Normal,
Timestamp = DateTime.Now,
Age = teammate.Profile.biometrics.age,
Weight = teammate.Profile.biometrics.weight,
Height = teammate.Profile.biometrics.height,
BreathingRate = datarow.columns[0].dataValue,
Ventilation = datarow.columns[1].dataValue,
Activity = datarow.columns[2].dataValue,
HeartRateBPM = datarow.columns[3].dataValue,
Cadence = datarow.columns[4].dataValue,
Velocity = datarow.columns[5].dataValue,
Speed = datarow.columns[6].dataValue,
HIB = datarow.columns[7].dataValue,
HeartrateRedZone = datarow.columns[8].dataValue,
HeartrateVariability = datarow.columns[9].dataValue,
Temperature = datarow.columns[10].dataValue

To use the simulators , you need to make some minor updates to each of the three simulator applications so that they use the managed APIs that you deployed using the exercises in Chapter 2. The team simulators are in the devices/device-teamsim folder. There you will find a simulator for each pseudo-company.

1. Navigate to the devices/device-teamsim/wigitech folder and open the WigiTechSim solution.

2. Open the App.config file and update the following configuration settings:

   <add key="DeviceAPI" value="https://[your-apim-host].azure-api.net/dev/v1/device/manifests" />
   
   <add key="RegistryAPI" value="https://[your-apim-host].azure-api.net/dev/v1/registry/profiles" />
   
   <add key="SimulationAPI" value="https://[your-apim-host].azure-api.net/dev/v1/simulation/datasets" />
   
   <add key="SubscriptionKey" value="subscription-key=[your-dev-key]" />

3. Do this for each of the other simulator applications as well.

4. Start the Device Explorer and each of the three simulator applications. Once they are connected to IoT Hub and are sending data, you can use the Device Explorer to check the messages coming from the devices associated with each of the simulators (see Figure 4-36).

   

   Figure 4-36. Three simulators and the Device Explorer

   Each of the device serial numbers is displayed in the console window so that you can easily correlate them to the Device Explorer.