ModusToolbox™ Project Creator User Guide

ModusToolbox™ tools package version 3.0.0

Project Creator version 2.0

About this document

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.

Note

ModusToolbox version 3.x BSPs and applications have been structured differently than version 2.x. For more details about those structure changes, see App Note AN235297. When creating an application, the BSP you select or import in the Project Creator tool determines the compatible template applications available. If they are not formatted to be compatible, 3.x BSPs will not work with 2.x applications and vice versa

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™ tools package user guide for more details about make commands, BSPs, and the overall structure of ModusToolbox™ applications.

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

Note

When launching from the executable, you can add the –verbose [0-3] option to specify more or less messaging in the message console. The default level is 1.

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.

Use the Expand All or Collapse All as needed to show or hide all the BSPs.

3.2.1 Import BSP

The “Choose BSP” page provides a Browse button to select any BSPs you may have created or received from a colleague. You can then create a new application for that imported BSP. After clicking the Browse button, the Find Directory dialog opens to select the appropriate BSP.

image3

Navigate to and select 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.

image4

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.

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.

image5

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™ tools package 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. Use the Expand All or Collapse All as needed to show or hide all the applications.

  • 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:

image6

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

  • Browse – 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.

  • Expand All – Show all applications for all categories.

  • Collapse All – Hide all applications for all categories.

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.

image7

3.3.3 Using search

Enter text in the Search field above the list of applications to limit the number of applications shown. This can make it easier to decide which application(s) to select. Text entered in this field is searched against keywords in the application’s manifest, title, and description. Along with applications that match the search, any imported applications are included at the beginning of the list, and any applications with a selected check box are included at the end of the list.

You can enter text with spaces, and they are treated as separate search terms. You can also use a quoted phrase, such as “psoc 6”, which is treated as a single term.

3.3.4 Import application

The Select Application page also provides a Browse button to select other applications you may have created or received from a colleague. After clicking the Browse 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.

image8

If the application does not have a makefile, a message displays indicating the application is not a valid ModusToolbox™ application.

image9

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.

image10

Note

During the project creation process, the tool automatically selects the best pair of BSP and application versions from the manifest file. 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:

image11

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

2.0.0

Added Expand All/Collapse All buttons. Changed “Custom” to “Import” in the tree.

Changed Import button to Browse.

Revision history

Revision

Date

Description

**

2019-10-16

New document.

*A

2020—3-26

Updated to version 1.1.

*B

2020-09-01

Updated to version 1.2.0.

*C

2021-03-25

Updated to version 1.30.

*D

2021-06-28

Updated CLI instructions.

*E

2021-09-28

Updated to version 1.40.

*F

2022-09-28

Updated to version 2.0.0. Removed information about the old flow