Skip to content

Latest commit

 

History

History
595 lines (379 loc) · 27.1 KB

README.md

File metadata and controls

595 lines (379 loc) · 27.1 KB
Raw

Getting Started Guide: Secure Cloud Connectivity and Voice Control Demo for Microchip PIC32 WFI32E Curiosity Board .

Devices: | PIC32 WFI32E | WFI32 | Trust&Go (ECC608) |

Features: | Secure Cloud connectivity | Voice Control |

Frequently Asked Questions

Latest release Latest release date

Introduction

  1. This page describes the Out of Box (OOB) operation of the PIC32 WFI32E Curiosity board .

  2. For accessing pre-built hex files, release notes, and known issues, please click the Releases tab.

Prerequisites

  • PIC32 WFI32E Curiosity Board kit

  • Wi-Fi Access Point or mobile hotspot with Internet access

  • Personal Computer

  • USB-UART converter (optional)

Note: Please use MPLABX 6.20 or higher with MHC 3.6.2 or higher to edit and regenerate the project

Hardware Setup

  1. Ensure that the credentials to the Wi-Fi AP with Internet access are handy

  2. Ensure that J202 jumper is connected to VBUS-VIN

  3. Connect host PC to the USB Power connector (J204) using a USB Type-A male to micro-B USB cable.

Demo block diagram

LED Indications

The on-board red user LED (D202) indicates the connectivity status of the demo.

Red LED Behavior Mode
ON Not connected to Wi-Fi
Fast Blinking Connecting to cloud
OFF Connected to cloud and the demo is operational
Slow Blinking Image issue. Re-flash the demo image to recover

The web application and voice assistant control the green user LED (D204).

Mode of Operation

The demo has a web app and voice-based interaction model. In the web-app based interaction mode, you can visualize the data telemetry from the PIC32 WFI32E Curiosity Board and interact with the the board using a web-browser based application. In the voice-based interaction mode, you can control the on-board user LED with voice commands using Amazon Alexa®.

ℹ️   While editing cloud.json or WIFI.CFG manually, it is preferred to use notepad.exe . Other editors like Notepad++ can damage the underlying FAT FS. You can read more about this generic issue in the discussion here . In case you come across this, reboot the device while SW1 is engaged to format and recover the MSD filesystem.

Web-App Mode

Perform the following steps:

  1. Connect the Curiosity Board to your PC

  2. 3 Green LEDs representing the power section readiness and the red user LED representing network connection status will be active when the board is powered up.

  3. The device enumerates as a mass storage device (MSD).

  4. Open the "clickme.html" file from the MSD on a browser.

ℹ️   It is recommended to use the latest version of a modern browser for this operation.

  1. Download the credentials configuration file (WIFI.CFG) from the landing page and copy it into the enumerated MSD.

ℹ️   It is recommended to not store the file directly on the enumerated MSD. Make sure that you download the file to your computer and then copy the file into the MSD. Please make sure the file is named WIFI.CFG while copying it to the MSD drive.

ℹ️   The on-chip filesystem is hosted on an SPI flash media and configured as FAT16. Browsers like Google Chrome do not handle direct download into FAT16 well. In case you face issues with directly saving the configuration file into the MSD, store the file into your PC first and manually copy the file into the drive to replace the default WIFI.CFG file.

  1. Once the credentials file is copied to the MSD, reset the device to start using the new credentials. Ensure that the copy process has completed before you reset the device.

  2. Upon reset, the device connects to the Wi-Fi followed by the cloud, and the red user LED will turn OFF.

  3. The device control page (landing page of “clickme.html” will indicate that the device data is now available by showing a (tick) mark above the state corresponding to the device connection stage.

  1. Temperature sensor data (in Celsius) will be shown in a graph on the page.

  2. Click on the "What's Next" button beneath the graphs to perform action(s) from the cloud.

  3. Select the "Implement a Cloud-Controlled Actuator" to control an on-board LED from the cloud.

  1. Click on the "Learn More" button to expand the card and Scroll to the bottom of the page to "Control Your Device".

  1. Select an LED state using the toggle button and click on "Send to Device". This will trigger a cloud message to control the on-board (Green) LED.

  1. To navigate directly to the Web-App, use a link in the format https://pic-iot.com/pic32mzw1/aws/ <ThingName>.

Voice Control Mode

  1. Create an account and log-in to the device registration page.

ℹ️   "Supported browsers:" Google Chrome, Mozilla Firefox, Safari, and Microsoft Edge. We recommend downloading the newest browser version for the best experience. Internet Explorer is not supported

You can reach this page by clicking on voice.html in the MSD

  1. Enter your thing name and a friendly name and claim your device by registering it.

Thing ID is at the top of the page just above the temperature graph

- Successfully claimed devices will show up in the device listing in the left side panel.

ℹ️   Only devices registered to the Microchip Cloud account can be registered for voice control and controlled via the voice skills. In case of registration errors, please contact Microchip support

  1. Using the Amazon Alexa® app, enable the skill " Microchip IoT" and add the dev board as a smart home device.

to navigate to the Amazon skill enablement page, click on Microchip IoT

Find out more information about connecting smart home devices at Connect a Smart Home Device to Alexa from this link

  1. You can now control the on-board user LED with voice commands using the "friendly name" provided while claiming the device in step 1.

    E.g: Alexa, turn on the light

OTA Demo

The user can follow the below steps to verify the OTA functionality by downloading the binary file of Test Application which is available at "pic32mzw1_curiosity_oob\binary\test_app.bin"

  1. As a part of OTA process device will try to connect to user defined HTTP server. If device is able to connect to server without any error, it will try to fetch json manifest information.

    • Use the below JSON file format for OTA Server JSON Manifest

      {
    "ota": [
            {
              "files" : [		
                          {
                            "slot_number":0,
                            "length":42248,
                            "URL":"http://192.168.10.14:8000/test_app.bin",
                            "digest":"3804B86D3185BF12A5CAB1128A3F99127B4BCF9CE0AEF98980E37B4D4E7730CF"
                          }
                      ]
            },
            {
                "Version": 1,
                "URL": "http://192.168.10.14:8000/ota_app.bin",
                "Digest": "812829d9cf88b9fa94d80643f08f21f8342a56211c97d427d0ab2910dee6c9f3",
                "Signature": "2+2R/43x3FvNoV8anNW2M5ndo+JlFNzHSjJ+iwL68w1v5XMcBPMx4+3u5lBFejUNU/MLLoP13zxwd45f6MCySQ==",
                "EraseVer": false
            }
        ]
}

      User needs to update the length and URL in the json file. By default, the Digest verification will be disabled.

    • User can use any HTTP server.

    • User may also use python command to create a local http server using below steps:

      • Open command prompt and change directory to the folder where Test App Binaryand JSON file are present.
      • Use the python command in command prompt to start the server : python -m http.server 8000

  2. Run the demo and wait till it gets connected to MQTT. Once the connection to MQTT server is established, enter the command "sysota set 0 0 0 60 "http://192.168.42.95:8000/ota.json"". This command is to be used to set the correct IP (replace the IP 192.168.42.95 in the above command with the IP of the device where the http server is running).

  3. Enter the command "start ota". This command will trigger the OTA demo and download the test app binary from the server.

  4. After completing the download, the device will have a reset and ask the user to "Press 'a' for Cloud Image or 'b' for OTA Downloaded Image". Enter 'b' so that it will jump to the test app and the message from Test App will be displayed as shown below.

Touch Demo

The user can follow the below steps to verify the touch functionality.

  1. Connect the QT8 Xplained Pro to the Xpro Header of the curiosity board.

  2. Issue the below command to enable/disable the touch functionality.

    "touch start" Enable touch functionality.

    "touch stop" Disable touch functionality.

    The command 'touch start' will enable a TCP socket server in the WFI32 device which will send the touch position coordinates to the connected client.

  3. When the demo starts, all the leds on the QT8 Xplained Pro will be glowing. After enabling the touch functionality , the leds turn off and start glowing based on the touch position.

  4. The user can run a script as a TCP client which can connect to the to the TCP server running on the WFI32 device at port 9000 to receive the touch coordinates.

Adding Another Sensor

The front-end supports visualization of up to three pieces of sensor data. Since the Curiosity Board contains Just the temperature sensor by default, we will use the user Switch (SW1) to simulate another sensor. Perform the sollowing steps to start visualizing the switch position in the web application.

  1. Download the latest version of the firmware from the releases tab.

  2. Open the project in MPLABX.

    • Use MPLABX version 6.20 or above and XC32 version 4.35.

  3. In “mqtt_app.c" file comment out the existing telemetry message line and uncomment the graduation step.

  1. Recompile the application and download it into the target.

    • You can access the firmware source code under the src/firmware folder of this repo
    • To compile the project, open the firmware using MPLAB X IDE version 6.20 or higher and use XC32 compiler version 4.35 or higher

  2. Follow the steps given under “Mode of Operation”.

  3. Press SW1 to see the web application graph reflecting the change.

Connecting to Your Cloud Instance

By default, the demo connects to an instance of AWS IoT maintained by Microchip. The demo lets you move the device connection between your cloud instance, and the Microchip maintained AWS IoT instance without a firmware change. Perform the following steps to get the device connected to your own cloud instance.

  1. Create an AWS account or log in to your existing AWS account.

  2. Navigate to IoT Core console > Manage > Things and click on “Create” / “Register a Thing”

  1. Select “Create a single thing”

  1. For thing name, copy and paste the thing name from the original demo web-app. This thing name originates from the device certificate and is used by the firmware to send messages to a unique topic.

  1. Select defaults for the other fields and click “Next” at the bottom of the page.

  2. Select “Create thing without certificate” in the next page.

  1. Go to “Security” > “Policies” and select “Create a Policy”

  1. Create a new policy which allows all connected devices to perform all actions without restrictions

❌   Note: This policy grants unrestricted access for all iot operations, and is to be used only in a development environment. For non-dev environments, all devices in your fleet must have credentials with privileges that authorize intended actions only, which include (but not limited to) AWS IoT MQTT actions such as publishing messages or subscribing to topics with specific scope and context. The specific permission policies can vary for your use cases. Identify the permission policies that best meet your business and security requirements.Please refer to sample policies and security best practices

Item Policy Parameter
Name allowAll
Action iot:*
Resource Arn *
Effect Allow

  1. Navigate to Certificates > Add certificate> Register certificates

  1. Select Create with “CA not registered with AWS IoT”

  2. “Upload” the device certificate.

  3. In the MSD enumerated when the Curiosity Board is plugged in, you can find a “.cer” file with an alphanumeric name. Select this file when prompted to select a certificate.

  4. Select “Activate all” and click “Register certificates”

  1. Select the certificate and Click “Attach policy” and select the “allowAll” policy we created.

  1. Click “Attach thing” and choose the “thing”.

  1. Navigate to “Settings” and copy the "endpoint" URL

  1. Follow below guide to replace the AWS MQTT broker name with the endpoint URL in the OOB project to connect to your own AWS account:
    https://microchipsupport.force.com/s/article/Change-the-MQTT-broker-name-in-the-WFI32-OOB-project-to-connect-to-own-AWS-account

  2. Program the updated code to the board, the device will connect to your own cloud instance.

  3. In the AWS IoT console, navigate to “test” and subscribe to topic “+/sensors”

  1. You will be able to observe periodic temperature data coming into the console from your device.

  2. To control the Green LED, publish the following message:

Topic $aws/things/thingName/shadow/update
Payload 
{
  "state": {
    "desired": {
      "toggle":1
    }
  }
}

Depending on the value of “toggle” (1/0) , the Green LED will be ON/OFF.

Restoring factory cloud configurations

After changing the cloud configurations to connect the device to your cloud instance, there are two mechanisms to recover the factory default configurations.

ℹ️   This step will just restore the cloud and Wi-Fi configurations to factory settings. The image is not altered.

  1. Reboot the device while SW1 is engaged.

    • Keep the switch engaged until the Red LED turns on.

  2. Flash the original demo image by downloading it from the releases tab.

Application Overview

The demo code is written as a FreeRTOS based MPLAB Harmony3 application that leverages the system service-based architecture of PIC32MZ W1.

The following table shows the main RTOS Tasks and their primary roles in the system.

Task Name Roles
app_wifi Maintains Wi-Fi state machine.
msd_app Maintains MSD device and the drive contents including device certificates and cloud configuration.
app_control Maintains synchronized datastore for all tasks.
mqtt_app Maintains MQTT state machine.

The MQTT service internally uses a modified version of the PahoMQTT client to maintain an MQTT connection with AWS IoT Core. The “mqtt_app” task publishes the temperature sensor data every second to AWS IoT Core.

Cloud Interaction

The application publishes data every second to the cloud endpoint.

Topic:

<thingName>/sensors

payload:

{
  "Temperature (C)": temperatureValue
}

  • This data is routed to the web application for rendering.

  • For interacting with the device from the cloud (webapp or voice), AWS device shadows are used.

Device subscribes to delta to receive actionable changes

Topic:

$aws/things/<thingName>/shadow/update/delta

User Interface (webapp/Voice) publishes payload to Device Shadow

Topic:

$aws/things/<thingName>/shadow/update

Payload:

{
  "state": {
    "desired": {
      "toggle": toBeUpdatedToggleValue
    }
  }
}

Device receives the shadow update, takes necessary action, and updates the reported shadow state.

Topic:

$aws/things/<thingName>/shadow/update

Payload:

{
  "state": {
    "reported": {
      "toggle": updatedToggleValue
    }
  }
}

The code for all this interaction is in mqtt_app.c

Secure Provisioning & Transport Layer Security

The PIC32 WFI32E Curiosity Boards kits are shipped with the WFI32 module variants that include an on-board Trust&Go secure element. Since Trust&Go devices are pre-provisioned, the firmware can utilise the on-chip certificate to securely authenticate with AWS IoT Core.

Server certificate verification is skipped to facilitate using the same demo code to connect with other cloud instances or custom MQTT brokers easily. Please refer to (Harmony3 documentation)[https://microchip-mplab-harmony.github.io/net] to learn more about peer certificate verification.

Understanding the Device Shadow in AWS

  1. The AWS broker allows for the use of Shadow Topics. The Shadow Topics are used to retain a specific value within the Broker so that End-Device status updates can be managed.

    • Shadow Topics are used to restore the state of variables or applications.

    • Shadow Topics retain expected values and report if Published data reflects a difference in value.

    • When difference exist the status of the delta is reported to those subscribed to appropriate topic messages.

  1. Updates to the device shadow are published on $aws/things/<ThingName>/shadow/update topic. When a message is sent to the board by changing the value of the toggle fields in Control Your Device section:

    • This message is published on the $aws/things/<ThingName>/shadow/update topic.

    • If the current value of toggle in the device shadow is different from the toggle value present in the AWS Device Shadow, the AWS Shadow service reports this change to the device by publishing a message on $aws/things/<ThingName>/shadow/update/delta topic.

    • The JSON structure of the message sent should be as below

      {
"state": {
    "desired": {
    "toggle": value
    }
},
"version" : 10
}

  2. AWS IoT Core publishes a delta topic message if there is a difference between the reported and desired states. The device would have already subscribed to the delta topic.

  3. You can read more about AWS device shadows (here.)[https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-data-flow.html]

Re-Flashing the device

In case you want to re-flash the device, perform the following steps:

  1. Download and install (MPLABX Integrated Programming Environment)[https://www.microchip.com/mplab/mplab-integrated-programming-environment]
  2. Connect the power source selection jumper (J202) shunt in ‘PKOB-VIN’ position
  3. Connect the Curiosity Board’s debug USB (J302) to your PC.
  4. Open MPLABX IPE and select ‘PIC32MZ1025W104132’ device and ‘PKOB’ tool.
  5. Download the latest FW image (hex file) from the (releases)[ https://github.com/MicrochipTech/PIC32MZW1_Curiosity_OOB/releases/latest] tab and load it into the IPE ‘hex file’ section.
  6. Click on the ‘connect’ and then the ‘program‘ buttons in the IPE and wait for device programming to complete.

Regenerating the demo with Harmony 3

To add additional features to the OOB demo, you might have to regenerate the demo code using Harmony3 after adding additional components or changing the existing configuration. Ensure that you use the same version or Harmony 3 components used in the original demo codebase while regenerating code. You can see the version dependencies of the demo in harmony-manifest-success.yml file found at src\firmware\src\config\pic32mz_w1_curiosity into Harmony3 content manager.

In case of a missmatch between the Harmony 3 components present in the demo and the ones available in disk, Harmony3 Configurator will popup a warning screen during launch. In the case of the sample shown below, the MHC component available in disk is 3.6.0 while the version used in the project is 3.5.1.

It is recommended to use the same versions used in the project while regenerationg the project.

To sync your Harmony3 setup to match the versions used in the demo, folow these steps:

  1. Open Harmony3 Content manager

  1. Click on Load Manifest

  1. When you select the project manifest file, the required versions of Harmony3 dependencies will be checked out by content manager on clocking the ''Apply. In this case, v3.7.0 of wireless_wifi was required by the project was not matching the version available in the local package and will be updated accordingly.

  1. Close content manager and open the Harmony configurator to continue.

While generating code, make sure that you use “USER_RECENT” merge strategy.

If the right dependencies are loaded, there should not be any additional merges while regenerating code without any configuration change.

  • Notes:

    In case the user is regenerating the code, one should make sure that, they do not overwrite the files related to sys_wifiprov, and other app files. Also, do not make any changes to the Task Delay for _SYS_OTA_Tasks and the sequence of Task creation in "SYS_Tasks" of "tasks.c" file.

Debugging

To monitor debug logs and to interact with the demo using a command-line interface, connect a USB-UART converter to the UART1 pins in the GPIO header of the Curiosity Board and open a UART terminal in the PC with settings 115200 8N1. Issue the help command to see a list of available commands.

UART Tx and Rx pins are marked in the GPIO Header (J207) silkscreen

This console also prints any error messages if something goes wrong in the FW.

WiFi MAC level logs are printed via UART2. UART2 TX and RX can be easily tapped into a USB-UART converter from the mikroBUSTM Socket (J200). (settings: 115200 8N1)