SAM_IoT_Central.md

Connecting the SAM-IoT WG Development Board (Part No. EV75S95A) to Azure IoT Central

NOTE: Should you encounter any issues/obstacles with the following procedure, check out the FAQ section

Introduction

Azure IoT Central is an IoT application platform that reduces the burden and cost of developing, managing, and maintaining enterprise-grade IoT solutions. Choosing to build with IoT Central gives you the opportunity to focus time, money, and energy on transforming your business with IoT data, rather than just maintaining and updating a complex and continually evolving IoT infrastructure.

The web UI lets you quickly connect devices, monitor device conditions, create rules, and manage millions of devices and their data throughout their life cycle. Furthermore, it enables you to act on device insights by extending IoT intelligence into line-of-business applications.

IoT Plug and Play enables solution builders to integrate IoT devices with their solutions without any manual configuration. At the core of IoT Plug and Play, is a device model that a device uses to advertise its capabilities to an IoT Plug and Play-enabled application. This model is structured as a set of elements that define:

• Properties that represent the read-only or writable state of a device or other entity. For example, a device serial number may be a read-only property and a target temperature on a thermostat may be a writable property

• Telemetry which is the data emitted by a device, whether the data is a regular stream of sensor readings, an occasional error, or an information message

• Commands that describe a function or operation that can be done on a device. For example, a command could reboot a gateway or take a picture using a remote camera

As a solution builder, you can use IoT Central to develop a cloud-hosted IoT solution that uses IoT Plug and Play devices. IoT Plug and Play devices connect directly to an IoT Central application where you can use customizable dashboards to monitor and control your devices. You can also use device templates in the IoT Central web UI to create and edit Device Twins Definition Language (DTDL) models.

Program the Plug and Play Demo

1. Clone/download the MPLAB X demo project by issuing the following commands in a Command Prompt or PowerShell window

   git clone https://github.com/Azure-Samples/Microchip-SAM-IoT-Wx.git
   cd Microchip-SAM-IoT-Wx
   git submodule update --init

2. Connect the board to PC, then make sure CURIOSITY device shows up as a disk drive on the Desktop or in a File Explorer window. Drag and drop (i.e. copy) the pre-built *.hex file (located in the folder at Microchip-SAM-IoT-Wx > firmware > AzurePnPDps.X > dist > SAMD21_WG_IOT > production) to the CURIOSITY drive

   

   NOTE: If this file copy operation fails for any reason, Make and Program Device by building the MPLAB X source code project that was used to generate the *.hex file

3. Set up a Command Line Interface (CLI) to the board

   • Open a serial terminal (e.g. PuTTY, TeraTerm, etc.) and connect to the COM port corresponding to your board at 9600 baud (e.g. open PuTTY Configuration window > choose session > choose Serial> Enter the right COMx port). You can find the COM info by opening your PC’s Device Manager > expand Ports(COM & LPT) > take note of Curiosity Virtual COM Port

     

4. Before typing anything in the terminal emulator window, disable the local echo feature in the terminal settings for best results. In the terminal window, hit [RETURN] to bring up the Command Line Interface prompt (which is simply the > character). Type help and then hit [RETURN] to get the list of available commands for the CLI. The Command Line Interface allows you to send simple ASCII-string commands to set or get the user-configurable operating parameters of the application while it is running

   

5. In the terminal emulator window, set the debug messaging level to 0 to temporarily disable the output messages. The debug level can be set anywhere from 0 to 4. Use the debug <level> command by manually typing it into the CLI. The complete command must be followed by hitting [RETURN]

   >debug 0

6. Perform a Wi-Fi scan to see the list of Access Points that are currently being detected by the board's Wi-Fi network controller. Use the wifi command's scan option by manually typing it into the CLI. The complete command must be followed by hitting [RETURN]

   >wifi -scan

7. Configure the SAM-IoT board's internal Wi-Fi settings with your wireless router’s SSID and password using the wifi command's set option by manually typing it into the CLI. The complete command must be followed by hitting [RETURN] (there cannot be any spaces used in the SSID or password)

   >wifi -set <NETWORK_SSID>,<PASSWORD>,<SECURITY_OPTION[1=Open|2=WPA|3=WEP]>

   For example, if the SSID of the router is "MyWirelessRouter" and the WPA/WPA2 key is "MyRoutersPassword", the exact command to type into the CLI (followed by [RETURN]) would be

   >wifi -set MyWirelessRouter,MyRoutersPassword,2

8. At the CLI prompt, type in the command reset and hit [RETURN] to restart the host application. The Blue LED should eventually stay solidly ON to signify that the SAM-IoT board has successfully connected to the wireless router.

   >reset

