MPLAB® Harmony v3 is now configurable through MPLAB Code Configurator (MCC). Although the instructions in this tutorial are for the MHC, the flow and experience of creating a project, configuring peripherals, and generating code using MCC are similar. Refer to the below links for specific instructions to use MPLAB Harmony v3 with MCC.
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:
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
- 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
- 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.
|Tool|| About|| Purchase|
SAM E70 Xplained
I/O1 Xplained Pro
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
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
- 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
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.
| Windows|| Linux|| Mac OSX|
Integrated Development Environment
|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
|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
|Microchip||Peripheral register specific definitions|
|arm||Core Specific Register Definitions (CMSIS)|
- CORE: The following table shows the summary of contents
|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
|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
|boards||BSP templates and configuration data|
- USB: The following table shows the summary of contents
|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|
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 machines. The Sensor, EEPROM, and USB tasks (in that order) are called from SYS_Tasks() routine which is run in an infinite loop.
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.
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.
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.
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.
- 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.
- The Microchip Harmony Configurator (MHC) generates all of the required source files, header files, and libraries (if any) under your project folder.
- 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
All steps must be completed before you will be ready to build, program, and run the application.
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