ModusToolbox™ Project Creator user guide

About this document

Version

1.40

Scope and purpose

This guide provides information and instructions for using the ModusToolbox™ Project Creator tool.

Intended audience

Read this document to learn how create a ModusToolbox™ application using the Project Creator tool.

Document conventions

Convention

Explanation

Bold

Emphasizes heading levels, column headings, menus and sub-menus

Italics

Denotes file names and paths.

Courier New

Denotes APIs, functions, interrupt handlers, events, data types, error handlers, file/folder names,

directories, command line inputs, code snippets

File > New

Indicates that a cascading sub-menu opens when you select a menu item

Reference documents

Refer to the following documents for more information as needed:

1. Overview

The Project Creator tool is used with the ModusToolbox™ software to create applications based on Board Support Packages (BSPs) and code examples found in the manifest files. The tool is provided as a graphical user interface (GUI) and a command-line interface (CLI) to create applications for use in any software environment you prefer. The GUI provides a simple interface for users who do not want to use the CLI.

1.1 Manifest files

Manifest files determine which BSPs and code examples display for use in the Project Creator tool in order to create applications. These files are located by default on GitHub. If for some reason your system cannot access these manifest files, then you will not be able to create an application.

KBA230953 describes methods for working around this issue.

1.2 Created application(s)

The Project Creator tool essentially runs a “git clone” command to create one or more applications onto your computer from a remote server. It also runs the “make getlibs” command to import the necessary libraries.

Different types of applications will have different files and directory structures. After creating the application(s), navigate to the specified root directory. Inspect the files and directories located there. Use these files to modify your application(s) as necessary in your preferred environment.

Note

The Project Creator tool generates a log file named project-creator.log in the Application(s) Root Path. This log file captures all commands run by the tool. It will be overwritten if you create a new application in the same path.

Refer to the ModusToolbox™ user guide for more details about make commands, BSPs, and the overall structure of ModusToolbox™ applications.

1.3 Library management flows

For ModusToolbox™ 2.2 and later, we implemented a new way of structuring applications, called the MTB flow. Using this flow, applications can share BSPs and libraries. If needed, different applications can use different versions of the same BSP/library. Shared BSPs, libraries, and versions are located in a directory named mtb_shared, which is adjacent to your application directories in the same root path. Refer to the Library Manager user guide for details.

Looking ahead, most example applications will use the new MTB flow. However, there are still various applications that use the previous flow, now called the LIB flow. These applications generally do not share BSPs and libraries, and these BSPs and libraries are located in an application’s libs subdirectory. ModusToolbox™ fully supports both flows.

2. Launch the Project Creator

You can launch the Project Creator from the Eclipse IDE for ModusToolbox™, as a stand-alone GUI tool, and as a command-line tool.

Note

If you prefer to use the Eclipse IDE, you should launch Project Creator tool from the Eclipse IDE included with ModusToolbox™ instead of as a stand-alone tool or from the command line.

2.1 From Eclipse IDE

The Eclipse IDE included with the ModusToolbox™ installer provides links and menu items to launch the Project Creator tool and create a project that applies to Eclipse.

For more information, refer to the quick start guide or user guide for the Eclipse IDE for ModusToolbox™.

2.2 As a stand-alone GUI tool

Launch the Project Creator as a stand-alone GUI tool by running its executable as appropriate for your operating system (for example, double-click it or select it using the Windows Start menu). By default, it is installed here:

<install_dir>/ModusToolbox/tools_<version>/project-creator

2.3 As a command-line tool

To run the Project Creator as a command-line tool, navigate to the install location and run the project-executable from a command-line prompt. By default, it is installed here:

<install_dir>/ModusToolbox/tools_<version>/project-creator

For more information about command-line options, run the project-creator-cli executable using the -h option. See CLI description later in this document for an example.

3. GUI description

The Project Creator GUI provides a series of pages used to create a project.

3.2 Choose BSP page

When you first launch the GUI, it displays the “Choose Board Support Package (BSP)” page that lists the available BSPs by various types, suchas as AIROC™, PSoC™ 4, and XMC™.

image2

Expand one or more categories to view the BSPs, and select the desired BSP by clicking it. A description for the selected BSP displays in the right pane.

3.2.1 Import BSP

The “Choose BSP” page provides an Import button to select any custom BSPs you may have created or received from a colleague. You can then create a new application for that custom BSP. After clicking the Import button, the Find Directory dialog opens to select the appropriate custom BSP. Navigate to the appropriate directory containing the BSP to import and click Choose.

The tool checks that the BSP to be imported has a makefile, but it does not validate the makefile for correctness. If the selected BSP has a makefile, it is added to the list with all the other BSPs.

image3

If the BSP does not have a makefile, a message displays asking whether to continue with the selected BSP or not. Select Yes to proceed with the selected BSP. Select No to close the dialog, and then either navigate to another directory to find the BSP or cancel the import operation.

Note

Custom BSPs created using the make bsp command include .mtbx files that provide pre-fetched library information.

For information about creating custom BSPs, refer to the ModusToolbox™ user guide.

3.3 Select application page

Select a board on the Choose BSP page and click Next > to display the “Select Application” page. This page displays the Template Applications available for the selected BSP, organized by categories.

