ModusToolbox™ installation guide

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:

If you installed any Beta release of ModusToolbox™ 3.0 software, you need to uninstall it before installing this release. To uninstall any 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.

Ensure you are downloading the core version "2.4.0" of the ModusToolbox™ tools package. There may be patch versions also available, but they will not work without the appropriate core version first installed. Also, patch version "2.3.1" will not work with core version "2.4.0," for example, because it is a patch for core version "2.3.0."

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

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>

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™ user guide.

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™ user guide. This variable applies to all versions of ModusToolbox™ software, so you will have to update it as you work with different versions.

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

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-2.4.0.bash

On Ubuntu systems, you must install additional packages using the following command:

$ sudo apt install libncurses5 libusb-1.0-0 libxcb-xinerama0

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.

In order for ModusToolbox™ to work correctly on macOS, you must install an additional Xcode package if you do not already have it installed. We recommend you install Xcode using the following command in a terminal window:

xcode-select –-install

1. Select an alternate installation path that does not include spaces. For example:

   C:\MyPath\ModusToolbox

   Any path without spaces will work.

2. 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.

3. 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

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

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/

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

Although you may not use these features, dependencies require that you set them up while installing the software.