Skip to content

Files

Latest commit

0cf3a0f · Apr 21, 2022

History

History
623 lines (409 loc) · 29.1 KB

quickstart-devkit-microchip-atsame54-xpro.md

File metadata and controls

623 lines (409 loc) · 29.1 KB
title description author ms.author ms.service ms.devlang ms.topic ms.date zone_pivot_groups ms.custom
Connect a Microchip ATSAME54-XPro to Azure IoT Central quickstart
Use Azure RTOS embedded software to connect a Microchip ATSAME54-XPro device to Azure IoT and send telemetry.
timlt
timlt
iot-develop
c
quickstart
10/18/2021
iot-develop-toolset
mode-other, contperf-fy22q3

Quickstart: Connect a Microchip ATSAME54-XPro Evaluation kit to IoT Central

Applies to: Embedded device development
Total completion time: 45 minutes

:::zone pivot="iot-toolset-cmake" Browse code :::zone-end :::zone pivot="iot-toolset-iar-ewarm, iot-toolset-mplab" Browse code :::zone-end

In this quickstart, you use Azure RTOS to connect the Microchip ATSAME54-XPro (from now on, the Microchip E54) to Azure IoT.

You'll complete the following tasks:

  • Install a set of embedded development tools for programming a Microchip E54 in C
  • Build an image and flash it onto the Microchip E54
  • Use Azure IoT Central to create cloud components, view properties, view device telemetry, and call direct commands

:::zone pivot="iot-toolset-cmake"

Prerequisites

  • A PC running Windows 10

  • Git for cloning the repository

  • Hardware

    • The Microchip ATSAME54-XPro (Microchip E54)
    • USB 2.0 A male to Micro USB male cable
    • Wired Ethernet access
    • Ethernet cable
    • Optional: Weather Click sensor. You can add this sensor to the device to monitor weather conditions. If you don't have this sensor, you can still complete this quickstart.
    • Optional: mikroBUS Xplained Pro adapter. Use this adapter to attach the Weather Click sensor to the Microchip E54. If you don't have the sensor and this adapter, you can still complete this quickstart.

Prepare the development environment

To set up your development environment, first you clone a GitHub repo that contains all the assets you need for the quickstart. Then you install a set of programming tools.

Clone the repo for the quickstart

Clone the following repo to download all sample device code, setup scripts, and offline versions of the documentation. If you previously cloned this repo in another quickstart, you don't need to do it again.

To clone the repo, run the following command:

git clone --recursive https://github.com/azure-rtos/getting-started.git

Install the tools

The cloned repo contains a setup script that installs and configures the required tools. If you installed these tools in another embedded device quickstart, you don't need to do it again.

Note

The setup script installs the following tools:

To install the tools:

  1. From File Explorer, navigate to the following path in the repo and run the setup script named get-toolchain.bat:

    getting-started\tools\get-toolchain.bat

  2. After the installation, open a new console window to recognize the configuration changes made by the setup script. Use this console to complete the remaining programming tasks in the quickstart. You can use Windows CMD, PowerShell, or Git Bash for Windows.

  3. Run the following code to confirm that CMake version 3.14 or later is installed.

    cmake --version
  4. Install Microchip Studio for AVR® and SAM devices. Microchip Studio is a device development environment that includes the tools to program and flash the Microchip E54. For this tutorial, you use Microchip Studio only to flash the Microchip E54. The installation takes several minutes, and prompts you several times to approve the installation of components.

[!INCLUDE iot-develop-embedded-create-central-app-with-device]

Prepare the device

To connect the Microchip E54 to Azure, you'll modify a configuration file for Azure IoT settings, rebuild the image, and flash the image to the device.

Add configuration

  1. Open the following file in a text editor:

    getting-started\Microchip\ATSAME54-XPRO\app\azure_config.h

  2. Set the Azure IoT device information constants to the values that you saved after you created Azure resources.

    Constant name Value
    IOT_DPS_ID_SCOPE {Your ID scope value}
    IOT_DPS_REGISTRATION_ID {Your Device ID value}
    IOT_DEVICE_SAS_KEY {Your Primary key value}
  3. Save and close the file.

Connect the device

  1. On the Microchip E54, locate the Reset button, the Ethernet port, and the Micro USB port, which is labeled Debug USB. Each component is highlighted in the following picture:

    Locate key components on the Microchip E54 evaluation kit board

  2. Connect the Micro USB cable to the Debug USB port on the Microchip E54, and then connect it to your computer.

    [!NOTE] Optionally, for more information about setting up and getting started with the Microchip E54, see SAM E54 Xplained Pro User's Guide.

  3. Use the Ethernet cable to connect the Microchip E54 to an Ethernet port.

Optional: Install a weather sensor

If you have the Weather Click sensor and the mikroBUS Xplained Pro adapter, follow the steps in this section; otherwise, skip to Build the image. You can complete this quickstart even if you don't have a sensor. The sample code for the device returns simulated data if a real sensor isn't present.

  1. If you have the Weather Click sensor and the mikroBUS Xplained Pro adapter, install them on the Microchip E54 as shown in the following photo:

    :::image type="content" source="media/quickstart-devkit-microchip-atsame54-xpro/sam-e54-sensor.png" alt-text="Install Weather Click sensor and mikroBUS Xplained Pro adapter on the Microchip ES4":::

  2. Reopen the configuration file you edited previously:

    getting-started\Microchip\ATSAME54-XPRO\app\azure_config.h

  3. Set the value of the constant __SENSOR_BME280__ to 1 as shown in the following code from the header file. Setting this value enables the device to use real sensor data from the Weather Click sensor.

    #define __SENSOR_BME280__ 1

  4. Save and close the file.

Build the image

  1. In your console or in File Explorer, run the script rebuild.bat at the following path to build the image:

    getting-started\Microchip\ATSAME54-XPRO\tools\rebuild.bat

  2. After the build completes, confirm that the binary file was created in the following path:

    getting-started\Microchip\ATSAME54-XPRO\build\app\atsame54_azure_iot.bin

Flash the image

  1. Open the Windows Start > Microchip Studio Command Prompt console and go to the folder of the Microchip E54 binary file that you built.

    getting-started\Microchip\ATSAME54-XPRO\build\app

  2. Use the atprogram utility to flash the Microchip E54 with the binary image:

    atprogram --tool edbg --interface SWD --device ATSAME54P20A program --chiperase --file atsame54_azure_iot.bin --verify

    [!NOTE] For more information about using the Atmel-ICE and atprogram tools with the Microchip E54, see Using Atmel-ICE for AVR Programming In Mass Production.

    After the flashing process completes, the console confirms that programming was successful:

    Firmware check OK
    Programming and verification completed successfully.
    

Confirm device connection details

You can use the Termite app to monitor communication and confirm that your device is set up correctly.

  1. Start Termite.

    [!TIP] If you have issues getting your device to initialize or connect after flashing, seeTroubleshooting](troubleshoot-embedded-device-quickstarts.md) for additional steps.

  2. Select Settings.

  3. In the Serial port settings dialog, check the following settings and update if needed:

    • Baud rate: 115,200
    • Port: The port that your Microchip E54 is connected to. If there are multiple port options in the dropdown, you can find the correct port to use. Open Windows Device Manager, and view Ports to identify which port to use.
    • Flow control: DTR/DSR

    :::image type="content" source="media/quickstart-devkit-microchip-atsame54-xpro/termite-settings.png" alt-text="Screenshot of serial port settings in the Termite app":::

  4. Select OK.

  5. Press the Reset button on the device. The button is labeled on the device and located near the Micro USB connector.

  6. In the Termite app, confirm the following checkpoint values to verify that the device is initialized and connected to Azure IoT.

    Starting Azure thread
    
    Initializing DHCP
        IP address: 192.168.0.21
        Mask: 255.255.255.0
        Gateway: 192.168.0.1
    SUCCESS: DHCP initialized
    
    Initializing DNS client
        DNS address: 75.75.75.75
    SUCCESS: DNS client initialized
    
    Initializing SNTP client
        SNTP server 0.pool.ntp.org
        SNTP IP address: 45.55.58.103
        SNTP time update: Jun 5, 2021 20:2:46.32 UTC 
    SUCCESS: SNTP initialized
    
    Initializing Azure IoT DPS client
        DPS endpoint: global.azure-devices-provisioning.net
        DPS ID scope: ***
        Registration ID: mydevice
    SUCCESS: Azure IoT DPS client initialized
    
    Initializing Azure IoT Hub client
        Hub hostname: ***.azure-devices.net
        Device id: mydevice
        Model id: dtmi:azurertos:devkit:gsg;1
    Connected to IoT Hub
    SUCCESS: Azure IoT Hub client initialized
    