image4

On this page, do one or more of the following:

  • Specify the Application(s) Root Path, or leave it as the default. All files and folders from the application(s) with a selected check box will be copied to this location in a folder with the Application Name(s).

  • Optionally pick an item from the Target IDE pull-down menu, which will generate the necessary files for the selected target. For more details, refer to the “Export to IDEs” chapter in the ModusToolbox™ user guide.

Note

If you launch the Project Creator tool from the Eclipse IDE, “Eclipse IDE for ModusToolbox™” is the only option available and it cannot be changed.

  • Expand one or more categories to see the applications available.

  • Select one or more check boxes for applications in the list. You can click on the check box or use the right-click context menu. See Select multiple applications for more details.

  • Type a New Application Name for the application(s) with a selected check box, or leave the name as the default.

3.3.1 Toolbar options

The “Select Application” page contains a toolbar with options to assist with the process, including:

image5

  • Search – Shows applications that include the text as entered. See Using search for more details.

  • Import – Allows you to add other applications to the list. See Import application.

  • Show/Hide – Toggle to show only the applications with check boxes selected or show all applications. If there is search text, then only applications with check boxes selected and applications with matching search text will be shown instead of all.

  • Select All – Select the check boxes for all applications currently shown in the list.

  • Unselect All – Unselect the check boxes for all applications currently shown in the list.

3.3.2 Select multiple applications

The “Select Application” page allows you to select multiple applications, as follows:

  • Click multiple check boxes next to the applications.

  • Click to highlight an application, then press and hold [Ctrl] and click additional applications.

  • Click to highlight an application, then press and hold [Shift] to select a range of applications.

When you have multiple applications highlighted, right-click to open the context menu Select Highlighted Applications.

image6

3.3.4 Import application

The Select Application page also provides an Import button to select other applications you may have created or received from a colleague. After clicking the Import button, the Find Directory dialog opens. Navigate to the appropriate directory containing the application to import and click Choose.

Note

Ensure that you only select an application supported by the BSP you selected on the Choose BSP page.

The tool checks that the application to be imported has a makefile, but it does not validate the makefile for correctness. If the selected application has a makefile, it is added to the list with the other applications.

image7

If the application does not have a makefile, a message displays asking whether to continue with the selected application or not. Select Yes to proceed with the import. Select No to close the message without importing, and then navigate to another directory to find an application or cancel the import operation.

3.4 Create an application

Click Create to start the process of creating a ModusToolbox™ application, and the GUI will display various messages showing the progress.

image8

Note

During the project creation process, the tool automatically selects the best pair of BSP and application versions from the manifest file. The selection process has the following preferences:

  • Versions that support the .mtb file flow (see Library management flows ) are preferred over versions that support the .lib file flow.

  • Release versions are preferred over any custom name versions.

Using the command line (see CLI description), you can manually select which version to use. If the BSP and application flow versions match, then the project-creator tool will create a project. If not, then it will show an error.

The GUI always shows applications that have at least one application version that is supported by at least one BSP version.

When the process competes, the tool will display a message similar to the following:

image9

You can continue creating new projects from the “Select Application” page by selecting a new application and then clicking the Create button again. You can also go back to the “Choose BSP” page to select another BSP and then continue the project creation process as usual.

To close the tool, click the Close button or the X button at the top-right of the GUI.

Note

If you launched the Project Creator tool from the Eclipse IDE, the Project Creator tool closes automatically upon completion, and the IDE will import the created application(s).

4. CLI description

You can also use the project-creator-cli executable to create applications from a command-line prompt or from within batch files or shell scripts. The exit code for the CLI is zero if the operation is successful, or non-zero if the operation encounters an error. For Windows, use the modus-shell bash installed in the ModusToolbox™ “tools” directory. For macOS and Linux, use the appropriate bash for your system.

The project-creator-cli executable is located in the same directory as the GUI version of the tool

(<install_dir>/ModusToolbox/tools_2.4/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 the basic options to specify a BSP and application:

$ project-creator-cli \

—board-id CY8CKIT-062-WIFI-BT \

–app-id mtb-example-psoc6-hello-world

5. Version changes

This section lists and describes the changes for each version of this tool.

Version

Change descriptions

1.0

New tool.

1.1

Redesigned the GUI to provide a better flow.

Added Settings and Help menus.

Added icon to indicate online/offline status.

Added Import BSP button.

1.2.0

Tool can be launched from Windows Start menu.

Updated versioning to support patch releases.

Updated to select and create multiple applications at one time.

Updated to provide information about new library management flow.

1.30

Updated versioning to allow for additional minor changes.

Updated the import process to check if the BSP/application includes a makefile.

Added Target IDE option to the GUI.

Added colors to the messages; red for error, yellow for warning, green for success.

1.40

Added categories for Template Applications.

Updated handling of .mtbx files.

Revision history

Revision

Date

Description

**

10/16/19

New document.

*A

03/26/20

Updated to version 1.1.

*B

09/01/20

Updated to version 1.2.0.

*C

03/25/21

Updated to version 1.30.

*D

06/28/21

Updated CLI instructions.

*E

09/28/21

Updated to version 1.40.