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.
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:
The following standard descriptors are supported:
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:
To set the string descriptor ID, use the following macros:
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:
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:
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:
g_my_global_serial
as ASCII: g_my_global_serial
as raw uint8 values: g_my_global_serial
as raw uint16 values: 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:
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: