Introduction
This chapter provides an overview of the ModusToolbox™ software environment, which provides support for many types of devices and ecosystems.
What is ModusToolbox™ software?
This section provides a list of various terms and definitions used in the ModusToolbox™ ecosystem.
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.
Run-time software
ModusToolbox™ tools also include 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. The ModusToolbox™ installer also conveniently bundles packages of all the necessary run-time components you need to leverage the key Infineon technology focus areas. Refer to
for more details.
Code examples
All current ModusToolbox™ examples can be found through the GitHub
code example page
. There you will find links to examples for the Bluetooth® SDK, PSOC™ 6 MCU, PSOC™ 4 device, 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 mtb-hal, mtb-pdl, and recipe-make. Some of these are identified as device-specific using the following categories:
cat1/cat1a = PSOC™ 6 MCUs (mtb-hal-cat1, recipe-make-cat1a, etc.)
cat2 = PSOC™ 4 devices and XMC™ Industrial MCUs (mtb-hal-cat2, mtb-pdl-cat2)
cat3 = XMC™ Industrial MCUs (recipe-make-cat3)
cat4 = AIROC™ CYW43907 and CYW54907 (mtb-hal-cat4)
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 devices.
AIROC™ Wi-Fi and Bluetooth® chips
PMG1 USB-C Power Delivery MCU
PSOC™ 4 MCU (See
AN79953: Getting Started with PSOC™ 4
for the supported PSOC™ 4 devices.)
PSOC™ 6 MCU
PSOC™ Control MCU
TRAVEO™ MCU
USB device controller
Wireless Charging devices
XMC™ Industrial MCU
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_CY8CPROTO-062-4343W
. 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.
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:
Note:
This image shows ModusToolbox™ version 3.5 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.5:
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, go to
. 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
Note:
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
: 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. | |
project-creator | Create a new application. | |
library-manager | Add and remove libraries and BSPs used in an application; edits the Makefile . | |
bsp-assistant | Create and update BSPs. | |
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. | |
lcs-manager-cli | Command-line tool to create local content to work without Internet. | |
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 use these utilities transparently.
Utility | Description |
|---|---|
GCC | Supported toolchain included with the ModusToolbox™ installer. |
GDB | The GNU Project Debugger is installed as part of GCC. |
JRE | Java Run-time Environment; required by the Eclipse IDE integration layer. |
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
CY_SHAREDLIB_PATH
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:
http://github.com/cypresssemiconductorco/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
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.
You can use various IDEs to program devices and establish a debug session (see
Using supported IDEs
). For programming,
ModusToolbox ™ Programmer
is available separately. It is a cross-platform application for programming devices. It can program, erase, verify, and read the flash of the target device.
ModusToolbox™ Programmer and the Eclipse IDE use 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™ software. The latest version of the tool is also available separately in a
GitHub repository
.
Tool | Description | Documentation |
|---|---|---|
ModusToolbox™ Programmer | ModusToolbox™ Programmer functionality is built into ModusToolbox™ Software. ModusToolbox™ is also available as a stand-alone tool. | |
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. | |
OpenOCD | Our specific implementation of OpenOCD is installed with ModusToolbox™ software. |
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.5 and 3.4 installed, and if you launch the Eclipse IDE from the ModusToolbox™ 3.4 installation, the IDE will use the tools from the
tools_3.5
directory to launch configurators and build an application. This section describes how to specify the path to the desired version.
Settings tool
The overall way to specify a path other than the default "tools" directory, is to use the Settings tool.
[image TBD]
Refer to the Settings too user guide more details.
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.5
This setting in the
Makefile
takes precedence over the Settings tool.
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.
Note:
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.