Migrating from ModusToolbox v1.1 to v2.x - KBA229043
- Subscribe to RSS Feed
- Mark as New
- Mark as Read
- Bookmark
- Subscribe
- Printer Friendly Page
- Report Inappropriate Content
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 | v1.1 | v2.x |
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. | Unchanged |
What is in a BSP | N/A | 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 | N/A | 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. |
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 | init_cycfg_all(); | 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. |
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 | ||
RGB LED | Each example wrote its own code; v2.x has new libraries to standardize access to hardware | |
Serial Flash programming | ||
Retarget-I/O | <install>\libraries\psoc6sw-1.1\components\psoc6pdl\utilities\retarget_io | |
Peripheral Driver Library | <install>\libraries\psoc6sw-1.1\components\psoc6pdl | |
CM0+ prebuilt applications | <install>\libraries\psoc6sw-1.1\components\psoc6pdl\devices\psoc6\cm0p\prebuilt | |
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 | <install>\libraries\psoc6sw-1.1\components\psoc6mw\ble | |
CapSense Library | <install>\libraries\psoc6sw-1.1\components\psoc6mw\capsense | |
CSDADC Library | <install>\libraries\psoc6sw-1.1\components\psoc6mw\csdadc | |
CSDIDAC Library | <install>\libraries\psoc6sw-1.1\components\psoc6mw\csdidac | |
USB Device Library | <install>\libraries\psoc6sw-1.1\components\psoc6mw\usb_dev | |
Device Firmware Update Library | <install>\libraries\psoc6sw-1.1\components\psoc6mw\dfu | |
Emupated EEPROM Library | <install>\libraries\psoc6sw-1.1\components\psoc6mw\em_eeprom | |
FreeRTOS kernel | <install>\libraries\psoc6sw-1.1\components\psoc6mw\rtos\freeRTOS | |
emWin Graphics Library | <install>\libraries\psoc6sw-1.1\components\psoc6mw\emWin | |
Secure Boot SDK | N/A |