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

cross mob

Migrating BTSDK applications from ModusToolbox 2.0/2.1 to ModusToolbox 2.2

Migrating BTSDK applications from ModusToolbox 2.0/2.1 to ModusToolbox 2.2

5 likes given 10 sign-ins 5 sign-ins

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.