Keep Termite open to monitor device output in the following steps.

:::zone-end :::zone pivot="iot-toolset-iar-ewarm"

Prerequisites

  • A PC running Windows 10

  • Hardware

    • The Microchip ATSAME54-XPro (Microchip E54)
    • USB 2.0 A male to Micro USB male cable
    • Wired Ethernet access
    • Ethernet cable
  • Termite. On the web page, under Downloads and license, choose the complete setup. Termite is an RS232 terminal that you'll use to monitor output for your device.

  • IAR Embedded Workbench for ARM (EW for ARM). You can download and install a 14-day free trial of IAR EW for ARM.

  • Download the Microchip ATSAME54-XPRO IAR sample from Azure RTOS samples, and unzip it to a working directory. Choose a directory with a short path to avoid compiler errors when you build.

[!INCLUDE iot-develop-embedded-create-central-app-with-device]

Prepare the device

To connect the Microchip E54 to Azure, you'll connect the Microchip E54 to your computer, modify a configuration file for Azure IoT settings, build the image, and flash the image to the device.

Connect the device

  1. On the Microchip E54, locate the Reset button, the Ethernet port, and the Micro USB port, which is labeled Debug USB. Each component is highlighted in the following picture:

    Locate key components on the Microchip E54 evaluation kit board

  2. Connect the Micro USB cable to the Debug USB port on the Microchip E54, and then connect it to your computer.

    [!NOTE] Optionally, for more information about setting up and getting started with the Microchip E54, see SAM E54 Xplained Pro User's Guide.

  3. Use the Ethernet cable to connect the Microchip E54 to an Ethernet port.

Configure Termite

You'll use the Termite app to monitor communication and confirm that your device is set up correctly. In this section, you configure Termite to monitor the serial port of your device.

  1. Start Termite.

  2. Select Settings.

  3. In the Serial port settings dialog, check the following settings and update if needed:

    • Baud rate: 115,200
    • Port: The port that your Microchip E54 is connected to. If there are multiple port options in the dropdown, you can find the correct port to use. Open Windows Device Manager, and view Ports to identify which port to use.
    • Flow control: DTR/DSR

    :::image type="content" source="media/quickstart-devkit-microchip-atsame54-xpro/termite-settings.png" alt-text="Screenshot of serial port settings in the Termite app":::

  4. Select OK.

Termite is now ready to receive output from the Microchip E54.

Configure, build, flash, and run the image

  1. Open the IAR EW for ARM app on your computer.

  2. Select File > Open workspace, navigate to the same54Xpro\iar folder off the working folder where you extracted the zip file, and open the azure_rtos.eww EWARM Workspace.

    :::image type="content" source="media/quickstart-devkit-microchip-atsame54-xpro/open-project-iar.png" alt-text="Open the IAR workspace":::

  3. Right-click the sample_azure_iot_embedded_sdk_pnp project in the left Workspace pane and select Set as active.

  4. Expand the sample, then expand the Sample folder and open the sample_config.h file.

  5. Near the top of the file uncomment the #define ENABLE_DPS_SAMPLE directive.

    #define ENABLE_DPS_SAMPLE
  6. Set the Azure IoT device information constants to the values that you saved after you created Azure resources. The ENDPOINT constant is set to the global endpoint for Azure Device Provisioning Service (DPS).

    Constant name Value
    ENDPOINT "global.azure-devices-provisioning.net"
    ID_SCOPE {Your ID scope value}
    REGISTRATION_ID {Your Device ID value}
    DEVICE_SYMMETRIC_KEY {Your Primary key value}

    [!NOTE] TheENDPOINT, ID_SCOPE, and REGISTRATION_ID values are set in a #ifndef ENABLE_DPS_SAMPLE statement. Make sure you set the values in the #else statement, which will be used when the ENABLE_DPS_SAMPLE value is defined.

  7. Save the file.

  8. Select Project > Batch Build. Then select build_all and Make to build all projects. You'll see build output in the Build pane. Confirm the successful compilation and linking of all sample projects.

  9. Select the green Download and Debug button in the toolbar to download the program.

  10. After the image has finished downloading, Select Go to run the sample.

Confirm device connection details

In the Termite app, confirm the following checkpoint values to verify that the device is initialized and connected to Azure IoT.

DHCP In Progress...
IP address: 192.168.0.22
Mask: 255.255.255.0
Gateway: 192.168.0.1
DNS Server address: 75.75.75.75
SNTP Time Sync...
SNTP Time Sync successfully.
[INFO] Azure IoT Security Module has been enabled, status=0
Start Provisioning Client...
[INFO] IoTProvisioning client connect pending
Registered Device Successfully.
IoTHub Host Name: iotc-********-****-****-****-************.azure-devices.net; Device ID: mydevice.
Connected to IoTHub.
Telemetry message send: {"temperature":22}.
Receive twin properties: {"desired":{"$version":1},"reported":{"maxTempSinceLastReboot":22,"$version":8}}
Failed to parse value
Telemetry message send: {"temperature":22}.
Telemetry message send: {"temperature":22}.

Keep Termite open to monitor device output in the following steps.

:::zone-end :::zone pivot="iot-toolset-mplab"

Prerequisites

  • A PC running Windows 10

  • Hardware

    • The Microchip ATSAME54-XPro (Microchip E54)
    • USB 2.0 A male to Micro USB male cable
    • Wired Ethernet access
    • Ethernet cable
  • Termite. On the web page, under Downloads and license, choose the complete setup. Termite is an RS232 terminal that you'll use to monitor output for your device.

  • MPLAB X IDE 5.35.

  • MPLAB XC32/32++ Compiler 2.4.0 or later.

  • Download the Microchip ATSAME54-XPRO MPLab sample from Azure RTOS samples, and unzip it to a working directory. Choose a directory with a short path to avoid compiler errors when you build.

[!INCLUDE iot-develop-embedded-create-central-app-with-device]

Prepare the device

To connect the Microchip E54 to Azure, you'll connect the Microchip E54 to your computer, modify a configuration file for Azure IoT settings, build the image, and flash the image to the device.

Connect the device

  1. On the Microchip E54, locate the Reset button, the Ethernet port, and the Micro USB port, which is labeled Debug USB. Each component is highlighted in the following picture:

    Locate key components on the Microchip E54 evaluation kit board

  2. Connect the Micro USB cable to the Debug USB port on the Microchip E54, and then connect it to your computer.

    [!NOTE] Optionally, for more information about setting up and getting started with the Microchip E54, see SAM E54 Xplained Pro User's Guide.

  3. Use the Ethernet cable to connect the Microchip E54 to an Ethernet port.

Configure Termite

You'll use the Termite app to monitor communication and confirm that your device is set up correctly. In this section, you configure Termite to monitor the serial port of your device.

  1. Start Termite.

  2. Select Settings.

  3. In the Serial port settings dialog, check the following settings and update if needed:

    • Baud rate: 115,200
    • Port: The port that your Microchip E54 is connected to. If there are multiple port options in the dropdown, you can find the correct port to use. Open Windows Device Manager, and view Ports to identify which port to use.
    • Flow control: DTR/DSR

    :::image type="content" source="media/quickstart-devkit-microchip-atsame54-xpro/termite-settings.png" alt-text="Screenshot of serial port settings in the Termite app":::

  4. Select OK.

Termite is now ready to receive output from the Microchip E54.

Configure, build, flash, and run the image

  1. Open MPLAB X IDE on your computer.

  2. Select File > Open project. In the open project dialog, navigate to the same54Xpro\mplab folder off the working folder where you extracted the zip file. Select all of the projects (don't select common_hardware_code or docs folders), and then select Open Project.

    :::image type="content" source="media/quickstart-devkit-microchip-atsame54-xpro/open-project-mplab.png" alt-text="Open projects in the MPLab IDE":::

  3. Right-click the sample_azure_iot_embedded_sdk_pnp project in the left Projects pane and select Set as Main Project.

  4. Expand the sample_azure_iot_embedded_sdk_pnp project, then expand the Header Files folder and open the sample_config.h file.

  5. Near the top of the file uncomment the #define ENABLE_DPS_SAMPLE directive.

    #define ENABLE_DPS_SAMPLE
  6. Set the Azure IoT device information constants to the values that you saved after you created Azure resources. The ENDPOINT constant is set to the global endpoint for Azure Device Provisioning Service (DPS).

    Constant name Value
    ENDPOINT "global.azure-devices-provisioning.net"
    ID_SCOPE {Your ID scope value}
    REGISTRATION_ID {Your Device ID value}
    DEVICE_SYMMETRIC_KEY {Your Primary key value}

    [!NOTE] TheENDPOINT, ID_SCOPE, and REGISTRATION_ID values are set in a #ifndef ENABLE_DPS_SAMPLE statement. Make sure you set the values in the #else statement, which will be used when the ENABLE_DPS_SAMPLE value is defined.

  7. Save the file.

  8. Before you can build the sample, you must build the sample_azure_iot_embedded_pnp project's dependent libraries: threadx, netxduo, and same54_lib. To build each library, right-click its project in the Projects pane and select Build. Wait for each build to complete before moving to the next library.

  9. After all prerequisite libraries have been successfully built, right-click the sample_azure_iot_embedded_pnp project and select Build.

  10. Select Debug > Debug Main Project from the top menu to download and start the program.

  11. If a Tool not Found dialog appears, select connect SAM E54 board, and then select OK.

  12. It may take a few minutes for the program to download and start running. Once the program has successfully downloaded and is running, you'll see the following status in the MPLAB X IDE Output pane.

    Programming complete
    
    Running
    

Confirm device connection details

In the Termite app, confirm the following checkpoint values to verify that the device is initialized and connected to Azure IoT.

DHCP In Progress...
IP address: 192.168.0.22
Mask: 255.255.255.0
Gateway: 192.168.0.1
DNS Server address: 75.75.75.75
SNTP Time Sync...
SNTP Time Sync successfully.
[INFO] Azure IoT Security Module has been enabled, status=0
Start Provisioning Client...
[INFO] IoTProvisioning client connect pending
Registered Device Successfully.
IoTHub Host Name: iotc-********-****-****-****-************.azure-devices.net; Device ID: mydevice.
Connected to IoTHub.
Telemetry message send: {"temperature":22}.
Receive twin properties: {"desired":{"$version":1},"reported":{"maxTempSinceLastReboot":22,"$version":8}}
Failed to parse value
Telemetry message send: {"temperature":22}.
Telemetry message send: {"temperature":22}.

Keep Termite open to monitor device output in the following steps.

:::zone-end

Verify the device status

To view the device status in IoT Central portal:

:::zone pivot="iot-toolset-cmake"

  1. From the application dashboard, select Devices on the side navigation menu.

  2. Confirm that the Device status is updated to Provisioned.

  3. Confirm that the Device template is updated to Getting Started Guide.

    :::image type="content" source="media/quickstart-devkit-microchip-atsame54-xpro/iot-central-device-view-status.png" alt-text="Screenshot of device status in IoT Central"::: :::zone-end :::zone pivot="iot-toolset-iar-ewarm, iot-toolset-mplab"

  4. From the application dashboard, select Devices on the side navigation menu.

  5. Confirm that the Device status is updated to Provisioned.

  6. Confirm that the Device template is updated to Thermostat.

    :::image type="content" source="media/quickstart-devkit-microchip-atsame54-xpro/iot-central-device-view-status-iar.png" alt-text="Screenshot of device status in IoT Central"::: :::zone-end

View telemetry

With IoT Central, you can view the flow of telemetry from your device to the cloud.

To view telemetry in IoT Central portal:

  1. From the application dashboard, select Devices on the side navigation menu.

  2. Select the device from the device list.

  3. View the telemetry as the device sends messages to the cloud in the Overview tab.

    :::zone pivot="iot-toolset-cmake" :::image type="content" source="media/quickstart-devkit-microchip-atsame54-xpro/iot-central-device-telemetry.png" alt-text="Screenshot of device telemetry in IoT Central"::: :::zone-end :::zone pivot="iot-toolset-iar-ewarm, iot-toolset-mplab" :::image type="content" source="media/quickstart-devkit-microchip-atsame54-xpro/iot-central-device-telemetry-iar.png" alt-text="Screenshot of device telemetry in IoT Central"::: :::zone-end

    [!NOTE] You can also monitor telemetry from the device by using the Termite app.

Call a direct method on the device

You can also use IoT Central to call a direct method that you've implemented on your device. Direct methods have a name, and can optionally have a JSON payload, configurable connection, and method timeout. In this section, you call a method that enables you to turn an LED on or off.

To call a method in IoT Central portal: :::zone pivot="iot-toolset-cmake"

  1. Select the Command tab from the device page.

  2. In the State dropdown, select True, and then select Run. The LED light should turn on.

    :::image type="content" source="media/quickstart-devkit-microchip-atsame54-xpro/iot-central-invoke-method.png" alt-text="Screenshot of calling a direct method on a device in IoT Central":::

  3. In the State dropdown, select False, and then select Run. The LED light should turn off. :::zone-end :::zone pivot="iot-toolset-iar-ewarm, iot-toolset-mplab"

  4. Select the Command tab from the device page.

  5. In the Since field, use the date picker and time selectors to set a time, then select Run.

    :::image type="content" source="media/quickstart-devkit-microchip-atsame54-xpro/iot-central-invoke-method-iar.png" alt-text="Screenshot of calling a direct method on a device in IoT Central":::

  6. You can see the command invocation in Termite:

    Receive method call: getMaxMinReport, with payload:"2021-10-14T17:45:00.000Z"
    

    [!NOTE] You can also view the command invocation and response on the Raw data tab on the device page in IoT Central. :::zone-end

View device information

You can view the device information from IoT Central.

Select About tab from the device page.

:::zone pivot="iot-toolset-cmake" :::image type="content" source="media/quickstart-devkit-microchip-atsame54-xpro/iot-central-device-about.png" alt-text="Screenshot of device information in IoT Central"::: :::zone-end :::zone pivot="iot-toolset-iar-ewarm, iot-toolset-mplab" :::image type="content" source="media/quickstart-devkit-microchip-atsame54-xpro/iot-central-device-about-iar.png" alt-text="Screenshot of device information in IoT Central"::: :::zone-end

Tip

To customize these views, edit the device template.

Troubleshoot and debug

If you experience issues building the device code, flashing the device, or connecting, see Troubleshooting.

:::zone pivot="iot-toolset-cmake" For debugging the application, see Debugging with Visual Studio Code. :::zone-end :::zone pivot="iot-toolset-iar-ewarm" For help with debugging the application, see the selections under Help in IAR EW for ARM.
:::zone-end :::zone pivot="iot-toolset-mplab" For help with debugging the application, see the selections under Help in MPLAB X IDE.
:::zone-end

Clean up resources

If you no longer need the Azure resources created in this quickstart, you can delete them from the IoT Central portal.

To remove the entire Azure IoT Central sample application and all its devices and resources:

  1. Select Administration > Your application.
  2. Select Delete.

Next steps

In this quickstart, you built a custom image that contains Azure RTOS sample code, and then flashed the image to the Microchip E54 device. You also used the IoT Central portal to create Azure resources, connect the Microchip E54 securely to Azure, view telemetry, and send messages.

As a next step, explore the following articles to learn more about using the IoT device SDKs to connect devices to Azure IoT.

[!div class="nextstepaction"] Connect a simulated device to IoT Central [!div class="nextstepaction"] Connect a simulated device to IoT Hub

Important

Azure RTOS provides OEMs with components to secure communication and to create code and data isolation using underlying MCU/MPU hardware protection mechanisms. However, each OEM is ultimately responsible for ensuring that their device meets evolving security requirements.