Introduction
This chapter provides an overview of the ModusToolbox™ software environment, which provides support for many types of devices and ecosystems. The major headings in this chapter include:
What is ModusToolbox software?
ModusToolbox™ software is a modern, extensible development environment supporting a wide range of Infineon microcontroller devices. It provides a flexible set of tools and a diverse, high-quality collection of application-focused software. These include configuration tools, low-level drivers, libraries, and operating system support, most of which are compatible with Linux-, macOS-, and Windows-hosted environments.
The following diagram shows a very high-level view of what is available as part of ModusToolbox™ software. This is not a comprehensive list. It merely conveys the idea that there are multiple resources available to you.
ModusToolbox™ software does not include proprietary tools or custom build environments. This means you choose your compiler, your IDE, your RTOS, and your ecosystem without compromising usability or access to our industry-leading CAPSENSE™, AIROC™ Wi-Fi and Bluetooth®, security, and various other features.
Another important aspect of the ModusToolbox™ software is that each product is versioned. This ensures that each product can be updated on an ongoing basis, but it also allows you to lock down specific versions of the tools for your specific environment. See Product versioning for more details.
Tools package
The ModusToolbox™ tools package provides you with all the desktop products needed to build sophisticated, low-power embedded, connected and IoT applications. The tools enable you to create new applications (Project Creator), add or update software components (Library Manager), set up peripherals and middleware (Configurators), program and debug (OpenOCD and Device Firmware Updater), and compile (GNU C compiler).
Infineon Technologies understands that you want to pick and choose the tools and products to use, merge them into your own flows, and develop applications in ways we cannot predict. That's why ModusToolbox™ software is not a monolithic, proprietary software tool that dictates the use of any particular IDE.
The ModusToolbox™ tools package installer provides required and optional core resources for any application. This section provides an overview of the available resources:
The installer does not include Code examples or Libraries (middleware), but it does provide the tools to access them.
Directory structure
Refer to the ModusToolbox™ tools package installation guide for information about installing ModusToolbox™ software. Once it is installed, the various ModusToolbox™ top-level directories are organized as follows:
This image shows ModusToolbox™ version 3.7 installed. Your installation may include more than one ModusToolbox™ version. Refer to the Product versioning section for more details.
The "ModusToolbox" directory contains the following subdirectories for version 3.7:
docs_[version]
This is the top-level documentation directory. It contains various top-level documents and the doc_landing.html file with links to documents provided as part of ModusToolbox™ software. This file is also available from the Dashboard.
resources_[version]
This directory contains a .json file with details about the version of the tools package. There are also a couple helper files for the icon and launch-tool.
tools_[version]
This contains all the various tools and scripts installed as part of ModusToolbox™ tools package. See Tool descriptions for more information.
Packs
Packs can be installed separately from a tools package release. These packs include additional software and tools for specific features, such as machine learning. If you install a pack, it will create a "packs" subdirectory in the root "ModusToolbox" installation directory. Refer to the pack documentation for specific details about a pack.
To install a pack, use the Setup program or go to https://softwaretools.infineon.com/tools. There will be links to either install the pack directly or download it to install manually. The pack documentation will provide additional instructions and requirements, as needed.
Tool descriptions
The tools_[version] directory includes the following configurators, tools, and utilities:
Configurators
Each configurator is a cross-platform tool that allows you to set configuration options for the corresponding hardware peripheral or library. When you save a configuration, the tool generates the C code and/or a configuration file used to initialize the hardware or library with the desired configuration.
Configurators are independent of each other, but they can be used together to provide flexible configuration options. They can be used stand alone, in conjunction with other configurators, or as part of a complete application. All of them are installed during the ModusToolbox™ installation. Each configurator provides a separate guide, available from the configurator's Help menu.
Configurators perform tasks such as:
- Displaying a user interface for editing parameters
- Setting up connections such as pins and clocks for a peripheral
- Generating code to configure middleware
Some configurators may not be useful for your application.
Configurators store configuration data in an XML data file that provides the desired configuration. Each configurator has a "command line" mode that can regenerate source based on the XML data file. Configurators are divided into two types: BSP Configurators and Library Configurators.
The following diagram shows a high-level view of the configurators that could be used in a typical application.
BSP configurators
BSP configurators configure the hardware on a specific device. This can be a board provided by us, a partner, or a board that you create that is specific to your application. Some of these configurators interact with the design.modus file to store and communicate configuration settings between different configurators. Code generated by a BSP Configurator is stored in a directory named GeneratedSource, which is in the same directory as the design.modus file. This is generally located in the BSP for a given target board. Some of the BSP configurators include:
-
Device Configurator : Set up the system (platform) functions such as pins, interrupts, clocks, and DMA, as well as the basic peripherals, including UART, Timer, etc. Refer to the Device Configurator user guide for more details.
-
CAPSENSE™ Configurator : (Installed separately) Configure CAPSENSE™ hardware, and generate the required firmware. This includes tasks such as mapping pins to sensors and how the sensors are scanned. Refer to the CAPSENSE™ Configurator user guide for more details.
There is also a CAPSENSE™ Tuner to adjust performance and sensitivity of CAPSENSE™ widgets on the board connected to your computer. Refer to the CAPSENSE™ Tuner user guide for more details.
-
QSPI Configurator : Configure external memory and generate the required firmware. This includes defining and configuring what external memories are being communicated with. Refer to the QSPI Configurator user guide for more details.
-
Smart I/O Configurator : Configure the Smart I/O. This includes Chip, I/O, Data Unit, and LUT signals between port pins and the HSIOM. Refer to the Smart I/O Configurator user guide for more details.
-
SegLCD Configurator : Configure LCD displays. This configuration defines a matrix Seg LCD connection and allows you to setup the connections and easily write to the display. Refer to the SegLCD Configurator user guide for more details.
Library configurators
Library configurators support configuring application middleware. Library configurators do not read nor depend on the design.modus file. They generally create data structures to be consumed by software libraries. These data structures are specific to the software library and independent of the hardware. Configuration data is stored in a configurator-specific XML file (for example, *.cybt, *.cyusbdev, etc.). Any source code generated by the configurator is stored in a GeneratedSource directory in the same directory as the XML file. The Library configurators include:
-
Bluetooth® Configurator : Configure Bluetooth® settings. These include options for specifying what services and profiles to use and what features to offer by creating SDP and/or GATT databases in generated code. This configurator supports both PSOC™ MCU and AIROC™ Bluetooth® applications. Refer to the Bluetooth® Configurator user guide for more details.
-
USB Configurator : Configure USB settings and generate the required firmware. This includes options for defining the Device Descriptor and Settings. Refer to the USB Configurator user guide for more details.
-
LIN Configurator : Configure various LIN settings, such as frames and signals, and generate the required firmware. Refer to the LIN Configurator user guide for more details.
-
EZ-PD™ Configurator : Configure the features and parameters of the PDStack middleware for PMG1 family of devices. Refer to the EZ-PD™ Configurator user guide for more details.
Other tools
ModusToolbox™ software includes other tools that provide support for application creation, device firmware updates, and so on. All tools are installed by the ModusToolbox™ tools package installer. With rare exception each tool has a user guide located in the docs directory beside the tool itself. Most user guides are also available online.
| Other tools | Details | Documentation |
|---|---|---|
| dashboard | Top-level starting point to create applications and BSPs. | user guide |
| project-creator | Create a new application. | user guide |
| library-manager | Add and remove libraries and BSPs used in an application; edits the Makefile. | user guide |
| bsp-assistant | Create and update BSPs. | user guide |
| mtb-settings | ModusToolbox™ Settings tool provides one place to configure various settings for all tools, such as proxy settings, content mode, manifest DB location, etc. | user guide is in the tool's docs directory |
| cymcuelftool | Older tool used to merge CM0+ and CM4 application images into a single executable. Typically launched from a post-build script. This tool is not used by most applications. | user guide is in the tool's docs directory |
| dfuh-tool | Communicate with a device that has already been programmed with an application that includes device firmware update capability. Provided as a GUI and a command-line tool. Depending on the ecosystem you target, there may be other over-the-air firmware update tools available. | user guide |
| lcs-manager-cli | Command-line tool to create local content to work without Internet. | user guide |
| mtbarchive | GUI and command-line tool to create a zip file archive of a project to share with colleagues. | The tool creates a readme file. |
Utilities
ModusToolbox™ software includes some additional utilities that are often necessary for application development. In general, you do not use these utilities actively; they are triggered by various user actions.
| Utility | Description |
|---|---|
| airoc-tools | Assorted utilities used for AIROC™ projects. |
| hardware-config-server | Background utility that brokers transactions between (potentially) multiple user-facing applications and a common design file. |
| make | Build system tools. |
| memoryreport | This tool generates memreport.txt and memreport.json files in the build directory that can be used with the Memory Configurator. |
| mtbgetlibs | Background utility that facilitates acquiring libraries. |
| mtbideexport | Background utility used to provide various IDE support. |
| mtblaunch | Background utility used to launch various tools. |
| mtbninja/ninja | Background utility to speed up builds. |
| mtbquery | Background utility used to query databases. |
| mtbsearch | Background utility used to search projects. |
| signcombinemkgen | Signer/combiner make generation tool. |
| SRecord | Collection of tools for manipulating EPROM load files. This is used to merge multi-core application images into a combined programmable HEX image. |
Build system infrastructure
The build system infrastructure is the fundamental resource in ModusToolbox™ software. It serves three primary purposes:
- create an application, update and clone dependencies
- create an executable
- provide debug capabilities
A Makefile defines everything required for your application, including:
- target hardware (board/BSP to use)
- source code and libraries to use for the application
- ModusToolbox™ tools version, as well as compiler toolchain to use
- compiler/assembler/linker flags to control the build
- assorted variables to define things like file and directory locations
The build system automatically discovers all .c, .h, .cpp, .s, .a, .o files in the application directory and subdirectories, and uses them in the application. The Makefile can also discover files outside the application directory. You can add another directory using the SEARCH variable. You can also explicitly list files in the SOURCES and INCLUDES make variables.
Each library used in the application is identified by a .mtb file. This file contains the URL to a git repository, a commit tag, and a variable for where to put the library on disk. For example, a capsense.mtb file might contain the following line:
https://github.com/Infineon/capsense#latest-v2.X#$$ASSET_REPO$$/capsense/latest-v2.X
The build system implements the make getlibs command. This command finds each .mtb file, clones the specified repository, checks out the specified commit, and collects all the files into the specified directory. Typically, the make getlibs command is invoked transparently when you create an application or use the Library Manager, although you can invoke the command directly from a command-line interface. See ModusToolbox™ build system for detailed documentation on the build system infrastructure.
Program and debug support
For programming and debugging, the ModusToolbox™ Programming tools package is available separately, and you should install that package along with the base tools package using the Setup program. You can use various IDEs to program devices and establish a debug session (see Using supported IDEs).
The following tools are part of the Programming tools package and they are no longer installed in the base package "ModusToolbox" tools directory:
| Tool | Description | Documentation |
|---|---|---|
| ModusToolbox™ Programmer | ModusToolbox™ Programmer functionality is built into ModusToolbox™ Software. ModusToolbox™ is also available as a stand-alone tool. | user guide |
| fw-loader | A simple command line tool to identify which version of KitProg is on a kit, and easily switch back and forth between legacy KitProg2 and current KitProg3. | readme.txt file in the tool directory |
| KitProg3 | This tool is managed by fw-loader, it is not available separately. KitProg3 is a low-level communication/debug firmware. Use fw-loader to upgrade your kit to KitProg3, if needed. | user guide |
| OpenOCD | Our specific implementation of OpenOCD is installed with ModusToolbox™ software. | developer's guide |
ModusToolbox™ software supports the Open On-Chip Debugger (OpenOCD) using a GDB server, and supports the J-Link debug probe. See Switch to J-Link for details.
ModusToolbox™ Programmer uses KitProg3 low-level communication firmware. The firmware loader (fw-loader) is a software tool you can use to update KitProg3 firmware, if you need to do so. The fw-loader tool is installed with the ModusToolbox™ Programming tools package. The latest version of the tool is also available separately in a GitHub repository.
Run-time software
ModusToolbox™ software also includes an extensive collection of GitHub-hosted repos comprising Code Examples, BSPs, plus middleware and applications support. We release run-time software on a quarterly "train model" schedule, and access to new or updated libraries typically does not require you to update your ModusToolbox™ installation.
New projects start with one of our many Code example templates that showcase everything from simple peripheral demonstrations to complete application solutions. Every Infineon kit is backed by a comprehensive BSP implementation that simplifies the software interface to the board, enables applications to be re-targeted to new hardware in no time, and can be easily extended to support your custom hardware without the usual porting and integration hassle.
The extensive middleware collection includes an ever-growing set of sensor interfaces, display support, and connectivity-focused libraries. Refer to https://github.com/Infineon/modustoolbox-software#libraries for more details.
Code examples
All current ModusToolbox™ examples can be found using the Project Creator tool. There you will find links to examples for the PSOC™, XMC™, and AIROC™ devices, among others. For most code examples, you can use the Create application from template to create an application and use it directly with ModusToolbox™ tools. For some examples, you will need to follow the directions in the code example repository to instantiate the example. Instructions vary based on the nature of the application and the targeted ecosystem.
In the ModusToolbox™ build infrastructure, any example application that requires a library downloads that library automatically.
You can control the versions of the libraries being downloaded and also their location on disk, and whether they are shared or local to the application. Refer to the Library Manager user guide for more details.
Libraries (middleware)
In addition to the code examples, there are many other parts of ModusToolbox™ that are provided as libraries. These libraries are essential for taking full advantage of the various features of the various devices. When you create a ModusToolbox™ application, the system downloads all the libraries your application needs. See ModusToolbox™ build system chapter to understand how all this works.
All current ModusToolbox™ libraries can be found through the GitHub ModusToolbox™ software page. A ModusToolbox™ application can use different libraries based on the Active BSP. In general, there are several categories of libraries. Each library is delivered in its own repository, complete with documentation.
Common library types:
Most BSPs have some form of the following types of libraries:
- Abstraction Layers – This is usually the RTOS Abstraction Layer.
- Base Libraries – These are core libraries, such as core-lib and core-make.
- Board Utilities – These are board-specific utilities, such as display support or BTSpy.
- MCU Middleware – These include MCU-specific libraries such as freeRTOS or Clib support.
AIROC Bluetooth Libraries:
For the AIROC™ Bluetooth® BSPs, there specific libraries that do not apply to any other BSPs, including:
- BTSDK Chip Libraries
- BTSDK Core Support
- BTSDK Shared Source Libraries
- BTSDK Utilities and Host/Peer Apps
BSP-specific base libraries:
BSP-specific libraries include the following:
-
PSOC™ Edge (mtb-dsl-pse8xxgp)
-
PSOC™ Control, PSOC™ 6, AIROC™ CYW20829, XMC7xxxx, TRAVEO™ II (mtb-hal-cat1, mtb-pdl-cat1, recipe-make-cat1a, cat1b, etc.)
-
PSOC™ 4 and PMG devices (mtb-pdl-cat2, recipe-make-cat2)
-
XMC™ Industrial MCUs (1000 and 4000) (recipe-make-cat3, mtb-xmclib-cat3)
-
AIROC™ CYW43907 and CYW54907 (mtb-hal-cat4, recipe-make-cat4)
-
AIROC™ CYW55513/CYW55913 (mtb-hal-cat5, mtb-pdl-cat5, recipe-make-cat5)
Device database (device-db)
The device-db consists of a set of devices, known as marketing part numbers (MPNs), distributed in a set of hierarchical directories. Each MPN contains a base view describing the basic characteristics of the device and additional views as defined by applications that use the device-db.
The most current version of device-db is included in new applications, and the device-db version is locked to contain only those MPNs available at that time. If, at a later date, you want to update the MPN to a newer device not available in the device-db, you will have to update it using the Library Manager.
The device-db is dependent on the application's PDL. In some cases when you need to update the device-db, you may also need to update the PDL. We recommend updating the PDL version as minimally as possible required by the device-db, because the PDL may contain many more changes than your application requires. Refer to the device-db README.md and RELEASE.md file for details.
BSPs
The BSP is a central feature of ModusToolbox™ software. The BSP specifies several critical items for the application, including:
- hardware configuration files for the device (for example, design.modus )
- start-up code and linker files for the device
- other libraries that are required to support a kit
BSPs are aligned with our development/evaluation kits; they provide files for basic device functionality. A BSP typically has a design.modus file that configures clocks and other board-specific capabilities. That file is used by the ModusToolbox™ configurators. A BSP also includes the required device support code for the device on the board. You can modify the configuration to suit your application.
Supported devices
ModusToolbox™ software supports development on the following Arm® Cortex-M MCUs.
- PSOC™ Edge
- PSOC™ Control
- PSOC™ 4 (See AN79953: Getting Started with PSOC™ 4 for the supported PSOC™ 4 devices.)
- PSOC™ 6
- AIROC™ Wi-Fi and Bluetooth® chips
- TRAVEO™
- USB device controller
- PMG1 USB-C Power Delivery
- Wireless Charging devices
- XMC™ Industrial
BSP releases
We release BSPs independently of ModusToolbox™ software as a whole. This search link finds all currently available BSPs on our GitHub site.
The search results include links to each repository, named TARGET_kitnumber. For example, you will find links to repositories like TARGET_KIT_PSC3M5_CC2. Each repository provides links to relevant documentation. The following links use this BSP as an example. Each BSP has its own documentation. The information provided varies, but typically includes one or more of:
- an API reference for the BSP
- the BSP overview
- a link to the associated kit page with kit-specific documentation
A BSP is specific to a board and the device on that board. For custom development, you can create or modify a BSP for your device.
Product versioning
ModusToolbox™ products include tools and firmware that can be used individually, or as a group, to develop connected applications for our devices. We understand that you want to pick and choose the ModusToolbox™ products you use, merge them into your own flows, and develop applications in ways we cannot predict. However, it is important to understand that every tool and library may have more than one version. The tools package that provides the set of tools also has its own version. This section describes how ModusToolbox™ products are versioned.
General philosophy
ModusToolbox™ software is not a monolithic entity. Libraries and tools in the context of ModusToolbox™ are effectively "mini-products" with their own release schedules, upstream dependencies, and downstream dependent assets and applications. We deliver libraries via GitHub, and we deliver tools though the ModusToolbox™ tools package and the ModusToolbox™ Setup program.
All ModusToolbox™ products developed by us follow the standard versioning scheme:
- If there are known backward compatibility breaks, the major version is incremented.
- Minor version changes may introduce new features and functionality, but are "drop-in" compatible.
- Patch version changes address minor defects. They are very low-risk (fix the essential defect without unnecessary complexity).
Code Examples include various libraries automatically. Prior to the ModusToolbox™ 2.3 release, these libraries were typically the latest versions. From the 2.3 release and newer, when you create a new application from a code example, any of the included libraries specified with a "latest-style" tag are converted to the "release-vX.Y.Z" style tag.
If you use the Library Manager to add a library to your project, the tool automatically finds and adds any required dependent libraries. From the 2.3 release and newer using the MTB flow, these dependencies are created using "release-vX.Y.Z" style tags. The tool also creates and updates a file named assetlocks.json in the deps subdirectory inside your application directory. This file maintains a history of all latest to release conversions made to ensure consistency with any libraries added in the future.
Tools package versioning
The ModusToolbox™ tools installation package is versioned as MAJOR.MINOR.PATCH. The file located at [install_path]/ModusToolbox/tools_[version]/version-x.y.z.xml also indicates the build number.
Every MAJOR.MINOR version of a ModusToolbox™ product is installed by default into [install_path]/ModusToolbox. So, if you have multiple versions of ModusToolbox™ software installed, they are all installed in parallel in the same "ModusToolbox" directory.
Multiple tools versions installed
When you run make commands from the command line, a message displays if you have multiple versions of the "tools" directory installed and if you have not specified a version to use.
INFO: Multiple tools versions were found in
"/cygdrive/c/Users/XYZ/ModusToolbox/tools_a.b
/cygdrive/c/Users/XYZ/ModusToolbox/tools_x.y
C:/Users/XYZ/ModusToolbox/tools_x.y C:/Users/XYZ/ModusToolbox/tools_x.y".
This build is currently using "C:/Users/XYZ/ModusToolbox/tools_x.y".
Check that this is the correct version that should be used in this build.
To stop seeing this message, set the CY_TOOLS_PATHS environment variable
to the location of the tools directory. This can be done either as an
environment variable or set in the application Makefile.
Specifying alternate tools version
By default, the ModusToolbox™ software uses the most current version of the tools_[version] directory installed. That is, if you have ModusToolbox™ versions 3.7 and 3.6 installed, and if you launch the Eclipse IDE, the IDE will use the tools from the tools_3.7 directory to launch configurators and build an application. This section describes how to specify the path to the desired version.
Environment variable
The overall way to specify a path other than the default "tools" directory, is to use a system variable named CY_TOOLS_PATHS. On Windows, open the Environment Variables dialog, and create a new System/User Variable, for example:
CY_TOOLS_PATHS=[ModusToolbox-install-path]/tools_[version]
Use a Windows style path, (that is, not like /cygdrive/c/). Also, use forward slashes. For example: C:/Users/XYZ/ModusToolbox/tools_3.x/
Use the appropriate method for setting variables in macOS and Linux for your system.
Specific project Makefile
If you want to use a specific "tools" path for your current project, edit that project's Makefile, as follows:
# If you install the IDE in a custom location, add the path to its
# "tools_X.Y" folder (where X and Y are the version number of the tools
# folder).
CY_TOOLS_PATHS+=C:/Users/XYZ/ModusToolbox/tools_3.x
This setting in the Makefile takes precedence over the environment variable .
Tools and configurators versioning
Every tool and configurator follow the standard versioning scheme and include a version.xml file that also contains a build number.
Configurator messages
Configurators indicate if you are about to modify the configuration file (for example, design.modus) with a newer version of the configurator, as well as if there is a risk that you will no longer be able to open it with the previous version of the configurator:
Configurators will also indicate if you are trying to open the existing configuration with a different, backward and forward compatible version of the Configurator.
If using the command line, the build system will notify you with the same message.
GitHub libraries versioning
GitHub libraries follow the same versioning scheme: MAJOR.MINOR.PATCH. The GitHub libraries, besides the code itself, also provide two files in MD format: README and RELEASE. The latter includes the version and the change history.
The versioning for GitHub libraries is implemented using GitHub tags. These tags are captured in the manifest files (see the Manifest files chapter for more details). The Project Creator tool parses the manifests to determine which BSPs and applications are available to select. The Library Manager tool parses the manifests and allow you to see and select between various tags of these libraries. When selecting a particular library of a particular version, the .mtb file gets created in your project. These .mtb files are a link to the specific tag. Refer to the Library Manager user guide for more details about tags.
Once complete with initial development for your project, if using the git clone method to create the application instead of the Project Creator tool, we recommend you switch to specific "release" tags. Otherwise, running the make getlibs command will update the libraries referenced by the .mtb files, and will deliver the latest code changes for the major version.
Dependencies between libraries
The following diagram shows the dependencies between libraries.
There are dependencies between the libraries. There are two types of dependencies:
Git repo dependencies via .mtb files
Dependencies for various libraries are specified in the manifest file. Only the top-level application will have .mtb files for the libraries it directly includes.
Regular C dependencies via #include
Our libraries only call the documented public interface of other Libraries. Every library declares its version in the header. The consumer of the library including the header checks if the version is supported, and will notify via #error if the newer version is required. Examples of the dependencies:
- The Device Support library (PDL) driver is used by the Middleware.
- The configuration generated by the Configurator depends on the versions of the device support library (PDL) or on the Middleware headers.
Similarly, if the configuration generated by the configurator of the newer version than you have installed, the notification via the build system will trigger asking you to install the newer version of the ModusToolbox™ software, which has a fragmented distribution model. You are allowed and empowered to update libraries individually.