This information applies to the nRF52840 SoC only.

This module provides highly customisable, multilingual string descriptor module.

The configuration is stored in the app_usbd_string_config.h file. In the top of the file, a list of supported languages must be defined. Use the values defined in app_usbd_langid.h. The first defined language is always the default one.

To create string descriptors, use the APP_USBD_STRING_DESC macro. If more than one language is supported, every string should contain two comma-separated values. If only one string is defined, NULL will be set for all other strings and the library will use the string from the default language.

Standard descriptors

Standard descriptors supported:

APP_USBD_STRINGS_MANUFACTURER - Manufacturer name
APP_USBD_STRINGS_PRODUCT - Product name
APP_USBD_STRING_SERIAL - Product serial number

Any of these string descriptors may be set using APP_USBD_STRING_DESC or a comma-separated list of these macros, if multilingual support is used. For example:

#define APP_USBD_STRINGS_LANGIDS \
 ((uint16_t)APP_USBD_LANG_ENGLISH | (uint16_t)APP_USBD_SUBLANG_ENGLISH_US), 
 ((uint16_t)APP_USBD_LANG_POLISH),
#define APP_USBD_STRINGS_PRODUCT \
 APP_USBD_STRING_DESC('S', 'e', 'r', 'i', 'a', 'l', ' ', 'p', 'o', 'r', 't'),
 APP_USBD_STRING_DESC('P', 'o', 'r', 't', ' ', 's', 'z', 'e', 'r', 'e', 'g', 'o', 'w', 'y')

Internal or external definition

Standard strings can be simply placed outside of the string module. This allows for generating a serial number. The USB CDC ACM Example uses this functionality.

Every standard string in a configuration file, has an additional definition in the form of: APP_USBD_STRINGS_<string>_EXTERN. If you set this macro to a value other than 0, then you will be responsible for memory allocation and initialisation of the selected string. Use it in the following way:

/** The mnemonic of a globally available serial variable */
#define APP_USBD_STRING_SERIAL g_my_global_serial.
#define APP_USBD_STRING_SERIAL_EXTERN 1

In another file:

uint16_t g_my_global_serial[SERIAL_NUMBER_STRING_SIZE + 1];
void make_serial(void)
{
 /* String descriptor code and descriptor size */
 g_my_global_serial[0] = (uint16_t)APP_USBD_DESCRIPTOR_STRING << 8 |
 sizeof(g_my_global_serial);
 ... /* Filling the descriptor */
}

User descriptors

It is also possible to declare any number of user descriptors. You can define them using the X macro technique. See the following example of declaring three user descriptors, one of which has an ID that equals 12:

#define APP_USBD_STRINGS_USER \
 X(APP_USER_1 , , APP_USBD_STRING_DESC('U', 's', 'e', 'r', ' ', '1'))
 X(APP_USER_2 , , APP_USBD_STRING_DESC('U', 's', 'e', 'r', ' ', '2'))
 X(APP_USER_ID12, =12, APP_USBD_STRING_DESC('U', 's', 'e', 'r', ' ', 'I', 'D', '1', '2'))

It is universal enough to define any user descriptor with any identifier. For example, the WinUSB driver requires a descriptor to be present on the 0xEE index:

X(APP_USER_WINUSB, =0xEE, APP_USBD_STRING_DESC('W', 'i' /* Driver itself*/))