Tools package release notes



About this document

Scope and purpose

ModusToolbox™ software is a set of tools that enable you to integrate our devices into your existing development methodology. ModusToolbox™ software consists of various libraries and middleware on GitHub, as well as an IDE and tools package installed on your computer. For more details about what is included with ModusToolbox™ software, refer to the ModusToolbox™ user guide, “ModusToolbox™ software overview” section. See also What’s included in this document.

This ModusToolbox™ 2.4 tools package is a complete release. It includes the latest features from all previous releases, including patches. This release does not replace any existing installed releases; it installs alongside them. If you have more than one release installed, refer to the ModusToolbox™ user guide, “Product versioning” section.

Intended audience

This document describes the features and known limitations for the ModusToolbox™ software provided as part of the ModusToolbox™ tools package included with the installer.

Document conventions




Emphasizes heading levels, column headings, menus and sub-menus


Denotes file names and paths.

Courier New

Denotes APIs, functions, interrupt handlers, events, data types, error handlers, file/folder names, directories, command line inputs, code snippets

File > New

Indicates that a cascading sub-menu opens when you select a menu item

Reference documents

Refer to the following documents for more information as needed:

Other documentation includes (but is not limited to):

1. Primary changes

This release of the ModusToolbox™ tools package includes the following updates and features:

1.1 Expanded device support

Look for announcements about new devices being released in the coming months. We’ve updated our tools to support these devices, and they will automatically become available in the tools when they’re released.

1.2 Update to Infineon

Cypress was acquired by Infineon Technologies over a year ago, and we’ve been updating our tools and libraries to be part of the Infineon ecosystem. This includes:

1.3 XMC™ simulation tool support

