Tip / Sign in to post questions, reply, level up, and achieve exciting badges. Know more

Knowledge Base Articles

Migrating from ModusToolbox v1.1 to v2.x - KBA229043

50 questions asked 25 likes received 25 sign-ins

Migrating from ModusToolbox v1.1 to v2.x - KBA229043

Author: JimT_21     Version: **

Translation - Japanese: ModusToolbox v1.1からv2.xへの移行 - KBA229043 - Community Translated (JA)

ModusToolbox™ v2.x is quite different from earlier versions. As a result, there is no simple porting option in the IDE to bring a project forward from ModusToolbox v1.1 into v2.x.

There are many fundamental changes in v2.x. For example, in v2.x, the board support package (BSP) is central to software development. A BSP provides a standard interface across Cypress kits to a board's features and capabilities. Other software (such as middleware or the user's application) can use the BSP to configure and control the hardware. There is no BSP in v1.1.

This KBA provides high-level steps and guidance for common situations you may encounter when moving to v2.x. If you are new to ModusToolbox 2.x, read the ModusToolbox Software Overview for a high-level look at how it works. That should help you understand some of this guidance. This KBA assumes you are familiar with the ModusToolbox IDE. Refer to the ModusToolbox IDE User Guide if you have questions about the IDE.

1. Create a ModusToolbox 2.x project.

Use the New Application wizard. Pick a BSP and a code example to use as starter application. In this process, pick a code example that provides most if not all the same functionality that you used in ModusToolbox 1.1.

If you are using a part different from what is available in a kit BSP, start with a BSP that is for a similar part, and then create a custom BSP for your device. See the BSP User Guide.

2. Add any missing libraries, and (optionally) remove any unused libraries.

The starter application may not include some middleware used by your application. Similarly, your application may not use everything included by default in the starter application. For example, if a kit supports CapSense®, the CapSense library is included by default by the kit BSP. If your application does not use CapSense, you can remove that library.

For PSoC 6 MCU-related projects, use the Library Manager to add or remove a library. You can also control the version of each library used.

For an application that uses the Bluetooth SDK, the libraries are in the SDK so you cannot use the Library Manager. Instead, you should modify the makefile directly. See the wiced_btsdk readme file for details.

If you make changes to a local copy of a library, and then use the Library Manager to update to a different version, you will be warned that there are unsaved changes and the update will be skipped.

3. Add remaining application source files into the project.

Copy the application-specific source files from the v1.1 to the v2.x project, including any additional external libraries you use. Organize them however you wish. Just put the source files anywhere in the project folder.

If you then use the IDE’s New Application command and Import the makefile for this project, all source files are discovered automatically and added to the project.

If you want to link to files by reference, rather than copy them directly into the project, you need to make corresponding changes to the makefile to add SOURCES and INCLUDES. See Running Modus Toolbox from the Command Line.

4. Resolve any issues that arise in the new build environment.

The issues you encounter will of course depend on the nature of your application and how you implement it. Some features are unchanged. Some now have additional options. Some require different solutions. This KBA cannot cover every possible case. However, we can look at some common situations.

Table 1. Differences Between ModusToolbox v1.1 and 2.x

Task, Feature, or Difference



Get started

Use the New Application Wizard to import a code example.

Unchanged, some implementation details vary

Where are code examples

Local files.

Some are installed as part of the SDK. Some are on GitHub. Download and unzip GitHub examples to get the necessary files.

GitHub repositories.

The v2.x build system creates the example project based on an application makefile that specifies the required repositories.

Import a code example

In the New Application wizard, select a kit and an example. If it is a GitHub example, import the modus.mk file for the example you downloaded. Projects point to library files in the SDK, not to local copies in the project folder.

In the New Application wizard, select a BSP and an example. All required files are cloned and replicated locally in the project folder. There is no modus.mk file. You must have internet access to import a code example. See KBA225201.

For an application that uses the Bluetooth SDK, you create an instance of wiced_btsdk before importing an example. This is the shared Bluetooth SDK library.

Create an empty project

Use the New Application Wizard. Pick your kit and then “EmptyPSoC6App”. There are “empty” choices for Bluetooth kits as well.


What is in a BSP


It varies depending on the kit. A BSP may include: startup code; linker files; board-independent macros for kit hardware (e.g. CYBSP_USER_BTN); hardware configuration files; links to libraries that support the kit hardware; and a simple API for managing the kit. See a BSP User Guide.

Where is the BSP


The BSP is in a folder with the prefix TARGET_. For MCU-related projects, the BSP is in the libs folder. For the Bluetooth SDK, it is in the Bluetooth SDK rather than in the application.

How to use a BSP

There are no BSPs. Get startup code and linker files from the SDK and add them to the project. Each example has them already, and has its own macros and configuration files.

It is specified in the application makefile and added to the project automatically by the V2.x build system.

Include cybsp.h in your application to use all the features of a BSP.

Many BSPs have an API reference. See an example here.

Where is generated code

Typically, in the GeneratedSource folder at the top level of the application project.

Typically, in the GeneratedSource folder in the BSP. For the Bluetooth SDK, additional configuration files (for example, for the Bluetooth Configurator) are in a second GeneratedSource folder in the application.

Modify a hardware design using a kit BSP

Modify the design.modus file in the application.

You override the BSP’s design.modus file. See a BSP User Guide for details on how to do this.

You can modify the design.modus file, but if you update the version of the BSP you get a warning that your changes will be lost. You need to move your changes into the new version.

Create or modify a hardware design for a custom board

In the New Application wizard, choose Custom Board and select a device. Board-specific files must be updated manually in the project.

Create a custom BSP. Any application created using your BSP gets the right files automatically. See a BSP User Guide.

Add or remove a library

Add files to the project explorer (or remove files), and manually update the include paths.

For a PSoC 6 MCU application, use the Library Manager. The application’s makefile is updated automatically and the project regenerated.

For an application that uses the Bluetooth SDK, the libraries are in the SDK, so you can’t use the Library Manager. Instead, you should modify the makefile directly. See the wiced_btsdk readme file.

Peripheral Driver Library (PDL) function calls

Use PDL function calls. There is no hardware abstraction layer (HAL).

Unchanged (except for version updates), but HAL function calls are available for many drivers. See the PSoC 6 HAL API Reference.

Initiate and enable an interrupt

Use PDL function calls (in the SysInt driver)

Unchanged, but HAL functions are available for the purpose.

Manage include paths

Add and manage paths manually with the Eclipse IDE C/C++ Build > Settings panels.

Created automatically during the make build file discovery process. You can set variables for additional paths in the application’s makefile.

See Running Modus Toolbox from the Command Line.

Included header files

What to include depends upon what resources you use. For basic resources, in main.c you might have:

#include "cycfg.h"

#include "cy_pdl.h"

#include "stdio_user.h"

#include "stdio.h"

#include "uart_debug.h"

What to include depends upon what resources you use, so these lists are not complete.

For basic resources in a PSoC 6 MCU application, in main.c you might have:

#include "cybsp.h"  // includes BSP headers, including PDL if in the BSP

#include "cyhal.h" // includes HAL-related headers

In an application that uses the Bluetooth SDK, among others you might have:

#include "wiced_bt_trace.h" // support for debug via UART

#include "wiced_bt_cfg.h" // Bluetooth stack configuration

#include "wiced_bt_stack.h" // Bluetooth management API

#include "wiced_platform.h" // hardware configuration

Initialize the system


For a PSoC 6 MCU application, unchanged if you do not use the HAL, call init_cycfg_all(). If you use the HAL, call cybsp_init(). Then in main.c, you can use HAL or PDL functions, as well as device configurator functions as necessary.

For an application that uses the Bluetooth SDK, the application_start function uses WICED function calls to initialize the transport and the Bluetooth stack.

Manage build settings, e.g.

Defined symbols

Name of output file

Compiler flags

Optimization level

Linker file and location

Additional libraries to link

Use the Eclipse IDE C/C++ Build > Settings panels.

Edit variables set in the application’s makefile.

See Running Modus Toolbox from the Command Line.

Use the Bluetooth SDK

The BTSDK is installed by the ModusToolbox installer. Example applications reference that local copy.

In the new application wizard, create the wiced_btsdk project once for any Eclipse workspace, before creating any other apps. Example applications in that workspace reference that local copy.

CM0+ default application

Provided as a precompiled .elf binary that you merge into a final executable using the cymcuelf tool.

Provided as a C array in a source file added to your project. Adjust linker script provided in BSP to adapt for different size applications. See the ReadMe file for details.

Get the Right Libraries

Table 2 lists many libraries available in v2.x, and where the same or similar code existed in v1.1. This may assist you in determining which libraries you need in v2.x. Some libraries are useful only for Mbed OS development. Note that a v2.x BSP automatically includes libraries required for a kit. For example, if the kit supports CapSense, the CapSense library is added by the BSP.

The code delivered for v2.x on GitHub is typically a newer version than what was delivered with v1.1. In most if not all cases, these are backward-compatible. While unlikely, you may need to make changes in your code to accommodate a new version of a library. A description of each library is available on GitHub. See psoc6-middleware for a complete list.

Table 2. ModusToolbox v1.1 Code and Corresponding v2.x Libraries

Functionality or Library

ModusToolbox 1.1

ModusToolbox 2.x (GitHub repo)

Hardware abstraction layer

None, v2.x has new BSP-related libraries


RTOS abstraction layer


Core Library



Each example wrote its own code; v2.x has new libraries to standardize access to hardware


Serial Flash programming





Peripheral Driver Library



CM0+ prebuilt applications



Build System

A very different implementation found here: <install>\libraries\platforms-1.0\common


Board Support Packages

Some code used in a BSP is in the pdl devices folder here:

multiple repositories, one per kit.

Bluetooth SDK

<install>\libraries\bt_20819A1-1.0\components\BT-SDK; download updates from cypress.com

multiple repositories comprise the SDK

Wifi Host Driver Library

Named WWD, it is in the WICED SDK installed as part of WICED Studio


Enterprise Security Library

In the WICED SDK installed as part of WICED Studio


HTTP Server Library

In the WICED SDK installed as part of WICED Studio


Connectivity Utilities Library

In the WICED SDK installed as part of WICED Studio


AWS-IOT Library

In the WICED SDK installed as part of WICED Studio


PSoC 6 BLE Library



CapSense Library



CSDADC Library






USB Device Library



Device Firmware Update Library



Emupated EEPROM Library



FreeRTOS kernel



emWin Graphics Library



Secure Boot SDK



Version history
Revision #:
1 of 1
Last update:
‎Dec 11, 2019 12:05 AM
Updated by: