Skip navigation
Home > All Places > Topics > Cypress Community Blogs > ModusToolbox Blog > Blog > 2020 > October

ModustoolBox (MTB) 2.2 brings with it a new unified workflow for applications. In ModustoolBox 2.0 or ModustoolBox 2.1, BTSDK apps had a different workflow than PSoC6 SDK apps, but with ModustoolBox 2.2, apps using PSoC6/BTSDK/AnyCloud SDK follow the same workflow.

In addition to the unified flow, there are some improvements available in MTB 2.2 such as added flexibility in how libraries are managed.

It’s necessary to make some changes in MTB 2.0/2.1 BTSDK applications to start using the unified flow in MTB 2.2. This blog will give you migration steps for BTSDK apps from MTB 2.0/2.1 to MTB 2.2


Before we move on to the steps for migration, there are some points to note:

  1. An MTB 2.0/2.1 workspace containing BTSDK app and wiced_btsdk 2.7.1 can be used with MTB 2.2 to build/program. If you want to access the library manager features of MTB 2.2, then you must upgrade your application to work with the MTB 2.2 flow.
  2. If you are using wiced_btsdk 2.7 or below but have updated to MTB 2.2, applications might break for some BSPs while using MTB 2.2 tools. The solution is to update to wiced_btsdk 2.7.1, or even better, migrate the app to the MTB 2.2 flow.
  3. BTSDK MTB 2.1 CEs are not compatible with MTB 2.2.


What has changed in BTSDK app structure in MTB 2.2?


  1. The first change you will notice is the option to create required apps from the BLE, mesh or HAL group. With MTB 2.1, all apps were created from a given group with no choice. Figure 1 shows the difference in the list of apps for the BLE CE group.
    Figure 1.  MTB 2.0/2.1 CE list(left) and MTB 2.2 CE list(right) in Project Creator

  2. In MTB 2.0/2.1, the wiced_btsdk repo needed to be cloned into the workspace before creating the application. In MTB 2.2, there is no need to create wiced_btsdk prior to the creation of app. The BTSDK apps include .mtb files for the Board Support Package (BSP) and the required libraries for the BSP are automatically detected and cloned into the shared library folder (mtb_shared) or in the libs folder in the project. Figures 2.1 and 2.2 show the difference.
      Figure 2.1. MTB 2.0/2.1 workspace vs MTB 2.2 BTSDK workspace

    Figure 2.2. MTB 2.0/2.1 BTSDK CE folder vs MTB 2.2 BTSDK CE folder

  3. The BSP and libraries can be shared or can reside locally in the project. When we say shared, it means that, all the apps created in the same workspace will use the same copy of the common libraries from the mtb_shared folder. New copies of the same shared libraries are not created for every new app. Use library manager 1.2 to make a BSP/library local or shared as shown in Figure 3 by selecting/deselecting the shared checkbox.
    Figure 3. Screenshot of library manager 1.2 to select a BSP/Library and make it shared or local

    If the BSP/library is shared, it will be created in the mtb_shared/wiced_btsdk folder. If the BSP/library is not shared, then it will be created in the libs folder in the project.

Steps to migrate an MTB 2.0/2.1 BTSDK application to the MTB 2.2 workflow


  1. Makefile Changes
    The makefile has changed significantly for BTSDK applications. Download the makefile and make changes to the following makefile variables according to your app:
        a. TARGET – the default target
        b. APPNAME – name of your project
        c. Copy any other app specific makefile variable from your MTB 2.0/2.1 CE makefile
        d. Save the makefile with the changes
        e. Copy this makefile and replace with the existing one in your app folder

  2. Adding deps folder and BSP/libraries to the application
    Library manager 1.2 must be used to add or update any BSP or libraries. Launch the library manager 1.2 tool from the start menu or go to the MTB installation folder and navigate to this path: ModusToolbox\tools_2.2\library-manager. From here launch the library manager 1.2 tool.
    a. Select the directory of your application using the browse option as shown in Figure 4.
    Figure 4. Screenshot of Library Manager 1.2 highlighting the ‘browse’ option

    Alternately, from the command line (modus-shell on Windows or from a command window on MacOS or Linux), navigate to the project directory and enter “make modlibs”. This will launch the library manager and will provide the correct directory.

    b. Next, select the required BSP from the ‘BSP’ tab. The dependency libraries are selected automatically. Select any other required libraries (ex: mesh, HID etc…) from the ‘Libraries’ tab.
    c. Click on the update button at the bottom right corner of the library manager. Wait for it to successfully update the BSP and libraries.

    d. Close the library manager. Now you can observe that in your project folder two new folders called deps and libs are added. Deps and libs contain the .mtb files of the BSP/libraries you selected in previous step and the dependency libraries, respectively.
    e. In the project directory, you can see that a new folder called ‘mtb_shared’ is created. If you navigate inside the folder into wiced_btsdk, you can see the BSP/library folders downloaded. This is the shared library that we talked about earlier in the blog.

  3. Update the Readme file of your project if required.
  4. Update the .gitignore file in your app if present. You can refer to the example .gitignore file. This is useful if you are maintaining your project on github.
  5. Open the .cybt  file present in your app with bt-configurator 2.20.0 tool (can be launched from the start menu or found in the MTB installation folder: ModusToolbox\tools_2.2\bt-configurator). Check the notice list in the bt-configurator for any changes required. If required, do the necessary changes and save the file.
    Alternately, from the command line (modus-shell on Windows or from a command window on MacOS or Linux), navigate to the project directory and enter “make config_bt”. This will launch the Bluetooth configurator and will open the .cybt file.
  6. All required changes have now been done for your app to work with the MTB 2.2 unified workflow. If desired, you can import your project into the Eclipse IDE for MTB 2.2 using the Eclipse IDE for MTB 2.2 menu item File > Import > ModusToolbox > ModusToolbox Application Import.
  7. Now you can build/clean/program/debug your application from the IDE and use any MTB 2.2 tool. You can use library manager 1.2 to update your app to use local/shared library or add/remove any BSP/library.



With wiced_btsdk 2.8, if you add more than one BSP to a project, the build will result in an error. Refer to the Bluetooth SDK 2.8 Release Notes.

To work with a different BSP, use library manager and remove (deselect) the older BSP, select the new BSP and update. Note that in a single project you can have only the BSP/BSPs of the same chip, but in a workspace if you have two or more projects, each one can use a different BSP.


Developing legacy WICED BT projects in ModusToolbox requires the shared project wiced_btsdk to be correctly configured in the workspace. For details creating project wiced_btsdk, see below:

