 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The USBXTM Device Class Human Interface Design (HID) module provides a high-level API for HID applications and configures the USBX Device Class HID Source, USBX Host Configuration, USBX Source and USBX Port HCD. The USBX Device Class HID module uses the USB peripheral on the Synergy MCU.
Unsupported Features
USBX composite device class supports only CDC-CDC and CDC-MSC device class.
The USB Device Class HID module allows a USB host system to communicate with the device as a keyboard device, a mouse device and other HID devices. This class is based on the USB standard and is a subset of the HID standard. The USBX Device Class HID module includes the following key features:
The USBX Device Class HID module defines APIs for sending and receiving HID events and reports. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.
USBX Device Class HID Module Summary
| Function Name | Example API Call and Description |
|---|---|
| ux_device_class_hid_event_set | ux_device_class_hid_event_set (hid, &hid_event);This function is called when an application needs to send a HID event to the host. |
| ux_device_class_hid_event_get | ux_device_class_hid_event_get (hid, & hid_event);This function is called when an application needs to receive a HID event from the host. |
| ux_device_class_hid_report_set | ux_device_class_hid_report_set (hid, descriptor_type, request_index, host_length);This function is called when an application needs to send a HID report to the host. |
| ux_device_class_hid_report_get | ux_device_class_hid_report_get (hid, descriptor_type, request_index, host_length);This function is called when an application needs to receive a HID report to the host. |
Status Return Values
| Name | Description |
|---|---|
| UX_SUCCESS | The data transfer was completed. |
| UX_TRANSFER_TIMEOUT | Transfer timeout, reading/writing not completed. |
| UX_MEMORY_INSUFFICIENT | Not enough memory. |
| UX_HOST_CLASS_UNKNOWN | Wrong class instance. |
| UX_FUNCTION_NOT_SUPPORTED | Unknown IOCTL function. |
Initialization of USBX Resources
The USBX has its own memory manager. The memory needs to be allocated to the USBX before the host or device side of the USBX is initialized. The USBX memory manager can accommodate systems where memory can be cached.
Definition of USB Host Controllers
It is required to define at least one USB host controller for USBX to operate in host-mode. The application-initialization file should contain this definition. SSP defines USB host controller when USB host controller driver is added to thread stacks.
Definition of Device Classes
It is required to define one or more device classes(s) with the USBX. A USB class is required to drive a USB device after the USB stack has configured the USB device. A USB class is very specific to the device; one or more classes may be required to drive a USB device depending on the number of interfaces contained in the USB device descriptors.
USB Class Binding
When the device is configured, the topology manager will let the class manager continue the device discovery by looking at the device-interface descriptors. A device can have one or more interface descriptors.
An interface represents a function in a device. For instance, a USB speaker has three interfaces, one for audio streaming, one for audio control, and one to manage the various speaker buttons.
The class manager has two mechanisms to join the device interface(s) to one or more classes. It can either use the combination of a PID/VID (product ID and vendor ID) found in the interface descriptor or the combination of Class/Subclass/Protocol.
The PID/VID combination is valid for interfaces that cannot be driven by a generic class. The Class/Subclass/Protocol combination is used by interfaces that belong to a USB-IF certified class such as a printer, hub, storage, audio, or Human Interface Design (HID).
The class manager contains a list of registered classes from the initialization of the USBX. The class manager will call each class one-at-a-time until one class accepts to manage the interface for that device; each class can only manage one interface. In the case of the USB audio speaker, the class manager will call all the classes for each of the interfaces.
Once a class accepts an interface, a new instance of that class is created; the class manager will then search for the default alternate setting for the interface. A device may have one or more alternate settings for each interface. The alternate setting 0 will be the one used by default until a class decides to change it.
For the default alternate setting, the class manager will mount all the endpoints contained in the alternate setting. If the mounting of each endpoint is successful, the class manager will complete its job by returning to the class that will finish the initialization of the interface.
The USBX Device stack or USBX Host stack consumes RAM for the control block. The Synergy Configuration tool allocates memory to the USBX memory pool statically in the auto-generate code as shown in the following table. You need to set the appropriate memory size in bytes to the USBX Pool Memory Size property of the USBX on ux component in the Synergy Configuration tool in section "USBX on ux Configuration." If multiple classes are used, set the total memory size to the property.
Memory (RAM) Requirements for the USBX Memory Pool
| USBX Class | S1 Parts | Other Parts |
|---|---|---|
| USBX Device HID (ux_device_class_hid) | 6.1KB + (Add the additional memory as per Note*1). | 12KB + (Add the additional memory as per Note*1). |
Note: If HID event buffer value is increased to large value, Application stack size and USBX thread stack size(USBX Source >> Common >> Stack size for USBX threads) need to increase.
UX_THREAD_STACK_SIZE: 512 (bytes) for S1 parts; 2048 (bytes) for the other parts
_ux_system_slave; sends and receives executed using this instance.This section describes how to include the USBX Device Class HID Module in an application using the SSP configurator.
To add the USBX Device Class HID Module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
USBX Device Class HID Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_ux_device_class_hid USBX Device Class HID | Threads | New Stack> X-Ware> USBX> Device > Classes > HID > USBX Device Class HID |
When the USBX Device Class HID Module is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.
The USBX Device Class HID Module must be configured by the user for the desired operation. The SSP configuration window automatically identifies (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules for successful operation. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.
Configuration Settings for the USBX Device Class HID Module
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_ux_device_class_hid | Specify the name of USBX Interface Descriptor for HID Class. It must be a valid C symbol. |
| USBX Device HID Entry Function | ux_device_class_hid_entry | Specify the name of a user callback function to get an event from HID Class. Name must be a valid C symbol. Refer to the USBX Stack User's Manual "Chapter 5: USBX Device Class Considerations USB Device HID Class" for more information about the user callback function. |
| USBX Device HID User Callback Function | ux_hid_device_callback | Specify the name of user entry function for the USBX Device HID Class module. Name must be a valid C symbol. See the USBX Stack User's Manual "Chapter 5: USBX Device Class Considerations USB Device HID Class" for more information about the user entry function. |
| USBX Device HID GetReport Callback Function | NULL | Specify the name of user entry function for the USBX Device HID Class module. Name must be a valid C symbol. See the USBX Stack User's Manual "Chapter 5: USBX Device Class Considerations USB Device HID Class" for more information about the user entry function. |
| USBX Device HID Instance Activate Callback Function | NULL | Specify the name of instance_activate user callback function for the USBX Device HID Class module. Name must be a valid C symbol. See the USBX Stack User's Manual "Chapter 5: USBX Device Class Considerations USB Device HID Class" for more information about the instance_activate callback function. |
| USBX Device HID Instance Deactivate Callback Function | NULL | Specify the name of instance_deactivate user callback function for the USBX Device HID Class module. Name must be a valid C symbol. Refer to the USBX Stack User's Manual "Chapter 5: USBX Device Class Considerations USB Device HID Class" for more information about the instance_activate callback function. |
| Multiple HID Report Support | Enable, Disable Default: Disable | Set Enable to support multiple HID report. This configuration is used to indicate which data fields are represented in each report structure. |
| Name of generated initialization function | ux_device_class_hid_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
Note: Most of the property settings for lower-level modules are intuitive and usually can be determined by inspection of the associated properties window from the SSP configurator.
Only a small number of settings must be modified from the default for the IP layer and lower-level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and are locked to prevent user modification. The following table identifies all the settings within the properties section for the module:
Configuration Settings for the USBX Device Class HID Source
| ISDE Property | Value | Description |
|---|---|---|
| USBX Device HID Event Buffer Length | Value must be greater than or equal to 32. Default : 64 | UX_DEVICE_CLASS_HID_EVENT_BUFFER_LENGTH Defines the size of Event Buffer Length. if the event buffer length value is more than 256. Slave request control maximum length value have to increase more than Event buffer length value. in USBX source module. (USBX Source: Property >> common >> Slave Request Control Maximum Length). |
| Maximum number of USBX Device HID Event queue. | Value must be greater than or equal to 16. Default: 16. | 'UX_DEVICE_CLASS_HID_MAX_EVENTS_QUEUE' This value represents the maximum number of hid event queue, in the USBX Device hid class driver. |
| Device HID Interrupt Out Support | Enabled, Disabled Default: Disabled | UX_DEVICE_CLASS_HID_INTERRUPT_OUT_SUPPORT When enabled, device HID interrupt OUT transfer is supported. |
| Device HID Zero Copy | Enabled, Disabled Default: Disabled | UX_DEVICE_CLASS_HID_ZERO_COPY Defined, it enables device HID zero copy and flexible queue support (works if HID owns endpoint buffer). |
| Show linkage warning | Enabled, Disabled Default: Enabled | Notification message for users will be shown if "Enabled" option is selected. This is just to warn users possible linkage errors by multiple symbol definitions. Select "Disabled" stops the notification message. |
Configuration Settings for the USBX Device Configuration Instance
| ISDE Property | Value | Description |
|---|---|---|
| Vendor ID | 0x045B | Specify Vendor ID assigned by USB-IF. This configuration is a part of the USB Device Descriptor (idVendor). |
| Product ID | 0x0000 | Specify Product ID assigned by manufacturer. This configuration is a part of the Device Descriptor (idProduct). |
| Device Release Number | 0x0000 | Specify Device Release Number in binary-coded decimal. This configuration is a part of the USB Device Descriptor (bcdDevice). |
| Index of Manufacturing String Descriptor | 0x00 | Specify the Index of Manufacturer String Descriptor defined in the USBX String Framework. This configuration is a part of the USB Device Descriptor (iManufacturer). Set zero if String Descriptor is not used. See section USBX-String-Framework-Configuration for more information. |
| Index of Product String Descriptor | 0x00 | Specify the Index of Product String Descriptor defined in the USBX String Framework. This configuration is a part of the USB Device Descriptor (iProduct). Set zero if String Descriptor is not used. See section "USBX String Framework Configuration" for more information. |
| Index of Serial Number String Descriptor | 0x00 | Specify the Index of Serial Number String Descriptor defined in the USBX String Framework. This configuration is a part of the USB Device Descriptor (iSerialNumber). Set zero if the String Descriptor is not used. See section "USBX String Framework Configuration" for more information. |
| Class Code | Communications(CDC), HID, Mass Storage, Miscellaneous, Vendor specific Default: Communications(CDC) | Select the USB Device Class Code. This configuration is a part of the USB Configuration Descriptor (bDeviceClass). |
| Index of String Descriptor describing this configuration | 0x00 | Specify the Index of String Descriptor describing this configuration. This configuration is a part of the USB Configuration Descriptor (iConfiguration). Set zero if String Descriptor is not used. See section "USBX String Framework Configuration" for more information. |
| Size of USB Descriptor in bytes for this configuration (Modify this value only for Vendor-specific Class, otherwise set zero) | 0x00 | Specify the size of USB Descriptor in bytes. Modify the value for Vendor-specific Class, otherwise you can set zero to calculate the size automatically in the auto-generated code from Synergy Configuration tool. This configuration is a part of the USB Configuration Descriptor (wTotalLength). |
| Number of Interfaces (Modify this value only for Vendor-specific Class, otherwise set zero) | 0x00 | Specify the Number of interfaces supported by this configuration. Modify the value for Vendor-specific Class, otherwise you can set zero to calculate the value automatically in the auto-generated code from Synergy Configuration tool. This configuration is a part of the USB Configuration Descriptor (bNumInterfaces). |
| Self-Powered | Enable, Disable Default: Enable | Enable this configuration if your USB Device is a self- powered device. This configuration is a part of the USB Configuration Descriptor (bmAttributes bit6). |
| Remote Wakeup | Enable, Disable Default: Disable | Enable this configuration if your USB Device supports remote wakeup. This configuration is a part of the USB Configuration Descriptor (bmAttributes bit5). |
| Maximum Power Consumption (in 2mA units) | 50 | Set the maximum power consumption of your device to indicate the amount of bus power required. This configuration is 2mA units, thus, the maximum 500 mA can be specified. This configuration is a part of the USB Configuration Descriptor (bMaxPower). |
| Supported Language Code | 0x0409 | Specify the Language ID Code. For example, 0x0409 English - United States. This configuration is used for Language ID Framework code generation. See section "USBX Language Framework Configuration" for more information. |
| Name of USBX String Framework | NULL | Specify the name of user defined USBX String Framework. This must be a valid C symbol. Set NULL if the String Descriptor is not used. See section "USBX String Framework Configuration" for more information. |
| Total index number of USB String Descriptors in USB String Framework | 0 | Specify the total number of index for String Descriptor. See section "USBX String Framework Configuration" for more information. |
| Name of USBX Language Framework | NULL | Specify the name of user defined USBX Language Framework. This must be a valid C symbol. If '0' is set to the property "Total Number of Language Support", this configuration is ignored. See section "USBX Language Framework Configuration" for more information. |
| Number of Languages to support (US English is applied if zero is set) | 0 | Specify the total number of languages to support. See section "USBX String Framework Configuration" for more information. If '0' is set here, US English (0x0409) is applied as the default language. |
| Name of generated initialization function | ux_device_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
Configuration Settings for the USBX Interface Configuration HID Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_usb_interface_descriptor_hid0 | Specify the name of USBX Interface Descriptor for CDC-ACM. It must be a valid C symbol. |
| Protocol code (None(0) /Keyboard(1) /Mouse(2)/Keyboard+Mouse(3)) | 0x00 | Both the keyboard and mouse interface will be available only if Keyboard+Mouse(3) protocol is selected. Select device class as Device (0x00) in device configuration when protocol selected is (Keyboard+Mouse). |
| (Keyboard) Interface Number of HID Class interface | 0x00 | Keyboard Interface will be available for use when protocol code selected is either Keyboard(1) or Keyboard+Mouse(3). |
| (Keyboard) Endpoint Number to be used for Interrupt-In | Endpoint 1-9 Default: Endpoint 1 | Specify the Endpoint Number of Interrupt-In Endpoint. It must not be duplicated with ones for the other Endpoints. |
| (Keyboard) Maximum packet size in bytes for Interrupt-In | 0x8 | Specify the maximum packet size this endpoint is capable of sending or receiving when this configuration is selected. |
| Interval for polling Interrupt-In EP for data transfers (milliseconds) | 0x8 | Specify the Interval for polling Endpoint transfers. This configuration is valid for Interrupt-In Endpoint. Value is in frame counts (1ms units for FS mode and 125us units for HS mode). |
| (Keyboard) Interrupt-Out Endpoint (Optional) | Enable, Disable Default: Disable | This configuration is reserved and currently not used. |
| Endpoint Number for Interrupt-Out (Optional) | Endpoint 1-9 Default: Endpoint 3 | This configuration is reserved and currently not used. |
| (Keyboard) Maximum packet size in bytes for Interrupt-Out EP (Optional) | 0x8 | This configuration is reserved and currently not used. |
| (Keyboard) Interval for polling Interrupt-Out EP for data transfers (milliseconds) (Optional) | 0x8 | This configuration is reserved and currently not used. |
| (Mouse) Interface Number of HID Class interface | 0x01 | Mouse Interface will be available for use when protocol code selected is either Mouse(2) or Keyboard+Mouse(3). |
| (Mouse) Endpoint Number to be used for Interrupt-In | Endpoint 1-9 Default: Endpoint 2 | Specify the Endpoint Number of Interrupt-In Endpoint. It must not be duplicated with ones for the other Endpoints. |
| (Mouse) Maximum packet size in bytes for Interrupt-In | 0x8 | Specify the maximum packet size this endpoint is capable of sending or receiving when this configuration is selected. |
| Interval for polling Interrupt-In EP for data transfers (milliseconds) | 0x8 | Specify the Interval for polling Endpoint transfers. This configuration is valid for Interrupt-In Endpoint. Value is in frame counts (1ms units for FS mode and 125us units for HS mode). |
| (Mouse) Interrupt-Out Endpoint (Optional) | Enable, Disable Default: Disable | This configuration is reserved and currently not used. |
| Endpoint Number for Interrupt-Out (Optional) | Endpoint 1-9 Default: Endpoint 4 | This configuration is reserved and currently not used. |
| (Mouse) Maximum packet size in bytes for Interrupt-Out EP (Optional) | 0x8 | This configuration is reserved and currently not used. |
| (Mouse) Interval for polling Interrupt-Out EP for data transfers (milliseconds) (Optional) | 0x8 | This configuration is reserved and currently not used. |
Configuration Settings for the USBX Port DCD on sf_el_ux for USBFS
| ISDE Property | Value | Description |
|---|---|---|
| Full Speed Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled | Select the interrupt priority for full-speed USB. |
| LDO Regulator (Only for S3 and S1 part MCUs) | Enable, Disable Default: Disable | Select the LDO regulator will be enabled. |
| Name | g_sf_el_ux_dcd_fs_0 | Module name. |
| USB Controller Selection | USBFS | Select the USB controller. |
Configuration Settings for the USBX Port DCD on USBHS
| ISDE Property | Value | Description |
|---|---|---|
| High Speed Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX), Disabled Default: Disabled | Select the interrupt priority for high speed USB. |
| Name | g_sf_el_ux_dcd_hs_0 | Module name. |
| USB Controller Selection | USBHS | Select the USB controller. |
Configuration Settings for the USBX on ux Instance
| ISDE Property | Value | Description |
|---|---|---|
| USBX Pool Memory Name | g_ux_pool_memory | Name must be a valid C symbol. |
| USBX Pool Memory Size | 18432 | See section "Azure RTOS USBX Memory Requirements" for the required memory size for each classes. |
| User Callback for Host Event Notification (Only valid for USB Host) | NULL | Name must be a valid C symbol. The name of User defined USBX Host event notification can be given to this property. |
| User Callback for Device Event Notification (Only valid for USB Device) | NULL | Name must be a valid C symbol. The name of User defined USBX Device event notification can be given to this property. |
| Name of generated initialization function | ux_common_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
The USB peripheral module uses the UCLK as its clock source; the UCLK should be configured for 48MHz operation. In the SSP configuration window, select the Clocks tab to view the clock-source setting.
The USB peripheral module uses MCU pins to communicate with external devices. Select I/O pins and configure to the external device requirements. The following table lists the pin selection method within the SSP Configuration Window and the subsequent tables demonstrate the selection process using USB pins as an example.
USBFS and USBHS Pin Selection Sequence
| Resource | ISDE Tab | Pin selection Sequence |
|---|---|---|
| USBFS | Pins | Select Peripherals > Connectivity: USBFS> USBFS0 |
| USBHS | Pins | Select Peripherals > Connectivity: USBHS> USBHS0 |
USBHS Pin Configuration Settings
| Property | Value | Description |
|---|---|---|
| Operation Mode | Disabled, Custom, Device, Host, OTG Default: Custom | Select device as the Operation Mode |
| USBDP | USBDP | USBDP pin |
| USBDM | USBDM | USBDM pin |
| OVRCURB | None | OVRCURB pin |
| OVRCURA | None | OVRCURA pin |
| VBUSEN | None | VBUSEN pin |
| VBUS | None, P407 Default: P407 | VBUS pin |
| EXICEN | None | EXICEN pin |
| ID | None | ID Pin |
| VCCUSB | VCCUSB | VCCUSB pin |
| VSSUSB | VSSUSB | VSSUSB pin |
USBHS Pin Configuration Settings
| Property | Value | Description |
|---|---|---|
| Operation Mode | Disabled, Custom, Device, Host, OTG Default: Custom | Select Device as the Operation Mode |
| USBHSDP | USBHSDP | USBHSDP pin |
| USBHSDM | USBHSDM | USBHSDM pin |
| OVRCURB | None | OVRCURB pin |
| OVRCURA | None | OVRCURA pin |
| VBUSEN | PB00 | VBUSEN pin |
| VBUS | PB01 | VBUS pin |
| EXICEN | None | EXICEN pin |
| ID | None | ID pin |
| USBHSRREF | USBHSRREF | USBHSRREF pin |
| AVCCUSBHS | AVCCUSBHS | AVCCUSBHS pin |
| AVSSUSBHS | AVSSUSBHS | AVSSUSBHS pin |
| PVSSUSBHS | PVSSUSBHS | PVSSUSBHS pin |
| VCCUSBHS | VCCUSBHS | VCCUSBHS pin |
| VSS1USBHS | VSS1USBHS | VSS1USBHS pin |
| VSS2USBHS | VSS2USBHS | VSS2USBHS pin |
The configurator generates processing to create and register the USBX Device Class HID module; however, communication must be done after the device is connected to the host.
The typical steps in using the USBX Device Class HID module in an application are:
1. Get the ux_system_slave slave device pointer
2. Wait until slave device's ux_slave_device_state is configured
3. For HID event sending, use the ux_device_class_hid_event_set API
4. For received HID event reading, use the ux_device_class_hid_event_get API
5. For HID report sending, use the ux_device_class_hid_report_set API
6. For received HID report reading, use the ux_device_class_hid_report_get API
These common steps are illustrated in a typical operational flow diagram in the following figure:
