MPLABCode Configurator UGDS40001829 D
MPLABCode Configurator UGDS40001829 D
Preface
Introduction
®
This document describes how to install, configure and use the MPLAB Code Configurator (MCC)
software tool before starting or during the development process of an embedded software application
®
designed with PIC microcontrollers.
Recommended Reading
This user's guide refers to MCC operation only. Other useful documents are listed below. The following
Microchip documents are available and recommended as supplemental reference resources:
• Release Notes for the MPLAB Code Configurator
• MPLAB X IDE User’s Guide
Table of Contents
Preface............................................................................................................................ 1
1. Introduction ...............................................................................................................3
2. Installation................................................................................................................. 4
2.1. Installing MPLAB Code Configurator from the Microchip Plugins Update Center........................4
2.2. Installing MPLAB Code Configurator from the Microchip Website............................................... 5
2.3. Updating MPLAB Code Configurator........................................................................................... 6
2.4. Older MPLAB Code Configurator Versions.................................................................................. 6
3. Operating Areas........................................................................................................ 7
3.1. Resource Management Area....................................................................................................... 7
3.2. Versions Area............................................................................................................................. 14
3.3. Pin Manager Package View Area...............................................................................................15
3.4. Pin Manager Grid View Area......................................................................................................16
3.5. The Composer Area................................................................................................................... 19
3.6. MCC Options..............................................................................................................................22
7. Revision History.......................................................................................................33
Customer Support......................................................................................................... 34
Legal Notice...................................................................................................................35
Trademarks................................................................................................................... 35
1. Introduction
®
The MPLAB Code Configurator (MCC) generates driver code using a Graphical User Interface (GUI).
®
The generated drivers control the peripherals on PIC microcontrollers. The GUI provides an easy means
® ®
for setting up the configuration of the peripherals. MCC is a plugin for the MPLAB X IDE and MPLAB
Xpress.
Additionally, the MCC is used to configure and generate libraries, which allows code generation and
configuration for software libraries and external components.
The generated drivers or libraries can be used in any Microchip PIC or AVR device application program.
MCC requires creating or opening an already existing project in the MPLAB X IDE or MPLAB XPress,
before launching the MCC plugin. This is necessary as the MCC needs to know the device used in the
project, to have access to device-specific information like registers, bits and configurations, and to set up
the MCC GUI.
The MCC generates source and header files based on selections made in the GUI. The generated files
are added to the active project of MPLAB X IDE or MPLAB Xpress.
2. Installation
The MPLAB Code Configurator can be installed in two ways: via the Microchip Plugins Update Center, or
from the Microchip website. The following chapters describe these procedures and also the MCC update
process.
2.1 Installing MPLAB Code Configurator from the Microchip Plugins Update Center
By default, MCC is not installed together with the MPLAB X IDE and must be downloaded separately and
installed. One way to do so is via the Microchip Plugins Update Center:
1. In the MPLAB X IDE, go to Tools -> Plugins.
2. Go to the Available Plugins tab.
3. Select MPLAB Code Configurator and click the Install button. See figure below.
4. The Plugin installer opens. Click Next and check the Terms and Agreements. After this step, the
Plugin installer begins downloading the MCC plugin.
5. When the MCC plugin download is complete, MPLAB X IDE will ask to be restarted. Upon restart,
the plugin is installed.
6. MCC can now be opened on a new or already existing MPLAB X IDE project. See Section 4.1
“Setting Up MPLAB X IDE and Launching MCC.“
Figure 2-1. Installing MPLAB Code Configurator
Once downloaded, extract the archive which contains the MCC plugin to a preferred location. To install
the downloaded plugin, complete the following instructions:
1. Open MPLAB X IDE.
2. Go to Tools -> Plugins.
3. Select the Downloaded tab and click on the Add Plugins... button.
4. Navigate to the folder where the downloaded .zip file was extracted and select the MCC plugin. It
should have a .nbm file extension.
5. Click on the Install button. MPLAB X IDE will ask to be restarted. Upon restart, the plugin is
installed. See figure below.
6. MCC can now be opened on a new or already existing MPLAB X IDE project. See Section 4.1
“Setting Up MPLAB X IDE and Launching MCC.”
Figure 2-3. Installing MCC from Downloaded File
3. Operating Areas
The MCC user interface consists of six main operating areas, as shown in Figure 3-1.
1. Resource Management Area: contains the Project Resources and all the available/device
resources. See 3.1 Resource Management Area section for more details.
2. Versions Area: shows the complete list of MCC Cores, Peripheral Libraries and Software Libraries
which can be used with the selected device. Some of these are installed together with MCC, others
are available for download. Depending on the selected device, some core and library versions are
interchangeable. See 3.2 Versions Area section for more details.
3. Pin Manager Package View Area: graphic interface for pin selection and configuration.
Bidirectional operation with the Pin Manager Grid View. See 3.3 Pin Manager Package View Area
section for more details.
4. Pin Manager Grid View Area: contains three inner tabs: Notifications (errors, warnings and
general information regarding the current selections), Pin Manager - Grid View (a table version of
the Pin Module Package View) and Output (MCC Log & MPLAB X IDE Log). See 3.4 Pin Manager
Grid View Area chapter for more details.
5. Composer Area: this is the main area in which a peripheral or library driver can be configured. It
displays the possible configurations of the peripheral/library. See 3.5 The Composer Area chapter
for more details.
Figure 3-1. MCC Operating Areas
Note: All operating areas are dockable. Each can be dragged and dropped into another position, even
out of the MPLAB X IDE main window (closing the IDE however will close all MCC windows, including the
ones moved outside the IDE).
The Project Resources section is common to both views of the Resource Management Area. This section
displays the list of on-chip peripherals, external components and libraries that have been selected for the
current MCC project. The information specific to each of the two views regarding this section is available
in 3.1.1 Resource Management Area - Tree View and 3.1.2 Resource Management Area - Flat View
sections.
There are three system modules that are always available in the Project Resources section. These
modules cannot be removed. The modules are:
1. Interrupt Module: configures the interrupts for the device.
2. Pin Module: configures the pins for the device.
3. System Module: configures the system clock, Configuration bits, and other device-level functions
for the device.
A module in the Project Resources window can be removed from the project by clicking the or
button to the right of the module name in the Project Resources section. The module will be removed
from the MPLAB X IDE project. When a module is removed from the Project Resources, all of the
unsaved configuration information for that module is lost.
At the top of the Project Resources section, there are three buttons:
• Generate: once the project configuration has been completed, clicking this button will trigger the
code generation process for that specific configuration.
• Import: an MCC configuration file (.mc3 extension) can be imported into the current project. If the
selected configuration has been created for a device other than the one used in the current project,
an alert message pops up offering the possibility of an experimental configuration migration. Once a
configuration file is selected, MCC loads and configures all modules detailed in the selected
configuration file. If there is a match between a module from the configuration and a module already
loaded in the current project, the settings for the loaded module is overwritten with the ones from the
imported configuration file. This is useful for the partial configurations created manually or provided
by the Export functionality detailed below. In the case of importing a configuration created for a
different device than the one used in the current project, an alert message pops up offering the
possibility of an experimental configuration migration or canceling the import process (See Figure
3-2). During device migration the import process might fail due to hardware mismatches between the
two devices, in which case a backup configuration file is created and saved in the project folder. (See
Section 6 “MCC Device Migration”).
Figure 3-2. Importing a Configuration Created for a Different Device
• Export: allows the export of partial configurations. Any loaded module in the Project Resources,
except System modules, can be selected for a partial configuration by right-clicking on the module
and selecting "Mark for config export" (see figure below for more details). All modules marked for
export are shown in bold. Clicking the Export button creates an MCC configuration consisting only of
the modules marked for export. To remove selection use "Unmark from config export" for a specific
module or "Unmark all for config export" for all modules/components selected for export.
Figure 3-3. The Context Menu of the Project Resources Area
Besides the partial configuration export mechanism, the Context menu of the Project Resources Area
(displayed above) includes several other operations on the loaded components or modules, such as:
• Force Update: regenerates code for all the selected modules/components, even if there were no
modifications added to their configuration. See Section 4.3 “Generating Code”.
• Refresh [module_name] Windows: reopens the configuration window of the selected module if that
window has been closed previously. If the Context menu is invoked by right-clicking under the
Resources list, with no module/component selected, this option will be available as Refresh Module
Windows and its effect will be global - all previously closed MCC windows will be reopened.
• [module_name] Help: opens the help content for the user interface of the selected module/
component, if available.
clicking the button to the right of the module name in the Project Resources section. The module will
be removed from the MPLAB X IDE project. When a module is removed from the Project Resources, all
of the unsaved configuration information for that module is lost.
clicking the button to the right of the module name. The module will be removed from the MPLAB X
IDE project. When a module is removed from the Project Resources, all the unsaved configuration
information for that module is lost. Next to the button, the button offers insight about a specific
selected module. The same module information can be retrieved from the [module_name] Help option in
the Project Resources context menu (see Figure 3-3 figure).
3.1.2.2 The Available Resources section
This section contains two buttons:
• Show [device_name] Product Page: opens the product page from the Microchip website in the
default browser.
• Show Available Resources: opens, or brings into focus, the Available Resources window in the
Composer Area. See the Figure 3-7 figure below.
The Available Resources window in the Composer Area represents a table of all software/peripheral
components available for the selected device with search and filter capabilities. Each module in this table
is indexed by three attributes: module name, module type and the library containing the module. These
attributes are mapped on each table column as follows:
• Module: displays the module icon, module name, link to module help (via the button and module
selection (via the button). When a module is selected, it is added to the Project Resources
section under the Resources Management area. A module can be searched by its name using the
text field in the Module column header. The Available Resources table can be sorted alphabetically
by module name when clicking on the arrow in the column header.
• Type: displays the type of functionality provided by each module (i.e. Peripheral, Interface, Mixed-
Signal). The table entries can be filtered by module type using the text field in the Type column
header. The Available Resources table can be sorted alphabetically by module type when clicking on
the arrow in the column header.
• Library: shows the name of the library containing a certain module. The table entries can be filtered
using the Available Libraries drop-down in the Library column header. Using the Available Libraries
drop-down, the table contents can be filtered to include modules from one or several libraries. Also, it
is possible to show modules from all libraries (using the All Libraries option) or clear the whole table
(using the Clear All Libraries option). The Available Resources table can be sorted alphabetically by
library name when clicking on the arrow in the column header. Depending on the selected device and
the selected filters, the Available Resources window might show several modules with the same
name but coming from different libraries. For example, in the case detailed in the Figure 3-7 figure
there are two ADC modules shown: one from the peripheral library and the other from the
MikroElektronika Clicks library. Generally, modules bearing the same name are mutually exclusive.
After a module selection, no other module with the same name can be selected. The module
selection button becomes grayed out and clicking on it will yield a pop-up message saying that the
operation cannot be completed (see the Figure 3-8 figure).
Figure 3-8. Module selection disabled
Besides the Versions Area, a core or a library can be loaded also via the MPLABX IDE menu in Tools →
Options → Plugins → MPLAB Code Configurator (see Section 3.8 “MCC Options”).
Note: All MCC libraries are published via the Microchip website: www.microchip.com/mcc.
By right-clicking on a specific pin, all available pin functions are listed for selection. A snapshot of the
package view configuration can be saved in PNG format by right-clicking on the package and selecting
"Export Image."
Figure 3-10. Package View Area
The three leftmost columns in the Table View indicate the module’s name, functionality name and the
direction, respectively.
The Table View allows to:
• Expand/collapse rows and ports (Figure 3-12)
• Hide and show ports and rows (Figure 3-13 and Figure 3-14)
• Show only the pins that are configured (Isolate) (Figure 3-15)
Figure 3-12. Collapsing Ports and Rows
• SEVERE: either the code generation or the compilation process will be faulty with the current
configuration.
• WARNING: the code will be generated according to settings made and it may compile, but it might
also fail to function as intended.
• HINT: this provides information to assist in the successful configuration of the module. The module
and the MCC can still be used. Action might be required.
• INFO: information only, no action is required.
These can be filtered out using the Type combo box. If there are any WARNING or SEVERE type
messages present in the Notifications tab when the Generate button is clicked, a message box
displays, giving the option of reconfiguration in order to eliminate the possible errors in the current
settings. This action can be skipped, assuming the notifications have been reviewed and taken into
consideration.
Figure 3-17. The Notifications Tab
Note: The notification type may change as the MCC configuration changes. For example, WARNING
might indicate that a module requires another module to be added to the project to operate correctly. After
the module is added, the notification type would change to INFO.
The EUSART Easy Setup tab in the Composer Area allows configuring various EUSART parameters
related to transmission and reception operations.
• Custom Name: a useful pin alias which can be used in the generated code. A set of macros are
made available in the Pin Module generated code for each selected pin in MCC.
• Start High: sets the pin to a high/low logic level at device initialization.
• Analog: configures the pin as analog or digital.
• Output: sets the pin direction of the pin.
• WPU: enables the weak pull-up resistor on the pin.
• WPD: enables the weak pull-down resistor on the pin.
• OD: enables the open-drain capability on the pin.
• IOC: configures the interrupt-on-change capability of the pin.
Note: Some of the settings detailed above may be missing on some pins or from the device completely.
Please refer to the pins configuration section in the device data sheet.
Figure 3-20. The Pin Module Tab
When opening MCC for the first time on an MPLAB X project, the configuration saving dialog will be
displayed asking for a name and saving path for the MCC configuration file attached to the project. The
MCC configuration is also saved to the disk when the Generate button is pressed, or if the MPLAB X IDE
Save button is clicked. An existing MCC configuration file can be loaded by double-clicking on the
desired .mc3 file in the Important Files section of the MPLAB X IDE project.
A list of all the files that need to be merged is shown at the top of the Merge [MCC] window. Each file in
the list must be selected, in turn, to ensure that all of the newly generated code is incorporated into the
project.
At the top of the Merge [MCC] window, in the center margin, there is an arrow, as shown in Figure 4-3.
Clicking on the arrow will replace all the edits in the current file with the MCC updated code that the MCC
has just generated. The numbers above the arrow indicate the current difference and the total number of
differences.
Figure 4-3. Merge [MCC] Window - Replacing All Edits with MCC Generated Code
The individual lines of MCC Updated Code can be selected to replace the edited code. As shown in
Figure 4-4, clicking on the arrows in the right margin of the left window will copy the MCC Updated Code
to the generated driver file. Once the changes are accepted, the Merge mechanism will remove the
highlighted file and highlight the next file on the list. To insure all updates are completed, a warning will be
generated if the Merge mechanism is closed before all the changes are accepted.
Figure 4-4. Merge [MCC] Window - Replacing Single Changes with MCC Generated Code
Note:
1. Remember to merge the code for every file shown in the file list of the Merge [MCC] window.
2. Be sure to save all the changed files from the Merge process.
1. The mcc.h and mcc.c files include the definitions of Configuration bits and the
‘OSCILLATOR_initializer’ function. These definitions are based on the settings which were
made for the System module in the Composer. Also included is the ‘SYSTEM_initializer’
function which can be called in the application program to call all the other default initializers (the
ones marked in the GUI by sprocket symbol).
2. The pin_manager.h and pin_manager.c files include the Pin Manager initializer functions
based on the configurations which were made in the Pin Manager GUI.
3. The interrupt_manager.h and interrupt_manager.c files are optional files which are
generated only when peripheral interrupts are enabled and they include interrupt initializer
functions.
4. The .c and .h are module specific files and include each module’s peripheral\library configuration
functions.
5. The main.c file is generated only when the MCC detects that there is no main.c file present in
the project. If there is any previous main.c in the project regardless of its creator (the user or the
MCC), it will not generate or overwrite the existing one. When using a main.c not generated by the
MCC, the lines ‘#include "mcc_generated_files/mcc.h";’ and
‘SYSTEM_Initializer()’ need to be added to the main.c file. The main.c file generated by
the MCC may include commented out code lines to enable interrupts. Remove the comments from
the appropriate lines if the application requires interrupts to be enabled when it starts.
The functions provided in any of these MCC generated files can be called from the user application code,
as required. The MPLAB X IDE provides auto-completion assistance of all of the MCC generated content.
While editing source code in the project, start typing in a MCC API, or MCC variable name, and press
<CTRL+ Space>. The MPLAB X IDE will show a list of options to complete the entry.
7. Revision History
Revision A (January 2016)
Initial release of the document.
Customer Support
Users of Microchip products can receive assistance through several channels:
• Distributor or Representative
• Local Sales Office
• Field Application Engineer (FAE)
• Technical Support
Customers should contact their distributor, representative or Field Application Engineer (FAE) for support.
Local sales offices are also available to help customers. A listing of sales offices and locations is included
in the back of this document.
Technical support is available through the web site at: http://www.microchip.com/support
• 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 protection features of our products. Attempts to break Microchip’s code protection feature may be a
violation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your software
or other copyrighted work, you may have a right to sue for relief under that Act.
Legal Notice
Information contained in this publication 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 unless otherwise stated.
Trademarks
The Microchip name and logo, the Microchip logo, AnyRate, AVR, AVR logo, AVR Freaks, BeaconThings,
BitCloud, CryptoMemory, CryptoRF, dsPIC, FlashFlex, flexPWR, Heldo, JukeBlox, KeeLoq, KeeLoq logo,
Kleer, LANCheck, LINK MD, maXStylus, maXTouch, MediaLB, megaAVR, MOST, MOST logo, MPLAB,
OptoLyzer, PIC, picoPower, PICSTART, PIC32 logo, Prochip Designer, QTouch, RightTouch, SAM-BA,
SpyNIC, SST, SST Logo, SuperFlash, tinyAVR, UNI/O, and XMEGA are registered trademarks of
Microchip Technology Incorporated in the U.S.A. and other countries.
ClockWorks, The Embedded Control Solutions Company, EtherSynch, Hyper Speed Control, HyperLight
Load, IntelliMOS, mTouch, Precision Edge, and Quiet-Wire 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, BodyCom,
chipKIT, chipKIT logo, CodeGuard, CryptoAuthentication, CryptoCompanion, CryptoController,
dsPICDEM, dsPICDEM.net, Dynamic Average Matching, DAM, ECAN, EtherGREEN, In-Circuit Serial
Programming, ICSP, Inter-Chip Connectivity, JitterBlocker, KleerNet, KleerNet logo, Mindi, MiWi,
motorBench, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, Omniscient
Code Generation, PICDEM, PICDEM.net, PICkit, PICtail, PureSilicon, QMatrix, RightTouch logo, REAL
ICE, Ripple Blocker, SAM-ICE, Serial Quad I/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.
Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries.
GestIC is a registered trademark of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of
Microchip Technology Inc., in other countries.
All other trademarks mentioned herein are property of their respective companies.
© 2018, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved.
ISBN: 978-1-5224-4245-5
ISO/TS 16949
Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer
fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California
® ®
and India. The Company’s quality system processes and procedures are for its PIC MCUs and dsPIC
®
DSCs, KEELOQ code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and
analog products. In addition, Microchip’s quality system for the design and manufacture of development
systems is ISO 9001:2000 certified.