9. In the terminal emulator window, set the debug messaging level to 0 to temporarily disable the output messages. The debug level can be set anywhere from 0 to 4. Use the debug <level> command by manually typing it into the CLI. The complete command must be followed by hitting [RETURN]

   >debug 0

10. At this point, the board is connected to Wi-Fi, but has not yet established a connection with the cloud (the green and red LEDs may be flashing). The cloud command can be used at any time to confirm the cloud connection status (which as of right now should be false). The complete command must be followed by hitting [RETURN]

    >cloud -status

Create an IoT Central Application

IoT Central allows you to create an application dashboard to monitor the telemetry and take appropriate actions based on customized rules.

1. Create a custom IoT Central application by starting with an existing Microchip IoT Development Board Template (if there is a problem with loading the template, refer to the Create an application section to create your IoT Central application from scratch). If you are not currently logged into your Microsoft account, you will be prompted to sign in with your credentials to proceed. If you do not have an existing Microsoft account, go ahead and create one now by clicking on the Create one! link

2. Azure IoT Builder will guide you through the process of creating your application. Review and select the various settings for your IoT Central application (if needed, refer to Create an application for additional guidance on selecting the settings for your application). Do not click the Create button just yet - only after reviewing and taking into consideration the following recommendations:

   • Choose a unique Application name (which will result in a unique URL) for accessing your application. Azure IoT Builder will populate a suggested unique Application name which can/should be leveraged, resulting in a unique URL shown on the screen. Take note of the unique/customizable portion of the URL (e.g. "custom-1pfphmras2b" like shown in the below screen shot) as it will be needed in a future step (suggest copy/pasting the exact text into a text editor doc file as temporary storage for the name)

     

   • If you select the Free plan, you can connect up to 5 devices for free. However, the free trial period will expire after 7 days which means a paid pricing plan will need to be selected to continue using the application. Of course, there is nothing to stop you from creating a new free trial application but the device will need to be configured for the app from scratch. Since the Standard plans each allow 2 free devices with no time-restricted trial period, if you only plan on evaluating 1 or 2 devices for connecting to the IoT Central app, then it's best to choose the Standard 2 plan to get the highest total allowable number of messages (30K per month)

     

   • Billing info section: If there is an issue with selecting an existing subscription in the drop-down list (or no subscriptions appear in the list at all), click on the Create subscription link to create a new subscription to use for the creation of this application. Take note of the exact subscription name (e.g. "Azure subscription 1" like shown in the below screen shot) which was selected as it will be needed in a future step (suggest copying/pasting the exact text into a text editor file as temporary storage for the name)

     

     NOTE: If the message Something went wrong appears underneath the Azure subscription field, open up a web browser and log into your account using the Azure portal then retry selecting (or creating) a valid subscription

     

3. Click the Create button (the application will be automatically saved in your IoT Central Portal)

4. Whenever specific settings are needed to be read (typically the custom URL to access the application in the future), look up the settings for your application by using the left-hand navigation pane to select Settings > Application > Management

5. To access any of your IoT Central applications in the future, you can also go to Azure IoT Central and click on My apps

   

Create an Enrollment Group

1. Using the left-hand side navigation pane of your IoT Central application, select Security > Permissions > Device connection groups

   

2. Click on the + New button and create a new enrollment group using any name (with Group type = IoT devices and attestation type = Certificates (X.509)). Hit the Save icon when finished

   

3. Now that the new enrollment group has been created, click on Manage Primary

   

4. Click on + Add certificate and browse to the root certificate file (root-ca.crt which should be located in the hidden .microchip_iot sub-folder that was created by the IoT Provisioning Tool). The IoT Provisioning Tool should have created the .microchip_iot hidden folder in the home directory (e.g. /Users/<username>/.microchip_iot). Click the Upload button (then click on Close when the certificate has been accepted)

   

5. Click on Manage Secondary and then click on + Add certificate. Browse to the signer certificate file (signer-ca.crt which should be located in the hidden .microchip_iot sub-folder that was created by the IoT Provisioning Tool). The IoT Provisioning Tool should have created the .microchip_iot hidden folder in the home directory (e.g. /Users/<username>/.microchip_iot). Click the Upload button (then click on Close when the certificate has been accepted)

   

6. Click on the Save icon at the top of the page, and note the ID Scope which was created for the enrollment group. The X.509 enrollment group has been successfully created and should be ready to go!

   

Test SAM-IoT Device with the IoT Central Application

1. Launch a terminal emulator window and connect to the COM port corresponding to the SAM-IoT board at 9600 baud (disable local echo for the terminal settings for best results). If there are continuous non-stop messages being displayed on the terminal, disable them by typing debug 0 followed by [RETURN]. Hit [RETURN] a couple of times to bring up the Command Line Interface prompt (which is simply the > character). Type help and then hit [RETURN] to get the list of available commands for the CLI. The Command Line Interface allows you to send simple ASCII-string commands to set or get the user-configurable operating parameters of the application while it is running

   

2. Look up the ID Scope for your IoT Central application (navigate to your application's web page and using the left-hand navigation pane, select Permissions > Device connection groups). The ID Scope will be programmed/saved into the ATECC608A secure element on the board in the next step

   

3. In the terminal emulator window, hit [RETURN] to bring up the Command Line Interface prompt (which is simply the > character>). At the CLI prompt, type in the idscope <your_ID_scope> command to set it (which gets saved in the ATECC608A secure element on the board) and then hit [RETURN]. The ID Scope can be read out from the board by issuing the idscope command without specifying any parameter on the command line - confirm that the ID Scope has been read back correctly before proceeding to the next step

   

   NOTE: Make sure the ID scope reads back correctly. If not, keep repeating the write/read sequence until the correct ID scope has been read back from the board

4. In the terminal emulator window, hit [RETURN] to bring up the CLI prompt. Type in the command reset and hit [RETURN]

5. Wait for the SAM-IoT board to connect to your IoT Central application’s DPS; the Blue and Green LEDs will be flashing and/or staying on at different times/rates (which could take up to a few minutes). Eventually the Blue and Green LEDs should both remain constantly ON.

   NOTE: If the Red LED comes on, then something may have been incorrectly programmed (e.g. wrong firmware, ID scope was entered incorrectly, etc.)

6. At this point, the board should have established a valid cloud connection (this can be confirmed visually by the Green LED staying on constantly). The cloud command can be used at any time to confirm the cloud connection status using the CLI. The complete command must be followed by hitting [RETURN]

   >cloud -status

7. Go back to your web browser to access the Azure IoT Central application. Use the left-hand side pane and select Devices > All Devices. Confirm that your device is listed – the device name & ID is the Common Name of the device certificate (which should be sn + {17-digit device ID}). Click on the device name to see the additional details available for viewing

   

8. If desired, change the Device name by clicking on Manage device > Rename

   

9. Click on the Commands tab; type PT5S in the Delay before rebooting SAM-IoT field and then click on Run to send the command to the device to reboot in 5 seconds

   

10. Within 5 seconds of sending the Reboot command, the SAM-IoT development board should reset itself. Once the Blue and Green LED's both stay constantly ON, press the SW0 and SW1 buttons (the Red LED may toggle with each button press)

    

11. Click on the Properties (Writable) tab and type 0 (zero) in the Disable Telemetry field, then hit Save

    

12. Click on the Raw data tab and confirm that the button press telemetry messages were received (scroll the page to the right to view the SW0/SW1 button push event column)

    

13. Click on the Refresh icon to display all messages received since the previous page refresh operation. Confirm that periodic telemetry messages are being continuously received approximately every 10 seconds (the default interval value for the telemetryInterval property)

    

14. Increase the ambient light source shining on top of the board. Wait approximately 30 seconds. Click on the Refresh icon to confirm that the light sensor value has increased

    

15. Click on the Properties (Writable) tab and try changing the property of the Yellow LED state between On, Off, & Blinking (remember to hit the Save icon for each property write operation to take effect). Confirm that the Yellow LED on the board corresponds to the state which was selected.

16. Click on the About tab to conveniently view all of the device's property settings/states on a single page.

Configure the Dashboard for Data Visualization

1. Navigate to the left-hand vertical toolbar and click on the Dashboards icon

   

2. Towards the top of the web page, click on the dashboard selector and change the view to Microchip IoT Light and Temperature Sensors

   

3. Towards the top of the web page, click on the Edit icon

   

4. For all of the existing tiles named Light or Temperature, click on the upper right-hand corner of the tile to select Configure

   

5. Select Device Group > SAM-IoT WM;2 - All devices and then check the box for your specific device name for Devices

   

6. Under the Telemetry category, click on + Capability and select the parameter pertaining to the title of the tile (e.g. Brightness from light sensor for each of the Light tiles or Temperature for each of the Temperature tiles)

   

7. Click on Update and repeat the process for the remainder of the existing tiles

   

8. After every tile has been configured to visualize your device's sensor data, click on the Save icon to save the latest changes to the dashboard

   

9. Confirm that the dashboard is being continuously updated with the expected telemetry data received from the device. For example, adjust the ambient light source directed at the board and observe that the light sensor values are changing accordingly

   

10. To access your IoT Central application(s) in the future, go to Azure IoT Central and click on My apps

    

Expand the Dashboard with Additional Tiles

To create additional tiles for your IoT Central dashboard, refer to Configure the IoT Central application dashboard. The below screen captures show additional possibilities of dashboard components that can highlight the telemetry data and properties facilitated by the Plug and Play interface. Note that multiple devices can be selected for each tile to allow groups of devices to be visualized within a single tile.