MPLAB® Code Configurator v3.xx User's Guide

Preface

Important: Notice to customers: All documentation becomes dated, and this manual is no exception. Microchip tools and documentation are constantly evolving to meet customer needs, so some actual dialogs and/or tool descriptions may differ from those in this document. Refer to our website (www.microchip.com) to obtain the latest documentation available.

Documents are identified with a “DS” number. This number is located on the bottom of each page, in front of the page number. The numbering convention for the DS number is “DSXXXXXXXXA”, where “XXXXXXXX” is the document number and “A” is the revision level of the document.

Introduction

This document describes how to install, configure and use the MPLAB® Code Configurator (MCC) software tool during or before starting the development process of an embedded software application designed with PIC® microcontrollers.

Recommended Reading

This user's guide refers to MCC operation only. Other applicable 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

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.
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."

(See Figure 2-1. Installing MPLAB® Code Configurator for a visual representation of the process.)

2.2 Installing MPLAB® Code Configurator from the Microchip Website

The MCC plugin can also be downloaded from the Microchip website by typing the address www.microchip.com/mcc in a web browser, selecting the Current Download tab, and downloading the Current Version .zip file. (See Figure 2-2.)

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 may 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.
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.”

(See Figure 2-3. Installing MCC from Downloaded File for a visual representation.)

2.3 Updating MPLAB® Code Configurator

When an MCC version newer than the one installed is available, the MPLAB X IDE will display a notification in the bottom right corner of the IDE window. By clicking on it, the plugin update wizard is launched. In the wizard, click on the Install button, and the software will download and install the new MCC plugin version. (See Figure 2-4.)

2.4 Older MPLAB® Code Configurator Versions

Older MCC versions are available at the same www.microchip.com/mcc address, under the Archive Download tab.

MCC Plugin Options

Several aspects of the operation of the MCC can be managed by using the "Options" panel, which can be invoked by clicking Tools → Options → Plugins → MPLAB Code Configurator in the menu bar of the MPLAB X IDE.

3.1 File Handling

1. Remove unused files from the project: Enabling this option tells the MCC to remove .c and .h files from modules which were removed from the MCC configuration between the subsequent generation procedures. This option ensures that the files included in the project (and thus in the compilation) are only those which are strictly necessary. However, this will not delete the files from the disk.
2. Delete unused files from the disk: This option gets enabled only when selecting "Remove unused files from the project," which performs the additional task of deleting unused files from the disk. Once a file is deleted, it cannot be recovered.

3.2 MCC Line Endings

Specify the type of line endings to use in the files generated by MCC. The default is DOS (<CR><LF>). Unix line endings (<LF>) may be specified.

3.3 Editor Behavior

1. Always ask before removing a module: Enabling this control enables the "Are you sure?" dialog box which appears while disabling or removing an enabled module.
2. Always ask before removing a pin: Enabling this control enables the "Are you sure?" dialog box which appears while deallocating or removing a pin from a peripheral.

3.4 Installing an MPLAB® Code Configurator Library

The MPLAB Code Configurator provides a peripheral or software library installation feature. This feature can be used to add MCC-compatible libraries. There are several libraries for various applications the user can choose from on the http://www.microchip.com/mcc webpage. An MCC Library file may have a .jar or a .mc3lib file extension.

Once this file is downloaded, open the MPLAB X IDE, and in the above menu go to Tools → Options → Plugins → MPLAB Code Configurator 3.x, click on the Install Library button and select the .jar file via the Open File dialog box. The Versions window will now list the newly added library as installed.

If there are multiple versions of a library, the newly installed one will not be the loaded one. To load a particular version of a library, right-click on it and select "Mark for Load," which will then highlight the user's choice. If the user has multiple libraries with multiple versions in each, one from each can be highlighted before loading them. See Section 3.3. "Versions Area" for more details about switching library versions.

Removing a library is done using the Remove Library button. The File selection dialogue window will open the Library folder. Select the library to remove and click on the Remove button on the File selection dialogue. The library can be verified if it is no longer present on the computer by going to the Versions operating area - the removed library version is not present on the computer anymore. It may be present as available for download.

If a library currently in use is attempted to be removed (green tick in the Versions area), MCC will not allow this to happen. To remove that library version, switch to another version, go back to the Options window and press the Remove Library button again for the library version to delete.

3.5 Installing an MPLAB® Code Configurator Core

