ModusToolbox™ USB Configurator user guide

ModusToolbox™ tools package version 3.0.0

USB Configurator version 2.50

About this document

Scope and purpose

The USB Configurator main use is to create device descriptor configuration and generate code with the descriptor tables as part of the device firmware.

Intended audience

This document helps application developers understand how to use the USB 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

The following define the abbreviations and terms used in this document:

  • API – application programming interface

  • BOS – binary device object store

  • CDC – communication device class

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

  • Descriptor – A defined-format data structure used by USB devices to report their attributes to a USB host or in other words a piece of stored data that indicates how other data is stored.

  • Endpoint – A uniquely addressable portion of a USB device that is the source or sink of information in a communication flow between the host and device.

  • HID – human interface device

  • USB – universal serial bus device

Reference documents

Refer to the following documents for more information as needed:

About this document

1 Overview

The Universal serial bus (USB) Configurator is a stand-alone tool included with the ModusToolbox™ software to configure USB device descriptors. See the Supported descriptors section for a list of supported USB descriptors. After configuring and saving a USB device descriptor, the USB Configurator generates configuration files that store USB device descriptors and other information (see Code generation) used by the USB device middleware configuration and operation.


1.1 Supported middleware



USB device middleware library

h ttps://

2 Launch the USB Configurator

There are several ways to launch the USB Configurator, and those ways depend on how you use the various tools in ModusToolbox™.

2.1 make command

As described in the ModusToolbox™ user guide Build System” chapter, you can run numerous make commands in the application directory, such as launching the USB 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 usbdev-configurator

This command opens the application USB Configurator GUI for an existing USB configuration (.*cyusbdev) file.

If there is no *. cyusbdev file, then this command launches the USB Configurator with default configuration. Open an existing *. cyusbdev file or create a new one for the application in which you want to configure the USB Configurator.

2.2 Eclipse IDE

If there is a *.cyusbdev file in the application folder, you can launch the USB Configurator GUI directly from the Eclipse IDE using any of the following methods:

  • Double-click on the *.cyusbdev file in the application.

  • Right-click on the top-level application folder, and select ModusToolbox™ > USB Configurator.

  • Click on the USB Configurator link in the Quick Panel.

Refer to the Eclipse IDE for ModusToolbox™ user guide for more details.


If there is no * .cyusbdev file in the application folder, the options from the menu and Quick Panel read the USB Configurator (new configuration). Select either option, and the USB Configurator opens with default configuration (*.cyusbdev) that will be saved to the design.cyusbdev file in the application folder. Refer to the USB device middleware library for more details about this code.

2.3 Executable (GUI)

Also, you can simply launch the USB 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:


On Windows, launch the tool from the Start menu. For other operating systems, navigate to the install location and run the executable. The USB Configurator opens with an untitled configuration file (*.cyusbdev). Save it as a new file and provide a file name, or open another existing *.cyusbdev file.

2.4 Executable (CLI)

You can run the usbdev-configurator executable from the command line. There is also a usbdev-configurator-cli executable, which re-generates the source code based on the latest configuration settings from a command- line prompt or from within batch files or shell scripts. The exit code for the usbdev-configurator-cli executable is zero if the operation is successful, or non-zero if the operation encounters an error. To use the usbdev- configurator-cli executable, you must provide at least the –config argument with a path to the configuration file.

For more information about the command-line options, run the usbdev-configurator or usbdev-configurator-cli executable using the -h option.

3 Quick start

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

  1. Launch the USB Configurator.

  2. Configure the device descriptors hierarchy in the Device Descriptor Tree pane.


  1. Configure device descriptor parameters in the Parameters pane.


  1. The Parameters pane contains a subpane for HID descriptor (HID Report pane).


  1. Save the configuration. See Code generation.

  2. Use the generated structures as input parameters for functions in your application.

4 Code generation

The USB Configurator generates header (.h) and source (.c) files that contain relevant firmware used by the USB Device middleware configuration and operation. The firmware contains arrays to store USB Device descriptors, structures that help the middleware to access descriptors, middleware and classes configuration structures, and a set of defines. The generated files cycfg_usbdev.h and cycfg_usbdev.c are located in the GeneratedSource folder next to the *. cyusbdev file.

Refer to the USB device middleware library for more information about this code.

5 GUI description

The USB Configurator GUI contains menus, toolbars, panes, and a subpane used to configure device descriptors.

6 Toolbars

Provides the basic buttons from the Menus to create, open, edit, and save files.


Also, the descriptor toolbar provides buttons to configure the descriptors hierarchy:

  • Add new descriptor – Click this button to create a new descriptor.

  • Delete selected descriptor – Removes the selected descriptor.

  • Import descriptor – Select a descriptor from the pull-down menu to transfer it into the configuration.

  • Expand all tree items – Clicking this button displays all the items in the Device Descriptors Tree.

  • Collapse all tree items – Clicking this button leaves only the Device Descriptors Tree visible.

  • Move up – Shifts up the selected descriptor.

  • Move down – Shifts down the selected descriptor.

6.2 HID Report toolbar

The HID Report toolbar provides the buttons to configure an HID descriptor report.


  • Add HID report item – Creates a new HID report item.

  • Delete HID report item – Removes the selected HID report item.

  • Load HID report – Opens an HID report file into the current HID Descriptor.

  • Import HID report – Transfers an HID report item into the configuration for the current HID Descriptor.

  • Move up HID report item – Shifts up an IDHIFDHID report item.

  • Move down HID report item – Shifts down an IDHIFDHID report item.

6.3 Array editor toolbar

The Array editor toolbar provides the buttons to edit array elements.


  • Add new element – Creates a new element.

  • Delete element – Removes the selected element.

  • Move up element – Shifts up an element.

  • Move down element – Shifts down an element.

7 Panes

The USB Configurator contains two panes that display information about descriptors and their parameters:

7.1 Device Descriptors Tree pane

This pane shows the descriptors hierarchy:

  • All the descriptors have their own hierarchy that can be created when their parent is selected. However, the Device Descriptors Tree is the root descriptor.

  • This pane shows the descriptors hierarchy:

To add specific descriptors, for example, CDC Interface descriptor or HID descriptor, add a special parent descriptor

  • Add CDC interface descriptor for CDC descriptor

  • Add HID alternate settings for HID descriptor.

7.2 Parameters pane

This pane shows configuration information for the selected descriptor.


The Parameters pane has different controls to edit different parameters (text box, combo box, or multi-line text box). Most parameters have a text box as the editing control.

  • Vendor-defined items – Some string parameters or HID report items, such as iSerialNumber, have a combo box with a list of predefined items. The “Empty” value is selected by default. To specify a value that is not on the list, select “Vendor-defined.” The combo box will change to a text box to type an appropriate value. To return to the combo box, erase the value and leave the control.

  • String pool – Parameters such as iChannelNames in AC Processing Unit of Audio Interface descriptor 1.0 support a string pool and require a multi-line text box. To insert several strings, use an end-line separator.

  • Read-only parameters – There are two types of read-only parameters: predefined bDescriptorType or auto- calculated bConfigurationValue.

  • Array parameters – Parameters such as bSubordinateInterface in union with Communication Alternate Settings is an array. Use “;” to separate elements. Also, you can open the Array editor dialog to set the parameters using the [ … ] button.

  • Hexadecimal/Decimal – When a value starts with “0x,” it is parsed as a hexadecimal value. Otherwise, it is parsed as a decimal.

  • Map and bit fields – Some parameters, such as bmAttributes, are read-only by themselves. However, you can insert them using the related bit fields below them in the parameters list. The bit fields size is 0B. Their name starts with the name of a field whole part, plus the bits for which they are responsible. For example, bmAttributes(1-0): Transfer Type.

8 Notice List

The Notice List combines notices (errors, warnings, tasks, and notes) from many places in the configuration into a centralized list. If a notice shows a location, double-click the entry to show the error or warning. Also, you can read an error message in a tooltip.


When you try to save the configuration with errors, a message shows the problem to fix.

9 Supported descriptors

All supported descriptors are described by USB Implementers Forum, Inc. You can find more details at

The supported descriptors:

  • Device, Configuration, IAD (Interface association descriptor), Interface, Endpoint descriptors, Endpoint Companion descriptors

  • Device descriptor (Billboard), Device Qualifier descriptor

  • Audio Interface descriptor 1.0 and 2.0

  • CDC Interface descriptor

  • HID descriptor and HID Report descriptor

  • BOS descriptors:

    • USB 2.0 Extension descriptors

    • Container ID Descriptor

    • Billboard Capability Descriptor

    • Billboard Alternate Mode Capability Descriptor

    • SuperSpeed Device Capability Descriptor

    • SuperSpeedPlus Device Capability Descriptor

    • PTM Capability Descriptor

  • MS OS String descriptor


The Interface Descriptor is represented by the two items to build a tree structure: Interface Descriptor with an empty parameters pane and Alternate Settings with all Interface Descriptor parameters.


Class-Specific AS Encoder/Decoder Descriptors from USB Audio v2.0 are not supported.

10 Known issues, limitations, and workarounds

The USB Configurator supports import from the HID Descriptor tool. Current version 2.40 contains an error related to strings. Per spec HID1.11, string items have such values:

  • String Index 0111 10 nn

  • String Minimum 1000 10 nn

  • String Maximum 1001 10 nn

However, the HID Descriptor tool generates:

  • String Index 0110 10 nn

  • String Minimum 0111 10 nn

  • String Maximum 1000 10 nn

Before importing, fix these items manually in the file generated with the HID descriptor tool.

11 Version changes

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


Change descriptions


New tool.


Updated the icons to be standard. Added Notice List.


Changed the user configuration storage location from the header file to the *.cyusbdev file.

Added New, Save As, Reset View commands. Changed the Load command to Open.

Updated the icons.

Removed the CUSTOM item from HID Report.

Removed the functionality to launch the USB Configurator from the Device Configurator.


Added the Undo/Redo feature.


Updated versioning to support patches.

Added Copy feature to the Notice List.

Added the calculation of the Endpoint Address for a new Endpoint Number.


Removed the command-line generate options: -g and –generate.


Added Device Descriptor Tree as the root element.

Added: Device Qualifier Descriptor with Other_Speed_Configuration Descriptor, Billboard Capability Descriptor, and Billboard Alternate Mode Capability Descriptor.

Added an Array Editor dialog for array fields.

Updated the GUI by moving to Qt-5.15.2

Removed: the migration of configuration to the current XML format – configuration saved in the comments in generated HEADER files (the old method).


Added SuperSpeed Device Capability Descriptor, SuperSpeedPlus Device Capability Descriptor, PTM Capability Descriptor, SuperSpeed Endpoint Companion Descriptor, SuperSpeedPlus Isochronous Endpoint Companion Descriptor.

Updated Array Editor.

Changed the device library file from xml to props.json.

Revision history






New document.



Updated to version 1.10.



Updated to version 2.10.



Updated to version 2.10.



Updated to version 2.20.



Updated to version 2.30.



Updated to version 2.40.



Updated to version 2.50.