Getting started
ModusToolbox™ software provides various graphical user interface (GUI) and command-line interface (CLI) tools to create and configure applications the way you want. You can use the Eclipse-based IDE, if installed, which provides an integrated flow with all the ModusToolbox™ tools. Or you can use other IDEs, such as VS Code, or no IDE at all. Plus, you can switch between GUI and CLI tools in various ways to fit your design flow. Regardless of what tools you use, the basic flow for getting started with ModusToolbox™ software includes these tasks:
Install and configure software
Launch Dashboard
Create application from template
Understand application structures
Build and program
This chapter helps you get started using various ModusToolbox™ tools. It covers these tasks, showing both the GUI and CLI options available.
Install and configure software
The ModusToolbox™ Setup program is located on our website here:
https://softwaretools.infineon.com/tools/com.ifx.tb.tool.modustoolboxsetup
The Setup program is used to install base packages and additional packages on Windows, Linux, and macOS. Select the latest tools package and any other packages you want, such as the Eclipse IDE for ModusToolbox™. The Setup program will also select dependency package, such as Programming tools. Refer to the
ModusToolbox™ software installation guide
for specific instructions.
GUI set-up instructions
In general, the GUI-based tools included as part of the ModusToolbox™ tools package work out of the box without any changes required. The same is true of packages installed through the Setup program in addition to the tools package. Simply launch the executable for the applicable GUI tool. On Windows, most tools are on the
Start
menu.
CLI set-up instructions
Before using the CLI tools, ensure that the environment is set up correctly. To check your installation, open the appropriate command-line terminal for your operating system.
Note:
For Windows, the tools package provides a command-line utility called "modus-shell." You can run this by typing "modus-shell" in the Windows search box.
Type
which make
. For most environments, it should return
/usr/bin/make
.
Type
which git
. For most environments, it should return
/usr/bin/git
.
If these commands return the appropriate paths, then you can begin using the CLI. Otherwise, install and configure the GNU make and Git packages as appropriate for your environment.
Launch Dashboard
The ModusToolbox™ tools package includes a tool called the Dashboard. You can launch this optional tool from the last step in the Setup program. You can also launch it manually as applicable for your operating system.
The Dashboard provides links to various sources of documentation and training materials. It also contains starting points: create a new application, create/edit a BSP, install or launch the ModusToolbox™ Setup program.
For more details about this tool, refer to the
Dashboard user guide
.
Create application from template
ModusToolbox™ software includes the Project Creator as both a GUI tool and a command line tool to easily create ModusToolbox™ applications. The Project Creator tool clones the selected BSP and code example template(s), and then creates the directory structure at the specified location with the specified name. The Project Creator tools also run the required processes to download and import all the necessary libraries and dependencies.
Note:
This section describes creating a new application from a template. The process to import or share an existing application is covered in the
Using applications with third-party tools
chapter.
Project Creator GUI
The Project Creator GUI tool provides a series of screens to select a BSP and code example template(s), specify the application name and location, as well as select the target IDE. The tool displays various messages during the application creation process.
Open the Project Creator GUI tool from the Dashboard or as applicable for your operating system. The executable file is installed in the following directory, by default:
<install_path>/ModusToolbox/tools_<version>/project-creator/
Refer to the
Project Creator user guide
for more details.
Note:
The
Target IDE
option (on the Select Application page) is used to generate necessary files for the selected IDE. The Dashboard passes any selected
Target IDE
to the Project Creator tool. If you launch the Project Creator GUI tool from the Eclipse-based IDE, if installed, the tool seamlessly exports the created application for use in the Eclipse IDE.
project-creator-cli
You can also use the project-creator-cli tool to create applications from a command-line prompt or from within batch files or shell scripts. The tool is located in the same directory as the GUI version (
<install_path>/ModusToolbox/tools_<version>/project-creator/
). To see all the options available, run the tool with the
-h
option:
./project-creator-cli -h
The following example shows running the tool with various options.
./project-creator-cli \
--board-id CY8CKIT-062-WIFI-BT \
--app-id mtb-example-psoc6-hello-world \
--user-app-name MyLED \
--target-dir "C:/my_projects"
In this example, the project-creator-cli tool clones the Hello World code example template from our GitHub server (
). It also updates the
TARGET
variable in the
Makefile
to match the selected BSP (
--board-id
), and obtains the necessary library files. This example also includes options to specify the name (
--user-app-name
) and location (
--target-dir
) where the application will be stored.
Note:
You can run the
git clone
and
make getlibs
commands directly from a terminal; however, we recommend using the Project Creator tools (GUI or CLI) because some applications require additional processes to acquire all the submodules. If you choose to run the commands manually, make sure you thoroughly understand all the requirements of the selected application. Refer to the code example README.md file for details as needed.
Understand application structures
After creating one or more applications, they will be located in a top-level container, or workspace directory, that contains a project creation log file, one or more application directories, plus a
mtb_shared
directory. Depending on the example you chose to create the application, it can be either single-core or multi-core.
Version 2.x BSPs/applications versus 3.x BSPs/applications
Some code examples still create ModusToolbox™ 2.x format BSPs and applications. These 2.x applications, as well as any you created using ModusToolbox™ versions 2.2 through 2.4, fully function in the 3.x ecosystem. The following table highlights a few key differences between 2.x BSPs/applications and 3.x BSPs/applications:
Item | Version 2.x | Version 3.x |
|---|---|---|
BSP Assistant usage | Not applicable | Creates and updates 3.x BSPs |
Default BSP type | Git repo, to make changes requires custom BSP | Application-owned, can be directly modified |
Local BSP location | Under the libs directory | Under the bsps directory |
design.modus file location | libs/COMPONENT_BSP_DESIGN_MODUS subdirectory | bsps/config subdirectory |
Makefile MTB_TYPE variable | Not applicable | Identifies single-core vs. multi-core applications |
This user guide focuses on the 3.x application structure. For more details about 2.x applications and BSPs, refer to the older revision of this user guide, located in the
docs_2.4
directory of the ModusToolbox™ 2.4 installation.
To take full advantage of the newest features, you can easily migrate version 2.x applications to the 3.x structure following Knowledge Base Article
KBA236134
. This KBA provides instructions for replacing your BSP and associated libraries with compatible versions for 3.x.
Note:
You cannot mix and match version 2.x format applications with 3.x format BSPs, or vice-versa.
Single-core 3.x application
A typical single-core 3.x application, such as "Hello World," is one project directory with application source code, a Makefile, and assorted files, in addition to the bsps, deps, images, and libs subdirectories. A single-core application uses the
ModusToolbox™ build system
to produce a single ELF file for use on a single-core MCU.
The following describe the contents for a single-core project directory:
.
gitignore
file – This file contains information about files for Git to ignore such as common, tool- or user-specific files that are typically not checked into a version control system.
LICENSE
file – This is the license agreement.
Source code – This is one or more files for your project's code. Often it is named
main.c
, but it could be more than one file and the files could have almost any name. Source code files can also be grouped into a subdirectory anywhere in the application's directory (for example,
sources/main.c
).
Makefile
– This is the project's
Makefile
, which contains configuration information such as
TARGET
for the BSP,
TOOLCHAIN
, and
MTB_TYPE
for the type of application; in this case,
COMBINED
.
README.md
file – This file describes the code example that was used to create the project.
bsps
subdirectory – This directory contains one or more BSPs for this specific project.
deps
subdirectory – By default, this subdirectory contains
<library>.mtb
files for libraries that were included directly or for which you changed using the Library Manager.
This subdirectory also contains the
assetlocks.json
file, which keeps track of the version for each dependent library.
images
subdirectory – If a project has images used by the
README.md
file, for example, this directory contains those images.
libs
subdirectory – This subdirectory may contain different types of files generated by the project creation process, based on how the project is created. You can regenerate these files using the Library Manager, so you do not need to add these files to source control.
If you update your project to specify any libraries to be local, then this directory will contain source code for those libraries.
By default, this subdirectory contains the
<library>.mtb
files for libraries included as indirect dependencies of the BSP or other libraries.
This directory also contains the
mtb.mk
file that lists the shared libraries and their versions.
Note:
If an application needs to modify a standard BSP's configuration, then it will include a templates directory with various BSP templates, which contain configuration files (for example, design.modus) and a reserved resources list. If an application uses the BSP's configuration as-is, then it won't include a templates directory.
Multi-core 3.x application
A multi-core 3.x application, such as "Dual-CPU_Empty_PSOC6_App," includes three makefiles and various assorted files described under
Single-core 3.x application
. It also contains separate subdirectories for each of the core projects, plus the bsps subdirectory that applies to all the core projects in the application. A multi-core application directory hierarchy builds multiple ELF files for various purposes (for example, to support boot loading, multi-core support, or secure enclave scenarios).
Multi-core application directory
A multi-core application directory contains the following files and subdirectories:
Makefile
– The application
Makefile
contains the
MTB_TYPE
variable set to
APPLICATION
, plus the
MTB_PROJECTS
variable to specify the included projects. This file also includes the
common_app.mk
file and the path information to the
application.mk
file in the installation
tools_<version>
directory. This is responsible for forwarding build related requests to the individual core projects and dealing with post-build activities (for example, generating single monolithic HEX files that can be used to program all projects simultaneously) when they are complete.
common.mk
– This makefile is shared across all projects. It contains variables including:
MTB_TYPE
,
TARGET
,
TOOLCHAIN
, and
CONFIG
. In this case,
MTB_TYPE=PROJECT
. This file also includes a reference to the
common_app.mk
file.
common_app.mk
– This makefile is shared across the entire application and all its projects. It contains path information to indicate the location of the installation
tools_<version>
directory.
bsps
subdirectory – This contains one or more BSPs for all projects in the multi-core application.
Multi-core project subdirectories – These contain the source code and
Makefile
for each specific core project. The name format is
proj_<core>
; for example, "
proj_cm7_0
" or "
proj_cm0p
".
Multi-core project directories
Each multi-core project directory contains its own project Makefile that is responsible for compiling and linking a single ELF image. Multi-core project directories are similar to single-core project directories in that they contain source code, as well as libs and deps subdirectories. One main difference is that multi-core project directories do not have a bsps subdirectory, because they use the same BSP from the multi-core application directory.
Source code – This is one or more files for the core project's code.
Makefile
– This is the core project's
Makefile
. It includes numerous variables used for the projects, such as
COMPONENTS
,
CORE
,
CORE_NAME
, and other variables used to specify flags and pre-build and post-build commands. This file also includes path information for source code discovery, shared repo location, and path to the compiler. Plus, it includes the
common.mk
file from the application and the path information to the
start.mk
file in the installation
tools_<version>
directory.
README.md
file – This file contains information for the specific core project.
deps
subdirectory – By default, this subdirectory contains
<library>.mtb
files for libraries that were included directly or for which you changed using the Library Manager.
This subdirectory also contains the
assetlocks.json
file, which keeps track of the version for each dependent library.
libs
subdirectory – This subdirectory may contain different types of files generated by the project creation process, based on how the project is created. You can regenerate these files using the Library Manager, so you do not need to add these files to source control.
If you update your project to specify any libraries to be local, then this directory will contain source code for those libraries.
By default, this subdirectory contains the
<library>.mtb
files for libraries included as indirect dependencies of the BSP or other libraries.
This directory also contains the
mtb.mk
file that lists the shared libraries and their versions.
mtb_shared directory
Each workspace you create with one or more applications will also include a
mtb_shared
directory adjacent to the application directories, and this is where the shared libraries are cloned by default. This location can be modified by specifying the
CY_GETLIBS_PATH
variable. Duplicate libraries are checked to see if they point to the same commit, and if so, only one copy is kept in the
mtb_shared
directory. You can regenerate these files using the Library Manager, so you do not need to add these files to source control.
Build and program
After the application has been created, you can use the supported IDE of your choice for building and programming. You can also use command line tools. The ModusToolbox™ build system infrastructure provides several make variables to control the build. So, whether you are using an IDE or command line tools, you edit the
Makefile
variables as appropriate. See the
ModusToolbox™ build system
chapter for detailed documentation on the build system infrastructure.
Variable | Description |
|---|---|
TARGET | Specifies the target board/kit. For example, CY8CPROTO-062-4343W |
APPNAME | Specifies the name of the application |
TOOLCHAIN | Specifies the build tools used to build the application |
CONFIG | Specifies the configuration option for the build [Debug Release] |
VERBOSE | Specifies whether the build is silent or verbose [0 - 3] |
ModusToolbox™ software is tested with various versions of the TOOLCHAIN values listed in the following table. Refer to the release information for each product for specific versions of the toolchains.
TOOLCHAIN | Tools | Host OS | Variable |
|---|---|---|---|
GCC_ARM | GNU Arm® Embedded Compiler | macOS, Windows, Linux™ | |
ARM | Arm compiler | Windows, Linux | |
IAR | Embedded Workbench | Windows | |
In the Makefile, set the
TOOLCHAIN
variable to the build tools of your choice. For example:
TOOLCHAIN=GCC_ARM
. There are also variables you can use to pass compiler and linker flags to the toolchain.
ModusToolbox™ software installs the GNU Arm toolchain and uses it by default. If you wish to use another toolchain, you must provide it and specify the path to the tools. For example,
CY_COMPILER_IAR_DIR=<yourpath>
. If this path is blank, the build infrastructure looks in the
ModusToolbox
install directory. These variables can also be set as environment variables for your system, so you don't have to change it for each application. See
Path make variables
for details about different variables' usage.
Use an IDE
The ModusToolbox™ ecosystem supports third-party IDEs, and we provide user guides for using those IDEs with a ModusToolbox™ application:
Use command line
make build
When the Project Creator tool finishes creating the application and imports all the required dependencies, the application is ready to build. From the appropriate terminal, type the following:
make build
This instructs the build system to find and gather the source files in the application and initiate the build process. In order to improve the build speed, you may parallelize it by giving it a
-j
flag (optionally specifying the number of processes to run). For example:
make build -j16
In multi-core applications, it is possible to build only the current project instead of the entire application by using the following command:
make build_proj
make program
Connect the target board to the machine and type the following in the terminal:
make program
This performs an application build and then programs the application artifact (usually an .
elf
or .
hex
file) to the board using the recipe-specific programming routine (usually OpenOCD). You may also skip the build step by using qprogram instead of program. This will program the existing build artifact.