You can now create a ModusToolbox™ application for devices that are supported by the XMC™ simulation tool. We automatically generate a simulation .tgz file as part of the post-build process. After the build is complete, you can upload the .tgz file to the simulation web application (

1.4 Application categories in Project Creator

The Project Creator tool now lists the various applications by category for easier browsing:


You can still use the search and filter features to find the application you want. But if you don’t know what you want, the category might help narrow it down.

1.5 Improved Machine Learning capabilities

This release includes Machine Learning features and improvements, including:

  • Data streaming for on-device validation on target

  • Size optimization option during model conversion

  • Improved cycle count and accuracy for 8-bit models

1.6 Single copy of KitProg3 firmware

In previous releases, a few tools like the Device Firmware Update (DFU) Host tool and CAPSENSE™ Tuner provided separate instances of the KitProg3 firmware. With this release, there is now only one copy of KitProg3, and it is located in the following directory:


1.7 Qt software update

We have updated the software version used to develop our GUI configurators and tools. For most users, there should be no impact. However, for Linux users, this update requires that you install an additional package called libxcb-xinerama0. Refer to the ModusToolbox™ installation guide for instructions as needed.

1.8 Update shipping toolchain to GNU C/C++ (GCC) 10.3

We have updated the GCC toolchain we include with our software to version 10.3. For most users, there should be no impact. However, if you are using the BTSDK, see the backward compatibility issue under Design Impact.

1.9 External memory via SFDP

We have updated openOCD to support external serial memory flashing of PSoC™ 6 MCUs via the Serial Flash Discoverable Parameters (SFDP) standard to query the attached flash memory at runtime to determine how to communicate with the device, as well as get memory-specific data directly from the memory instead of configuring it in the QSPI Configurator.

1.10 Eclipse IDE Improvements

We have made a couple updates to the Eclipse IDE included with our software, including a Terminal view and an Import Application shortcut.

1.10.1 Integrated Terminal

The new Terminal view in the Eclipse IDE console let’s you access a command line terminal directly in the IDE. By default, the terminal uses your login shell on Linux and macOS, or the “modus-shell” Cygwin bash shell provided with your ModusToolbox™ tools installation on Windows. You can specify a different shell from Window > Preferences > ModusToolbox™ Tools.


1.10.2 Import Application shortcut

In the Quick Panel, there is now a shortcut to the ModusToolbox™ application import option. This shortcut bypasses the standard Eclipse Import tool to make importing and application easier and more straight-forward.


1.11 Improved custom BSP process

We have updated the implementation of .mtbx files to provide better custom BSP support. Details for creating a

custom BSP are provided in the ModusToolbox™ user guide. The main difference is that the make

import_deps command is obsolete and no longer required. There is no issue with backward compatibility

with previous releases.

1.12 Configurator updates

This release includes the following updates:

  • Update EZ-PD™ Configurator from Beta to Production. The version provides multi-instance support.

  • Update LIN Configurator from Beta to Production. This version provides multi-instance support, plus support to import LDF files format and import/export for NCF format.

  • Update CAPSENSE™ Configurator and Tuner to support major version of CAPSENSE™ middleware and new devices.

  • Update SegLCD Configurator due to backend changes.

  • Update “Secure Policy” Configurator to configure the Scratch region address and size.

  • Update USB Configurator to support PMG1 devices.

  • Update Machine Learning (ML) Configurator to support ML 1.2, as well as to add Undo/Redo commands, Optimization drop-down, and support for Validate on Target.

  • Update Device Configurator, Smart I/O, and cfg-backend-cli Performance improvements. See also Design impact section.

2. What’s included

This release includes the following tools and versions:

Tool Name

Current Release

Previous Release (Patch)




2.30 (2.40)


Configurator & Tuner



Configurator Backend CLI







1.0 (no change)









Device Firmware Update (DFU) Host Tool



Eclipse IDE for








Firmware Loader (fw-loader)






GNU make Build System



1.2.0 (1.5.0)


11.0 (no change)





Library Manager






N/A (1.0)




1.0 (1.10)

ML core tools and inference regression application


1.0 (1.1.0)


1.3.0 (Windows)

1.2.0 (Linux/macOS) (no change)

1.2.0 (Windows)

1.2.0 (Linux/macOS)

OpenOCD (ModusTool box™- specific)



Project Creator



Proxy Helper



Python (for Windows)







“Secure Policy”




Segment LCD




Smart I/O








2.1 Supported tool chains

The GCC Arm Embedded toolchain GCC 10.3 is installed with the ModusToolbox™ software. This toolchain has no use restrictions and does not require license activation (it is distributed under the terms of the GNU Public License).

Although not installed with ModusToolbox™ software, the build system also supports these tool chains for most applicationsand devices (see the application file for applicable support):

  • Arm compiler v6.11 (Windows and Linux hosts)

  • IAR Embedded Workbench v8.32 minimum (Windows only)

2.2 Supported boards

The boards available for use varies with different releases of BSPs and libraries on GitHub. You can see the current list of BSPs in the Project Creator tool using the default manifest URL:



Additional boards will be made available on an ongoing basis.

2.3 Open source

Portions of this software package are licensed under free and/or open source licenses such as the GNU General Public License. Such free and/or open source software is subject to the applicable license agreement and not our license agreement covering this software package. The applicable license agreements are available online:

3. Design impact

This section includes issues that might impact current designs.

3.1 New device-configurator-cli executable

In the ModusToolbox™ 2.4 release, there is a new device-configurator-cli executable (in <install-path>/ModusToolbox/tools_2.4/device-configurator-3.10.0) that replaces the cfg-backend-cli executable

The cfg-backend-cli executable still exists in the ModusToolbox™ 2.4 release as a wrapper that launches the device-configurator-cli executable. The cfg-backend-cli executable will not be available in the ModusToolbox™ 3.0 release or thereafter.

3.2 GCC 10 backward-compatibility issue for BTSDK

As noted under Primary changes, this release has been updated to use GCC version 10.3. This version of GCC defaults to using the -fno-common compiler setting. The previous version of GCC defaulted to -fcommon.

If you have an existing application that was created using BTSDK versions prior to BTSDK 3.1, upgrading to the ModusToolbox™ 2.4 release might cause the application build to produce “multiple definition” linker errors. All such issues are addressed in BTSDK 3.1 and greater, so this issue only applies to projects created in earlier versions.

Use these instructions to resolve the errors:

  1. Identify the CSP directory that your device uses. Use the following command line executed from a modus-shell window from the top-level application folder:

$ make get_app_info | grep CY_BASELIB_PATH

This gives the following output for example:


  1. Inside the CSP directory identified in step 1, edit the make/recipe/ file to add -fcommon to the CY_CORE_CFLAGS setting. For example, change the following:





by adding -fcommon, as follows:






4. Known issues/limitations

This section lists the known issues/limitations of this release:

4.1 Installation



On Windows 7 machines, you may see a message indicating that some drivers or prerequisites were not installed.

This message can be safely ignored.

After updating from macOS Mojave to Big Sur, the previously installed version of ModusToolbox™ reports various errors in the Eclipse IDE and other tools.

This issue is likely caused by xcode not being updated properly.

Re-install ModusToolbox™ 2.4. See the installation guide as needed.

Re-install x-code; run:

xcode-select –install

On common Linux distributions, the serial UART ports (usually /dev/ttySx or /dev/ttyUSBx devices) belong to the root user and to the dialout and plugdev groups. Standard users are not allowed to access these devices.

An easy way to allow the current user access to the Linux machine’s serial ports is by adding the user to the dialout or plugdev group. This can be done using the following command:

$sudo usermod -a -G dialout,plugdev $USER


For this command to take effect, the user must log out and then log back in.

4.2 Project Creator



When creating projects that use git submodules, you may see red text noting that the submodules are being cloned. Normally red text indicates errors; however, in this case the messages are just an anomaly.

None. These messages can be safely ignored.

Using the Project Creator Target IDE feature, the application that was exported to a third-party IDE doesn’t work in that IDE.

There are limitations to the export process. For example, IAR and µVision are not supported in macOS or Linux. In other cases, you need to update configuration settings in the third-party IDE. Refer to the “Export to IDEs” chapter in the Mo dusToolbox™ user g uide for more details.

In the default case, project creation and library updates require internet access. In some cases, using a VPN may adversely affect the time required for these operations due to a delay in DNS server response times for external IP addresses such as

If you experience issues such as this, project creation and library update times can be improved by disabling the VPN connection during those during operations.

To determine if this is an issue for you, open a terminal window and enter “nslookup”. If the response is not immediate, then you may benefit from disabling your VPN connection.

When trying to create a new project you may not see any BSPs or a pplications to select, as well as the following error message:

Unable to open file at http: //gi fineon/mtb- super- manifest/ra w/v2.X/mtb- super-manif est-fv2.xml

Some boards and a pplications may be missing. Check the console for a detailed error message.

Verify that you have a network connection and see the instructions in the In stallation problem section above concerning proxy settings.

This may also be caused by your work environment not having access to GitHub. Refer to KBA2 30953 for details on how to work around this problem.

4.3 Proxy



When trying to create a new project, you may see the following error message:

Unable to open file at http: //github .com/Infineon/mtb- super-manif est/raw/v2.X/mtb-s uper-manifest.xml.

Some boards and apps may be missing. Check the logfile for a detailed error message.

This can happen if you are behind a firewall and do not have your proxy settings configured. You must set your HTTP_PROXY and HTTPS_PROXY environment variables or use the Proxy Helper tool from the Settings menu. You can also find it in:

<install_path>/ ModusToolbox/ tools_2.4 /proxy-helper

In some cases, incorrect proxy settings in the Project Creator or Library Manager tool can prevent the proxy server settings from being edited to correct values.

Run the Proxy Helper tool from the Settings menu to reset the proxy mode to direct. The tool is also located in:

<install_path>/ ModusToolbox/ tools_2.4 /proxy-helper

For example:

./proxy-helper –config set mode=direct




An XMC™ MCU project build fails for the following circumstances:

  • Using the Linux OS, and

  • Settting the toolchain to IAR.

IAR support is not available for XMC™ MCUs in Linux by default. To use the IAR toolchain in Linux:

1. Obtain the appropriate linker script from IAR and copy it to your ModusToolbox™ application directory.

2. Edit the application Makefile to use the appropriate linker script.

A legacy BTSDK project (version 2.7.1 or older) fails to build in ModusToolbox™ 2.4.

See KBA234113.

When using VS Code with Cortex-Debug v0.4.5, some operations may not work on Linux and macOS via FTDI, KitProg3, or MiniProg4 programmers, with messages indicating that the USB device is busy. The J-Link probe is not impacted.

This can happen for various operations (Program, Erase, Launch, Attach) when executed a second time, due to Cortex- Debug not terminating the OpenOCD process.

Manually terminate the OpenOCD process and switch versions of Cortex-Debug from v0.4.5 to v0.4.4, v0.4.6, or later.

This issue is tracked on GitHub:

When launching a debug session, execution does not halt at main() on PSoC™ 64 devices with J-Link/SEGGER debug tools. This may happen on virtual or slow PCs, or when the communication interface (SWD, JTAG) speed =< 100k Hz.

Add small delay at the very beginning of Reset_Handler so the J-Link will have enough time to halt the CPU before startung execution of the application. A delay of 100 ms should be sufficient in most cases. Example of a simple delay loop in Reset_Handler:

/* 1<<22 corresponds to 4M so loop should take approx. 12M cycles */

mov r0, #1

lsl r0, #22


subs r0, #1

bne debug_delay

bl Cy_OnResetUser

cpsid i …

When trying to debug a FreeRTOS AWS project in the Eclipse IDE when connected via the MiniProg4 probe, you might see the following messages the ModusToolbox™ Console:

“Failed to write memory at <address>”

“Error: Write failure during wipe of variable: uxT opUsedPriority at <address>”

These messages can be safely ignored.

Debugging/ programming does not work on macOS machines based on M1 processors with J-Link probes.

Use kits with onboard FTDI for programm ing/debugging.

Sometimes the J-Link ‘Program’ configuration for CYW 43907/CYW53907 devices may fail if executed after an ‘Erase’ operation on macOS/Linux. This is caused by an issue in the J-Link script used for these devices.

Turn the devices’ power supply off and on, and then try the ‘Program’ configuration again.

Programming the S25FS512S external memory device mounted on the CYW9P62 S1-43012EVB-01 kit might not work if SFDP auto-detection is selected in the QSPI Configurator. This is caused by corrupted SFDP table in this memory.

Select “S25FS512S” instead of “Auto detect SFDP” for the memory slot in the QSPI Configurator.

After programming a PSoC™ 4 device, the following message displays:

Polling target psoc4.cpu failed, try to reexamine

None. You can safely ignore this message. This might occur if the SWD is disconnected after the reset.

The ModusToolbox™ build process stops at some points, such as during a uto-discovery, and it takes longer than other times.

This is likely due to anti-virus software scanning various ModusToolbox™ directories. To resolve this, change your anti-virus settings to exclude the following as appropriate for your installation (where ~ is your home directory):

  • Installation directory (e.g., ~/ ModusToolbox/)

  • Settings directory (e.g., ~/. modustoolbox/)

  • Applications directories (e.g., ~/MyExamples/)

  • Eclipse IDE workspace directory (e.g., ~/mtw/)

While debugging an application built with the GCC toolchain, some breakpoints cannot be reached as the application code referenced by the breakpoints is inlined.


The GDB behavior described above has no functional impact on the application execution.

Switch the optimization level from -Og (default in the CONFIG=Debug mode) to -O0, by editing the application Makefile:



Changing the optimization flag to -O0 may impact the application behavior or memory usage. We recommend disabling the compiler optimizations only for debugging purposes.

PSoC 64 Secure MCUs do not support the programming and debugging via JTAG interface. It is because of the specifics of PSoC 64 MCUs - JTAG pins are configured after unpredictable amount of time after what causes a lot of warnings during programming via JTAG.

Use SWD interface with PSoC 64 Secure MCUs in Eclipse and VS Code IDEs

Unable to acquire PSoC 4 target with J-Link probe if target is in PROTECTED state. J-Link probe does not support device acquisition in Test Mode. This prevents invocation of SROM API making it impossible to re- program or erase the chip in PROTECTED state.

The workaround is to unprotect/erase the chip using MiniProg4 or KitProg3 probe.

A “Failed to read memory at <address>” message may appear in “Memory View” of the Eclipse IDE when connected via the MiniProg4 probe and try to read memory from invalid address.

You can safely ignore this error

In VS Code, usability behavior might be observed after a Restart operation with PSoC 64 Secure MCUs. For example, “Failed to launch OpenOCD GDB Server: Timeout” error may appear when KitProg3 Attach launch config is running, or if debug session is broken with J- Link.

No reliable workaround

In VS Code, “Exception has occurred” error might appear when you execute Attach launch configuration. Such errors started to be visible in VS Code - 1.53.2.

You can safely ignore this error.

In VS Code, “Failed to launch undefined GDB Server: Timeout.” error might appear if to launch Debug J-Link launch configuration with KIT_XMC47_RELAX_V1 after several ‘step over’, ‘step into’ operations during the previous Debug session what was stopped.

Re-run the launch configuration again after failure

In VS Code, the J-Link launch configuration does not stop at Reset_Handler after ‘Restart’, but at some other line of code. For PSoC 6 MCUs, this is associated with any “monitor” command in GDB. For example, if you press the Restart button, the Cortex-Debug plugin sends “monitor halt” and “monitor reset” commands to the GDB causing GDB to go out-of-sync with the target.

GDB does not know what the “monitor xxx” command does. It does not expect that “monitor reset” will change the state of the target.

For XMC and PSoC 4 MCUs, such behavior is caused by the using “Cortex M0” target for PSoC 4 and “Cortex- M4” for XMC devices as the workaround for other issue with Attach in SEGGER SW.

Step through code to enter the Reset_Handler.

When attempting to Program/Debug with Miniprog4 or J-Link probes in JTAG mode, the tool displays errors similar to the following:


These errors are likely caused by the device being in sleep mode. Open the Device Configurator, and set the System Idle Power Mode setting to ‘Active’ to turn off DeepSleep mode. JTAG is not available in sleep mode. Alternately, use SWD to acquire the target, and then switch to JTAG.

If an application includes multiple BSPs that span major version numbers (for example, v1.x and v2.x) as local dependencies, there will be build conflicts. This is because of changes in the names of the BSP’s dependencies.

There are two options:

  1. The application can be updated to use the new MTB flow with the BSPs (and dependencies) marked as shared.

  2. All local BSPs within a application must have the same major version number. Once the application is updated to only have a single major version of the BSP, any of the dependent libraries that were pulled down by the removed BSP version need to be removed from the application. This includes removing any .lib or .mtb files. The problematic dependencies that must be removed include the following:

    1.x BSP dependencies: psoc6pdl, psoc6hal

    2.x BSP dependencies: mtb-pdl, mtb-hal

KitProg3 and J-Link launch configurations do not work when you change the build configuration from Debug to Release or vice-versa. This applies to the Eclipse IDE for ModusToolbox and Visual Studio (VS) Code.

Launch configurations contain the path to the executable, and that changes for each build configuration.

After you change from Debug to Release or vice-versa, click the “Generate Launches” command in the Quick Panel.

You can alternately run the following command to create new launch configurations:

  • make eclipse for Eclipse IDE for ModusToolbox

  • make vscode for VS Code

    Be aware that this option overwrites any changes you may have made to the configurations.

On macOS for a PSoC 64 or PSoC 6A project, using the Eclipse IDE for ModusToolbox, the “Attach” launch configuration fails every second time it is used:

  • for an RTOS-based project

  • if “Attach” is launched when the target is halted on breakpoint

Reset the device each time you run the “Attach” configuration.

For the Arm Cortex CM4 core, some code in main() executes before the debugger stops at start of main(). This means that some code executes twice; once before the debugger stops execution, and again after the debugger resets the program counter to the start of main() and you start debugging.

If you observe this issue, and it affects your application, put a delay loop at the start of main() to allow time for debugging subsystem in itialization. The following code tests for the presence of the debugger before entering the delay loop:

int main(void)


/* If an active debugger is detected, give it some time to execute SYSRESETREQ

* otherwise, the application runs before the debugger is fully operational */

if (CoreDebug->DHCSR & Core Debug_DHCSR_C_DEBUGEN_Msk)




See KB A231071 for details.

Junk characters might be observed in a UART terminal during programming of the connected kit or after programming is completed.

Clear UART buffers after programming is completed.

On some occasions, the Eclipse IDE will fail to run launch configurations with various errors, such as:

“XXX has encountered a problem. Debug session already started. Terminate the first one before restarting”

Depending on the steps taken prior to launching a configuration, there are several reasons this may occur. The easiest way to resolve the issue is to restart Eclipse.

There is a programming error for Cypress platforms that connect via FTDI on macOS Catalina. The boards include:

  • CY W920819EVB-02

  • CY W920820EVB-02

  • CYW9207 19B2Q40EVB-01

  • CYW9 20721B2EVK-01

  • CYW9 20721B2EVK-02

  • CYW9 20721B2EVK-03

  • CY W989820EVB-01

  • CYW 920706WCDEVAL

  • CYW92 0735Q60EVB-01

This only happens in macOS Catalina 10.15.5 because of a serial port detection error. The macOS Catalina FTDI driver is missing the necessary device identification information.

To resolve this issue, update to macOS Catalina 10.15.6 or newer.

A “JTAG-DP STICKY ERROR” message may appear in the IDE when connected via the JTAG interface of a MiniProg4 probe in CMSIS-DAP HID mode.

You can safely ignore this error, or switch the MiniProg4 to CMSIS-DAP bulk mode.

JTAG performance on MiniProg4 may be significantly slower than SWD.

There is no workaround except using the SWD interface if JTAG performance is not acceptable.

You must manually reset after programming PSoC 6 kits when using GDB SEGGER + Jlink + JTAG interface.

Update each of the following Launch Configurations under the Debugger tab. In the Device Name field, delete the “_tm” suffix.


  • “<app-name> Erase (JLink)”

  • “<app-name> Program (JLink)”

Starting from KitProg3 v2.10, when KitProg3 is in CMSIS-DAP Bulk mode, it is not possible to debug and use USB-I2C/SPI bridging (for example, in the CapSense Tuner, Bridge Control Panel) at the same time. This affects Windows OS only. It does not affect Linux or macOS users.

If you would like to use debug and USB-I2C/SPI bridging at the same time, there are two possible workarounds:

  • If performance for programming and debug is not critical, switch KitProg3 to CMSIS-DAP HID mode via the fw-loader utility. Firmware Loader is installed with ModusToolbox software, and is available separately on GitHub.

  • If you need faster performance for programming and debug, use the onboard KitProg3 for programming purposes and MiniProg4 for bridging purposes or vice versa. Both devices can be in CMSIS-DAP bulk mode.

    Details are in KBA23 1025.

Starting from KitProg3 v2.10, in some cases Windows 7 does not recognize the KitProg3 bridge. So the USB-I2C/SPI bridge devices are not available in either CMSIS-DAP HID or CMSIS-DAP bulk mode.

Install a digitally signed driver manually from the Windows Update Catalog. Follow steps from KBA 231026.

In Linux OS, with KitProg3 in CMSIS-DAP HID mode, a debug session in ModusToolbox can be destroyed if you use the Firmware Loader –device-list command while debugging. This is limitation of hidapi library used on Linux. MacOS and Windows OSs are not impacted.

If you have a debug session running, don’t use the firmware loade tool.

KitProg3 v2.10 or later is installed as part of the ModusToolbox 2.2 or later tools package. This version of KitProg3 will not work with PSoC Creator 4.3 or PSoC Programmer 3.28.7.

If you updated your kit to KitProg3 v2.10 and wish to use the kit with PSoC Creator 4.3 and PSoC Programmer 3.28.7, get a previous version of fw-loader (with an earlier version of KitProg3) and update the kit. The fw- loader tool is available here:

github. com/Infineon/Firmware- loader

If this is not urgent, you can wait for a newer PSoC Programmer version with support for KitProg3 v2.10, expected soon.

4.5 Eclipse IDE



In the Eclipse IDE you can open multiple, separate Terminals (for example Terminal, Terminal 1, Terminal 2, etc.). However, if you close the original, primary Terminal, the tool does not allow you to open any new separate Terminals. Instead new Terminals open as sub-tabs within the selected Terminal.


To fix this issue, reset the Perspective using Window > Perspective > Reset Perspective.

Sometimes when importing an application using the Eclipse IDE, a message displays stating the following: Unable to add the shared library project at “<workspace_location>/mtb_shared” to the workspace. That project is for reference only; functionality is not affected.

This message can be safely ignored.

For some macOS machines running on M1 processors, the Eclipse IDE may fail to start with a message such as:

ModusToolbox quit unexpectedly.

The message details also state that the “attachment of code signature supplement failed.”

This problem occurs any time that Eclipse was last opened in an empty workspace prior to a reboot. After the reboot, the application fails to start. Run the following command in the /Applications/ModusToolbox/ ide_x.y/ directory:

xattr -dr *


You may have to adjust the path if you installed ModusToolbox™ in a non-default location. When complete, launch the Eclipse IDE again. This workaround works for all cases so far discovered

In the updated Eclipse IDE for this release, the News tab has been removed. However, it may appear if you open an older release application in the updated IDE. If so, it may contain an error message like:

“Unable to access the news site. Please check your internet connection then click on the button below to try again.”

The web page that provided content to the News tab is no longer maintained. You can safely ignore the message about site access.

If you want to remove the News tab from this workspace, select Window > Perspective > Reset Perspective…

Some BTSDK projects imported in the Eclipse IDE on macOS and Linux fail to build.

If an existing project is exported from Eclipse using File > Export > General > Archive File, and then the resultant .zip file is imported into another workspace using File > Import > General > Existing Projects into W orkspace, any files that had the executable permission bit set in the original project will have the executable bit stripped in the new imported project.

This can vary from project to project, but can include executables necessary to the build process, which can cause the imported project to fail to build, or other possible side effects depending on what executables may be in the archive.

Identify what files were executable in the original project ( pre-export) and then manually fix them in the new imported project with the following terminal command:

chmod +x <filename>

For projects that use external resources located outside of the application folder root (such as mtb_shared, wiced_btsdk, or 3rd-party libraries), some IDE code browsing and analysis features (such as resolving includes or opening object declarations for objects and headers located in those external resources) may not be usable or show unresolved includes immediately after project creation.

These will be resolved after building the project, as the IDE parses the output messages from the build to find paths to those resources.

On macOS Catalina, some IDE GUI windows/elements do not display correctly in some cases.

Resize the window or scroll to fix the display problem. In some cases, use the Refresh option.

We are investigating these issues and will address them in a future release.

If you delete the shared library directory (named mtb_shared, by default) from disk and then regenerate it using make getlibs or the Library Manager, the directory will not be restored properly for use in the Eclipse IDE. This is because several files required by the Eclipse IDE are not restored as they were when the application was created.


You can delete the mtb_shared directory at any time because it can be recreated. You might do this when sharing the application, for example. The shared library directory only contains files that are already controlled and versioned, so you should NOT check it into a revision control system.

After regenerating the mtb_shared directory and assorted libraries, open the Eclipse IDE and follow these steps:

  1. Delete the mtb_shared folder shown in the IDE Project Explorer. Do NOT select the check box “Delete project contents on disk” (if you do, you will have to regenerate it again).

  2. Select File > Import > C/C++ > Existing Code as Makefile Project and click Next >.


  1. Under Existing Code Location, click Browse…, navigate to the application’s root directory, select the mtb_shared folder, and click Select Folder.

  2. Under Toolchain for Indexer Settings, select ARM Cross GCC.

  3. Click Finish.

  1. After the import completes, build the application.

Some applications when imported into the Eclipse IDE from Mbed OS fail to build with an error, such as: cc1.exe fatal error: .mbed_config.h: No such file or directory

This happens because the application is generating a path to the mbed_config.h header file that make build system cannot find. Fix this by removing the relative path ‘.’ in the makefile. Change this:

ASM_FLAGS += -include

ASM_FLAGS += .mbed_config.h

To this:

ASM_FLAGS += -include

ASM_FLAGS += mbed_config.h

On Windows, when building a project and/or programming the device, the IDE reports one or more errors similar to the following:

*** fatal error - cygheap base mismatch detected - 0x18032C408/0x18032D408

This occurs because you likely have multiple versions of Cygwin in your build environment path. The IDE uses a version of Cygwin in the ModusToolbox installation directory. Remove the instance of “C:cygwin64bin” from your path.

Markdown (*.md) files do not render correctly in the IDE. For example, tables do not show rows and columns. Also, the IDE may show an error for the file such as:

“Cannot resolve element with id ‘figure-1’”.

This is a known issue with viewing markdown files in Eclipse. Various rendering errors can be safely ignored. We recommends using an external editor, such as Visual Studio Code or Typora to view markdown files.

When creating a new application, the IDE attempts to open any found files. Occasionally (and randomly), some of these files are opened in an external text editor instead of in the IDE.

This appears to be an Eclipse bug with no workaround. However, since *.md files do not render well in Eclipse (as noted above), you should use an external editor, such as Visual Studio Code or Typora, and set that editor as the default.

Sometimes, the Eclipse “egit” plugin locks directories. This prevents the Library Manager from removing BSPs/libraries from these locked directories. When this happens, you will see an error message in the Library Manager console indicating that permission is denied for removing a particular directory.

Before running the Library Manager from the Eclipse IDE, right-click on the project and select Team > Disconnect. When you are done with the Library Manager, go to Team > Share Project and select the correct project to reconnect.


Various projects may be set up differently, and the process to use the Team options will vary as well.

The IDE Project >Build Configurations > Active menu item to set Debug or Release mode is non-functional. This is due to the project’s Makefile.

To set Debug or Release mode, edit the project’s Makefile, which contains the following:

# Default build configuration. Options include:


# Debug – build with minimal optimizations, focus on debugging.

# Release – build with full optimizations


If you include external folders/files in your application, the Eclipse IDE will occasionally unselect your application project in the Project Explorer. However, it will leave the Launch section populated with links in the Quick Panel. Using those Launch links may result in a reported error of “Could not resolve cy_prj_path.”

To resolve this, click on the appropriate project for your application in the Project Explorer, and then click on the Launch link again.

4.6 Library Manager



Issue using a VPN.

See Project Creator.

After running the Library Manager, the files shown in the Eclipse IDE Project Explorer are not updated.

To see the updated files, click on the project in the IDE Project Explorer and press [F5] to refresh the Eclipse view.

Opening multiple instances of the Library Manager at the same time for the same application could cause confusion and indeterminate states in applications.

Do not open multiple instances of the Library Manager for the same application. This issue will be addressed in a later release.

Sometimes when you click Update in the Library Manager, the tool will begin to process your request and then appear to freeze.

Terminate the Library Manager and relaunch it. This issue will be addressed in a future release.

When you remove a library item, the Library Manager deletes the associated directory from the “libraries” directory (typically this is called “libs”). On Windows, if there are any processes that have a lock on that directory, or a file in that directory, the directory removal will not work completely. Th Library Manage will remove most of the directory contents and will also mark the library item as removed.

To remove the library completely, you must release the lock on the folder or file, and then manually delete the directory. The steps to release the lock depend entirely on the process that is holding the lock. Common scenarios include:

  • A command-line prompt is in that directory. In this case, “cd” to a different directory.

  • A text editor has a file from that directory open. In this case, close the file in the text editor. Depending on the text editor, you may have to exit the entire text editor.

  • The Eclipse git “egit” plugin has a lock on the folder. In this case, exit and restart the ModusToolbox Eclipse IDE.

In all cases, once the lock is removed you must remove the associated directory from the libraries directory before the Library Manager will be able to work with that particular library again.

4.7 Device Configurator



On macOS machines, there is an issue with the the Device Configurator Create Design dialog where you cannot select the desired MCU device from the list with the mouse. When you type in a partial part number, a drop-down menu displays various part numbers that match the value you typed. However, you cannot select the one you want with the mouse.

To select the desired device, either type the complete part number in the field or use the arrow keys on the keyboard.

This is a known Qt bug (third-party company), which has been reported.

4.8 CAPSENSE™ Tuner



If using the UART communication interface, a low packet- transferring rate may cause the CapSense Tuner to disconnect due to a data-reading timeout error.

You can resolve this using either of these solutions:

  • Increase the UART communication baud rate.

  • Increase the value of the uartSingleReadTimeout parameter available in the tuner INI file.

You can find the tuner INI file as follows:

  • Windows:

    <user_home>/AppDat a/Roaming/Cypress Semiconductor Corporation/CapSense Tuner.ini

  • Linux:

    /home/<user_home >/.config/Cypress Semiconductor Corporation/CapSense Tuner.ini

  • macOS:

    /Users/<user_hom e>/.config/Cypress *Semiconductor Corporation/CapSense Tuner.ini

4.9 Machine Learning



The ml-coretools model converter fails on macOS machines running on M1 processors.

There is no workaround for this problem. We currently do not support machine learning on M1-based macOS machines.

On macOS, maching learning validation on target fails with a message similar to the following:

/Applicatio ns/ModusToolbox/tools _2.4/ml-coretools/ml- coretools-streaming failed (255)

This error is caused by using a hex that was not generatated by a macOS machine. Rebuild the hex using macOS and retry the operation.

Large datasets >10 MB will take > 2 minutes to complete. Also, the system may run out of memory causing the conversion process to fail.

Use datasets smaller than 10 MB as much as possible, or use a computer with more memory.

4.10 Documentation



Various documents included with the release may contain incomplete information, or may not contain up- to-date screen captures or information.

New versions of documents, including this release notes document, may be available online at: environment

Revision history



Description of Change



Initial Release.



Updates for Production.



Updates for version 1.1.



Updates for version 2.0.



Copyright text for FreeType.



Added known issues.



Updates for version 2.1.



Adding Known Issues for version 2.1; fixed Rev. in footer.



Adding known Issue for QSPI Configurator.



Removed fixed known issue.



Added known issues for Programming/Debugging.



Updates for version 2.2.



Added several known issues.



Added issue about programming in DeepSleep mode.



Added issue about Eclipse IDE and macOS Big Sur.



Added issued for no access to GitHub.



Updates for version 2.3. Updated text for M1 workaround. Added issue about importing into




Updated text for known issue about build failing in Eclipse for imported projects.



Added issue for PSoC™ 4 error message that can be ignored.



Updates for version 2.4.



Updated the version of modus-shell for Windows to 1.3.0.

Added build issues for legacy BTSDK projects, as well as XMC™ projects using Linux and IAR.