3.3.5.5 Amazon Alexa Connect Kit (ACK) OTA Bootloader Application on SAM D21 Curiosity Nano
Description
The Application demonstrates the usage OTA upgrade feature on SAMD21 Curiosity Nano evaluation kit using Amazon Alexa connect kit(ACK) SDK. The communication between SAM D21 Curiosity Nano and ACK Module is through UART interface.
This following bullet points provides links to the detailed topics:
- Modules/Technology Used
- Hardware Used
- Software/Tools Used
- Hardware Setup
- Setting up the build platform
- Project file structure
- Steps to program the hex file
- OTA Architecture
- Setting up environment for OTA update
- Building and upgrading the latest application firmware
- Comments
Modules/Technology Used
- Peripheral Modules
- SERCOM
- Systick
- Port
- NVMCTRL
Hardware Used
Software/Tools Used
This project has been verified to work with the following versions of software tools:
Refer Project Manifest present in harmony-manifest-success.yml under the project folder firmware/src/config/default.
- Refer the Release Notes to know the MPLAB X IDE and MCC Plugin version.
- Python 3.8.
Because Microchip regularly updates tools, occasionally issue(s) could be discovered while using the newer versions of the tools. If the project does not seem to work and version incompatibility is suspected. It is recommended to double-check and use the same versions that the project was tested with. To download original version of MPLAB Harmony v3 packages, refer to document How to Use the MPLAB Harmony v3 Project Manifest Feature (DS90003305).
Hardware Setup
- Connect Pin "PB02(ACK HOST INTERRUPT Pin)" of SAM D21 Curiosity Nano Evaluation Kit to "INT"(INST) pin of ACK Module.
- Connect Pin "PB03(ACK MODULE RESET Pin)" of SAM D21 Curiosity Nano Evaluation Kit to "RESET"(RES) pin of ACK Module.
- Connect Pin "PA20(Host MCU TX)" of SAM D21 Curiosity Nano Evaluation Kit to "ACK RX" pin of ACK Module.
- Connect Pin "PA21(Host MCU RX)" of SAM D21 Curiosity Nano Evaluation Kit to "ACK TX" pin of ACK Module.
- Connect Pin "VTG(Voltage Target)" of SAM D21 Curiosity Nano Evaluation Kit to "IOREF" pin of ACK Module.
- Connect common ground between SAM D21 Curiosity Nano Evaluation Kit and ACK Module.
- Power the SAM D21 Curiosity Nano Evaluation Kit Evaluation Kit from a Host PC through a Type-A male to Micro-B USB cable connected to Micro-B port (J105).
- Power the ACK Module from a
Host PC through a Type-A male to Micro-B USB cable connected to Micro-B port
(DEBUG).
Setting up the Build Platform
- Download and extract ACK Device SDK 4.2 from Amazon developer website.
- Copy and paste extracted SAM D21 ACK
port folder "samd21_amazon_ack" into ACK device SDK's user platform
folder.
<Your ACK SDK Downloaded folder>/ACK_Device_SDK_4.2.202201251359/user/platform
- Make sure the user creates amazon.com account for downloading the SDK. The user would use the Amazon credentials to register the development device (amazon.com account provides an option to register the development device).
- ACK Module with Espressif chipset is used in these demo's. Make sure the user downloads proper ACK SDK from the Amazon website.
- Create Product and add device capabilities to the product once product is created.
- Download the product configuration file from created product and provision the Ack module using CLI command.
Project File Structure
- ACK SDK file/directory structure,
refer "Readme.txt" in:
<Your ACK SDK Downloaded folder>\ACK_Device_SDK_4.2.202201251359\
- SAM D21 ACK port file/directory is as follows:
- user/platform/samd21_amazon_ack/
- applications: Contains all the ACK host sample applications built on MPLABX Tools and xc32 compiler
- bootloader: Contains bootloader for over-the-air(OTA) firmware upgrade feature
- hmcu_port: Contains shared host specific platform and OTA files
- ota: Contains OTA source, config and header files
- ack_samd21_cutom_loader.c: Contains bootloader specific code
- ack_samd21_platform.c: Contains SAMD21 platform specific code
- user/platform/samd21_amazon_ack/
Programming Hex File
The pre-built hex file can be programmed by following the below steps.
- Open MPLAB X IDE
- Close all existing projects in IDE, if any project is opened.
- Go to File -> Import -> Hex/ELF File.
- In the Import Image File window,
- Create Prebuilt Project,
- Click the Browse button to select the prebuilt hex file.
- Select Device as ATSAMD21G17D.
- Ensure the proper tool is selected under Hardware Tool and click on Next button.
- Select Project Name and Folder,
- Select appropriate project name and folder and click on Finish button
- Create Prebuilt Project,
- In MPLAB X IDE, click on Make and Program Device button to program the device.
- Follow the steps in Running the Demo section below.
OTA Architecture
- The SAM D21 Curiosity Nano Evaluation Kit has SAMD21G17D microcontroller mounted on it.
- The SAMD21G17D has 128 KB of Flash
memory. For the implementation of OTA, the Flash memory is divided into 4
sections/regions namely Bootloader, Status, Primary and Staging partition:
- Bootloader: This section starts from the top of the Flash and has a size of 3KB. It is used to store the bootloader application. The bootloader checks whether a new version of the application firmware is present or not in the staging region. if present, the bootloader upgrades the application firmware from the staging region to primary memory region and runs the latest application firmware from the primary memory region; if not present, the bootloader runs the existing application firmware in the primary memory region.
- Status: This section starts from end of the bootloader region and has a size of 1KB. It stores known pattern to indicate that a new version of application firmware is present in staging region.
- Primary: It starts from end of the status region and has a size of 62KB. The primary region holds the application firmware.
- Staging: It starts from end
of the primary partition and has a size of 62KB. The staging region holds a new
version of the application firmware which needs to be upgraded.
Setting up Environment for OTA Update
- Open the project (samd21_amazon_ack\bootloader\firmware\bootloader_sam_d21_cnano.X) in MPLAB X IDE
- Build the code by clicking on the Clean and Build project button in MPLAB X IDE tool bar, but do not program.
- Open the project (samd21_amazon_ack/applications/HelloWorld/firmware/HelloWorld.X) in MPLAB X IDE.
- Open the MPLAB Code Configurator (MCC) from Tools > MPLAB Harmony 3 Configurator for HelloWorld project.
- After successful opening of MCC, in
Project Graph select System and disable Generate Fuse Settings as
shown below and generate the code.
- Change the memory configuration in project properties (Right click on HelloWorld_sam_d21_cnano project > select properties > select xc32-ld > Symbols and Macros).
- Change the Preprocessor macro
definitions as below to place the code in primary
region:
ROM_ORIGIN=0x1000; ROM_LENGTH=0xF800
- Define ACK_HOST_FIRMWARE_UPDATE in HelloWorld application file ack_user_config.h.
- Increase Memory pool size macro ACK_MEMORY_POOL_SIZE value to 684 in ack_user_configh.h.
- Build the code by clicking on the Clean and Build project button in MPLAB X IDE tool bar, but do not program.
- Navigate to ota > utility
folder inside Your ACK SDK Downloaded folder and run hexmerge.py script to
merge bootloader and HelloWorld project's hex
file:
python hexmerge.py -o bootloader_helloworld_combined.hex -f your_sdk_folder/user/platform/samd21_amazon_ack/bootloader/firmware/bootloader_sam_d21_cnano.X/dist/default/production/bootloader_sam_d21_cnano.X.production.hex your_sdk_folder/user/platform/samd21_amazon_ack/applications/HelloWorld/firmware/HelloWorld.X/dist/default/production/HelloWorld.X.production.hex
- Program bootloader_helloworld_combined.hex to SAM D21 Curiosity Nano Evaluation Kit by following steps in Steps to program the hex file section.
- Output file bootloader_helloworld_combined.hex will be present in utility folder if specific path is not specified while running script.
- The fuse settings are not programmable through firmware and enabling the fuse settings increases the size of the binary when generated through the Hex file, So disabling it.
Building and Upgrading the Latest Application Firmware
- Open the project (samd21_amazon_ack/applications/HelloWorld/firmware/HelloWorld.X) in MPLAB X IDE.
- Change the firmware version from 1 to 2 in ACKUser_GetFirmwareVersion function in file ack_user_device.c.
- Build the code by clicking on the Clean and Build project button in MPLAB X IDE tool bar, but do not program.
- Navigate to ota > utility
folder inside Your ACK SDK Downloaded folder and run hex2ota.py script to
create a file suitable for uploading as latest application image from a hex file that
was created by building the HelloWorld application.
python hex2ota.py --device-type ACKTESTDEVICE <Your ACK SDK Downloaded folder>/user/platform/samd21_amazon_ack/applications/HelloWorld/firmware/HelloWorld.X/dist/default/production/HelloWorld.X.production.hex SecondOtaFirmware.ota
- --device-type: USER Device Type should be entered, for example, here it is used as "ACKTESTDEVICE".
- Upgrade the firmware using amazon portal.
- Once successfully completed, click on Switch SW0 on SAMD21 Curiosity Nano to reset the device.
Comments
- If the user wishes to remove the firmware update feature from the application undefined ACK_HOST_FIRMWARE_UPDATE Macro in ack_user_config.h and change Preprocessor macro definitions settings to default.
- Reference Training Module: Getting Started with Harmony v3 Peripheral Libraries on SAM D21 MCUs.
- This application demo builds and
works out of box by following the instructions above in Running the Demo
section. If the user needs to enhance/customize this application demo, should use the
MPLAB Harmony v3 Software framework. Refer links below to setup and build the
applications using MPLAB Harmony.
- How to Setup MPLAB Harmony v3 Software Development Framework (DS90003232).
- How to Build an Application by Adding a New PLIB, Driver, or Middleware to an Existing MPLAB Harmony v3 Project (DS90003253).
- MPLAB Harmony v3 is configurable through MPLAB Code Configurator (MCC). Refer to the below links for specific instructions to use MPLAB Harmony v3 with MCC.
-
Note: When creating a new project, set the xc32-gcc compiler (project properties->xc32-gcc->Option Categories->Optimization) optimization-level to -O2 in the project properties. This improves memory optimization and allows for adding extended code.