Getting Started with USB on SAM MCUs Using MPLAB® Harmony v3

 Objective

MPLAB® Harmony v3 is a flexible, fully integrated embedded software development framework for 32-bit microcontrollers (MCUs) and microprocessors (MPUs).

MPLAB Harmony v3 includes the MPLAB Harmony Configurator (MHC) tool, a set of modular peripheral libraries, drivers, system services, middleware, and numerous example applications, all of which are designed to help you quickly and easily develop powerful and efficient embedded software for Microchip’s 32-bit PIC® and SAM devices.

This tutorial shows you how to use MHC to create a simple USB CDC class serial terminal menu application and will help you get started on developing USB-based applications for SAM MCUs using the MPLAB Harmony v3 software framework.

Here's a screenshot of this training module application's output:

output.png
Figure: Serial Terminal Output

The training module application makes use of the SAM E70 Xplained Evaluation Kit and the I/O1 Xplained Pro Extension Kit (sold separately).

This application reads the current room temperature from the AT30TSE758A temperature sensor chip on the I/O1 Xplained Pro every second using I²C. This is indicated by a blinking orange LED on the I/O1 Xplained Pro. Further, it also writes these temperature values into the sensor chip's own integrated EEPROM using the same I²C peripheral instance. The application also uses an ADC channel to read the output voltage of the TEMT6000 ambient light sensor on the I/O1 Xplained Pro Extension Kit and displays it as a percentage of the sensor's full-scale output when requested through the serial terminal menu. This serial terminal menu is made available through the SAM E70 Xplained Evaluation Kit's Target USB port by configuring it as a USB CDC class device. This menu allows you to fetch temperature, light sensor data, and even toggle the LED on the SAME70 Xplained Evaluation Kit.

The application you create will utilize the following Harmony v3 components:

  • I²C Driver (TWIHS) to fetch the temperature and access the EEPROM on the AT30TSE758A.
  • Timer System Service (TC) to periodically sample temperature sensor data every second.
  • CDC Function Driver of the USB Device Stack (USBHS) for the serial terminal menu accessible via PC.
  • ADC Peripheral Library (AFEC) to read the TEMT6000 ambient light sensor output voltage.
  • PIO Peripheral Library (PIO) to toggle some LEDs and multiplex pin functions.

The name of the peripheral used by a driver or library (as per the device datasheet) is mentioned in brackets for reference.

Two Ways to Use This Tutorial

  1. Create the project from scratch:
    • Use the provided source files and follow the step-by-step instructions provided below.
  2. Use the attached project as an example:
    • Build the attached project and program the SAM E70 Xplained Evaluation Kit to observe the output.

Lab Objectives

  1. Create an MPLAB® X IDE Harmony v3 project for a SAME70 microcontroller from scratch.
  2. Use MHC to configure and generate code for the Harmony TIME System Service.
  3. Use MHC to configure and generate code for the Harmony I²C Driver and USB Device Stack Middleware (CDC Function Driver).
  4. Use MHC to configure and generate Harmony Peripheral Libraries for TC, TWIHS, AFEC, and PIO.
  5. Use the Harmony Driver, System Service, Middleware, and Peripheral Library APIs to implement the application.

 Materials

Hardware Tools

Tool About Purchase
board-50px.png
SAM E70 Xplained
Evaluation Kit
io1-xpro-extension-50px.png
I/O1 Xplained Pro
Extension Kit

The SAM E70 Xplained Evaluation Kit includes an on-board Embedded Debugger (EDBG). No external tools are necessary to program or debug the ATSAME70Q21B. For programming or debugging, the EDBG connects to the host PC through the DEBUG USB Micro-B connector on the SAM E70 Evaluation Kit.

Hardware Connection Setup

hardware_e70.png
Figure: Hardware Setup

Apart from the hardware tools listed above, the following cables are required:

  • 1 USB Type-A male to Micro-B male cable for programming or debugging.
  • 1 USB Type-A male to Micro-B male cable for the USB CDC serial port.

Connection Diagram

connections.png
Figure: Connection Diagram
  • I/O1 Xplained Pro is connected to the SAM E70 Xplained Evaluation Kit using the EXT1 connector.
  • The serial terminal over the USB CDC interface is accessed via the TARGET USB Port.
  • The on-board Embedded Debugger (EDBG) is accessed via the DEBUG USB Port.

Software Tools

This project has been verified to work with the following versions of software tools:
MPLAB X IDE v5.45, MPLAB XC32 Compiler v2.50

Because we regularly update our tools, occasionally you may discover an issue while using the newer versions. If you suspect that to be the case, we recommend that you double-check and use the same versions that the project was tested with.

Tool About Installers
Installation
Instructions
Windows Linux Mac OSX
MPLAB® X
Integrated Development Environment
MPLAB® XC32
C/C++ Compiler
For this lab, download the following packages using Harmony Content Manager:
Package Name Version Used Description
mhc v3.5.1 Contains the current implementation of the MHC tool.
dev_packs v3.8.0 Describes all peripherals, memory, etc. of supported 32-bit devices.
core v3.8.1 Includes Drivers and Services with simple to use abstractions of peripherals and shared resources.
csp v3.8.2 Chip Support Package: Includes the Peripheral Libraries (PLIBs).
bsp v3.8.2 Board Support Package: Includes templates and configuration data for supported development boards.
usb v3.7.0 Includes USB Middleware and Drivers.

The contents of these packages are detailed below.

  • MHC: The following table shows the summary of contents.
File/Folder Description
doc Help documentation and licenses for libraries used
np_templates New Project templates for supported toolchains
*.jar Java implementations of MHC modules
mhc.jar Main Java executable (run: java -jar mhc.jar -h)
runmhc.bat Windows cmd batch file to run standalone MHC Graphical User Interface (GUI)
  • DEV_PACKS: The following table shows the summary of contents.
Folder Description
Microchip Peripheral register specific definitions
arm Core Specific Register Definitions (CMSIS)
  • CORE: The following table shows the summary of contents.
Folder Description
apps Example applications for core library components
config Core module configuration scripts
docs Core module library help documentation
driver Core module peripheral device drivers
osal MPLAB Harmony Operating System Abstraction Layer
system MPLAB Harmony system services
templates Application and system file templates
  • CSP: The following table shows the summary of contents.
Folder Description
apps Example applications for CSP library components
arch Initialization and starter code templates and data
docs CSP library help documentation
peripheral Peripheral library templates and configuration data
  • BSP: The following table shows the summary of contents.
Folder Description
boards BSP templates and configuration data
  • USB: The following table shows the summary of contents.
Folder Description
apps Example applications for USB library components
config USB module configuration scripts
docs USB module library help documentation
driver USB module driver source files
middleware USB middleware source files
templates Application and system file templates

Overview

This lab shows you how to create an MPLAB X Harmony v3 project from scratch and configure/generate code for the following:

  • Harmony v3 Peripheral Libraries for TC, I²C, ADC, and PIO peripherals.
  • Harmony v3 Driver for I²C.
  • Harmony v3 USB High-Speed Driver and USB Device Stack Middleware (CDC Function Driver).
  • Harmony v3 TIME System Service.

The application is divided into three tasks:

  • Sensor Task
  • EEPROM Task
  • USB Task

Each task runs its own state machines. The Sensor, EEPROM, and USB tasks (in that order) are called from SYS_Tasks() routine which is run in an infinite loop.

app_tasks.png
Figure: Application state machine

After the initialization of the I²C sensor client, the sensor task waits for the one-second periodic timer event generated by the TIME system service. On every one-second periodic timer event, the sensor task submits a temperature sensor read request through the I²C interface and also toggles the LED on the I/O1 Xplained Pro. When a temperature sensor read is completed, the sensor task notifies the EEPROM task to store the read temperature value in the EEPROM.

sensor_task.png
Figure: Sensor Task state machine

After the initialization of the I²C EEPROM client, for every notification from the sensor task, the EEPROM task writes the temperature value to the EEPROM.

eeprom_task.png
Figure: EEPROM Task state machine

After the initialization of the USB Device layer, the USB task waits for the device to be enumerated and configured by the USB Host. Once configured, it waits for a character to be sent via the USB CDC serial port. If the character sent is a valid command, the corresponding action is performed. If the character is not a valid command, it starts waiting for another character to be sent via the USB CDC serial port.

usb_task.png
Figure: USB Task state machine

Lab Source Files and Solutions

This ZIP archive contains the completed project for this lab. It also contains the source files needed to perform the lab step-by-step as per the section "Procedure" on this page.

You are free to extract the contents of the archive to any directory of your choice. See the notes below.

Note:

  1. The project location of a Harmony v3 project is independent of the location of the Harmony Framework path (i.e., you do not need to create or place a Harmony v3 project in a relative path under the Harmony v3 framework folder). The project can be created or placed in any directory of your choice.
  2. The Microchip Harmony Configurator (MHC) generates all of the required source files, header files, and libraries (if any) under your project folder.
  3. This is unlike older Harmony v2 projects that are required to be created in a location under the Harmony framework.


Extracting the ZIP archive creates the following folders:

  • getting_started_drivers_middleware contains the lab solution in the firmware folder and source files in the dev_files folder.
    • dev_files contains the application source files and other support files (if any) required to perform the lab.
    • firmware contains the completed lab solution project. You can directly build this project and program the hardware to observe the output.

Procedure

All steps must be completed before you will be ready to build, program, and run the application.

Lab Index

Step 1: Create and Configure Harmony v3 Project

Step 2: Configure TIME System Service, I²C, USB and ADC

Step 3: Configure Clocks, Pins and Application Tasks

Step 4: Generate Code
Step 5: Add Application Code to the Project
Step 6: Build, Program and Observe the Output

© 2021 Microchip Technology, Inc.
Notice: ARM and Cortex are the registered trademarks of ARM Limited in the EU and other countries.
Information contained on this site regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer's risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights.