ModusToolbox™ Device Configurator user guide

ModusToolbox™ tools package version 3.0.0

Device Configurator version 4.0.0

About this document

Scope and purpose

This guide provides information and instructions for using the Device Configurator to update various

parameters for you ModusToolbox™ application.

Intended audience

This document helps application developers understand how to use the Device Configurator as part of creating a ModusToolbox™ application.

Document conventions




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


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

Abbreviations and definitions

  • Resource – Includes peripherals, pins, clocks, etc. used in an application.

  • Configurator – A GUI-based tool used to configure a resource.

  • Application – One or more projects related to each other.

  • Personality – A file that defines a resource behavior.

  • Device Support Library – A device support library provides critical firmware and device data files to configurators. Device support libraries are identified with a file named devicesupport.xml. It is used to find things like other tools, devices, and personalities.

Reference documents

Refer to the following documents for more information as needed:

1. Overview

The Device Configurator is part of a collection of tools included with the ModusToolbox™ software. Use the Device Configurator to enable and configure device peripherals, such as clocks and pins, as well as standard MCU peripherals that do not require their own tool.

Some complex peripherals, such as CAPSENSE™, SegLCD, etc., have specialized configuration tools, and the Device Configurator provides links to launch those separate tools (see Launch other configurators). After configuring and saving a particular device’s settings, the Device Configurator generates firmware for use in your application (see Code generation).


2. Launch the Device Configurator

You can launch the Device Configurator in various ways as described in this section; however, the tool’s configuration (design.modus) file requires an association to an application in order to obtain device configuration information.

The design.modus file contains all the required hardware configuration information about the device for the application. When you save updates, the Device Configurator generates/updates source code in the GeneratedSource directory next to the design.modus file. Applications use the design.modus file and generated source code in future application builds.

2.1 make command

As described in the ModusToolbox™ tools package user guide build system chapter, you can run numerous make commands in the application directory, such as launching the Device Configurator. After you have created a ModusToolbox™ application, navigate to the application directory and type the following command in the appropriate bash terminal window:

make device-configurator

This opens the Device Configurator using the application’s design.modus file.

2.2 Eclipse IDE

If you use the Eclipse IDE for ModusToolbox™, you can launch the Device Configurator for the selected application. In the Project Explorer, right-click on the project and select ModusToolbox™ > Device Configurator <version>. You can also click the QSPI Configurator link in the IDE Quick Panel.


Similar to the make command method, launching the Device Configurator using the Eclipse IDE opens the tool using the application’s design.modus file. Refer to the Eclipse IDE for ModusToolbox™ user guide for details about the IDE.

2.3 Executable (GUI)

If you don’t have an application or if you just want to see what the configurator looks like, you can launch the Device Configurator GUI 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:


When launched this way, the Device Configurator opens without any configuration information. You can either open a specific *.modus file or create a new one.

2.4 Open configuration file

Click File > Open and navigate to the location of the *.modus file to open. The tool may open the following dialog, indicating that it cannot find the device support library (props.json) file:


The dialog provides pointers for where you can find the appropriate file for your device. Click OK to close the dialog, and then navigate to the appropriate directory containing the props.json file.

2.5 Create new configuration

Click File > New to open the Create Design dialog, which provides fields to create new *.modus files.

To create a new *.modus file:

  1. Click the Browse [ … ] button next to File name, navigate to the location to save the new file, and enter a file name.

  2. Click the Browse [ … ] button next to Libraries, navigate to the location of the device-db props.json file, and select it. Also, find and select the appropriate PDL props.json file.

  3. Select a Device from the pull-down menu.

  4. If applicable, select one or more Additional devices from the list.

  5. Click OK to close the dialog and load the new *.modus file into the Device Configurator.


2.6 Executable (CLI)

The Device Configurator executable can be run from the command line, and it also has a “cli” version of the executable as well. Running configurator executables from the command line can be useful as part of batch files or shell scripts to re-generate the source code based on the latest configuration settings. The exit code for the executable is zero if the operation is successful, or non-zero if the operation encounters an error. For more information about the command-line options, run the executable using the -h option.

3. Quick start

This section provides a simple workflow for how to use the Device Configurator.

  1. Launch the Device Configurator.

  2. Enable a desired peripheral on the Peripherals tab by clicking the enable check box. Notice the Parameters pane becomes populated with fields.


  1. Notice also that a new task may appear in the Notice List pane.

    See Icons for descriptions of the various icons displayed in the Device Configurator.

  2. Double-click on a task to jump to the parameter that needs to be addressed.


  3. Select an appropriate parameter value and the task should be removed from the Notice List.

  4. When all tasks have been completed, select the Code Preview pane to see a preview of the code that will be generated upon saving.


  5. Use the various tabs to enable and configure other resources as needed in the same manner as peripherals.

  6. Save the *.modus file to generate source code.

    The Device Configurator generates code into a “GeneratedSource” directory in your Eclipse IDE application, or in the same location you saved the *.modus file for non-Eclipse IDE applications. That directory contains the necessary source (.c) and header (.h) files that use the relevant driver APIs to configure the hardware.

    Application code then uses this code to configure the system.

  7. Use the appropriate API in your application code.

4. Code generation

The Device Configurator generates structures, defines, and initialization code for the blocks on the chip. All generated code is located in the GeneratedSource folder next to the *.modus file. Refer to the Peripheral Driver Library (PDL) API Reference for more information about this code. Each enabled resource has a link to the specific driver documentation in the Parameters pane.


The Device Configurator generates code based on the hardware resources that are enabled. If a resource is not enabled, no configuration will be generated for it. This means the resource will retain its default reset state. In most cases, this is powered off. However, some features are enabled by default, such as debug connectivity. To disconnect these features, you must call the appropriate API functions to turn the feature off.

The defines and structures are all named based on the resource that created it. In general, these have the form <resource-name>_config. These structures can be passed to the PDL functions that are responsible for configuring the hardware block.

The functions are specific to a resource category and have names of the form init_cycfg_<resource-category>. The init function for a particular resource type is located in GeneratedSource/cycfg_<resource-category>.h. There are also the cycfg.h and cycfg.c files. Include the cycfg.h file in your application to access the generated header files. The cycfg.c file implements init_cycfg_all(), which calls all other generated functions, for example init_cycfg_pins().

The resource types include:

  • Clocks: Peripheral clocks.

  • Connectivity: Configuration of the programmable analog and digital routing resources.

  • Peripherals: Fixed function analog and digital peripherals.

  • System: Overall configuration function to setup all power and clock options.

It is up to you to make use of the generated code based on the application’s needs. This can be done as part of the application’s main() loop.

5. GUI description

The Device Configurator GUI contains menus, icons, tabs, and several panes used to configure MCU peripherals.

5.2 Device tabs

The Device Configurator can be used to configure multiple devices. All devices selected in the Create Design dialog display in top-level tabs above the Resource tabs.


All the settings for each Device tab are configured separately.


If you need to update or change devices, you must use the command line option or make changes manually by editing the makefile. You must also make changes to the BSP makefile or you will encounter build errors. The best way to change devices is to create a custom BSP. Refer to the ModusToolbox™ user guide for more details.

5.3 Resource tabs

See Resource tabs.

5.4 Panes

See Panes.

5.5 Icons

When configuring various options with this tool, you will see the following icons:


Indicates there is a tooltip. Hover over the icon to display a brief message about the setting.


Enables or disables a specific resource.


There may be occasions where an error, warning, task, or info icon displays for an enabled resource. See Notice List pane for more details.


When shown in Parameters, this indicates that it is a read-only field.

When shown for a Resource, this indicates the resource is locked and disabled. There is a tooltip explaining why the resource is locked.


When shown for a Resource, this indicates the resource is locked and enabled. There is a tooltip explaining why the resource is locked.


After assigning a signal, clicking this icon jumps to the linked resource(s).

6. Resources tabs

For most device families, the Device Configurator contains several tabs, each of which provides access to specific resources. However, for some device families, there are no separate tabs; resources are shown in a single pane, sometimes under collapsible trees.

When you enable a resource, or select an enabled resource, the Parameters pane displays various configuration options. As described under Icons, some enabled resources may contain errors, warnings, tasks, or infos that indicate some action might be required to resolve the issue. See Notice List pane for more details.


Only the tabs relevant for a selected device are displayed, so some of the tabs may not be included for some devices.

  • Peripherals – Options to enable any of the analog, digital, system, and communication hardware capabilities of the chip that are not related to the platform.

  • Pins – Options for all the pin related resources.

  • Analog-Routing – This tab shows all the analog resources, whether enabled or not, and how they connect. It also allows you to edit routes.

  • System – Options for chip-wide configuration settings such as system clocks, power management, and debug interfaces.

  • Peripheral-Clocks – Options for all the peripheral clocks.

  • DMA – Provides configuration of the DMA channel and transaction descriptors.

Each of the tabs (except the Analog-Routing tab) has the following features:

  • Filter – The Resource column shows all available resources in an expandable tree. The filter box above the list of peripherals allows you to limit the peripherals shown in the tree as well as a Hide disabled resources filter button. There are also Expand and Collapse commands.

  • Cut, Copy, Paste – Use these commands to move and copy settings from one resource of the same type to another.

    • When you use Cut, the settings will be copied to the clipboard, and the selected resource will be disabled.

    • When you use Copy, the settings will just be copied to the clipboard.

    • When you use Paste, the selected resource will be enabled if needed. The selected resource must support the same Personality name and version as the cut/copied resource.

  • Name(s) – This displays the current resource name(s). This is an editable field where you can specify optional, alternate names for this resource. This is also used in generated code.


Enter any string in this field. The tool converts the name into a legal C identifier and replaces non-legal characters with underscores. If entering more than one name, use a coma-separated list.

  • Personality – Each resource has a “Personality” file that contains the information for the given resource.

    • Some peripherals, such as Serial Communication Block (SCB) and Timer, Counter, Pulse Width Modulator (TCPWM), have a pull-down menu to select a specific personality, such as UART, SPI, or I2C.

    • Some peripherals have multiple personality versions from which you can select.

    • Some peripherals have a read-only field that only shows the name of this resource’s personality file.

6.1 Peripherals

The Peripherals tab/tree is where you enable various analog, digital, system, and communication peripherals for the device to include in your application. The filter box and the hide disabled button above the list of peripherals allows you to limit the resources shown in the tree. This tab allows you to enter one or more Names for the resource. It also shows the selected Personality, where applicable.

6.1.1 Device families with tabs


6.1.2 Device families without tabs


6.2 Pins

The Pins tab/tree is where you enable all the pin related resources. All available pins are shown in an expandable tree, arranged by port number. The filter box and the hide disabled button above the list of pins allows you to limit the pins shown in the tree. This tab allows you to enter one or more Names for the resource. It also shows the selected Personality, where applicable.

The interactive pin package diagram shows the different states of the pins; there is a legend on the diagram. You can enable/disable a pin by double-clicking it in the diagram. There are also zoom commands to resize the diagram as needed. If you zoom the image larger than the frame area, scroll bars appear to move to different area of the diagram. You can also press the [Alt] key to use the pan tool.

Pin states are shown in different colors:

  • Black – No connect

  • White – Disabled

  • Green – Enabled

  • Grey – Power/ground pins

  • Orange – Fixed function pins

  • Red – Error state

  • Semi-transparent – The hardware resource’s enabled state has been locked.

6.2.1 Device families with tabs


6.2.2 Device families without tabs


6.3 Analog-Routing tab

The Analog-Routing tab shows the various analog resources in your application. Enabled resources are green.


There are zoom commands to resize the diagram as needed. The Edit image19 command opens the Analog Route Editor.

6.3.1 Analog Route Editor

The Analog Route Editor allows you to manually edit the routing of analog resources in your application. It also provides the ability to lock-down all or some of the results.


If there are configuration errors, complete routing results will not be available; only locked resources. If you open the Analog Editor in this error state, a warning message will display. You can still lock and unlock switches, but you won’t get complete routing results as long as the configuration has errors.

image20 Select a resource

To select an analog resource, click on it. Any enabled (green) element in the tree can be selected. The resource and the associated route(s) become blue. Also, the Edit Route command appears on the toolbar. See Edit Route.


At the same time, the selected analog resource(s) is highlighted in the Nets tree.


You can also select items in the tree to highlight them in the diagram.

image23 Edit Route

With an editable analog resource selected, click the Edit Route command to enable edit mode. If multiple routes are selected, a pull-down menu displays to select the route to edit. You cannot edit multiple routes at the same time.

In edit mode, the net tree shows only the applicable route entries, and you cannot select resources using the tree. However, the lock/unlock check boxes remain enabled for use. The inactive switches change color to indicate they can be selected to use for the route being edited.

Route changes are live with updates applied automatically as you make changes. Selecting a switch adds it to the current route in a locked state and the route tree is updated to reflect the modifications.

If a change results in an error, a message displays. The routes are automatically rolled back to the previous state, so you will lose at most the last invalid change.

The toolbar shows the Finish edit command to return the editor to selection mode.


