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™.
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.
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.
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.
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:
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.
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.
If the application does not have a makefile, a message displays indicating the application is not a valid ModusToolbox™ application.
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.
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:
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 |