6.1.5.1 Building and Running the Azure Cloud Demo Application

Building the Application

To build this application, open the project file (apps/azure_demo/azure_demo_sam_e54_xpro_wincs02.X/) in MPLAB X IDE. For more details on opening the project file in MPLAB X IDE, refer to the Opening the Project File. The following table provides details on the project file.

Running the Application

1. Create a Root of Trust Chain for WINCS Devices:
   The demo application includes a set of tools in ../apps/azure_cloud/tools folder. It enables easy creation of certificate infrastructure and individual device certificates with very minimal user inputs.

   Note:

   • On Windows Operating Systems, make sure the GitBash is installed to run these tools.
   • These scripts are based on the Azure's Create and Upload Certificates for Testing tutorial.
   1. Right click and open the Git Bash in the tools folder

      

   2. Run the create_initial_setup.sh as illustrated in the following figure. It will request the user to provide the domain suffix and common name for Root CA.

      

   3. Up on successful execution of above command, following three new folders will be created

      

2. Device Certificate
   1. Run the create_device_certificate.sh to create individual device certificate. It requests the user to provide Subordinate/Intermediate CA folder name and a unique device id (Common Name).

      

      Note:

      • Note down the information of device ID or common name for later use in Azure configuration.
      • In order to modify the default subject identifier information, open the create_device_certificate.sh and update the following macros.

      

   2. On successful execution of device certificate, a new folder is created inside the ../tools/devcerts folder as illustrated in following figure
      Note: Note down the information of certificate and key file names (by default device ID or common name) for use later in the Azure TLS configuration
   3. Use the PC companion mode of the setup and program the .pem and * .key* files (highlighted/marked below) using file_upload tools.

      

3. To establish a connection with a Azure IoT Hub without using Azure DPS or configuring Azure IoT Central service, follow Appendix A.1.

   Note:

   • This is applicable to only v2.0.0 Azure Cloud Demo
   • In 32-bit Azure Cloud demo application the authentication type is X.509 Self-Signed
4. Connect the debugger USB port on the SAM E54 Xplained Pro evaluation kit to computer using a micro USB cable
5. Open the project and launch MCC with Harmony3
6. Change the configuration. There are two options to change the configuration:
   1. Option 1: Change the configuration manually in the code
      1. Open the code in MPLAB IDE v6.00 or higher and add Home AP and device information in the application code.
         • In configuration.h, add Wi-Fi configurations in SYS_RNWF_WIFI_STA_SSID, SYS_RNWF_WIFI_STA_PWD, SYS_RNWF_STA_SECURITY.
         • In configuration.h, add Serial Number (Common Name) in the macro SYS_RNWF_MQTT_CLIENT_ID. This value is the same the user can get as shown in Figure 6-24 for “Device ID”. The device ID will be listed as shown in the following figure.

           

         • In configuration.h, add IoT hub’s URL in the macro SYS_RNWF_MQTT_CLOUD_URL (see the following figure).

           

         • In configuration.h, add username in format iothub broker url}/{registration_id}/?api-version=2021-04-12 to macro SYS_RNWF_MQTT_CLOUD_USER_NAME. Replace {iothub broker url} with URL of the IOT hub and {registration_id} with Serial Number (Common Name).
         • Similarly, in configuration.h, SYS_RNWF_MQTT_TOPIC_NAME is in format devices/{registration_id}/messages/events/. Replace {registration_id} with Serial number (Common Name).
   2. Option 2: Change the configuration via MCC.
      • For more details about Wi-Fi configurations, refer Figure 4-25.
        1. The following fields can be configured via MCC Wi-Fi settings;
           1. SSID
           2. Security Type
           3. Passphrase
      • Refer Figure 4-31 to understand how to make Cloud Configuration changes
        1. The following fields can be configured via MCC settings.
           • Cloud URL
             1. Replace with IOT hub’s URL.

                This value is displayed on the “Overview” tab of the IoT Hub webpage. Refer Figure 6-23.

           • Client ID
             1. Add Serial Number (Common Name). Refer

                

                .

                (Or)

                Go to “Devices” in the IoT Hub. The user can find the Serial Number in the device list. Refer Figure 6-22.

           • Username
             1. The format of username field is {iothub broker url}/{registration_id}/?api-version=2021-04-12. Replace {iothub broker url} with IoT hub’s URL and {registration_id} with Serial Number (Common Name).
           • Publish Topic Name
             1. The format of publish topic name is devices/{registration_id}/messages/event. Replace {registration_id} with the user’s Client ID.
7. Generate the code as illustrated below

   

8. Build and program the code to the hardware using MPLABX IDE

   

9. Open the Terminal application (for example, Tera Term or PuTTY) on the PC

   Connect to the "EDBG Virtual COM Port" and configure the serial settings as follows:

   1. Baud: 115200
   2. Data: 8 Bits
   3. Parity: None
   4. Stop: 1 Bit
   5. Flow Control: None
10. Press the Reset button on the host board, see Figure 6-1.
11. As the board boots up, application will list available certificates and keys on WINCS02PC board. The board will connect to Home-AP configured. After this, the demo will attempt to connect to Azure IoT Hub (using link configured it sends telemetry data for button press events and its count to the cloud.). To verify the device-to-cloud and cloud-to-device telemetry, use Azure IoT Explorer application (https://learn.microsoft.com/en-us/azure/iot/howto-use-iot-explorer).