If a route is edited so that it uses switches associated with a location where no personalities are instantiated, you must manually power on the containing block at startup in order for the switches to function. Refer to the PDL API Reference Guide and the Device Technical Reference Manual for more details.

6.4 System tab

The System tab provides access to system-level items, such as system clocks, power management, and debug interfaces. All available resources are shown in an expandable tree. The filter box and the hide disabled button above the list of resources allows you to limit the items shown in the tree. This tab allows you to enter one or more Names for the resource. It also shows the selected Personality,where applicable.


The interactive clock diagram shows all the system clocks and how they connect to each other. You can enable/disable a clock by double-clicking it in the diagram. Enabled clocks are green, disabled clocks are white, and clocks in error state are red. There are also zoom commands to resize the diagram as needed.


The semi-transparent (faded) elements in the diagram indicate that their enabled state is locked.

6.5 Peripheral-Clocks tab

The Peripheral-Clocks tab lists all the clocks in a design used to drive the various peripherals. All available clocks are shown in an expandable tree. The filter box and the hide disabled button above the list of resources allows you to limit the items shown in the tree. This tab allows you to enter one or more Names for the resource. It also shows the selected Personality, where applicable.


6.6 DMA tab

The DMA tab lists all the DMA resources in the design. All available DMA channels are shown in an expandable tree. The filter box and the hide disabled button above the list of resources allows you to limit the items shown in the tree. This tab allows you to enter one or more Names for the resource. It also shows the selected Personality, where applicable.


7. Panes

The Device Configurator tool contains the following primary panes that display information based on what is selected in a particular resource tab:

  • Parameters – This pane shows the various parameters for any specific resource enabled in one of the tabs.

  • Notice List – This pane shows any errors, warnings, tasks, and infos for the application.

  • Code Preview – This pane shows a preview of the code that will be generated for the selected resource when you save the *.modus file.

7.1 Parameters pane

The Parameters pane contains all the parameters for a selected, enabled resource. This pane will show different parameters for each resource, grouped by various categories. For example, the parameters for the TCPWM peripheral are completely different than those for a pin resource. The filter box above the list of parameters allows you to limit the items shown in the pane. Some resources also provide a link to launch a separate configurator.


7.1.1 Configuration help

Nearly all resources provide a link to open the Peripheral Driver Library (PDL) documentation to the specific driver. This is the Doxygen-generated HTML file located in the installation directory. To see links to the documentation, simply highlight a resource; you do not need to enable it.

7.1.2 Parameter descriptions

As described under Icons, all parameters have a tooltip icon image28 to indicate there is information about the parameter. Hover the mouse cursor over the icon to display a description of the parameter.

7.1.3 Parameter values

Different parameter types have different ways to specify a value, as follows:

  • Pull-down Menu – For parameters with a specific set of values, use the pull-down menu to select the appropriate value.

  • Selection Box – For parameters with a variable set of values, click the ellipsis [] button to open a selection box. There, use the check boxes to select one or more appropriate values for the parameter.


After selecting these parameter types, use the Go To image29 button to jump to the selected resource.

  • Check Box – For parameters with a true or false value, use the check box to enable or disable the parameter.

  • Text Box – For parameters with editable values, type the value in the text box.


Values preceded by ‘0’ are interpreted as octal; values preceded by ‘0x’, ‘0X’, and ‘#’ are interpreted as hexadecimal.

7.1.4 Signal Select Indicators

For parameters where you select a signal, there is a pull-down menu for single-select signals and a button to open a dialog for multi-select signals.


The signals have guidance icons next to them to indicate the status of the signal, as follows:

  • Green – preferred

  • Yellow – valid

  • Red – constrained

After selecting one or more signals, use the Go To image31 button to jump to the selected signal or open a dialog to select from multiple signals.

7.1.5 Launch other configurators

For peripherals with their own configuration tools (CapSense, SegLCD, etc.), the Device Configurator provides links to launch those separate configurators. After enabling the peripheral on the Peripherals Tab, the Parameters pane contains a <Configurator> parameter, where <Configurator> is the name of the other configurator.


Click on [Launch < Configurator > …] to launch the configurator.


When launching another configurator from the Device Configurator, it passes information, such as the location of the *.modus file and any configuration data, to that other configurator. Those other configurators can be launched independently from the Device Configurator. When launched independently, you will need to either open or create the appropriate configuration file for that tool. If you want to use the configuration tools independently for the same application, make sure to save the source files in the correct “GeneratedSource” folder for the appropriate application.

