4.6 Upgrading MPLABX Projects to MCC v5.6.2 and Harmony Components

If your application code is currently running MCC v5.5.2, follow this section to upgrade the application code to MCC v5.6.2 and upgrading the harmony components version according to Harmony Components.

Version v5.6.2 of MCC introduces a new file structure for managing projects and environments. This updated structure utilizes .yml files and the .mc4 format to store information about MCC components and settings, replacing the previous single .mc3 file approach.

The following steps guide you through creating a new environment for MCC v5.6.2 and upgrading existing projects to use this environment with specific harmony components version according to Harmony Components.

Follow Installing the IDE and Compiler and Installing the MCC Plugin to install the latest version of MPLABX and MCC.
Follow Installing the Harmony 3 Dependencies and refer to the Harmony Components to install the latest dependency versions.
The default MCC content path will be in the following format: “C:\Users\xxx\.mcc”.
This can be viewed in Tools > Options > Plugins > Content:
Open the existing project to be upgraded in the IDE.
Ensure project properties use latest CMSIS, DFP and compiler as defined in the Tool Chain.
Use the IDE ribbon to launch MCC.
1. The below warnings will popup after launching MCC. They are expected, select “Yes” or “OK” to proceed.
2. Depending on the versions used in the existing project, MCC may automatically download previously used versions by the existing project.
The MCC window will be shown in the following figure:
Note: At this point, the versions used by the Harmony Components in the project graph may not be the latest as defined in the Harmony Components table. The Content Manager inside MCC is used to specify the H3 content versions for the current project.
The remaining steps outline the process of selecting the correct versions and upgrading the code.
Open the Content Manager within MCC.
1. Within the MCC window, select Project Resource.
2. Select Content Manager.
  
  Note: It is important the Content Manager is opened within MCC using the above method and NOT by using the ribbon icon.
3. Within the MCC Content Manager window, toggle the Show Local Content Only option to the ON position:
Select all the latest versions according to Harmony Components. Some versions may be defaulted to the previously used versions of the existing projects. The correct versions of these components need to be selected. For example, the following versions are not properly set to the ones defined in the Harmony Components table, they must be changed accordingly:
After all versions are corrected, some warnings may popup:
These warnings are expected and must be ignored. The component “wireless_zigbee” is not used and can be ignored. The versions of csp and bsp have been validated for the applications, therefore can also be ignored.
Apply with warnings.
Right click Generate button and select the option Force Update on All.
Left click Generate button to initiate the code generation.

There will likely be multiple files that are generated, please refer to the below table to view which generated files need to be applied.


File Paths	Apply
Files under the path “`…/src/config/default`”	Apply all the changes under this path except for the file “`freertos_hooks.c`” This file must be left unmerged.
Files under the “`…/src`” path	The file “`app_user_edis.c`” can be left unmerged and the generated “`app_idle_tasks.c`” file must be applied. The remain files are generated as blank templates. Depending on the application, some files under this directory have either been added to the project or edited to define application code. These files should be reviewed carefully so none of the user defined application code is lost.
Files under “`…/src/app_ble`”	These files also contain application-level user changes related to BLE. These files must be reviewed carefully so none of the user defined BLE application code is lost.

For example, when upgrading the legacy_adv project to MCC v5.6.2, the following generated files must be merged/applied:
- …/src/config/default/interrupts.c
- …/src/config/default/initialization.c
- …/src/config/default/pds.h
- …/src/config/default/rf_system.h
- …/src/config/default/pmu_system.h
- …/src/config/default/info_block.h
- …/src/config/default/device_vectors.h
- …/src/config/default/mw_aes.h
- …/src/config/default/ble_dm_sm.c
- …/src/config/default/host_hci_defs.h
- …/src/config/default/gatt.h
- …/src/config/default/bt_sys.h
- …/src/config/default/ble_l2cap.h
- …/src/config/default/ble_gap.h
- …/src/config/default/ble_dm.h
- …/src/config/default/app_idle_task.c
- ../src/app_idle_task.c
For these specific files, all the changes can be merged. See the image below for an example:
Following the legacy_adv example, the following generated files must left unmerged and not applied:
- …/src/app_user_edits.c
- ../src/config/default/freertos_hooks.c
- ../src/app.c
- ../src/app_ble/app_ble.c
These files contain user defined application code that must not be merged. The generated file will delete the user application code if changes are applied. In this case, do NOT apply the generated code and continue to other files, see the below image:
Many of the file differences can be explained by a single change that does not affect the functionality. The generated code uses a different copyright date than the existing code. For these files that only contain this single change can be ignored and left unmerged.

After all the necessary code has been merged/applied, the merge window can be closed to leave the existing files unmerged. The only files remaining in the merge window must be files described in 14.b and 14.c These files are intended to be left unmerged, so select “Yes”.
Clean and build the project.
Test and validate the generated code.
To upgrade additional projects, repeat steps 4-16. The MCC environment only needs to be created once.