The MPLAB Code Configurator provides a core switching feature. This feature works simultaneously on various projects with different core versions without uninstalling or reinstalling the plugin. To install a new core, download first the new core from the Microchip MCC webpage (http://www.microchip.com/mcc). This file may have a .mc3core file extension. Once this file is downloaded, open the MPLAB X IDE and in the above menu go to Tools → Options → Plugins → MPLAB Code Configurator 3.x, click on the Install Core button and select the .mc3core file via the Open File dialog box. The Versions window will now list the fresh core installation.

To switch to another core version, either double click on it, or right-click on it and select "Switch Core Version." The Versions window will now refresh the core selection with the user's choice. The core installations can always be checked by opening the Core folder, from Tools → Options → Plugins → MPLAB Code Configurator 3.x path. Refer to Section 3.4. "Versions Area" for more details about core switching.

Removing a core version is done from the Remove Core button. The Folder selection dialogue window will open the "Core" folder. Select the core version to remove and click on the Remove button on the Folder selection dialogue. The core version can be verified it is no longer present on the computer anymore by going to the Versions operating area - the core version removed is not present on the computer anymore. It may be present as available for download.

If a core version currently in use is attempted to be removed (green tick in the Versions area), MCC will not allow this to happen. To remove that core version, switch to another core version, go back to the Options window and press the Remove Core button again for the core version to delete.

Generating MCC Code

Now that MCC has been installed and its main operating areas are learned, it is time to set up MCC according to the user's needs and begin configuring the project. The following subsections cover basic MCC operation and the code generation process.

4.1 Setting Up MPLAB X IDE and Launching MCC

To generate drivers using the MCC in MPLAB X IDE, follow these steps:

1. Create a new MPLAB X IDE project or open an existing project.
2. If multiple projects are open in MPLAB X IDE, set one as the main (active) project by selecting "Set as Main Project" in the MPLAB X IDE. For the active project, the MCC automatically includes the generated driver files.
3. Open the MCC plugin tool. In the menu bar of the MPLAB X IDE, go to Tools → Embedded → MPLAB Code Configurator 3.x: Open/Close. Or click on the MCC icon in the MPLAB X IDE toolbar.

Note: For MAC users, the "Embedded" selection will be under the Preferences menu. This launches the MCC GUI. (See Figure 4-1. Opening the MCC in MPLAB® X IDE.)

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.

4.2 Generating Code

When the MCC Generate button is pressed in the Project Resources window, the listed actions are performed by MCC. Details of the code generation are shown in the MCC Output tab. (See 6.4.2 The MPLAB® Code Configurator - Output Tab.)

1. The MCC configuration file is saved.
2. MCC generates code for the peripheral or library module if the module's configuration has changed since the last time MCC generated code for that module.

Note: All modules can be forced to be generated by MCC by right-clicking in the Project Resources section from the 6.1 Resource Management Area and selecting "Force Update," before clicking on the Generate button.

If MCC attempts to regenerate a file on the disk that has been modified outside of MCC, the Merge [MCC] window is displayed. Use the Merge [MCC] window to select whether to keep the modified file (default action) or replace the modified content with the content generated by MCC. The Merge [MCC] window is discussed in Section 4.3.2 "The Merge [MCC] Window.”

4.2.1 Saving and Loading the MCC Configuration

Saving and loading the MCC configuration is integrated into the MPLAB X IDE Save and Load functions. The MCC configuration is saved whenever the Generate button is pressed. The MCC configuration can also be saved by clicking on the MPLAB X IDE Save tool or selecting Save from the File menu.

The MCC configuration file is included in the MPLAB X IDE project under the Important Files folder. The configuration file uses the extension .mc3. Double-clicking on the MCC configuration file will cause that MCC configuration to be loaded.

4.2.2 The Merge [MCC] Window

If any of the files generated by the MCC have been edited outside of MCC and saved to the disk, then the Merge [MCC] window appears in the Composer Area. Use the Merge [MCC] window to select whether to keep the edits or replace them with the newly generated MCC code.

Note: The user's edits will never be overwritten by the MCC-generated code, except explicit action in the Merge [MCC] window.

When changes have been made to both a generated file and the corresponding MCC UI within the Composer Area, the Merge [MCC] window shown in Figure 4-2 will be displayed. The Merge [MCC] window allows resolving the conflicts between the newly generated file and the edits made to the file.

When the newly generated MCC content has been accepted, MCC makes the changes to the file. To the MPLAB X IDE, these changes are the same as if they were typed in the new content. The normal MPLAB X IDE edit undo can be used in the MCC Merge operation.

(See Figure 4-2. Merge [MCC] Window - File List and Figure 4-3. Merge [MCC] Window - Replacing All Edits with MCC Generated Code, and Figure 4-4. Merge [MCC] Window - Replacing Single Changes with MCC Generated Code for visual examples.)

Notes:

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.

MCC Content Manager

The MCC Content Manager (CMT) allows users to select specific versions of the component modules and libraries to be used for their MCC projects. Refer to the MCC Content Manager Reference for more information.

MCC Classic

MCC Classic is the original plugin and user interface for the MPLAB® Code Configurator. It consists of six main operating areas, as shown in Figure 6-1.

1. Resource Management Area: Contains the Project Resources and all the available/device resources. See 6.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 6.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 6.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 6.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 6.5 The Composer Area chapter for more details.

(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 those moved outside the IDE.)

6.1 Resource Management Area

The Resource Management Area comes with two separate views: the tree view and the flat view. Both provide access to the complete list of software/peripheral components and the selected components for the current project configuration. For more details on each view, refer to 6.1.1 Resource Management Area - Tree View and 6.1.2 Resource Management Area - Flat View sections.

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 6.1.1 Resource Management Area - Tree View and 6.1.2 Resource Management Area - Flat View sections.

System modules (Interrupt Module, Pin Module, System Module) are always available in the Project Resources section and cannot be removed.

A module in the Project Resources window can be removed by clicking the 'X' 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 unsaved configuration information for that module is lost.

At the top of the Project Resources section, there are three buttons:

• Generate: Triggers the code generation process for the current configuration.
• Import: Allows importing an MCC configuration file (.mc3 extension). If the selected configuration is for a different device, an experimental configuration migration alert may appear.
• Export: Allows exporting partial configurations. Modules can be marked for export, and clicking the Export button creates an MCC configuration consisting only of the marked modules.

(See Figure 6-2. Importing a Configuration Created for a Different Device for a visual example.)

(See Figure 6-3. The Context Menu of the Project Resources Area for additional operations like Force Update, Refresh, and Help.)

6.1.1 Resource Management Area - Tree View

This view is split into the Projects Resources section and the Device Resources section. Both sections can be navigated using arrow keys.

6.1.1.1 The Project Resources section

Displays peripherals, libraries, or external components selected for the current project. Selection is done via the Device Resources section. System Module, Pin Module, and Interrupt Module are selected by default. Configuration is done through the Composer Area. Peripherals and libraries are added by double-clicking their names in the Device Resources section. Modules can be removed using the 'X' button.

6.1.1.2 The Device Resources section

Lists the data sheet, external components, and libraries available for the device, based on loaded libraries. Double-clicking a peripheral or library moves it from Device Resources to Project Resources, invoking the Pin Manager.

(See Figure 6-5. Resource Filtering in Device Resources - Tree View for filtering options.)

6.1.2 Resource Management Area - Flat View

This view is similar to the Tree View but presents information in a flat structure, split into Project Resources and Available Resources sections.

6.1.2.1 The Project Resources section

Displays selected project components. Modules can be removed using the 'X' button. A '?' button offers insight into a selected module.

6.1.2.2 The Available Resources section

Contains buttons to show the device's product page or to open the Available Resources window in the Composer Area.

(See Figure 6-7. Available Resources Window for details on modules, types, and libraries.)

6.2 Versions Area

Provides information about versions of MCC Core, Peripheral Library, Software Library, or other components. Loaded versions are indicated by a green checkmark. MCC can be configured to use a specific library version. Core versions can be switched, and library versions can be marked for load.

(See Figure 6-9. Versions Area for a visual representation.)

Note: All MCC libraries are published via the Microchip website: www.microchip.com/mcc.

6.3 Pin Manager Package View Area

Describes color coding for pins: Gray (not usable), Blue (available), Green (allocated), Yellow (alternate). The graphical Pin Manager can be zoomed using the mouse wheel or +/- keys. Right-clicking a pin lists available functions. Package view configurations can be exported as PNG images.

(See Figure 6-10. Package View Area for a visual example.)

6.4 Pin Manager Grid View Area

This area contains three tabs: Pin Manager Grid View, Output, and Notifications.

6.4.1 The Pin Manager Grid View

Allows selecting the device package. The table view displays pin numbers for the selected package. The leftmost columns show module name, functionality, and direction. The table view allows expanding/collapsing rows and ports, hiding/showing ports and rows, and isolating configured pins.

(See Figure 6-11. The Grid View Area, Figure 6-12. Collapsing Ports and Rows, Figure 6-13. Hiding Ports and Rows, Figure 6-14. Restoring Ports and Rows (Show All), and Figure 6-15. Isolating the Selected Pins for visual examples.)

6.4.2 The MPLAB® Code Configurator - Output Tab

Displays MCC operation results and the MPLAB X IDE Log.

(See Figure 6-16. The MPLAB® Code Configurator - Output Tab.)

6.4.3 The Notifications Tab

Displays messages during configuration, indexed by Category, Module Name, and Type (SEVERE, WARNING, HINT, INFO). WARNING or SEVERE messages may prompt reconfiguration.

(See Figure 6-17. The Notifications Tab.)

6.5 The Composer Area

Displays the configuration GUI for a selected peripheral, library, or external component. Peripherals and libraries are configured here based on application requirements.

6.5.1 The Easy Setup Tab

Allows configuring various parameters related to transmission and reception operations for modules like EUSART.

(See Figure 6-18. The Easy Setup Tab of the PIC16F1947 EUSART Module.)

6.5.2 The Registers Tab

Provides direct access to configure module registers and settings. Changes in Easy Setup are reflected here, and vice versa.

(See Figure 6-19. The Register View.)

6.5.3 The Pin Module Tab

Allows additional pin configuration. Settings include Pin Name, Module, Function, Custom Name, Start High, Analog, Output, WPU, WPD, OD, and IOC. Some settings may vary by device.

(See Figure 6-20. The Pin Module Tab.)

Generated Sources and Header Files

The generated drivers are included in the active MPLAB X IDE project.

Key files include:

• mcc.h and mcc.c: Definitions for Configuration bits and oscillator/system initializers.
• pin_manager.h and pin_manager.c: Pin Manager initializer functions.
• interrupt_manager.h and interrupt_manager.c: Optional files for peripheral interrupts.
• Module-specific .c and .h files: Contain peripheral/library configuration functions.
• main.c: Generated if no existing main.c is found. If an existing main.c is used, include statements for MCC headers and the SYSTEM_Initializer() function must be added.

Functions from these files can be called from user application code. MPLAB X IDE provides auto-completion assistance.

(See Figure 6-21. Generated Source and Header Files for a file tree structure.)

MCC Device Migration

MCC device migration refers to using a configuration created for one device on a different device. Note that MCC device migration is not supported in MCC. Users are responsible for verifying the suitability of migrated code. Unintended migration can occur if the selected device in MPLAB X IDE is changed after MCC configuration or if an MCC configuration file is copied to another project.

MCC Melody

MCC Melody is a new flavor of MCC providing Libraries, Drivers, Peripheral Libraries (PLIB), and Hardware Initializers (HWI) for developing embedded software for Microchip PIC® and AVR® Microcontrollers (MCUs) and dsPIC® Digital Signal Controllers (DSCs).

Key features include:

• A structured relationship manager (MCC Builder) for visualizing component dependencies.
• An implementation enabling components in the online development ecosystem (e.g., MPLAB Xpress IDE).
• A content manager for granular, component-level versioning and selection.

For more information, refer to the MCC Melody Technical Reference.

MCC Harmony

MPLAB Harmony 3 provides a Chip Support Package (CSP), core hardware abstraction libraries, extensive middleware, and a graphical configuration tool for C language embedded software development for Microchip 32-bit microcontrollers and microprocessors. Refer to the Microchip MPLAB Harmony Github Page for more information.

Revision History

The Microchip Website

Microchip provides online support via its website (www.microchip.com). This site offers data sheets, errata, application notes, sample programs, design resources, user's guides, hardware support documents, latest software releases, and archived software.

General Technical Support includes FAQs, technical support requests, online discussion groups, and a Microchip design partner program member listing.

Business information includes product selectors, ordering guides, press releases, seminar listings, and sales office/distributor information.

Product Change Notification Service

Microchip's product change notification service keeps customers updated on product changes. Subscribers receive email notifications for changes, updates, revisions, or errata related to specified product families or development tools. To register, visit www.microchip.com/pcn.

Customer Support

Users can receive assistance through several channels:

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

Technical support is also available via the website: www.microchip.com/support.

Microchip Devices Code Protection Feature

Microchip products meet their data sheet specifications. Microchip believes its products are secure when used as intended. Attempts to breach code protection features are prohibited and may violate the Digital Millennium Copyright Act. Code protection is constantly evolving, and Microchip is committed to improving these features.

Legal Notice

This publication and its information may be used only with Microchip products for design, testing, and integration. Use in any other manner violates these terms. Device application information is for convenience and may be superseded by updates. Users are responsible for ensuring their application meets specifications. Contact a local Microchip sales office or visit www.microchip.com/en-us/support/design-help/client-support-services for additional support.

Trademarks

Microchip's trademarks include names like Microchip, Adaptec, AnyRate, AVR, dsPIC, MPLAB, and XMEGA, among many others. A comprehensive list of registered and unregistered trademarks is provided, covering various product lines and technologies.

Quality Management System

For information regarding Microchip's Quality Management Systems, please visit www.microchip.com/quality.

Worldwide Sales and Service

Microchip provides worldwide sales and service contact information, including corporate offices, regional offices across the Americas, Asia/Pacific, and Europe, with phone and fax numbers.