7.2 Notice List

The Notice List pane combines notices (errors, warnings, tasks, and infos) from many places in your design into a centralized list. If a notice shows a location, you can double-click the entry to navigate to the error or warning.


Notices display in rows. Use the filters above the notices to show or hide different types of notices, as follows:

  • Errors – These indicate there is at least one problem that must be addressed before you can build your application. Typical errors could include compiler build errors and connectivity errors.

  • Warnings – These report unusual conditions that might indicate a problem, although you can usually build the application regardless.

  • Tasks – These are actions you need to perform to resolve an issue, such as enabling a resource. If you save without resolving a task, it becomes an error.

  • Infos – These are informational messages from the system to indicate something occurred.

The Notice List pane contains the following columns (each column header contains an arrow control to change the sorting of the notices in the table):

  • Icon – Displays the icons for the error, warning, task, or info.

  • Fix – This may display a wrench icon, which can be used to automatically address the required notice.

  • Description – Displays a brief description of the notice.

  • Location – Displays the specific line number or other location of the message, when applicable.

7.2.1 Fix a task/error

When a wrench image34 icon displays in the Fix column, click on it and select the appropriate action from the pull-down menu. When all related issues have been addressed, the notice will be removed from the Notice List pane.



The fixes listed are not necessarily the only way to fix the issue. They are merely common options. Also, if you save the *.modus file with outstanding tasks, they become errors saved in the GeneratedSource/cycfg_notices.h file.

7.2.2 Copy a notice

You can copy a notice to your system’s clipboard using [Ctrl]+[c] or right-click and select Copy. Then, paste the notice text into an email, document, and so on.

7.3 Code Preview pane

The Code Preview pane is a read-only preview of the code that will be generated for the currently selected resource when you save the *.modus file. As you update configuration options, the Code Preview pane updates the code shown. This code will be written to the appropriate file(s) located in the GeneratedSource folder of your application.


You can select and copy code from this pane using [Ctrl]+[C] key or using the right-click menu option.

You can use the Search feature to find instances of specific terms.

8. Version changes

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


Change Descriptions



New tool.


Added support for WICED Bluetooth devices.


Changed the Platform tab to System tab.

This affects the file name generated during code generation. Older versions of the Device Configurator generated cycfg_platform.(c/h) files; it now generates cycfg_system.(c/h) files. If you are updating a design from a previous version, manually remove the old cycfg_platform.(c/h) files and update any references you created to use the new file names.

Moved the Analog-Routing Editor to a tab.

Updated the File menu for library settings.

Added Update All Personalities menu item.

Added the ability to enter multiple resource Names using comma-separated list.


Added Open System Explorer menu item.

Added Change Devices menu item and dialog.

Added Undo/Redo operations to the Edit menu.

Added major/minor version number to the title bar.


Added Copy feature to the Notice List.

Added ability to see documentation links without enabling a resource.

Added frequencies to clock diagram.

Added feature to support incremental patch updates.


Added Search feature to Code Preview.

Implemented various performance improvements.

Fixed an issue with multiple font sizes in the GUI.

Fixed the PDL display name when using the MTB flow.

Updated to allow analog routing from the SAR to any analog resource or pin.


Removed Change Devices dialog.

Updated the tool to recognize obsolete devices.

Added path to files in the Code Preview Pane.

Use command line tools instead.

Displays an error in the Notice List instead of blocking the file from being opened.


Fixed the name conflict warning notices when the selected device is changed to not check against non- existent chip locations.

Added a ‘Fix’ to name conflict warnings in the notice list.

Locked down number entry to the English format (decimal place is always a period).

Made various performance improvements.

Added a search filter to the dialog that allows for the selection of multiple signals.

Added additional MPN consistency checking preprocessor macros to cyf_notices.h.

Added a log file that can be accessed from the About box. Debug messages are redirected to it.

Added back the ‘Fix’ to the MPN consistency notice.

Fixed error message displayed when the same *.modus file is opened in multiple instances of the Device-Configurator and mpn checking command line arguments are provided.


Updated back-end to support multi-core applications.

Updated Create Design dialog.

Changed device library file from xml to props.json.

Revision history






New document.



Updated to version 1.1.



Updated to version 2.0.



Updated to version 2.1.



Updated to version 2.20.



Updated to version 2.21.



Updated to version 3.0.



Updated to version 3.10.