how to build an application by adding a new plib, driver, or middleware … · 2020. 4. 3. · or...

TB3253 How to Build an Application by Adding a New PLIB, Driver,or Middleware to an Existing MPLAB Harmony v3 Project

IntroductionThis document describes how to add new peripheral libraries (PLIBs), driver, or middleware to a generated MPLAB®

Harmony v3 project.

An existing MPLAB Harmony v3 project can be found from one of the following sources:

1. Created from scratch.2. From the apps folder from one of the GitHub MPLAB Harmony v3 repositories.3. An example of application demonstration code was downloaded from one of the 32-bit MCU development kits

or a product page. For example, from the Documents and Software tab in Curiosity PIC32MZ EF 2.0Development Board product page.

4. An example project received from Microchip as a reference.

This document is a guide for launching an existing application in MPLAB X IDE and extending it. New PLIBs, drivers,system services, or middleware can be added as required by the end user application.

© 2020 Microchip Technology Inc. Technical Brief DS90003253A-page 1

https://github.com/Microchip-MPLAB-Harmonyhttps://www.microchip.com/DevelopmentTools/ProductDetails/PartNO/DM320209https://www.microchip.com/DevelopmentTools/ProductDetails/PartNO/DM320209

1. Description

Downloading and Installing the MPLAB Harmony v3 Software Development FrameworkTo download and use the MPLAB Harmony v3 software development framework, refer to the document How to setupMPLAB Harmony v3 Software Development Framework.

Note: As a recommendation, the user must download or keep the latest MPLAB Harmony v3 repositories using thelink given above.

Opening an Existing MPLAB Harmony v3 ProjectTo open an existing MPLAB Harmony v3 example project in MPLAB X IDE, follow these steps:

1. Launch MPLAB X IDE, and navigate to File > Open project.2. From the existing project path, open the firmware folder.3. Select the project .X file, and then click the Open Project button.

Figure 1-1. Open Project Window

4. After the project is opened, go to Tools > Embedded, and then click on the MPLAB Harmony 3 Configurator.Figure 1-2. MPLAB Harmony v3 Configurator main window

5. The Select Harmony Path dialogue box will be displayed.

TB3253Description


http://ww1.microchip.com/downloads/en/DeviceDoc/How_to%20_Setup_MPLAB_%20Harmonyv3_%20Software_%20Development_Framework_DS90003232A.pdfhttp://ww1.microchip.com/downloads/en/DeviceDoc/How_to%20_Setup_MPLAB_%20Harmonyv3_%20Software_%20Development_Framework_DS90003232A.pdf

Figure 1-3. Select Harmony Path

6. Browse and select the folder path where the files were downloaded or cloned from the MPLAB Harmony v3repositories.

7. If the Select Harmony Path window does not appear, see the MPLAB Harmony Launcher window, and verifythe MPLAB Harmony v3 Project path. If the path is incorrect or blank, click on the Reconfigure Paths buttonand provide the MPLAB Harmony v3 Project path, and then select the folder path for the location of thedownloaded or cloned MPLAB Harmony v3 repositories.Figure 1-4. MPLAB Harmony v3 Launcher

8. After the MPLAB Harmony v3 Project path is displayed, click on the Launch button to launch the MPLABHarmony Configurator (MHC).

9. The Configuration Database Setup dialogue will be displayed, where users can change the Device FamilyPack (DFP) path, if required.Note: In this demonstration, the default settings are used.

Figure 1-5. Configuration Database Setup

10. Click Launch. The Open Default Saved State dialogue is displayed.

TB3253Description


11. Click on the Open button to open the existing (saved) project configuration .xml file.Figure 1-6. Open Default Saved State

12. The MHC will be opened in a Standalone mode.Figure 1-7. MHC in Standalone Mode

Available Components

Active Components Project Graph

Console

Tree View Configuration

Generate Code

Note: For this demonstration, Standalone mode is used for the MHC Window Manager by changing the settings inthe MPLAB X IDE by selecting Tools > Options > Plugins > MPLAB Harmony Configurator3 > Window Manager. Ifthe Native Netbeans mode of the MHC is required, users can set it to the default mode by configuring it.

1.1 Reconfiguring Clocks, Pins, and Other ComponentsThe existing MPLAB Harmony project might need the reconfiguration of some of the fundamental systemcomponents, such as the clocks, pins, and interrupts. To configure these system components, in the MHC go to Toolsand select one of the available listed configuration tools.

The following figure shows how to reconfigure the Clock by using the Clock Configuration tool.

TB3253Description


Figure 1-8. Clock Configuration

1.2 Adding Peripheral LibrariesThe existing MPLAB Harmony project might need the addition of some of the Peripheral Libraries (PLIBs), such asthe USART/UART, I2C, ADC, DAC, SPI, and Timer. To add and configure these PLIBs, in the MHC go to AvailableComponents > Peripherals and select one of the available listed PLIBs.

The following figure shows how to add and configure the UART2.

Figure 1-9. Add and Configure the UART2

1.3 Adding Drivers and System ServicesThe existing MPLAB Harmony project might need the addition of some Drivers and System Service Libraries (Driverssuch as, USART, I2C, SPI, I2C EEPROM, SPI EEPROM, USB Full Speed Driver, and System Services such as,Console, and File System). To add and configure these Drivers or System Services, in the MHC go to AvailableComponents > Harmony > Drivers or System Services and select one of the available listed Drivers or SystemServices.

The following figure shows how to add and configure the USART Driver.

TB3253Description


Figure 1-10. Add and Configure the USART

The following figure shows how to add and configure the Console System Service.

Figure 1-11. Add and Configure the Console System Service

1.4 Adding MiddlewareThe existing MPLAB Harmony project might need the addition of some middleware libraries, such as USB, WiFi, andAudio. To add and configure these middleware libraries, in the MHC go to Available Components > Libraries andselect one of the available listed middleware Libraries.

TB3253Description


For example, to add USB device stack to the HID, configure the USB HID Function Driver to act as a Mouse, asshown in the following figure.

Figure 1-12. Configuring the USB HID Function Driver

1.5 Regenerate and Build the Reconfigured ProjectTo regenerate and build the reconfigured project follow these steps:

1. In the MHC window, click on the Generate Code button to generate the code.Figure 1-13. Generate Code

Note: Save the modified MHC configuration in the default location if the MHC is not prompted when the codeis generated.

2. Once the code generation is completed, go to MPLAB X IDE to build the generated code.3. Click the Clean and Build Project button to build the project.

Figure 1-14. Clean and Build Project

4. Click the Output tab to check the build status as shown in the figure below.

TB3253Description


Figure 1-15. Output Window

TB3253Description


2. References• For additional information on MPLAB Harmony v3, go to the Microchip web site:

https://www.microchip.com/mplab/mplab-harmony and https://microchipdeveloper.com/harmony3:start• Detailed documentation on various MPLAB Harmony v3 components can be found in the doc folder of the

corresponding repository.• How to Setup MPLAB Harmony v3 Software Development Framework:

https://www.microchip.com/mymicrochip/filehandler.aspx?ddocname=en1000821• Curiosity PIC32MZ EF 2.0 Development Board details can be found here:

https://www.microchip.com/DevelopmentTools/ProductDetails/PartNO/DM320209

TB3253References


https://www.microchip.com/mplab/mplab-harmonyhttps://microchipdeveloper.com/harmony3:starthttps://www.microchip.com/mymicrochip/filehandler.aspx?ddocname=en1000821https://www.microchip.com/DevelopmentTools/ProductDetails/PartNO/DM320209

The Microchip WebsiteMicrochip provides online support via our website at http://www.microchip.com/. This website is used to make filesand information easily available to customers. Some of the content available includes:

• Product Support – Data sheets and errata, application notes and sample programs, design resources, user’sguides and hardware support documents, latest software releases and archived software

• General Technical Support – Frequently Asked Questions (FAQs), technical support requests, onlinediscussion groups, Microchip design partner program member listing

• Business of Microchip – Product selector and ordering guides, latest Microchip press releases, listing ofseminars and events, listings of Microchip sales offices, distributors and factory representatives

Product Change Notification ServiceMicrochip’s product change notification service helps keep customers current on Microchip products. Subscribers willreceive email notification whenever there are changes, updates, revisions or errata related to a specified productfamily or development tool of interest.

To register, go to http://www.microchip.com/pcn and follow the registration instructions.

Customer SupportUsers of Microchip products can receive assistance through several channels:

• Distributor or Representative• Local Sales Office• Embedded Solutions Engineer (ESE)• Technical Support

Customers should contact their distributor, representative or ESE for support. Local sales offices are also available tohelp customers. A listing of sales offices and locations is included in this document.

Technical support is available through the website at: http://www.microchip.com/support

Microchip Devices Code Protection FeatureNote the following details of the code protection feature on Microchip devices:

• Microchip products meet the specification contained in their particular Microchip Data Sheet.• Microchip believes that its family of products is one of the most secure families of its kind on the market today,

when used in the intended manner and under normal conditions.• There are dishonest and possibly illegal methods used to breach the code protection feature. All of these

methods, to our knowledge, require using the Microchip products in a manner outside the operatingspecifications contained in Microchip’s Data Sheets. Most likely, the person doing so is engaged in theft ofintellectual property.

• Microchip is willing to work with the customer who is concerned about the integrity of their code.• Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code

protection does not mean that we are guaranteeing the product as “unbreakable.”

Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protectionfeatures of our products. Attempts to break Microchip’s code protection feature may be a violation of the DigitalMillennium Copyright Act. If such acts allow unauthorized access to your software or other copyrighted work, youmay have a right to sue for relief under that Act.

Legal NoticeInformation contained in this publication regarding device applications and the like is provided only for yourconvenience and may be superseded by updates. It is your responsibility to ensure that your application meets with

TB3253


http://www.microchip.com/http://www.microchip.com/pcnhttp://www.microchip.com/support

your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHEREXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION,INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY ORFITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchipdevices 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 suchuse. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights unlessotherwise stated.

TrademarksThe Microchip name and logo, the Microchip logo, Adaptec, AnyRate, AVR, AVR logo, AVR Freaks, BesTime,BitCloud, chipKIT, chipKIT logo, CryptoMemory, CryptoRF, dsPIC, FlashFlex, flexPWR, HELDO, IGLOO, JukeBlox,KeeLoq, Kleer, LANCheck, LinkMD, maXStylus, maXTouch, MediaLB, megaAVR, Microsemi, Microsemi logo, MOST,MOST logo, MPLAB, OptoLyzer, PackeTime, PIC, picoPower, PICSTART, PIC32 logo, PolarFire, Prochip Designer,QTouch, SAM-BA, SenGenuity, SpyNIC, SST, SST Logo, SuperFlash, Symmetricom, SyncServer, Tachyon,TempTrackr, TimeSource, tinyAVR, UNI/O, Vectron, and XMEGA are registered trademarks of Microchip TechnologyIncorporated in the U.S.A. and other countries.

APT, ClockWorks, The Embedded Control Solutions Company, EtherSynch, FlashTec, Hyper Speed Control,HyperLight Load, IntelliMOS, Libero, motorBench, mTouch, Powermite 3, Precision Edge, ProASIC, ProASIC Plus,ProASIC Plus logo, Quiet-Wire, SmartFusion, SyncWorld, Temux, TimeCesium, TimeHub, TimePictra, TimeProvider,Vite, WinPath, and ZL are registered trademarks of Microchip Technology Incorporated in the U.S.A.

Adjacent Key Suppression, AKS, Analog-for-the-Digital Age, Any Capacitor, AnyIn, AnyOut, BlueSky, BodyCom,CodeGuard, CryptoAuthentication, CryptoAutomotive, CryptoCompanion, CryptoController, dsPICDEM,dsPICDEM.net, Dynamic Average Matching, DAM, ECAN, EtherGREEN, In-Circuit Serial Programming, ICSP,INICnet, Inter-Chip Connectivity, JitterBlocker, KleerNet, KleerNet logo, memBrain, Mindi, MiWi, MPASM, MPF,MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, Omniscient Code Generation, PICDEM,PICDEM.net, PICkit, PICtail, PowerSmart, PureSilicon, QMatrix, REAL ICE, Ripple Blocker, SAM-ICE, Serial QuadI/O, SMART-I.S., SQI, SuperSwitcher, SuperSwitcher II, Total Endurance, TSHARC, USBCheck, VariSense,ViewSpan, WiperLock, Wireless DNA, and ZENA are trademarks of Microchip Technology Incorporated in the U.S.A.and other countries.

SQTP is a service mark of Microchip Technology Incorporated in the U.S.A.

The Adaptec logo, Frequency on Demand, Silicon Storage Technology, and Symmcom are registered trademarks ofMicrochip Technology Inc. in other countries.

GestIC is a registered trademark of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of MicrochipTechnology Inc., in other countries.

All other trademarks mentioned herein are property of their respective companies.© 2020, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved.

ISBN: 978-1-5224-5881-4

Quality Management SystemFor information regarding Microchip’s Quality Management Systems, please visit http://www.microchip.com/quality.

TB3253


http://www.microchip.com/quality

AMERICAS ASIA/PACIFIC ASIA/PACIFIC EUROPECorporate Office2355 West Chandler Blvd.Chandler, AZ 85224-6199Tel: 480-792-7200Fax: 480-792-7277Technical Support:http://www.microchip.com/supportWeb Address:http://www.microchip.comAtlantaDuluth, GATel: 678-957-9614Fax: 678-957-1455Austin, TXTel: 512-257-3370BostonWestborough, MATel: 774-760-0087Fax: 774-760-0088ChicagoItasca, ILTel: 630-285-0071Fax: 630-285-0075DallasAddison, TXTel: 972-818-7423Fax: 972-818-2924DetroitNovi, MITel: 248-848-4000Houston, TXTel: 281-894-5983IndianapolisNoblesville, INTel: 317-773-8323Fax: 317-773-5453Tel: 317-536-2380Los AngelesMission Viejo, CATel: 949-462-9523Fax: 949-462-9608Tel: 951-273-7800Raleigh, NCTel: 919-844-7510New York, NYTel: 631-435-6000San Jose, CATel: 408-735-9110Tel: 408-436-4270Canada - TorontoTel: 905-695-1980Fax: 905-695-2078

Australia - SydneyTel: 61-2-9868-6733China - BeijingTel: 86-10-8569-7000China - ChengduTel: 86-28-8665-5511China - ChongqingTel: 86-23-8980-9588China - DongguanTel: 86-769-8702-9880China - GuangzhouTel: 86-20-8755-8029China - HangzhouTel: 86-571-8792-8115China - Hong Kong SARTel: 852-2943-5100China - NanjingTel: 86-25-8473-2460China - QingdaoTel: 86-532-8502-7355China - ShanghaiTel: 86-21-3326-8000China - ShenyangTel: 86-24-2334-2829China - ShenzhenTel: 86-755-8864-2200China - SuzhouTel: 86-186-6233-1526China - WuhanTel: 86-27-5980-5300China - XianTel: 86-29-8833-7252China - XiamenTel: 86-592-2388138China - ZhuhaiTel: 86-756-3210040

India - BangaloreTel: 91-80-3090-4444India - New DelhiTel: 91-11-4160-8631India - PuneTel: 91-20-4121-0141Japan - OsakaTel: 81-6-6152-7160Japan - TokyoTel: 81-3-6880- 3770Korea - DaeguTel: 82-53-744-4301Korea - SeoulTel: 82-2-554-7200Malaysia - Kuala LumpurTel: 60-3-7651-7906Malaysia - PenangTel: 60-4-227-8870Philippines - ManilaTel: 63-2-634-9065SingaporeTel: 65-6334-8870Taiwan - Hsin ChuTel: 886-3-577-8366Taiwan - KaohsiungTel: 886-7-213-7830Taiwan - TaipeiTel: 886-2-2508-8600Thailand - BangkokTel: 66-2-694-1351Vietnam - Ho Chi MinhTel: 84-28-5448-2100

Austria - WelsTel: 43-7242-2244-39Fax: 43-7242-2244-393Denmark - CopenhagenTel: 45-4450-2828Fax: 45-4485-2829Finland - EspooTel: 358-9-4520-820France - ParisTel: 33-1-69-53-63-20Fax: 33-1-69-30-90-79Germany - GarchingTel: 49-8931-9700Germany - HaanTel: 49-2129-3766400Germany - HeilbronnTel: 49-7131-72400Germany - KarlsruheTel: 49-721-625370Germany - MunichTel: 49-89-627-144-0Fax: 49-89-627-144-44Germany - RosenheimTel: 49-8031-354-560Israel - Ra’ananaTel: 972-9-744-7705Italy - MilanTel: 39-0331-742611Fax: 39-0331-466781Italy - PadovaTel: 39-049-7625286Netherlands - DrunenTel: 31-416-690399Fax: 31-416-690340Norway - TrondheimTel: 47-72884388Poland - WarsawTel: 48-22-3325737Romania - BucharestTel: 40-21-407-87-50Spain - MadridTel: 34-91-708-08-90Fax: 34-91-708-08-91Sweden - GothenbergTel: 46-31-704-60-40Sweden - StockholmTel: 46-8-5090-4654UK - WokinghamTel: 44-118-921-5800Fax: 44-118-921-5820

Worldwide Sales and Service


http://www.microchip.com/supporthttp://www.microchip.com

Introduction1. Description1.1. Reconfiguring Clocks, Pins, and Other Components1.2. Adding Peripheral Libraries1.3. Adding Drivers and System Services1.4. Adding Middleware1.5. Regenerate and Build the Reconfigured Project

2. ReferencesThe Microchip WebsiteProduct Change Notification ServiceCustomer SupportMicrochip Devices Code Protection FeatureLegal NoticeTrademarksQuality Management SystemWorldwide Sales and Service