GitHub - cypresssemiconductorco/wiced_btsdk: BTSDK (headers, libraries, chip and BSP files, peer/host applications, buil…


Q: Will Library Manager do the work?

Normally, to update the libraries in a project, we use Library Manager provided by ModusToolbox.

In this case, Library Manager won't give much help here. Because it can only update the Libraries and WICED BSPs inside the project wiced_btsdk, while it can't update the whole project itself, a.k.a. the framework. So if only Library Manager is used, then you will be using the latest BSPs via the old wiced_btsdk framework, which will cause you errors. (This is because the directories like btsdk-include in wiced_btsdk will stay in older version in this situation, which won't provide the correct reference to the latest BSPs).

We notice that, wiced_btsdk is managed by Git, a version control system. Hence we can use Git to update the entire project to the latest version, to avoid the issue stated above.

So this blog illustrates how to use Git to update wiced_btsdk in ModusToolbox. For better practise, the demonstration uses Eclipse IDE for ModusToolbox 2.2.


Q: Can I only follow the universal process of using Git in Eclipse to get the job done?

Normally, to update a project in Eclipse, you can right-click on wiced_btsdk and then choose Team => Pull.... Somehow this universal process doesn't fit in wiced_btsdk because it adopts different library management in it.

In order to update wiced_btsdk soundly, you should follow the flow stated below.


Q: Will this blog apply to ModusToolbox 2.2 or later?

The answer only depends on whether the project wiced_btsdk exists in your workspace. The version of ModusToolbox is irrelevant.

If you import the latest version of WICED BT code examples that support MTB flow, then it won't require the project wiced_btsdk (Instead wiced_btsdk and it's BSPs are moved to the new shared project named mtb_shared). So the project wiced_btsdk won't exist in your workspace. Hence this blog won't apply to this situation. This kind of projects follow the unified workflow and they are called the unified MTB projects in this blog.

But if you insist to develop WICED BT applications in the legacy style (i.e. staying in the old versions of the code examples) that support LIB flow, then the project wiced_btsdk is still needed and wiced_btsdk probably exists in your workspace already. Hence this blog will apply to this situation. This kind of projects follow the legacy workflow and they are called the legacy MTB projects in this blog.

In other words, all versions of ModusToolbox (<MTB2.2 or >=MTB2.2) support legacy MTB projects. Since wiced_btsdk is a legacy MTB project, this blog applies to all versions of ModusToolbox, including 2.2 or later.

In fact, the main purpose of this blog is trying to enable the legacy WICED BT projects to get the latest wiced_btsdk (2.8.0 or later) while preserve the old developing workflow.

This is useful when you have a heavily customized legacy WICED BT projects that you have difficulties migrating it to unified MTB projects, but you still want to get the latest wiced_btsdk and the latest ModusToolbox for it.

Besides, this blog applies to all ModusToolbox projects in all versions of ModusToolbox, no matter what dependency flow it follows (LIB flow or MTB flow), and what version ModusToolbox is, (<MTB2.2 or >=MTB2.2). This is because, It's merely about version control. It's not about dependency flow or ModusToolbox features.



  1. Right-click on wiced_btsdk, and then choose Team => Remote => Fetch from....
  2. Click on the button Finish.
  3. Ensure all the new refs have been fetched, and then click on the button Close.
  4. Right-click on wiced_btsdk, and choose Team => Reset....
  5. Now you can see all the versions of wiced_btsdk in Tags, including the latest one. Choose the latest version, select Reset Type to Hard, and then click on the button Reset.
  6. After the Reset process completed, you should see that the project wiced_btsdk has been reset to the latest version v2.8.0 from previous v2.6.0. But the sub-directories / libraries inside it remain in v2.6.0. This is the issue we are trying to avoid.
  7. To fix this, right-click on wiced_btsdk and choose Build Targets => Create....
  8. Create the build target getlibs. Configure as below and click on the button OK.
  9. Then you should see the build target is created under wiced_btsdk. Double-click on it to run the build target. This action may last for a few minutes.
  10. When the last action finishes, you can see now the sub-directories/libraries inside wiced_btsdk should all be updated to the latest version, aligning with wiced_btsdk itself.
  11. (Optional) Sometimes you can get exceptions. You might find that some of the sub-directories stalls in the previous version. This can be confirmed by the console log, with lines saying some sub-directories were skipped to be updated, as below.

    This is because uncommitted/untracked files in these sub-directories are detected, which means the files inside them might have been altered manually or unawares. So these directories are skipped for safety.
    Before going on, you should take care of these changes, or make sure the changes can be discarded. Then you can correct these directories to the desired version by one of the two steps below, and finally you should have all sub-directories updated, nice and clean:
  • a) Right-click on these directories respectively (not wiced_btsdk) and choose Team => Reset.... Then reset them to the latest version respectively. The steps are similar to the steps [4]~[5] resetting wiced_btsdk, stated above.
  • b) Close ModusToolbox, go to the folder of wiced_btsdk, manually delete these sub-directories inside wiced_btsdk, re-open ModusToolbox and run the build target getlibs again.



  1. You may relate this flow to the feature --recurse-submodule provided by Git. But in fact wiced_btsdk doesn't rely on this feature. So you can only use the build target getlibs to update the sub-directories.
  2. You can also rollback/switch between the versions of wiced_btsdk, following the same flow above. Do this by choosing the version tag you want, instead of the latest one.
  3. Other ModusToolbox project governed by Git can use the same flow above to update/rollback, too.
  4. Sometimes you may want to rollback/switch only some of the sub-directories (e.g. merely rollback 20706A2 to v2.5.0 in dev-kit\baselib), while other sub-directories remain the same, for experimental/temporary usage. In this case, the step [11-a] can also help you with this. But when it comes to BSPs/Libraries, you may better use Library Manager on this purpose for smoother experience.
  5. The flow above uses getlibs to satisfy the dependencies, that's whay the flow is compatible to the unified MTB projects and the legacy MTB projects. Because getlibs supports both LIB flow and MTB flow in ModusToolbox projects.



Filter Blog

By date:
By tag: