µC/USB-Device is configurable at compile time via approximately 20 #defines in the application’s copy of usbd_cfg.h. µC/USB-Device uses #defines when possible, because they allow code and data sizes to be scaled at compile time based on enabled features and the configured number of USB objects. This allows the Read-Only Memory (ROM) and Random-Access Memory (RAM) footprints of µC/USB-Device to be adjusted based on application requirements.
It is recommended that the configuration process begins with the default configuration values which in the next sections will be shown in bold.
The sections in this chapter are organized following the order in µC/USB-Device’s template configuration file, usbd_cfg.h.
Core Configuration
Generic Configuration
USB Device Configuration
Interface Configuration
String Configuration
Debug Configuration
Configurations in this section only need to be set if you use the core debugging service. For more information on that service, see the Debug and Trace page.
Classes Configuration
Audio Class Configuration
Constant Description Enables or disables record. Configures the alignment in octets that audio buffers allocated for each AudioStreaming interface will use. The alignment is dependent of the peripheral used to move data between the memory and the audio peripheral. Note that this buffer alignment should be a multiple of the internal stack's buffer alignment set with the constant If the CPU cache is used with the audio buffers, If all above requirements must be taken into account, Possible Values USBD_AUDIO_CFG_PLAYBACK_ENEnables or disables playback.
DEF_ENABLED
or DEF_DISABLEDUSBD_AUDIO_CFG_RECORD_ENUSBD_AUDIO_CFG_PLAYBACK_EN and USBD_AUDIO_CFG_RECORD_EN can be DEF_DISABLED at the same time. In that case, only the AudioControl interface is active. No AudioStreaming interface can be defined. It may be useful to configure an audio device which does not interact with the host through USB for audio streaming.
DEF_ENABLED
or DEF_DISABLEDUSBD_AUDIO_CFG_FU_MAX_CTRLEnables all Feature Unit controls or disables all optional controls. When disabled, only the mute and volume controls are kept. DEF_ENABLED or
DEF_DISABLED
USBD_AUDIO_CFG_MAX_NBR_AICConfigures the maximum number of class instances. Unless you plan on having multiple configurations or interfaces using different class instances, this can be set to 1. From 1 to 254. Default value is 1 . USBD_AUDIO_CFG_MAX_NBR_CFGConfigures the maximum number of configurations in which audio class is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed. From 1 (full-speed) or 2 (high-speed) to 254. Default value is 2. USBD_AUDIO_CFG_MAX_NBR_ITConfigures the maximum number of input terminals. From 1 to 255. Default value is 2. USBD_AUDIO_CFG_MAX_NBR_OTConfigures the maximum number of output terminals. From 1 to 255. Default value is 2 . USBD_AUDIO_CFG_MAX_NBR_FUConfigures the maximum number of feature units. From 1 to 255. Default value is 2 . USBD_AUDIO_CFG_MAX_NBR_MUConfigures the maximum number of mixer units. A Mixer Unit is optional. From 0 to 255. Default value is 0 . USBD_AUDIO_CFG_MAX_NBR_SUConfigures the maximum number of selector units. A Selector Unit is optional. From 0 to 255. Default value is 0 . USBD_AUDIO_CFG_MAX_NBR_AS_IF_PLAYBACKConfigures the maximum number of playback AudioStreaming interfaces per class instance. From 1 to 255. Default value is 1 .
USBD_AUDIO_CFG_MAX_NBR_AS_IF_RECORD
Configures the maximum number of record AudioStreaming interfaces per class instance. From 1 to 255. Default value is 1 . USBD_AUDIO_CFG_MAX_NBR_IF_ALTConfigures the maximum number of operational alternate setting interfaces per AudioStreaming interface. From 1 to 255. Default value is 2 . USBD_AUDIO_CFG_CLASS_REQ_MAX_LENConfigures the maximum class-specific request playload length in bytes. Among all class-specific requests supported by Audio 1.0 class, the Graphic Equalizer control of the Feature Unit use the longest payload size for the SET_CUR request. The payload for the Graphic Equalizer control can take up to 34 bytes depending of the number of frequency bands present. If the Graphical Equalizer control is not used by any feature unit, this constant can be set to 4. Refer to audio 1.0 specification, Table 5-27 for more details about Graphic Equalizer control. From 1 to 34. Default value is 4 . USBD_AUDIO_CFG_BUF_ALIGN_OCTETSUSBD_CFG_BUF_ALIGN_OCTETS as the audio buffers are passed to the USB device controller that can also have its alignment requirement. If your platform does not require buffer alignment, this should be set to USBD_AUDIO_CFG_BUF_ALIGN_OCTETS.USBD_AUDIO_CFG_BUF_ALIGN_OCTETS should also take into account the cache line size requirement. To sum up, the value of USBD_AUDIO_CFG_BUF_ALIGN_OCTETS is influenced by:USBD_AUDIO_CFG_BUF_ALIGN_OCTETS will be the worst case among all alignment requirements.Typically 1, 2, 4 or 8. Default value is
USBD_CFG_BUF_ALIGN_OCTETS
.USBD_AUDIO_CFG_PLAYBACK_FEEDBACK_ENEnables or disables the playback feedback support. If an isochronous OUT endpoint using the asynchronous synchronization is associated to an AudioStreaming interface, you need to set
DEF_ENABLED
to enable the feedback support. Refer to section Playback Feedback Correction for more details about the audio feedback.DEF_ENABLED or
DEF_DISABLED
USBD_AUDIO_CFG_PLAYBACK_CORR_ENEnables or disables built-in playback stream correction. DEF_ENABLED or
DEF_DISABLED
USBD_AUDIO_CFG_RECORD_CORR_ENEnables or disables built-in record stream correction. DEF_ENABLED or
DEF_DISABLED
USBD_AUDIO_CFG_STAT_ENEnables or disables audio statistics for playback and record. DEF_ENABLED or
DEF_DISABLED
Communication Device Class Configuration
Some constants are available to customize the CDC base class. These constants are located in the USB device configuration file, usbd_cfg.h. Table - CDC Class Configuration Constants shows their description.Constant Description Possible Values USBD_CDC_CFG_MAX_NBR_DEVConfigures the maximum number of class instances. Each associated subclass also defines a maximum number of subclass instances. The sum of all the maximum numbers of subclass instances must not be greater than USBD_CDC_CFG_MAX_NBR_DEV.From 1 to 254. Default value is 1. USBD_CDC_CFG_MAX_NBR_CFGConfigures the maximum number of configurations in which CDC class is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed. From 1 (low- and full-speed) or 2 (high-speed) to 254. Default value is 2. USBD_CDC_CFG_MAX_NBR_DATA_IFConfigures the maximum number of Data interfaces. From 1 to 254. The default value is 1.
CDC Abstract Control Model Serial Class Configuration
usbd_cfg.h.Constant Description Possible Values USBD_ACM_SERIAL_CFG_MAX_NBR_DEVConfigures the maximum number of subclass instances. The constant value cannot be greater than USBD_CDC_CFG_MAX_NBR_DEV. Unless you plan on having multiple configurations or interfaces using different class instances, this can be set to the default value.From 1 to USBD_CDC_CFG_MAX_NBR_DEV. Default value is 1.
Communication Device Class Ethernet Emulation Model Subclass Configuration
There are various configuration constants necessary to customize the CDC EEM subclass. These constants are located in the usbd_cfg.h file. Table - CDC EEM Configuration Constants shows a description of each constant.Constant Description Possible Values USBD_CDC_EEM_CFG_MAX_NBR_DEVConfigures the maximum number of class instances. Unless you plan having multiple configuration or interfaces using different class instances, this should be set to 1. From 1 to 254. Default value is 1. USBD_CDC_EEM_CFG_MAX_NBR_CFGConfigures the maximum number of configuration in which CDC EEM is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed. From 1 (full-speed) or 2 (high-speed) to 254. Default value is 2. USBD_CDC_EEM_CFG_RX_BUF_LENConfigures the length, in octets, of the buffer(s) used to receive the data from the host. This buffer must ideally be a multiple of the max packet size of the endpoint. However, most of the time this can be set to the Ethernet Maximum Transmit Unit (MTU -> 1518) + 2 for the CDC EEM header for better performances. 64 or more. Multiple of maximum packet size if below (MTU + 2). Default value is 1520. USBD_CDC_EEM_CFG_ECHO_BUF_LENConfigures the length, in octets, of the echo buffer used to transmit an echo response command upon reception of an echo command from the host. Size of this buffer depends on the largest possible echo data that can be sent by the host. Higher than 2. Default value is 64. USBD_CDC_EEM_CFG_RX_BUF_QTY_PER_DEV (optional)Configures the quantity of receive buffers to be used to receive data from the host. It is not mandatory to set the value in your usbd_cfg.h file. Before setting this value to something higher than 1, you MUST ensure that you USB device driver supports URB queuing. You must also correctly configure the constant USBD_CFG_MAX_NBR_URB_EXTRA. Increasing this value will improve the data reception performances by providing multiple buffering mechanism.1 or more. Default value is 1.
Human Interface Device Class Configuration
The HID class uses an internal task to manage periodic input reports. The task priority and stack size shown in Table - HID Internal Task’s Configuration Constants are defined in the application configuration file, Constant Description Possible Values USBD_HID_CFG_MAX_NBR_DEVConfigures the maximum number of class instances. Unless you plan on having multiple configurations or interfaces using different class instances, this can be set to the default value. From 1 to 254. Default value is 1. USBD_HID_CFG_MAX_NBR_CFGConfigures the maximum number of configurations in which HID class is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed. From 1 (low- and full-speed) or 2 (high-speed) to 254. Default value is 2. USBD_HID_CFG_MAX_NBR_REPORT_IDConfigures the maximum number of report IDs allowed in a report. The value should be set properly to accommodate the number of report ID to be used in the report. From 1 to 65535. Default value is 1. USBD_HID_CFG_MAX_NBR_REPORT_PUSHPOPConfigures the maximum number of Push and Pop items used in a report. If the constant is set to 0, no Push and Pop items are present in the report. From 0 to 254. Default value is 0. app_cfg.h. Refer to the HID Periodic Input Reports Task page for more details about the HID internal task.Constant Description Possible Values USBD_HID_OS_CFG_TMR_TASK_PRIOConfigures the priority of the HID periodic input reports task. From the lowest to the highest priority supported by the OS used. USBD_HID_OS_CFG_TMR_TASK_STK_SIZE
Configures the stack size of the HID periodic input reports task. The required size of the stack can greatly vary depending on the OS used, the CPU architecture, the type of application, etc. Refer to the documentation of the OS for more details about tasks and stack size calculation. From the minimal to the maximal stack size supported by the OS used.
Mass Storage Class Configuration
There are various configuration constants necessary to customize the MSC device. These constants are located in the usbd_cfg.h file. Table - MSC Configuration Constants shows a description of each constant. Since MSC device relies on a task handler to implement the MSC protocol, this OS-task’s priority and stack size constants need to be configured if µC/OS-II or µC/OS-III RTOS is used. Moreover if Constant Description Possible Values USBD_MSC_CFG_MAX_NBR_DEVConfigures the maximum number of class instances. Unless you plan having multiple configuration or interfaces using different class instances, this should be set to 1. From 1 to 254. Default value is 1. USBD_MSC_CFG_MAX_NBR_CFGConfigures the maximum number of configuration in which MSC is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed. From 1 (low- and full-speed) or 2 (high-speed) to 254. Default value is 2. USBD_MSC_CFG_MAX_LUNConfigures the maximum number of logical units. From 1 to 255. Default value is 1. USBD_MSC_CFG_DATA_LENConfigures the read/write data length in octets. Higher than 0. The default value is 2048. USBD_MSC_CFG_FS_REFRESH_TASK_ENEnables or disables the use of a task in µC/FS storage layer for removable media insertion/removal detection. If only fixed media such as RAM, NAND are used, this constant should be set to DEF_DISABLED. Otherwise, DEF_ENABLED should be set.DEF_ENABLED or DEF_DISABLED USBD_MSC_CFG_DEV_POLL_DLY_mSConfigures the period of the µC/FS storage layer’s task. It is expressed in milliseconds. If USBD_MSC_CFG_FS_REFRESH_TASK_EN is set to DEF_DISABLED, this constant has no effect. A faster period may improve the delay to detect the removable media insertion/removal resulting in a host computer displaying the removable media icon promptly. But the CPU will be interrupted often to check the removable media status. A slower period may result in a certain delay for the host computer to display the removable media icon. But the CPU will spend less time verifying the removable media status.The default value is 100 ms. USBD_MSC_CFG_FS_REFRESH_TASK_EN is set to DEF_ENABLED, the µC/FS storage layer task’s priority and stack size need also to be configured. These constants are summarized in Table - MSC OS-Task Handler Configuration Constants.Constant Description Possible Values USBD_MSC_OS_CFG_TASK_PRIOMSC task handler’s priority level. The priority level must be lower (higher valued) than the start task and core task priorities. From the lowest to the highest priority supported by the OS used. USBD_MSC_OS_CFG_TASK_STK_SIZEMSC task handler’s stack size. The required size of the stack can greatly vary depending on the OS used, the CPU architecture, the type of application, etc. Refer to the documentation of the OS for more details about tasks and stack size calculation. From the minimal to the maximal stack size supported by the OS used. Default value is set to 256. USBD_MSC_OS_CFG_REFRESH_TASK_PRIOµC/FS storage layer task’s priority level. The priority level must be lower (higher valued) than the MSC task. From the lowest to the highest priority supported by the OS used. USBD_MSC_OS_CFG_REFRESH_TASK_STK_SIZEµC/FS storage layer task’s stack size. The required size of the stack can greatly vary depending on the OS used, the CPU architecture, the type of application, etc. Refer to the documentation of the OS for more details about tasks and stack size calculation. From the minimal to the maximal stack size supported by the OS used. Default value is set to 256.
Personal Healthcare Device Class Configuration
Some constants are available to customize the class. These constants are located in the If using µC/OS-II or µC/OS-III RTOS port, enable or disable the scheduler feature. You should set it to If you set QoS based scheduler’s task priority. You must ensure that the scheduler’s task has a lower priority (i.e. higher priority value) than any task writing PHDC data.usbd_cfg.h file. Table - Configuration Constants Summary shows a description of each of them.Constant Description Possible Values USBD_PHDC_CFG_MAX_NBR_DEVConfigures the maximum number of class instances. Unless you plan on having multiple configuration or interfaces using different class instances, this can be set to 1. From 1 to 254. Default value is 1. USBD_PHDC_CFG_MAX_NBR_CFGConfigures the maximum number of configuration in which PHDC is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed. Default value is 2. From 1 (low- and full-speed) or 2 (high-speed) to 254. Default value is 2. USBD_PHDC_CFG_DATA_OPAQUE_MAX_LENMaximum length in octets that opaque data can be. Equal or less than MaxPacketSize - 21. Default value is 43. USBD_PHDC_OS_CFG_SCHED_ENDEF_DISABLED if the device only uses one QoS level to send data, for instance. (See the PHDC RTOS QoS-based scheduler page). If you set USBD_PHDC_OS_CFG_SCHED_EN to DEF_ENABLED and you use a µC/OS-II or µC/OS-III RTOS port, PHDC will need an internal task for the scheduling operations. There are two application specific configurations that must be set in this case. They should be defined in the app_cfg.h file.DEF_ENABLED, you must ensure that the scheduler’s task has a lower priority (i.e., higher priority value) than any task that can write PHDC data.
DEF_ENABLED
or DEF_DISABLEDUSBD_PHDC_OS_CFG_SCHED_EN to DEF_ENABLED and you use a µC/OS-II or µC/OS-III RTOS port, PHDC will need an internal task for the scheduling operations. There are two application specific configurations that must be set in this case. They should be defined in the app_cfg.h file. Table - Application-Specific Configuration Constants describes these configurations.Constant Description Possible Values USBD_PHDC_OS_CFG_SCHED_TASK_PRIOFrom the lowest to the highest priority supported by the OS used. USBD_PHDC_OS_CFG_SCHED_TASK_STK_SIZEQoS based scheduler’s task stack size. The required size of the stack can greatly vary depending on the OS used, the CPU architecture, the type of application, etc. Refer to the documentation of the OS for more details about tasks and stack size calculation. From the minimal to the maximal stack size supported by the OS used. Default value is 512.
Vendor Class Configuration
Some constants are available to customize the class. These constants are located in the USB device configuration file, Configures the maximum number of Microsoft extended properties that can be defined per Vendor class instance. For more information on Microsoft OS descriptors and extended properties, refer to the Microsoft Hardware Dev Center .usbd_cfg.h. Table - General Configuration Constants Summary shows their description.Constant Description Possible Values USBD_VENDOR_CFG_MAX_NBR_DEVConfigures the maximum number of class instances. Unless you plan on having multiple configurations or interfaces using different class instances, this can be set to 1. From 1 to 254. Default value is 1. USBD_VENDOR_CFG_MAX_NBR_CFGConfigures the maximum number of configuration in which Vendor class is used. Keep in mind that if you use a high-speed device, two configurations will be built, one for full-speed and another for high-speed. From 1 (low- and full-speed) or 2 (high-speed) to 254. Default value is 2. USBD_VENDOR_CFG_MAX_NBR_MS_EXT_PROPERTYFrom 1 to 255. Default value is 1.