Author: JamesT_21 Version: *I
This document applies to ModusToolbox IDE v2.0. Version 1.1 has differences in UI and work flow. To see an earlier version of this document you must be logged in to the Community. Then:
- Click the Version identifier toward the top right of the document.
- In the comparison window that appears, on the left, pick the version you want to look at. You can ignore the rendering of differences on the right hand side.
Refer to version 37 of the document for ModusToolbox 1.1
Refer to version 32 of the document for ModusToolbox 1.0
ModusToolbox™ IDE is built on the Eclipse IDE. For those unfamiliar with an Eclipse IDE, this FAQ answers questions about how to get common tasks done.
If you are already familiar with an Eclipse IDE, you will find useful answers here on unique ModusToolbox IDE features such as the Quick Panel and how to build an application.
Questions are organized into the following categories:
- Project Management
- Build System
In this document, the term "Application" means deployable firmware for the target hardware. To build an application, you require a collection of one or more Eclipse projects.
A "Project" is a compilation unit. A ModusToolbox IDE application may consist of several Eclipse projects but typically is a single project.
How do I get started building an application using ModusToolbox IDE?
Use the Quick Panel New Application link (or select File > New > ModusToolbox IDE Application). Then choose a board support package (BSP).
A list of available starter applications appears on the next screen. Select the one that most closely matches what you need. Click Next to see a summary of your choices, and Finish to create the project in the IDE. The downloaded library files (for example, the Peripheral Driver Library or the CapSense library) are in the libs folder in the project. The readme.md file describes the example and how to use it. See KBA225201 for details.
Where do I find code examples?
Use the Quick Panel New Application link (or select File > New > ModusToolbox IDE Application). You are presented will available code examples (starter applications).
How do I get code example files onto my computer?
Use the Quick Panel New Application link (or select File > New > ModusToolbox IDE Application). This copies all the files required for the example into your Eclipse workspace and creates an Eclipse project.
If you just want all the files without an Eclipse project, use the ModusToolbox Project Creator tool. See KBA225201 for details.
If for some reason you want a local copy of a code example repository, in the Quick Panel click the Search Online for Code Examples link. Find the repository that contains the example(s) you want. You can clone the repository using git, or download the repository. However, the repository is incomplete. It does not include library or BSP source files. The ModusToolbox build system identifies dependent libraries and clones them automatically when you use the IDE or Project Creator to create the example, or use make getlibs. from the command line.
Parts of the code example’s readme file is hard to read in the IDE. How do I fix that?
Cypress uses GitHub to deliver examples and libraries. We use GitHub-flavored markdown, which has some extensions (like support for tables) that are not understood by the Eclipse markdown editor. There are a few things you can do. You can look at the readme file on GitHub. You can right-click the document in the project explorer and choose “Open With…” to pick a different application. You can get a more capable markdown editor and install that. You can also set up the Eclipse IDE to open a markdown document in that editor.
How do I set up the IDE to use my preferred markdown editor?
If a document does not open the editor you want, use Window > Preferences > Editors > File Associations and set up the file association. For the *.md file type, assign it to your preferred markdown viewer. When you double-click a .md file in the Eclipse project explorer, it opens in your external editor.
What is the Project Creator tool and why would I use it?
This tool does the same thing as the IDE’s New Application wizard, except that it does not create an Eclipse project. It creates a folder that contains all the files required for a project. You might use this tool if you want all the source files for an example so you can add the files to another IDE.
You can find this tool in the <ModusToolbox install>/tools_n.n/project-creator folder.
What is the Library Manager tool and why would I use it?
The Library Manager allows you to select the BSPs that are available for you project, allows you to select the active BSP, and allows you to select the firmware packages to include in the application. The tool contains two tabs: BSP and Library. The Boards tab displays by default when you open the tool. The Library tab displays only valid libraries that for the active board. For more information, refer to the Library Manager User Guide.
How do I find the right panel or option when I don’t know where anything is?
Use the Eclipse IDE Quick Access feature. This is a search engine that helps you find things in an Eclipse IDE. The IDE is a complex application with significant resources located in various menus, panels, windows, and so forth. The Quick Access field solves the problem of not knowing where things are.
Type a search term into the Quick Access field, and you are presented with hits. Each item is a link. Clicking a link either executes the command or takes you to the location in the Eclipse UI.
How do I rename an application?
Give it a name as you create the application. After creation, the application cannot be easily renamed in the IDE.
How do I share a project?
There are two ways to do this: via an archive file, and from the file system.
- Export an archive file: Select File > Export >General > Archive File. Select the project that represents the application. Send the archive to the person who needs the application. That person imports via File > Import > General >Existing projects into workspace and sets options to import the archive file.
- To import projects from the file system, use File > Import > General > Existing projects into workspace; point to the root directory that contains the project(s) you want to import. You must enable Copy project into workspace.
Pro Tip: When you archive a project, do not include the build folder. The IDE regenerates this information, you don’t need to include it. You will save many megabytes of space excluding the build folder.
How do I create a new/empty workspace?
Choose File > Switch Workspace > Other... and then create the new workspace. You can do this by just entering a new name, or browsing and creating a folder.
How do I change workspaces?
Choose File > Switch Workspace, and then pick an existing workspace.
What is a perspective and how does ModusToolbox IDE use them?
In Eclipse, a perspective is the collection of panes and views visible in the user interface. The ModusToolbox IDE has its own perspective, which is what appears when you launch the IDE for the first time. This is called the ModusToolbox perspective. It contains views that enable project management, code creation, and debugging all in the same perspective. It also contains the Quick Panel, which contains one-click shortcuts to the most common tasks. By default, the IDE does not use the standard Eclipse C/C++ or Debug perspectives.
How can I change to a different perspective?
There are at least three ways.
Select Window > Perspective > Open Perspective and choose the one you want. You can also click the Open Perspective button in the toolbar. The icon for any perspective you open appears as a button on the toolbar.
To the right of that is a button for each of the perspectives you have used, such as the ModusToolbox perspective. Just click the button corresponding to the perspective you want to use.
How can I make my own perspective?
This is one of the most powerful features of an Eclipse IDE. You can open, close, or relocate any view in any panel. In effect, you can build your own UI. When the UI is set up to your liking, use Window > Perspective > Save Perspective As. Give it a name, and it is added to the list of available perspectives.
How do I remove or delete a project from the project explorer?
In the project explorer, select the project(s) you want to remove. Then press the Delete key, or right-click and choose Delete. The Delete Resources dialog appears.
To remove a project from the explorer, but keep the actual project, make sure that Delete project contents on disk is disabled.
To delete the project permanently, enable the Delete project contents on disk option. Project deletion cannot be undone.
What are workspace settings?
Workspace settings are preferences that apply to the entire workspace. In general, these are set by changing options in Window > Preferences.
How do I share workspace settings across workspaces?
You can export preferences from one workspace and import them into another. Select File > Export > General > Preferences. This creates a preferences file. You can use the file as a backup of your preferences. You can switch to any workspace and import the preferences.
When creating a new workspace, expand the Copy Settings option and specify which preferences from the current workspace you want to use in the new workspace.
What is a working set and why would I want to use one?
A working set is a collection of Eclipse projects. Fundamentally it is just a group, but you can perform various operations that will affect all the projects in the group. For example, you can show, hide, or build a working set. This can make it easier to manage multiple related projects.
How do I create a working set?
To make things easy, do the following:
- In the project explorer, first select all the projects you want in the working set.
- Use the View drop-down menu in the project explorer and choose Select Working Set.
- Click New, and then select C/C++ and click Next. If you selected the projects first, they appear already selected in the New Working Set dialog. Otherwise, you can pick them one by one.
In the View menu you can make the working set the top-level element. Only selected working sets are visible. You can show projects that aren’t in the working set in the Other Projects collection.
How do I set up dependencies between projects?
When working with a set of applications, you may wish to ensure that if you build one, the projects it depends upon build first.
In the project explorer, right-click a project and choose Properties. Click the Project References item. In the panel, select the projects on which this project depends.
What does it mean to close a project, and how do I do it?
A closed project requires no resources and is not affected by any workspace command (e.g., Build All).
To close projects, select them, right-click, and choose Close.
You can also select one you want to keep open, right-click, and choose Close Unrelated Projects. Every project not related to your selected project will close.
What is the difference between a local file and a linked file, and how do I tell which is which?
A local file is a file that exists inside the project directory in your workspace. It is unique to the project that owns the file. Any change you make to this file has local effect only. You are changing the file in the project.
A linked file is a file that the project refers to, but it does not maintain a local copy. Most commonly, linked files are library source files. However, it can be a file anywhere that is used by reference. The project points to the original file and does not have a local copy. That means, if you change the linked file, you change every project that uses that file.
How can you tell which is which? This is a particularly subtle part of the Eclipse UI. The icon for a linked file has a tiny arrow. Like this.
How do I link to files instead of duplicating files in each project that uses them?
This is easy, but obscure. You can link to a single file, or an entire folder full of files.
Use File > New > Other, select Folder (or file) and click Next.
In the resulting dialog, specify the parent folder that will hold the new linked folder in the Project explorer. Click Advanced. Then Click Link to alternate location (Linked Folder). Click the Browse button and navigate to the folder you want to link to the project. Instead of an absolute path, you can use path Variables to specify the location. The folder name is set automatically, but you can rename it whatever you want.
Click Finish and you’re done. The project now has a link to the folder and its contents. All the files in the folder appear, you do not need to add them individually. If you change a file, any project that uses that file is affected. In the project explorer it looks like this:
The folder icon has a tiny arrow, which means this folder and its contents are linked, not included directly in the project.
How do I launch multiple instances of Eclipse on macOS?
By design, macOS allows one instance of an app. There is a way around this from the terminal. This is a macOS issue, not an Eclipse problem.
From the terminal, do the following:
- Navigate to the application directory, for example: cd /Applications/eclipse/
- Open the app: open -n Eclipse.app &
The & immediately sends the app to the background, and you now have two instances of Eclipse running.
Can I use an Eclipse IDE with a version control system?
The short answer is yes. However, you need to be careful about what gets checked in. The IDE does not restrict what it checks in. The IDE can add everything in a project, not just the files you want. As a result way too many files, including binaries, can get checked in. This can cause grief.
Although the Eclipse egit plugin typically manages this automatically, even then you can have problems. If the project builds with an error, inappropriate files will be checked in when you add files to source code control.
At a minimum, do not check in these folders or their contents:
You need to manage your version control system to exclude these files. For example, ensure that your .gitignore file lists these directories.
(The Debug and Release folders are the output folders for the standard build configurations defined for ModusToolbox projects. There are no source or original files in these directories.)
How do I show line numbers?
Select Window > Preferences > General > Editors > Text Editors and find the Show line numbers option.
How do I search across all files in a project or workspace?
Use the Search menu. When the dialog opens, control the scope of the search with the options near the bottom of the dialog.
How do I go from a file listed in the project explorer to the actual file in the file system?
In the project explorer, right-click the file, choose Properties. In the dialog, note the Location field. Click the button to the right of the location.
I have multiple files of the same name open in the editor. How do I tell which project each one belongs to?
There are at least two ways to do this.
- Hover over the tab in the editor. The project and path within the project to the file appear.
- Enable the Link with Editor option in the explorer pane. When this is enabled, the file with focus in the editor is highlighted in the project explorer.
How do I build an application?
In the project explorer, select the project. In the Quick Panel click Build <appname> Application. You can also right click the project and choose Build Project. If there are dependent projects those build as well.
What does Build All build?
The Project > Build All command builds every open project in a workspace. You probably don’t want to use this command if you have more than one application in a workspace.
In addition, open projects can be hidden in the project explorer. If you hide an application and its projects (using working sets for example), those projects will still be built if they are open.
How do I add middleware or a library to a project?
In the project explorer, select the project. Then in the Quick Panel, click the Library Manager link. Click the Libraries tab to see all available libraries. You can select the version you want, as well as the library.
How do I set up an application to run on a different kit?
In the project explorer, select the project. Then in the Quick Panel, click the Library Manager link. Click the Boards tab to see all available kits. If you are working with a code example, make sure that the example supports the kit you want to use.
What is the project’s makefile and what does it do?
For ModusToolbox, every application has a makefile. That file fully describes the application, including what board or kit to use, what tool chain to use, what files to use, what libraries to include, what compiler and linker flags control the build, and so on. See the ModusToolbox documentation for more information on the makefile.
Where do I find build settings?
In ModusToolbox IDE, compiler and linker settings are controlled by the makefile that describes the application. They are not set in the Eclipse UI.
There are many settings in the project’s properties that you may want to adjust. To see a project’s properties, use Project > Properties or right-click a project and choose Properties. Then navigate to the panel you need.
What is a build configuration?
The ModusToolbox makefile has two default build configurations, Debug and Release. Use the CONFIG variable in the makefile to choose which to use. For example, CONFIG=Debug.
In an Eclipse IDE, a build configuration is a collection of all the project properties and build settings. Because ModusToolbox IDE uses a makefile to specify build options, changing the Eclipse build configuration has no effect on how the ModusToolbox application builds.
Where do I specify compiler symbols and defines?
In the makefile that defines the application. See Running ModusToolbox from the Command Line for detailed documentation
How can I tell if a build was successful?
The easy way is to look in the Problems tab of the console pane. The console window shows any errors, but they can be hard to find in the console log.
How do I terminate a build?
When you start a build, a progress bar appears in the bottom-right corner of the window. There is a little button to the right.
Click the button; the Progress tab opens in the Console area. It looks like this.
Click the red terminate button; the build stops.
Advanced Tip: Some builds are very quick, and every time a build ends, focus shifts back to the Console tab, foiling your attempt to cancel the build. You can change that behavior. Go to Window > Preferences > C/C++ > Build > Console and disable Bring console to top when building (if present). The Progress tab will now keep focus when it's open.
I have an error that a symbol (e.g. bool or uint32_t) could not be resolved. What’s going on and what do I do about it?
The odds are this is a false positive. Other symbols defined in the file are fine, but one shows up as an error. The code builds despite this error.
This is a problem with the Eclipse code indexer. You can force a reindexing of the application. Right-click a project in the project explorer and choose Index > Rebuild. The error may persist, even if you rebuild the index.
It is possible that the file that defines the symbol may not be in the #include hierarchy. This is a real problem. In this case you would see many errors, not just one or two, because every symbol in the header file would be unresolved. Make sure the header is included and the problem goes away.
What are launch, run, and debug configurations?
Each of these is a collection of settings that control how the target is programmed and debugged. A run configuration programs the target and begins execution. A debug configuration does the same, but launches the debugger and (typically) stops execution at the first line of main(). A launch configuration can execute a combination of run and debug configurations.
PSoC 6 MCU projects use these configurations. In the ModusToolbox IDE, an application typically includes configurations named Attach, Erase, Program, and Debug.
For details on how to program or debug either a PSoC 6 MCU project, see the “Program/Debug with ModusToolbox IDE” chapter in the ModusToolbox IDE User Guide.
How do I start a debug session?
The simple way is to scroll to the Launches section of the Quick Panel. Then click the desired configuration.
A ModusToolbox IDE application typically has a Program and a Debug configuration. The Program configuration builds the code, downloads the code to flash and begins execution. The Debug configuration does the same but launches a debug session as well.
See the “Program/Debug with ModusToolbox IDE” chapter in the ModusToolbox IDE User Guide for details.
When I try to program or debug I get a connection error. What do I do?
Sometimes the error is self-explanatory, sometimes not. Here’s a fairly common error where you might need a little help understanding what’s going on.
Error: unable to find CMSIS-DAP device
Error: No Valid JTAG Interface Configured
The most common cause, you don’t have a board connected, or the board doesn’t have power. Connect or power up the board, and you should be fine.
Another error you may see is:
Error: KitProg firmware is out of date, please update to the latest version using fw-loader tool
Many Cypress boards come from the factory with the older KitProg2 installed. ModusToolbox does not work with KitProg2. You need to upgrade the communication firmware on the kit to KitProg3, and the fw-loader tool does that.
In a nutshell, the firmware loader is a command line tool that comes with ModusToolbox software. You can use it to determine what KitProg is on your kit, and upgrade to KitProg3. You can also go back to KitProg2 if you need to.
The firmware loader tool is installed with the IDE. You can get the latest directly from the Firmware-loader GitHub repository.
How do I step through assembly code?
The ability to do this is not visible in the ModusToolbox perspective. Use the Debug perspective, which has this capability enabled by default. Perspective icons are at the top right of the IDE’s window. If the icon is not visible, use Window > Perspective > Open Perspective.
Then, in the Debug perspective’s Debug panel, enable the Instruction Stepping Mode button.
Pro Tip: You can modify the ModusToolbox perspective to make this option visible. Use Window > Perspective > Customize Perspective. Click the Action Set Availability tab. Turn on C/C++ Debug. The Instruction Stepping icon now appears in the ModusToolbox perspective
I like the Debug perspective better. How do I use it by default when I debug?
Use Window > Preferences > Run/Debug > Perspectives. In that panel, locate the GDB OpenOCD Debugging launcher, and change to the Debug perspective.
When debugging, how do I see variables, registers, and memory?
All this information appears in various views within the IDE. In the default ModusToolbox perspective:
If a view is not visible, select Window > Show View, and pick the view that you want. You can drag views to new locations, maximize or minimize, and manage the arrangement of views as you wish.
How do I see local variables?
The Variables view shows local variables. Any variable that is in scope should appear automatically in this view. This view does not and cannot display global variables.
How do I see global variables?
Use the Expressions view to see global variables. You can drag the variable name into this view or click Add new expression and type in the name. You can also use this view to create and evaluate complex expressions.
When I start a debug session, an editor window appears that tells me there is a break at an address with no debug information available. But the debug session starts fine. What's going on and what do I do about it?
Here's a typical warning with this "error." The address mentioned will vary.
This is the warning that appears when a source file can't be found. Sometimes that's an actual problem, although in this case (the debug session starts fine) it isn't.
You can configure Eclipse preferences to show this warning less frequently. Click the Preferences button in this window. That takes you to the general debug settings panel in Eclipse preferences, as shown below. The default is to show this window all the time.
Enable the Only if source file name is known but not found option. Then the warning appears when, in fact, a source file can't be found.
When I terminate a debug session, the processor stops. How do I stop debugging but leave the processor running?
In the Debug view, right-click the openocd process, and select Terminate. This shuts down the debug connection and leaves the processor running.
You can also select the openocd thread, and then click the Terminate button in the toolbar.
How do I remove terminated debug sessions from the Debug view?
A terminated debug session remains visible in the Debug view.
You don't need to do anything. It is removed automatically when you start the next debug session. However, if you want to remove terminated debug sessions manually:
- Select one or more and press the Delete
- Right-click and choose Remove All Terminated
How do I start debugging without downloading the executable again?
In Run > Debug Configurations, choose an Attach configuration.