ModusToolbox™ tools package installation guide¶
ModusToolbox™ tools package version 3.0.0
About this document¶
Scope and purpose
This guide provides instructions for installing the ModusToolbox™ tools package, version 2.4.0. This is a set of tools that enable you to integrate our devices into your existing development methodology. Refer to the tools package release notes for details about what is included. Refer to earlier revisions of this guide for instructions to install previous versions of ModusToolbox™ tools packages.
Intended audience
This document helps application developers understand how to install the ModusToolbox™ tools package.
Reference documents
Refer to the ModusToolbox™ tools package user guide for a description of the software and instructions to get started. You can also refer to the ModusToolbox™ training available on GitHub.
If you plan to use the Eclipse IDE included with the ModusToolbox™ software, refer to these documents, which are also available from the Eclipse IDE Help menu:
Eclipse IDE for ModusToolbox™ quick start guide: brief instructions to create, build, and program applications.
Eclipse IDE for ModusToolbox™ user guide: more detailed information about using the IDE.
1 General information¶
1.1 System requirements¶
The ModusToolbox™ software consumes approximately 2 GB of disk space. Like most modern software, it requires both free disk space and memory to run effectively. We recommend a system configuration with a PassMark CPU score > 2000 (cpubenchmark.net), at least 25 GB of free disk space, and 8 GB of RAM. The product will operate with fewer resources; however, performance may be degraded.
ModusToolbox™ software is supported on the following 64-bit operating systems:
Host OSn |
Supported |
Recommended |
---|---|---|
Windows |
7 SP1, 10, 11 |
10 |
macOS |
Catalina, Big Sur, Monterey (Intel processors) |
Big Sur |
Big Sur, Monterey (Arm processors) |
||
Linux |
Ubuntu 18.04 LTS, 20.04 LTS |
20.04 LTS |
Note
All the above operating systems are supported by all 3.x releases.
On macOS, Arm processors are supported via Rosetta.
ModusToolboxTM software isnotsupported on 32-bit operating systems.
1.2 Uninstall Beta versions¶
If you installed any Beta release of ModusToolbox™ 3.0 software, you need to uninstall it before installing this release. To uninstall a Beta release:
Windows: The current release installer will prompt you to uninstall a previous version 3.0 installation. You can also use the Windows Control Panel.
Linux: Go to the directory where you extracted the tar.gz installer. Delete the docs_3.0, tools_3.0, and ide_3.0 directories, as well as EULA 3.0 text file from the “ModusToolbox” directory.
macOS: The current release installer contains a check box to uninstall a previous version 3.0 installation.
Note
If you plan to use the Eclipse IDE for ModusToolbox™ included with the installation, be aware that uninstalling the ModusToolbox™ software does not remove any Eclipse IDE workspaces you may have previously created. You should manually delete these workspaces or move them to another location. See also Step 3: Run the Eclipse IDE for more details about workspaces.
2 Step 1: Download the software¶
ModusToolbox™ software is available from the Infineon Developer Center website (https:// softwaretools.infineon.com/tools/com.ifx.tb.tool.modustoolbox) to download and/or install.
Select the appropriate package for your operating system:
Windows: ModusToolbox_3.0.0.<build>-windows-install.exe
Linux: ModusToolbox_3.0.0.<build>-linux-install.tar.gz
macOS: ModusToolbox_3.0.0.<build>-macos-install.pkg
You can then click Download or Install:
If you click Download, the selected package will be downloaded to your computer. Refer to Step 2 to install the software.
If you have not used the website before, and if you click Install, a message will display asking you to install the Developer Center. Follow the instructions on the website to install the software.
2.1 Prerequisites¶
ModusToolbox™ software requires the following Unix programs (with minimum versions) to work properly. On Windows, these are provided by the installer program. For macOS and Linux, you must install these programs as appropriate:
cmp (v2.8.1)
git (2.17.0)
make (v3.81)
mktemp (v8.25)
perl (v5.18.2)
python (v3.7)
cysecuretools (v3.10) – Refer to the “Secure Boot” SDK User Guide for more details.
Some versions of Ubuntu Linux do not include ‘make’ by default. Use the following command to install it:
sudo apt-get install make
2.2 SEGGER J-Link¶
If you plan to use the SEGGER J-link debugger, you must download and install the appropriate software pack for your OS. It is not included with the ModusToolbox™ software. Use version 6.98 or later. For Linux, if you install this using the tar.gz file, make sure you install J-Link in a common location. Otherwise, you must configure the Eclipse IDE to specify the location, as follows:
Window > Preferences > MCU > Global SEGGER J-Link Path
Executable: JLinkGDBServerCLExe
Folder: <J-Link_extracted_location>
3 Step 2: Install ModusToolbox™ software¶
Note
Do not use spaces in the installation directory name. Various tools, such as Make, do not support spaces. Also, do not use common illegal characters, such as:
/ : * ? ” < > |
Note
If your user home directory contains spaces, see Installing with spaces in user home directory.
3.1 Installing in non-default location¶
If you install ModusToolbox™ software in a non-default location, you will need to set the environment variable CY_TOOLS_PATHS to point to the <install_path>/ModusToolbox/tools_3.0 directory, or set that variable in each Makefile. You must use forward slashes in the variable’s path, even in Windows. Refer to the “Product versioning” section in the ModusToolbox™ tools package user guide.
3.2 Installing with previous versions¶
ModusToolbox™ version 3.0 installs alongside previous versions of the software (version 2.4, 2.3, etc.); therefore, all versions can be used independently. However, be aware that various programs including the Eclipse IDE and the build system will detect and use the most current version of the “tools” directory by default. For example, if you have both versions 3.0 and 2.4 installed, and if you launch the Project Creator from the Eclipse IDE for version 2.4, it will open the version from the “tools_3.0” directory instead of the “tools_2.4” directory.
To control this behavior, use the environment variable CY_TOOLS_PATHS as described in the “Product Versioning” section in the ModusToolbox™ tools package user guide. This variable applies to all versions of ModusToolbox, so you will have to update it as you work with different versions.
3.3 Windows¶
Run the ModusToolbox_3.0.0.<build>-windows-install.exe installer program and follow the prompts to install for the current user only or for all users of the same machine. For more information, see the Default versus advanced Windows installation section later in this document.
By default, ModusToolbox™ software is installed here:
C:\Users\<user_name>\ModusToolbox
Note
If you have not installed ModusToolbox™ software previously, you may be prompted to restart your computer due to installation of Microsoft Visual C++ redistributable files.
3.4 Linux¶
Extract the ModusToolbox_3.0.0.<build>-linux-install.tar.gz file to your <user_home> directory. The extraction process will create a “ModusToolbox” directory there, if there is not one there already.
After extracting, you must run the following scripts before running ModusToolbox™ software on your machine:
OpenOCD: <user_home>/ModusToolbox/tools_3.0/openocd/udev_rules/install_rules.sh
AIROC™ Bluetooth® Boards: <user_home>/ModusToolbox/tools_3.0/driver_media/install_rules.sh
Firmware Loader: <user_home>/ModusToolbox/tools_3.0/fw-loader/udev_rules/install_rules.sh
Post-Install Script: <user_home>/ModusToolbox/tools_3.0/modus-shell/postinstall
IDC Registration Script: <user_home>/ModusToolbox/tools_3.0/idc_registration-3.0.0.bash
On Ubuntu systems, you must install additional packages using the following command:
$ sudo apt install libncurses5 libusb-1.0-0 libxcb-xinerama0
3.5 macOS¶
Double-click the downloaded ModusToolbox_3.0.0.<build>-osx-install.pkg file and follow the wizard.
The ModusToolbox™ software will be installed under the Applications folder in the volume you select in the wizard.
Note
The ModusToolbox™ package installer installs a custom USB driver for use with ModusToolbox™ on macOS versions prior to Catalina. It may pop up a “System Extension Blocked” dialog. In this case, go to Security Preferenceand clickAllowfor the driver to be installed.
In order for ModusToolbox™ to work correctly on macOS, you must install an additional Xcode package if you don’t already have it installed. We recommend you install Xcode using the following command in a terminal window:
xcode-select –-install
Note
You may install Xcode from the App Store, but it will likely consume much more disk space than using the above command.
4 Step 3: Run the Eclipse IDE¶
The ModusToolbox™ software includes an optional Eclipse IDE. To run the IDE:
Windows: The installer provides an option to run the Eclipse IDE on the final step. You can also select the “Eclipse IDE for ModusToolbox™ 3.0” item from the Windows Start menu.
Linux: Navigate to <user_home>/ModusToolbox/ide_3.0/eclipse and run modustoolbox-eclipse.
macOS: Run the “Eclipse IDE for ModusToolbox™ 3.0” app.
When the Eclipse IDE runs for the first time, a dialog opens to specify the Workspace location. The default location for the workspace is: <user_home>/mtw.
Note
Be aware that the default Eclipse IDE workspace location (<user_home>/mtw) is the same for all versions of ModusToolbox™ software. If you plan to use more than one version, you must specify different workspace names for each one. Enter the workspace location and name and click Launchto open the IDE.
Note
If you change the workspace location or name, do not use spaces or illegal characters anywhere in the path.
Note
If your user home directory contains spaces, see Installing with spaces in user home directory.
After the IDE opens for the first time, the End User License Agreement (EULA) displays.
Read the EULA and click Accept to proceed. If you click Decline, the IDE will close.
5 Default versus advanced Windows installation¶
The ModusToolbox™ installer for Windows provides options to install for the current user or for all users of the same computer. Depending on if you have administration privileges or not, you may be asked to enter a password.
Note
If you select “Install for all users” and then later select install for the current user, the Windows “Apps & features” setting will list only one instance of ModusToolbox™ 3.0. Use the uninstaller to point to the type of installation (All Users or Current User), depending on the order they were installed. To see all installations, navigate to Control Panel > Programs and Features.
After selecting the installation type, follow the prompts to accept the license agreement and select the installation path.
On the Select Installation Type, choose “Default Installation” or “Advanced Installation.”
The default option installs the tools and drivers needed by ModusToolbox.
The advanced option allows you to deselect pre-requisite software and drivers that are already installed.
After continuing with the installation steps and the post-installation process, the following dialog will display if you specified a non-default installation directory as a reminder to set an environment variable.
6 Installing with spaces in user home directory¶
The ModusToolbox™ installer tries to install in your user home directory by default. However, it prevents you from installing into a directory that contains spaces.
If possible, create a new user account and user home directory that doesn’t contain spaces. If you cannot create a new user home directory without spaces, then you must perform some extra manual installation steps.
Note
Even though this process is shown for Windows, these steps apply in general to macOS and Linux as well.
6.1 Step 1: Install at a custom path.¶
Select an alternate installation path that does not include spaces. For example:
C:\MyPath\ModusToolbox
Any path without spaces will work.
After installation is complete, create a directory to store your workspaces. For example:
C:\MyPath\mtb-projects
You can choose any path as long as it doesn’t contain spaces.
Also, create a hidden “dot” directory named “.modustoolbox” to store the cache, offline content, and manifest.loc file discussed later in this section. For example:
C:\MyPath.modustoolbox
6.2 Step 2: Create a variable to specify the path to Tools.¶
Because you are installing ModusToolbox™ into a non-default location, you need to specify the path to your “tools” directory using an Environment Variable. Open the Environment Variables dialog, and create a new System or User Variable, depending on your installation type (current user or all users). For example:
CY_TOOLS_PATHS = C:/MyPath/ModusToolbox/tools_3.0
Note
Use a Windows-style path (not Cygwin-style, like /cygdrive/c/). Also, use forward slashes.
6.3 Step 3: Create a variable to specify the path to cache.¶
The ModusToolbox™ make system clones all the repos needed for your project, directly into your project. So, the resulting project is self-contained. It uses cache to speed up the clone operations. Normally, the make system would create and use cache directory at:
C:\Users\<user_name>.modustoolbox\
You need to fix this for the new install location for ModusToolbox™ by changing the location where the make system keeps the cache. Create a new System or User Variable, depending on your installation type (current user or all users). For example:
CY_GETLIBS_CACHE_PATH = C:/MyPath/.modustoolbox/cache/
Note
Use a Windows-style path (not Cygwin-style, like /cygdrive/c/). Also, use forward slashes.
Alternately, you can disable the caching. The downside is that this will slow down the clone operation and overall project creation, as well as the library update experience. To disable the cache, create a User Variable:
CY_GETLIBS_NO_CACHE = 1
6.4 Step 4: Create a variable to specify the global path.¶
Because you are installing ModusToolbox™ into a non-default location, you need to specify the global path using an Environment Variable. Open the Environment Variables dialog, and create a new System or User Variable, depending on your installation type (current user or all users). For example:
CY_GETLIBS_GLOBAL_PATH = C:/MyPath/.modustoolbox/global
Note
Use a Windows-style path (not Cygwin-style, like /cygdrive/c/). Also, use forward slashes.
6.5 Step 5: Specify the custom path to use for offline content and manifest.loc.¶
Although you may not use these features, dependencies require that you set them up while installing the software.
6.5.1 Offline content path¶
Specify the non-default location to the “offline” directory with an Environment Variable. For example:
CY_GETLIBS_OFFLINE_PATH = C:/MyPath/.modustoolbox/offline/
6.5.2 manifest.loc¶
Likewise, create an Environment Variable to specify the non-default location of the manifest.loc file. For example:
CyManifestLocOverride = C:/MyPath/.modustoolbox/manifest.loc
Revision history¶
Revision |
Date |
Description |
---|---|---|
** |
2017/12/29 |
New document. |
*A |
2018/09/18 |
Complete update for production release. |
*B |
2018/11/21 |
Updated the system requirements section. Added information about uninstalling issues. Updated to clarify macOS instructions. |
*C |
2019/02/27 |
Updated for version 1.1. Added custom drivers information. Updated linux instructions. |
*D |
2019/09/26 |
Added information to clarify usage with multiple versions and workspaces. |
*E |
2019/10/17 |
Updated for version 2.0. Added a note for macOS Catalina. |
*F |
2019/10/21 |
Added git as a prerequisite. |
*G |
2020/10/14 |
Added a link to KBA229345. |
*H |
2020/02/13 |
Added a comment about using forward slashes for the CY_TOOLS_PATHS variable. |
*I |
2020/03/26 |
Updated for version 2.1. |
*J |
2020/02/04 |
Corrected macOS executable name. |
*K |
2020/04/14 |
Corrected “optional” step for installing with spaces in user home directory. |
*L |
2020/09/01 |
Updated for version 2.2. Updated to include Python 3.7 requirement. Removed macOS Catalina notarization warning. |
*M |
2021/03/25 |
Updated for version 2.3. Added installer instructions for Windows and multiple users. Added Linux instruction for libncurses5. Updated for macOS Big Sur. |
*N |
2021/09/10 |
Updated for version 2.4. |
*O |
2022/09/22 |
Updated for version 3.0. Added instructions for CY_GETLIBS_GLOBAL_PATH. Updated formatting for version 3.0. |
*P |
2022/10/20 |
Updated the name of the Eclipse executable. |