Editing an Existing MPLAB® Code Configurator (MCC) Melody Project

MCC Melody Tour

In this section, the MPLAB^® Code Configurator (MCC) Melody plug-in will be opened, its key features will be highlighted, and the various configurations used to set up the project will be examined. 

This class was developed using the latest version of the MPLAB X IDE (v6.20) and MCC Melody plug-in (v5.5.0) at the time. These tools are always evolving with updates being made. Our recommendation would always be to try and use the latest version of the toolchain when developing applications, especially with newer devices.

Let’s now open MCC Melody and take a tour. To access MCC Melody, click on the blue shield icon  at the top of MPLAB X IDE. 

If the downloaded project was created with an older version of the tools, you might be prompted to upgrade to a more recent version of the toolchain. This is advisable as updates often address known issues in previous versions. However, if necessary, you can always revert to an older version using a feature known as the content manager.

Depending on the version of the toolchain you're using, you may need to choose between MCC Classic and MCC Melody. Choose MCC Classic only if the project you're evaluating was developed using MCC Classic or if your device isn't compatible with MCC Melody. For all newer devices and projects, MCC Melody is the recommended choice, as all future support and development will be focused on it. You may also be given the option to load various libraries, but this won't be utilized in this demonstration. However, if necessary, you can add libraries later using the content manager.

Let’s take a moment to go through the essential features of the tool.

Project Resources

In the standard Window configuration, you will notice the Project Resources section situated at the top left of the tool. This section shows the integrated peripherals, external components, and libraries the MCC Melody project is using. You will also find components in the System Modules, which are included by default in any project and cannot be removed. These modules are named Clock Control, Configuration Bits, Interrupt Manager, Main, and Pins.

 

Clock Control

Here is where you can manage, distribute, and adjust the clock signals from available oscillators, with support for both internal and external clock sources.

Configuration Bits

In this module, you can configure a unique set of features that can only be modified when the target microcontroller is programmed. Read during reset, these bits allow you to enable or disable specific hardware features in the microcontroller. The features affected by the configuration bits include the clock source, the Watchdog Timer (WDT), the Brown-Out Detector (BOD), and the Memory Read protection. These bits do not run code; they act as fuses located within the program memory space.

Interrupt Manager

Here you can manage and prioritize interrupt requests configured in the project for features and peripherals you’ve added.

Main

This module is used to create the main.c source file during the code generation process.

Pins

The Pins module allows you to configure various features of the pins used in this specific application.

The Generate button is at the top of the Project Resources section. Once you have completed the project configuration, you can initiate the Application Programming Interface (API) code generation process, or in other words, firmware that will make the microcontroller work the way you want it to for the specified configuration by clicking this button.

Device Resources

Immediately below Project Resources is the Device Resources section. This section lists a variety of resources unique to the chosen microcontroller, including available peripheral drivers, system resources, hardware peripheral initializers, and libraries.

You can move a resource from the Device Resources section to the Project Resources section by clicking the green plus sign next to a resource.

This indicates that the feature or peripheral has been added to the Project, and code will be generated for this resource based on its configuration explained later in this demonstration. The resource can be removed from Project Resources by clicking on the red X symbol next to its listing.

Pin Package and Pin Grid Views

Immediately below and to the right of Device Resources are the Pin Package and Pin Grid Views.

The Pin Package view displays the pins available on your selected device package. The package can be changed using the dropdown menu at the top of the section to align with the one used in your application.

Next to the Pin Package view, you'll see the Pin Grid View.  This view displays all available pins for your chosen microcontroller in a grid format. Package pin numbers are positioned at the top of the grid, with most pins having an associated PORT and individual port bit number listed directly underneath. Each grid row signifies an available device resource signal, and by clicking the corresponding cell, you can assign the signal to a pin.

Many devices allow various signals on the device to be routed to different pins and can even be rerouted at run time dynamically. Signals that have been assigned are highlighted in green with a lock icon on the relevant pins. Available pins are either blue with an unlocked icon, indicating that the associated signal can be used on multiple pins, or orange, indicating that the signal can only be used on one pin at a time. 

The MCC Builder window provides services like the Project Resources but with the added advantage of visually depicting dependencies. It features a more user-friendly, schematic-style editor that clearly shows the connections and dependencies among your project libraries, drivers, and hardware peripherals. This allows for a more thorough understanding of each component's configuration within the broader context, helping you concentrate on the pertinent details of your current setup, such as the application you are working on and its relationship with other components.

Within the builder window, you can rearrange components for a cleaner view using the layout buttons located at the top of the pane.

Zooming and panning are accomplished with a mouse scroll wheel and by right-clicking and dragging the grid, respectively. Each component features a plus sign associated with a collapsible menu that displays various parameters of the component.
For example, expanding the Peripherals menu on the Microcontroller component reveals System and Peripheral resources available on the device. Expanding the Universal Asynchronous Receiver Transmitter (UART), reveals not only how many instances of the peripheral are available on the device but also how they interface with the other components.

So that was a quick tour of the main components found in MCC Melody. 

Back to Top

Working with Device Resources

In this section, you'll see how you can configure a selected target Microcontroller by editing the project downloaded from the Discover tool earlier in the class.

As mentioned, the Project Resources section of the MCC Melody tool shows all device-specific resources that are currently being used in the project. You already looked at how to add a peripheral driver to the project from the Device Resources section. Let’s start by looking at Drivers.

Drivers are employed when you, as a developer, want to configure peripherals or features using a graphical representation of the resource.

Clicking on the Driver instance for the UART device resource or peripheral in the Project Resources listing or in the Builder Window opens a configuration window specific to that Driver called the Easy View. The Easy View allows you to configure a particular device resource using radio buttons, drop-down menus, and fields.

At the top of the Easy View is the toolbar. This provides quick access to certain feature like Search to find a certain parameter in the View with options to increase the Text size or Expand/Collapse the focus section.

Inside of the builder window you’ll notice that the UART consists of two peripheral-related components: the driver you just looked at and a second component called the Peripheral Library (PLIB).

PLIBs represent the firmware that will be generated based on your configuration setup in MCC Melody. In some instances, like this one for the UART, an associated Driver will be included. This library indicates that development has been done for this common peripheral that is available on most Microcontroller devices, such as a UART or Timer, to provide an abstraction layer to the associated firmware created, making it more portable if the generated code needs to be ported to a different device.

Hovering over the question mark next to the library listing inside of the Icon legend will give a high-level overview of what each component represents. Clicking on the question mark will take you to an overview page providing additional information on these components. 

You can access Device Library-specific resources by hovering over the Driver component in the Builder Window and then clicking the question mark that appears or by clicking the question mark next to a Driver listing inside of the Project Resources window. This will open an associated API reference landing page that explains how to use the various functions, macros, and other firmware components that will be created when the code is generated.

If the resource is a Library, the API reference page will also include use cases, complete with code examples and video overviews.  

In the Device Resources section, you’ll also notice a section for Hardware Peripherals. This could be confusing as the Device and PLIB Drivers you just looked at are used to initialize and configure peripherals. Hardware Peripheral initializers are a different way to represent the device resource as associated registers that align with what you would see in the datasheet registers section as opposed to the Easy View used with Drivers.

The choice between which of the two device resource representations you will use depends on your preference and comfort level as a developer.  

Expanding the Hardware Peripherals drop-down and clicking the green square next to the Analog-to-Digital Converter (ADC) Driver adds it to the project resources.

Clicking on the ADC Initializer component in Project Resources opens the Register Initialization view. As you can see this presents all registers for this peripheral that can be configured using drop-down selections. The associated hexadecimal value is shown next to the register name based on the selections made. The Toolbar feature again can be used to locate certain parameters in the Register Initialization view and highlight any changes made.

You can remove the ADC Initializer device resource by clicking on the red X next to the component in the Project Resources listing as it won’t be used in this class.

Note that register changes associated with configuration changes made inside of the Easy View can be visualized by clicking the Register Initialization tab. However, at the time of this class development, this is currently only a read-only format. My recommendation is to always make sure that tools are updated as new features are always being added.

That’s a high-level overview of how to work with Device Resources. Let’s now look at how we can use what we’ve learned here to modify the Discover Demo Project.

Back to Top

Configuring an MCU and Editing a Project

MCU Clock Configuration

Clicking on the Clock Control component in the Project Resources section opens the associated Easy View.

Any changes you make to each Easy View parameter will determine the firmware API that is produced when you click the Generate button. For further details, you can click the question mark next to each parameter, which will direct you to the relevant section of the corresponding datasheet in the online documentation. 

Referring to the Clock Module section in the PIC18F56Q71 datasheet, you can see that the clock module embedded in contemporary PIC^® microcontrollers could be overwhelming when looking at it for the first time.

As these modules become more flexible and configurable, their complexity also increases. This was the whole reason that MCC Melody was created to help reduce complexity and make these features easier to use.  If you were to configure peripherals and other features on a microcontroller from the register perspective, there is an increased chance of introducing some errors in associated code or firmware which could have a significant effect on the amount of time spent on bench testing and debugging. However, using the Clock Module Easy view can dramatically reduce these errors.

Not only is the Clock Module configuration simplified graphically, but the MCC Melody Easy View also provides real-time feedback to the user in the System Clock field as various parameters are adjusted, such as Clock Source and Clock Divider to help mitigate these errors. The Easy View feature also provides feedback for peripherals affected by the Clock Module's configuration.

For instance, if you reduce the System Clock to 250KHz and open the UART2 Driver Easy View, you will see a high baud rate error percentage for the chosen baud rate.

Additionally, MCC Melody features a Notifications tab at the bottom of the tool window. When you click this tab, it displays any relevant Errors, Warnings, or Hints, including a note in this scenario that the Baud Rate error surpasses the recommended 2 percent.

When you develop applications at the register level, you might unintentionally encounter issues beyond mere syntax errors. Take the UART baud rate example provided, for instance. Despite the baud rate error exceeding 2 percent, the corresponding code would have compiled successfully. Yet, communication via the UART would be inconsistent, which could result in much time bench testing to locate the problem's source. By employing MCC Melody, you could identify the problem early in the development phase and mitigate costly debugging and redesign.

Let’s look at how this will affect our application by generating the code (click Generate ) and then downloading it to the Curiosity Nano board (click Make and Program Device  ).

Evaluating the output in the Data Visualizer Terminal and pressing the pushbutton on the Curiosity Nano board, you would expect an upper case ‘S’ but instead you get some random character. Entering an upper case ‘T’ in the terminal you would expect the LED on the Curiosity Nano board to toggle ON/OFF but nothing happens.

Of course, you know why the application isn’t working. Let’s go ahead and fix the application inside of MCC Melody.

By raising the Clock Control to a higher system clock, in this case, 500 KHz, you will see that the baud rate error percentage now shows an acceptable value.

We’ll keep everything else for the UART set to default settings.

UART Driver Configuration

As mentioned earlier, some standard peripherals like the UART have their related peripheral libraries abstracted to improve portability across devices. In these cases, the PLIB Easy View needs to identify the peripheral or feature on the target device that should be assigned to it, or in other words, determine the PLIB's dependency. When you scroll down through the PLIB Easy View to the Dependency Selection, you select the UART dependency from the UART Dependency Selection dropdown.

In this case, the UART2 instance of the peripheral, noting that the PIC18F56Q71 device used in this class has two UART peripheral instances. The number of instances available will vary across different devices. Selecting UART2 as the UART dependency adds the UART2 Driver block to the application builder.

Clicking on the UART2 driver block opens the UART2 Easy View, which was previously used to verify the baud rate error percentage.

In the UART Driver Easy View, in the Configuration Settings area, the baud rate is set to 9600 by manually entering the value into the corresponding Requested Baudrate field. You may notice this is referred to as Requested Baudrate since the actual baud rate will be limited by the previously defined clock configuration.

It is important to note that the Calculated Baudrate, which displays the actual Baud rate based on the clock settings, is located immediately below the Requested Baudrate field. The previously discussed Baud Rate Error is right below the Calculated Baudrate field.  

You can find additional UART settings below these fields but those are left at their default settings in this application. 

UART and LED Pin Assignment

In this application, the UART sends and receives messages via a serial terminal on your host computer through the USB port. The Curiosity Nano boards come equipped with a UART-to-USB converter built into their debugging circuitry. To establish this connection, you must specifically assign the target microcontroller UART pins to connect to the corresponding circuitry on the Curiosity Nano board.  

Referring to the Pin Grid View in the Melody tool, notice that the UART2 peripheral is set to receive RX signals on pin 17, which is PORTB bit 5, and transmit TX data on pin 16 or PORTB bit 4.

Let’s verify this connection by selecting the Kit Window tab, scrolling down to the External Links section, and clicking on the PIC18F56Q71 Curiosity Nano Schematics link.

Upon opening, the first page of the schematics for the board will show how the various features on the board connect to the PIC18F56Q71 Microcontroller.

The Serial/CDC Port refers to the UART-to-USB converter, and the pins selected in Melody are confirmed as correct, with the UART2 TX signal on RB4 or PORTB bit 4 and UART2 RX connected to RB5. Also note that LED0 connects to pin RC7 and the pushbutton or switch to RA0, as confirmed in the MCC Melody Pin Grid View in the Pins General Purpose Input/Output (GPIO) signal assignment.  

The LED connected to RC7 is set as an output, and the switch connected to RA0 is set as an input.  

Referring to the open schematics, the first page indicates that both the switch and LED are Active Low.

On the next page of the schematics, at the bottom, you will see that the Anode of the LED connects to a voltage source and the Cathode through a current limiting resistor to pin RC7.

Therefore, driving the RC7 LOW or to 0V will turn the LED ON. The switch connects to the RA0 pin through a current limiting resistor, with the other lead connected to ground. When you press the pushbutton, the connection will complete, and RA0 will be pulled to 0V.

You may notice a critical component missing common to most switch interfaces when following the connection from the switch current limiting resistor to the pin on the Microcontroller on the schematic. A pull-up resistor is typically used to eliminate unwanted noise on the pin and false triggers.

Back to the MCC Melody tool, click on the Pins component inside of Project Resources to open the associated Easy View.

Inside of the Pins Easy View, all the pins selected from the Pin Grid View are shown, including some additional capabilities. You can also rename that pin to something more intuitive than the default name, and this will be reflected in the generated firmware associated with that pin. Looking at the row associated with RA0 shows that the pin is associated with function GPIO, set as an input, the custom name has been set to SW0 to align with the switch name in the PIC18F56Q71 Cnano schematics and that the Weak Pullup is enabled. Most pins on modern PIC and AVR^® microcontrollers feature the ability to assign a weak pull up resistor to its input to further reduce the number of external components needed.  

When the switch is pressed, firmware polling that pin will recognize the switch press and then transmit the S character. Also, note that pin RC7 tied to the LED has been configured as an output with the Custom Name LED. 

Generate Code

Remember that modifications were made to the Clock Frequency for the device earlier changing the system clock frequency to 500 kHz from 1 MHz. These alterations will not take effect until the Generate button , located at the top of the Project Resources pane, is pressed to regenerate the code.  

The successful generation of firmware is indicated by the message Generation complete in the MCC output window at the bottom of the MPLAB X IDE.

Code has now been generated for the project based on the changes made. Next, let’s look at how to use this code in an application.

Back to Top

Navigating and Using Generated Code

Navigating back to the Projects tab and expanding the Header Files submenu, then MCC Generated Files, and finally uart, double-click on the uart2.h header file to open. 

As you browse through the header file, you will notice numerous definitions, macros, and functions. These are designed to make it easy to use and modify UART behavior during runtime. For each function definition, you will find additional details that echo the information you previously accessed in the API reference within MCC Melody. This information was initially viewed when you clicked on the question mark adjacent to the peripheral component in the Project Resources section.

On a Windows machine, holding the CTRL key and then selecting a function with a left-click of the mouse will take you to that function inside of the uart2.c source file to see how it works.

Using this code in conjunction with the device datasheet is a fantastic way to learn more about the associated feature or peripheral this function controls. 

Back in the Projects tab, double-clicking on the main.c source file to open it, you can see the code that uses the generated API to implement the application.

The first part of the code we’ll take a look at is associated with the switch press, which prompts the UART to transmit the character 'S' for display in the Data Visualizer Serial Monitor window.

Looking at the code, an if statement is used to check the pin voltage on RA0 that was given the custom name SW0 using the API-generated macro SW0_GetValue().
We can see what actions the macro is performing by clicking on the macro name here while holding down the CTRL key on my Windows^® machine.

This will open the pins.h header file to the line of code where the SW0_GetValue() is defined. As you can see here, the macro simply returns the value of the RA0 bit in the PORTAbits register that holds the value of the RA0 or SW0 pin.

If that value is LOW then this means the SW0 has been pressed and that the character ‘S’ is transmitted over the UART using the UART2_Write() call. Again holding CTRL and then Right Clicking takes me to the UART2_Write definition which in effect calls the UART2_Write() function.  

Using the same technique to navigate to the UART2_Write() we can see that firmware simply assigns a register called U2TXB, an acronym for the UART 2 Transmit Buffer, with the txData parameter which in this case is ‘S’ character. Loading a value into this register automatically triggers a transmit over the UART TX line. 

Returning to the main(), before exiting the if statement a 350 ms delay is implemented to avoid sending multiple ‘S’ characters at the same time. Changing the value of delay parameter will change the output to the terminal window. As an example of reducing the delay parameter to say 100 ms and reprogramming the device, we can see that multiple ‘S’ characters are transmitted as the while(1) loops through the check quicker now that we’ve released the button.

On the other hand, adding another zero to get 1000 ms or 1 second and reprogramming the PIC18F56Q71 we can see that now if we press the button too quickly the loop through to the button check may be going so slowly that it might just miss some of the presses. Let’s return the parameter to 350 ms as this seemed to work pretty well.

The next section of code will check when a character has been sent to the UART from the Serial Monitor window in the Data Visualizer over the UART-to-USB connection. If that character is ‘T’, the code will toggle the LED on the Curiosity Nano board ON/OFF.  

Holding CTRL and then right-clicking takes me to DELAY_milliseconds() function in a new source file called delay.c which implements a blocking while loop for the number of milliseconds sent as a 16-bit variable. Each time through the while loop a delay_ms(1) function is called.

Clicking on the delay_ms(1) while holding the CTRL key further reveals the associated define inside of the builtins.h file.

So this is a great way to see how code has been created and used within the API that can be used as a reference when creating your own custom code. 

Here another if statement is used that checks if a character has been received by the UART using the UART2_IsRxReady().

Checking the macro using CTRL and right-clicking and then doing the same on the UART2_IsRxReady macro returns the inverse value of the value of the RXBE bit, or Receive Buffer Empty Status bit, in the UART FIFO Status register. The value returned is inverted to make the Boolean value a TRUE or HIGH since the bit will be HIGH when the Receive Buffer is empty.

If there is a value in the Receive Buffer…or in other words the UART2_IsRxReady() is TRUE, then an 8-bit variable called rxValue defined just before the while(1) is assigned the value. Again, let’s use CTRL and right-click to navigate to the UART_Read(). This is defined as the UART2_Read function call which we can see returns the contents of the UART2 Receive Buffer or U2RXB. An important point here is that only after calling the UART_Read() here will the UART2_IsRxReady() flag be reset. This occurs once the UART2_Read() value is assigned to the rxValue.

The next line of code uses a final if statement which checks the rxValue variable. If it contains the ‘T’ character, then the LED_Toggle() macro is executed. Using the CTRL left-click we can see that the LED_Toggle() macro performs an exclusive OR on the LATC7 bit in the LATC register which will toggle the value output on the RC7 pin connected to the LED.

Now that we have a better understanding of how to navigate and use the code from the basicUARTcomms example, let's now look at how to keep our tools up to date and how we can revert resources using the Content Manager.

Back to Top

Versioning and the Content Manager

There are a few ways that the tools and resources can be updated or reverted for an MCC Melody project.

The MCC Melody tool's Content Manager is used to update or even revert components of a project like the libraries or tool versions used. The Content Manager tool can be accessed by clicking the button located at the top right corner of the Device Resources panel.
You could also use the Content Manager button  in the MPLAB X IDE toolbar at the top of the IDE but you will need to close MCC Melody.

The Content Manager tool is specifically designed to manage firmware drivers and library content types at a component level for your project. This allows for independent updating of individual project component modules.

If a driver or library update causes your project to malfunction, you have the option to revert to a previous version of the driver or library to restore the application's functionality. For example, within the Content Manager, expanding the Drivers accordion menu reveals a list of all available peripheral drivers.

Each entry includes a version number and indicates whether the driver is the latest version (highlighted in green) or if an update is available (highlighted in yellow), followed by a driver description. 

You can view other available driver versions by expanding the drop-down in the Version column.

To revert, simply select an older driver version and click the Apply button at the top of the Content Manager. The update process may take a few minutes, after which the MCC Melody will restart. There is also a Select Latest Version(s) button that, when selected and the Apply button pressed, will automatically update all updatable content. The successful updates will be confirmed in the Output window.

The version of the MCC Core used can be found in the details tab of the original Discover example.

For other related driver versions, such as those for peripherals, you can refer to the original header files of a specific module, where these versions are mentioned in the comments at the top of the file.

If these files have been misplaced or overwritten, you can still access the original header files in the GitHub repository for the corresponding example. 

To do this, navigate to the specific Discover example page, select the Open with drop-down, and click on GitHub.

Once you are redirected to the GitHub page for the example, click on the folder with .X.

To access the individual source files for each peripheral or system module, use the folder navigation tree on the right of the repository. You can now download or simply copy the code.

So that’s it! You should now understand how to open an existing MCC Melody project, make changes, update the generated API and then navigate the code.