Configurable string descriptor module

This information applies to the following SoCs: nRF52820, nRF52833, and nRF52840.

This module provides support for highly customizable, multilingual string descriptor for USB Device library.

The configuration is stored in the sdk_config.h file. In the APP_USBD section 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.

Creating descriptors from macros

You can create string descriptors from the following creation macros. They can be used interchangeably.

Macro	Description	Example
APP_USBD_STRING_DESC	Creates string descriptor from a NULL-terminated string.	APP_USBD_STRING_DESC("Nordic Semiconductor")
APP_USBD_STRING_RAW8_DESC	Creates string descriptor from raw uint8 values.	APP_USBD_STRING_RAW8_DESC(0x12, 0x34, 0x56, 0x78)
APP_USBD_STRING_RAW16_DESC	Creates string descriptor from raw uint16 values.	APP_USBD_STRING_RAW16_DESC(0x1234, 0x5678)

If more than one language is supported, every string must contain two comma-separated values. If only one string is defined, NULL is set for all other strings and the library uses the string from the default language.

All strings are held as uint8 values, which means that only ASCII characters are available. You can enable UTF-8 encoding by setting APP_USBD_CONFIG_DESC_STRING_UTF_ENABLED to 1.

Maximum string length is defined by APP_USBD_CONFIG_DESC_STRING_SIZE. It is by default set to 31, which makes it possible to use built-in transaction buffer. Any value higher than 31 creates a new buffer and increases memory consumption.

You can configure either:

• predefined standard descriptors, or
• your own user descriptors (see Configuring user descriptors).

Configuring standard descriptors

The following standard descriptors are supported:

• APP_USBD_STRINGS_MANUFACTURER - Manufacturer name
• APP_USBD_STRINGS_PRODUCT - Product name
• APP_USBD_STRING_SERIAL - Product serial number
• APP_USBD_STRINGS_CONFIGURATION - Configuration string

Set these string descriptors by Creating descriptors from macros, or by using a comma-separated list of these macros if multilingual support is used. For example:

#define APP_USBD_STRINGS_LANGIDS \
 APP_USBD_LANG_AND_SUBLANG(APP_USBD_LANG_ENGLISH, APP_USBD_SUBLANG_ENGLISH_US), \
 APP_USBD_LANG(APP_USBD_LANG_POLISH), \
 APP_USBD_LANG(APP_USBD_LANG_SWAHILI)

#define APP_USBD_STRINGS_PRODUCT \
 APP_USBD_STRING_DESC("Serial port"), \
 APP_USBD_STRING_DESC("Port szeregowy"), \
 APP_USBD_STRING_DESC("Bandari ya serial")

To set the string descriptor ID, use the following macros:

• APP_USBD_STRING_ID_MANUFACTURER
• APP_USBD_STRING_ID_PRODUCT
• APP_USBD_STRING_ID_SERIAL
• APP_USBD_STRING_ID_CONFIGURATION

Note

Setting ID to 0 disables the string.

Defining standard strings as external

Standard strings can be placed outside of the string module and saved in RAM. This enables you for example to generate a serial number based on Factory Information Configuration Registers (FICR). The USBD serial number generator uses this functionality.

Every standard string in the configuration file has an additional definition: APP_USBD_STRINGS_<string descriptor>_EXTERN. The "<string descriptor>" can be one of the following:

• MANUFACTURER
• PRODUCT
• SERIAL
• CONFIGURATION

If you set APP_USBD_STRING_<string descriptor>_EXTERN to a value other than 0, you become responsible for memory allocation and initialization of the selected string.

To define a string as external, change the define in the configuration file:

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

Note

You can replace the g_my_global_serial variable name with the name of your variable.

After changing the define in the configuration file, do one of the following in a file of your choice:

• Define the external string g_my_global_serial as ASCII:

  uint8_t g_my_global_serial[SERIAL_NUMBER_STRING_SIZE];
  
  void make_serial(void)
  {
   ... /* Filling the descriptor */
  }

• Define the external string g_my_global_serial as raw uint8 values:

  uint8_t g_my_global_serial[SERIAL_NUMBER_STRING_SIZE + 4];
  
  void make_serial(void)
  {
   /* Set two first values to 0, to differentiate from ASCII string */
   g_my_global_serial[0] = 0;
   g_my_global_serial[1] = 0;
   /* String descriptor code and descriptor size */
   g_my_global_serial[2] = sizeof(g_my_global_serial) - 2;
   g_my_global_serial[3] = APP_USBD_DESCRIPTOR_STRING;
   ... /* Filling rest of the descriptor */
  }

• Define the external string g_my_global_serial as raw uint16 values:

  uint16_t g_my_global_serial[SERIAL_NUMBER_STRING_SIZE + 2];
  
  void make_serial(void)
  {
   /* Set first value to 0, to differentiate from ASCII string */
   g_my_global_serial[0] = 0;
   /* String descriptor code and descriptor size */
   g_my_global_serial[1] = (uint16_t)APP_USBD_DESCRIPTOR_STRING << 8 |
   (sizeof(g_my_global_serial) - 2);
   ... /* Filling rest of the descriptor */
  }

Configuring user descriptors

To define your own user descriptors, use 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("User 1")) \
 X(APP_USER_2 , , APP_USBD_STRING_DESC("User 2")) \
 X(APP_USER_ID12, =12, APP_USBD_STRING_DESC("User ID12"))

This approach is universal and can be used to define any user descriptor with any identifier. For example, the WinUSB driver requires a descriptor on the 0xEE index:

X(APP_USER_WINUSB, =0xEE, APP_USBD_STRING_RAW8_DESC(0, 'M', 0, 'S', /* Driver itself*/))