 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The USBX™ Host Class HID module provides a high-level API for human interface device (HID) applications and configures the USBX Host Class HID Source, USBX Host Configuration, USBX Source and USBX Port HCD. The USBX Host Class HID module uses the USB peripheral on the Synergy MCU.
The USBX Host Class Human Interface Device (HID) module supports the USBX HID class. It provides the following features:
The USBX Host Class HID module defines APIs for registering callbacks, starting and stopping periodic reports and reporting gets and sets. 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 Host Class HID Module Summary
| Function Name | Example API Call and Description |
|---|---|
| ux_host_class_hid_report_callback_register | ux_host_class_hid_report_callback_register(hid, &call_back);This function is used to register a callback from the HID class to the HID client when a report is received. |
| ux_host_class_hid_periodic_report_start | ux_host_class_hid_periodic_report_start(hid);This function is used to start the periodic (interrupt) endpoint for the instance of the HID class that is bound to this HID client. |
| ux_host_class_hid_periodic_report_stop | ux_host_class_hid_periodic_report_stop(hid);This function is used to stop the periodic (interrupt) endpoint for the instance of the HID class that is bound to this HID client. |
| ux_host_class_hid_report_get | ux_host_class_hid_report_get(hid, &client_report);This function is used to receive a report directly from the device without relying on the periodic endpoint. |
| ux_host_class_hid_report_set | ux_host_class_hid_report_set(hid, &client_report);This function is used to send a report directly to the device. |
| ux_host_class_hid_keyboard_key_get | ux_host_class_hid_keyboard_key_get(keyboard_instance, &keyboard_char, &keyboard_state);This function is used to read the keyboard data received from the device. |
| ux_host_class_hid_mouse_buttons_get | ux_host_class_hid_mouse_buttons_get(&mouse_instance, &mouse_buttons);This function is used to read the mouse button information received from the device. |
| ux_host_class_hid_mouse_position_get | ux_host_class_hid_mouse_position_get(mouse_instance, &x_position, &y_position);This function is used to read the position information of the mouse received from the device. |
| ux_host_class_hid_remote_control_usage_get | ux_host_class_hid_remote_control_usage_get(remote_control_instance, &usage, &value);This function is used to read the remote controller information received from the device. |
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 Host HID (ux_host_class_hid) | N/A | HID Mouse: 38KB HID Keyboard: 46KB |
The memory size of the USBX Host HID as shown in the table above is with the following configurations (default settings) being made. The size can be reduced if the Source module is used.
UX_THREAD_STACK_SIZE: 512(bytes) for S1 parts; 2048(bytes) for the other parts
This section describes how to include the USBX Host Class HID Module in an application using the SSP configurator.
To add the USBX Host Class HID Module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
USBX Host Class HID Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_ux_host_class_hid0 USBX Host Class HID | Threads | New Stack> X-Ware> USBX> Host > Classes > HID > USBX Host Class HID |
When the USBX Host 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 Host 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 Host Class HID Module
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_ux_host_class_hid0 | Specify the name of USBX Host Mass HID module instance. It must be a valid C symbol. |
| HID Client - Keyboard Support | Enable, Disable Default: Enable | Set Enable to support USB keyboard devices. This configuration registers the USBX HID Keyboard Client. |
| HID Client - Mouse Support | Enable, Disable Default: Enable | Set Enable to support USB mouse devices. This configuration registers the USBX HID Mouse Client. |
| HID Client - Remote Control Support | Enable, Disable Default: Enable | Set Enable to support USB remote control devices. This configuration registers the USBX Remote Control Client. |
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 Host Class HID Source
| ISDE Property | Value | Description |
|---|---|---|
| HID Keyboard Thread Priority | Value must be greater than 0 or empty Default: 20 | UX_THREAD_PRIORITY_KEYBOARD Define the priority of the HID keyboard thread. |
| Memory size for HID Report Decompression | Value must be greater than 0 or empty Default: 4096 | UX_HOST_CLASS_HID_DECOMPRESSION_BUFFER Define the memory size to build a decompressed report |
| Number of Entries for HID Local Usage Item Table | Value must be greater than 0 or empty Default: 1024 | UX_HOST_CLASS_HID_USAGES Define the size of HID local usage item table. One item entry consumes 4 bytes. |
| Host HID Interrupt Out Support | Enabled, Disabled Default: Disabled | UX_HOST_CLASS_HID_INTERRUPT_OUT_SUPPORT When enabled, host HID interrupt OUT transfer is supported. |
| HID report transfer timeout | Value must be greater than 0 or empty Default: 10000 | UX_HOST_CLASS_HID_REPORT_TRANSFER_TIMEOUT When set, this represents the HID report transfer timeout value in millisecond. |
| 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 Host Configuration Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_ux_host0 | Specify the name of USBX Host Configuration instance. It must be a valid C symbol. |
| Name of generated initialization function | ux_host_hid_init0 | Name of generated initialization function selection. |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection. |
Configuration Settings for the USBX Port HCD 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. |
| VBUSEN pin Signal Logic | Active Low, Active High Default: Active High | Select the VBUSEN pin signal logic. |
| 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_hcd_fs_0 | Module name. |
| USB Controller Selection | USBFS | Select the USB controller. |
Configuration Settings for the USBX Port HCD on sf_el_ux for 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. |
| FIFO size for Bulk/Isochronous Pipes | 512, 1024, 1536, 2048 bytes Default: 512 bytes | Select the FIFO size for bulk and isochronous transfers. |
| Number of Isochronous Pipes Reserved | 0,1,2 Default: 0 | Select the number of isochronous pipes to reserve. |
| VBUSEN pin Signal Logic | Active Low, Active High Default: Active High | Select the VBUSEN pin signal logic. |
| Enable High Speed | Enable, Disable Default: Enable | Select if high speed should be enabled. |
| Name | g_sf_el_ux_hcd_hs_0 | Module name. |
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. |
| 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 Host Class HID Module; however, communication must be done after the Host is connected to the host.
The typical steps in using the USBX Host Class HID Module in an application are:
1. Get the first instance of the connected device with the ux_host_stack_class_instance_get API.
2. Wait for ux_success.
3. Wait for device status live.
4. Wait for client instance live.
5. If the Device is a keyboard.
6. Receive keyboard data using the ux_host_class_hid_keyboard_key_get API.
7. If the Device is a mouse.
8. Receive mouse data using the ux_host_class_hid_mouse_buttons_get API and ux_host_class_hid_mouse_position_get API.
9. If the Device is a remote controller.
10. Receive remote controller data using the ux_host_class_hid_remote_control_usage_get API.
These common steps are illustrated in a typical operational flow diagram in the following figure:
