Getting Started with USB on SAM MCUs Using MPLAB® Harmony v3
Contents
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.
The accompanying image is a screenshot of this training module application's output:
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, and 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
Two Ways to Use This Tutorial
Create the project from scratch:
- Use the provided source files and follow the step-by-step instructions provided below
- 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
Create an MPLAB X Integrated Development Environment (IDE) Harmony v3 project for a SAME70 microcontroller from scratch.
- Use MHC to configure and generate code for the Harmony TIME System Service.
- Use MHC to configure and generate code for the Harmony I²C Driver and USB Device Stack Middleware (CDC Function Driver).
- Use MHC to configure and generate Harmony Peripheral Libraries for TC, TWIHS, AFEC, and PIO.
- Use the Harmony Driver, System Service, Middleware, and Peripheral Library APIs to implement the application.
Materials
Hardware Tools
Hardware Connection Setup
Connection Diagram
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
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, Inter-Integrated Circuit (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
- Electrically Erasable Programmable Read-Only Memory (EEPROM) Task
- USB Task
Each task runs its own state machine. The Sensor, EEPROM, and USB tasks (in that order) are called from SYS_Tasks() routine which is run in an infinite loop.
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.
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.
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.
Figure: USB task state machine
Lab Source Files and Solutions
This ZIP archive contains the completed project for this lab.
ZIP
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 1.1 - Install the MPLAB Harmony Configurator (MHC) Plug-in in MPLAB X IDE
- Step 1.2 - Create MPLAB Harmony v3 Project using MPLAB X IDE
- Step 1.3 - Open MPLAB Harmony Configurator and Configure Project Settings
Step 2: Configure TIME System Service, I²C, USB, and ADC
- Step 2.1 - Configure TIME System Service
- Step 2.2 - Configure I²C Driver
- Step 2.3 - Configure USB Device Stack Middleware
- Step 2.4 - Configure ADC Peripheral Library
Step 3: Configure Clocks, Pins, and Application Tasks
- Step 3.1 - Configure Clocks
- Step 3.2 - Configure Pins
- Step 3.3 - Add and Configure Application Tasks
Step 4: Generate Code
Step 5: Add Application Code to the Project
Step 6: Build, Program and Observe the Output