USB Host Class Drivers#

The USB Host module offers several class drivers that allow you to provide support for a broad range of USB devices. In this section, each of the class drivers will be explained.

• USB Host Android Accessory Class Driver

• USB Host CDC Base Class Driver

• USB Host CDC ACM Class Driver

• USB Host HID Class Driver

• USB Host MSC Class Driver

• USB Host USB-to-Serial Class Driver

USB Host Android Accessory Class Driver#

The Android Accessory class driver provided by Micrium OS USB Host is a class driver that will handle any Android devices (v3.1 and higher). It will switch them to the "Accessory Mode" and offers raw communication APIs to communicate with an embedded Android application.

The class driver implementation complies with AOAv1 as described here:https://source.android.com/devices/accessories/aoa.html.

USB Host Android Accessory Class Example Applications#

Accessory Example#

This example represents a template that you can use to start the development of your Android Accessory class project. When using this application, any Android devices connected to the host that supports the Android Open Accessory Protocol will be switched to the accessory mode.

The application offers blank functions that you can use to implement the communication with the Android device.

Location#

The example implementation is located in /examples/usb/host/ex_usbh_aoap_accessory.c.

API#

This example offers only one API named Ex_USBH_AOAP_Init(). This function is normally called from a USB host core example.

USB Host Android Accessory Class Programming Guide#

• Prerequisites

• Initializing the USB Host Android Accessory Class Driver

• Using USB Host Android Accessory Class Application Functions

  • Conn

  • Disconn

• Communicating Using the USB Host Android Accessory Class Driver

Prerequisites#

The following compile-time configurations from the USB Host core are required for this class driver to work properly.

Reference: USB Host Compile-Time Configurations .

• USBH_CFG_FIELD_EN_MASK: The following fields must be stored: USBH_CFG_FIELD_EN_DEV_VENDOR_ID and USBH_CFG_FIELD_EN_DEV_PRODUCT_ID.

Initializing the USB Host Android Accessory Class Driver#

In order to support the Android function connections, you must first initialize the class driver. This is done by calling the function USBH_AOAP_Init().

Listing - Example of call to USBH_AOAP_Init() in the USB Host Android Accessory Class Programming Guide page shows an example of a call to USBH_AOAP_Init() using default arguments. For more information on the configuration arguments to pass to USBH_AOAP_Init(), see USB Host Android Accessory Class Configuration .

Listing - Example of call to USBH_AOAP_Init()#

USBH_AOAP_APP_FNCTS  App_USBH_AOAP_Fncts = {
    .Conn    = App_USBH_AOAP_Conn,
    .Disconn = App_USBH_AOAP_Disconn
}

void  App_USBH_AOAP_Init()
{
    RTOS_ERR           err;
    USBH_AOAP_STR_CFG  aoap_str_cfg;

    aoap_str_cfg.AccStrManufacturer    = "Micrium inc";
    aoap_str_cfg.AccStrManufacturerLen =  11u;
    aoap_str_cfg.AccStrModel           = "AOAP demo";
    aoap_str_cfg.AccStrModelLen        =  9u;
    aoap_str_cfg.AccStrDescription     = "AOAP application for demonstration purposes";
    aoap_str_cfg.AccStrDescriptionLen  =  43u;
    aoap_str_cfg.AccStrVersion         = "1.0";
    aoap_str_cfg.AccStrVersionLen      =  3u;
    aoap_str_cfg.AccStrURI             = "www.micrium.com";
    aoap_str_cfg.AccStrURI_Len         =  15u;
    aoap_str_cfg.AccStrSerial          = "123456789";
    aoap_str_cfg.AccStrSerialLen       =  9u;

    USBH_AOAP_Init(&aoap_str_cfg,
                   &App_USBH_AOAP_Fncts,
                   &err);
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occurred. Error handling should be added here. */
    }
}

Using USB Host Android Accessory Class Application Functions#

The Android Accessory class driver provides two callback functions that will be called on connection and disconnection of an Android device.

These callbacks can have multiple purposes. Some of these include:

• Provide handles on the Android function to your application

• Execute some event driven simple task

• Trigger another task in your application

• Etc.

Below is a description of each of the available callback functions.

Conn#

This function is called when an Android function is connected. It will provide all the necessary handles on the Android function to your application. Your application can also use it to return a pointer to an application object that is linked to this particular Android function. This pointer will be passed to any other callback function that is related to the Android function.

Listing - Example of implementation of Conn function in the USB Host Android Accessory Class Programming Guide page shows an example of implementation of the Conn callback function.

Listing - Example of implementation of Conn function#

void  *App_USBH_AOAP_Conn(USBH_DEV_HANDLE        dev_handle,
                          USBH_FNCT_HANDLE       fnct_handle,
                          USBH_AOAP_FNCT_HANDLE  aoap_fnct_handle)
{
    /* An Android function was connected. aoap_fnct_handle should be saved in your application for later use. */

    /* You can allocate an object that will be linked to this Android function. */

    /* You can trigger one of your application task form here. */

    return (<pointer to application object>);   /* DEF_NULL can be returned as well. */
}

Disconn#

This function is called when an Android function is disconnected.

Listing - Example of implementation of Disconn function in the USB Host Android Accessory Class Programming Guide page shows an example of implementation of the Conn callback function.

Listing - Example of implementation of Disconn function#

void  App_USBH_AOAP_Disconn(USBH_AOAP_FNCT_HANDLE   aoap_fnct_handle,
                            void                   *p_arg)
{
    /* An Android function was disconnected. */

    /* p_arg is the pointer you returned in the Conn function associated to this function. */
    /* You can free the object if necessary.                                               */

    /* You can trigger one of your application task form here. */
}

Communicating Using the USB Host Android Accessory Class Driver#

The Android Accessory Protocol does not define any data format for communication. So it is your responsibility to define one that will be understood by both your embedded and Android applications.

The USB Host Android Accessory class driver provides two raw communication functions: USBH_AOAP_AccDataRx() and USBH_AOAP_AccDataTx(). These functions will block until the data transfer is completed.

Listing - Simple loopback communication example in the USB Host Android Accessory Class Programming Guide page shows a simple example of a loopback communication.

Listing - Simple loopback communication example#

void  App_USBH_AOAP_CommLoopback ()
{
    CPU_INT32U  xfer_len;
    CPU_INT08U  simple_buf[64u];
    RTOS_ERR    err;

                                                         /* Receive data from Android function.  */
    xfer_len = USBH_AOAP_AccDataRx(aoap_fnct_handle,
                                   simple_buf,
                                   64u,
                                   5000u,
                                  &err);
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occurred. Error handling should be added here. */
    }

                                                         /* Send back data to Android function.  */
    (void)USBH_AOAP_AccDataTx(aoap_fnct_handle,
                              simple_buf,
                              xfer_len,
                              5000u,
                             &err);
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occurred. Error handling should be added here. */
    }
}

USB Host Android Accessory Class Configuration#

• AOAP initialization

  • p_str_cfg

  • p_app_fncts

• Optional Configurations

  • Buffer Alignment

  • Memory Segments

  • Optimize Speed Quantities

  • Allocation at initialization quantities

• Post-Init Configurations

  • Standard Requests Timeout

This section defines the configurations related to Micrium OS USB Host Android Accessory Class driver that are specified at run-time.

AOAP initialization#

Initializing the USB Host Android Accessory class driver module of Micrium OS is done by calling the function USBH_AOAP_Init(). This function takes two configuration arguments that are described here.

p_str_cfg#

p_str_cfg is a pointer to a configuration structure of type USBH_AOAP_STR_CFG. Its purpose is to inform the USB Host Android Accessory class driver module on Android Accessory descriptive Strings.

Note that all the descriptive strings MUST have a persistent storage.

Table - USBH_AOAP_STR_CFG configuration structure in the USB Host Android Accessory Class Configuration page describes each configuration field available in this configuration structure.

Table - USBH_AOAP_STR_CFG configuration structure#

p_app_fncts#

p_app_fncts is a pointer to a structure of type USBH_AOAP_APP_FNCTS. Its purpose is to provide a set of application callbacks to be called when an Android Accessory function is connected and when it is disconnected. For more information on these callbacks, see USB Host Android Accessory Class Programming Guide .

The sections below describe each configuration field available in this configuration structure.

.Conn#

An Android Accessory function was connected. This function provides the handles that were associated to it to your application.

Listing - .Conn function signature#

void *App_USBH_AOAP_Conn (USBH_DEV_HANDLE dev_handle, USBH_FNCT_HANDLE fnct_handle, USBH_AOAP_FNCT_HANDLE aoap_fnct_handle)

.Disconn#

An Android Accessory function was disconnected. Once you return from this function, the handles passed at the Conn function for this Android Accessory function won't be valid anymore.

Listing - .Disconn function signature#

void App_USBH_AOAP_Disconn(USBH_AOAP_FNCT_HANDLE aoap_fnct_handle, void *p_arg)

Optional Configurations#

This section describes the configurations that are optional. If you do not set them in your application, the default configurations will apply.

The default values can be retrieved via the structure USBH_AOAP_InitCfgDflt.Note that these configurations must be set before you call the function USBH_AOAP_Init().

Buffer Alignment#

This module allocates some buffers used for data transfers with the devices. You may have a specific need of address alignment for these buffers depending on your USB controller. If you use more than one USB controller, you must set the alignment to the largest value.

Memory Segments#

This module allocates some control data and buffers used for data transfers with the devices. It has the ability to use a different memory segment for the control data and for the data buffers.

Optimize Speed Quantities#

This configuration is mandatory IF you set USBH_CFG_OPTIMIZE_SPD_EN to DEF_ENABLED and therefore USBH_AOAP_ConfigureOptimizeSpdCfg() must be called from your application.

When the optimize speed mode is enabled, you have to provide further information to this module. In this case, this module will use indexes and arrays to retrieve its internal objects from your handles instead of browsing through a list. This configuration tells the size of each of these tables.This configuration is available only when USBH_CFG_OPTIMIZE_SPD_EN is set to DEF_ENABLED.

Allocation at initialization quantities#

This configuration is mandatory IF you set USBH_CFG_INIT_ALLOC_EN to DEF_ENABLED and therefore USBH_AOAP_ConfigureInitAllocCfg() must be called from your application.

When this module allocates all its objects at initialization, it must know how many objects of each type it must allocate. This configuration tells the number of objects to allocate.This configuration is available only when USBH_CFG_INIT_ALLOC_EN is set to DEF_ENABLED.

Post-Init Configurations#

This section describes the configurations that can be set at any time during execution AFTER you called the function USBH_AOAP_Init().

These configurations are optional. If you do not set them in your application, the default configurations will apply.

Standard Requests Timeout#

Timeout, in milliseconds, for the standard requests executed by this module.

USB Host Android Accessory Class Configuration For Speed Optimization#

If you set USBH_CFG_OPTIMIZE_SPD_EN to DEF_ENABLED, you will have to provide additional information to the USB host Android Accessory class driver module. In this case, it will use indexes and arrays to retrieve its internal objects from your handles instead of browsing through a list. Hence, it is necessary to know the size of these tables.

Table - USBH_AOAP_CFG_OPTIMIZE_SPD configuration structure in the USB Host Android Accessory Class Configuration For Speed Optimization page describes each configuration field available in this configuration structure.

Table - USBH_AOAP_CFG_OPTIMIZE_SPD configuration structure#

USB Host Android Accessory Class Configuration For Allocation at Initialization#

If you set USBH_CFG_INIT_ALLOC_EN to DEF_ENABLED, you will have to provide additional information to the USB host Android Accessory class driver module. In this case, it will allocate all its objects at initialization and will be unable to allocate more objects during execution. Hence, you must provide the number of each object type to allocate. This greatly depends on your needs and on the USB devices you plan to use.

Table - USBH_AOAP_CFG_INIT_ALLOC configuration structure in the USB Host Android Accessory Class Configuration For Allocation at Initialization page describes each configuration field available in this configuration structure.

Table - USBH_AOAP_CFG_INIT_ALLOC configuration structure#

USB Host CDC Base Class Driver#

The CDC base class driver provided with Micrium OS USB Host is a class driver that handles any CDC devices for which a subclass driver is implemented.

The class driver implementation complies with the "Universal Serial Bus Class Definitions for Communication Devices",_revision_1.2,_November_3,_2010.

USB Host CDC Base Class Programming Guide#

• Prerequisites

• Initializing the Class Driver

  • Class Driver Initialization

  • Class Driver Post-Initialization

• Communicating Using the Class Driver

Prerequisites#

The following compile-time configurations in the USB Host core are required for this class driver to work properly.

Reference: USB Host Compile-Time Configurations .

• USBH_CFG_FIELD_EN_MASK: Following fields must be stored: USBH_CFG_FIELD_EN_IF_CLASS, USBH_CFG_FIELD_EN_IF_SUBCLASS and USBH_CFG_FIELD_EN_IF_PROTOCOL.

• USBH_CFG_PERIODIC_XFER_EN: Must be set to DEF_ENABLED if USBH_CDC_CFG_NOTIFICATIONS_RX_EN is set to DEF_ENABLED.

Initializing the Class Driver#

Class Driver Initialization#

In order to support the connections of CDC functions, you must first initialize the class driver. To do this, you call the function USBH_CDC_Init().

Listing - Example of call to USBH_CDC_Init() in the USB Host CDC Base Class Programming Guide page shows an example of a call to USBH_CDC_Init() using default arguments. For more information on the configuration arguments to pass to USBH_CDC_Init(), see USB Host CDC Base Class Configuration .

Listing - Example of call to USBH_CDC_Init()#

void  App_USBH_CDC_Init()
{
    RTOS_ERR  err;

    USBH_CDC_Init(&err);
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occurred. Error handling should be added here. */
    }

    :
    :

Class Driver Post-Initialization#

Once the CDC class driver has been initialized, it is time to initialize all the CDC subclass driver(s). For more information on how to initialize your CDC subclass, refer to its section in USB Host Class Drivers.

Once, and only once you initialized all your CDC subclass driver(s), you must complete the initialization of the CDC base class driver. This is done by calling the function USBH_CDC_PostInit().

Listing - Example of call to USBH_CDC_PostInit() in the USB Host CDC Base Class Programming Guide page gives an example of a call to USBH_CDC_PostInit().

Listing - Example of call to USBH_CDC_PostInit()#

:

    /* TODO: Initialize all your CDC subclass driver(s).    */

    :
    :

    USBH_CDC_PostInit(&err);
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occurred. Error handling should be added here. */
    }
}

Communicating Using the Class Driver#

The CDC base class driver is not meant to be used directly to communicate with a device via your application. You should always use a subclass driver (such as CDC ACM). For more information on how to communicate using your CDC subclass driver(s), refer to its section in USB Host Class Drivers .

USB Host CDC Base Class Configuration#

• Compile-Time Configurations

• Run-Time Configurations

  • Class Driver Initialization

  • Optional Configurations

    • Buffer Alignment

    • Event URB Quantity

    • Memory Segments

    • Optimize Speed Quantities

    • Allocation at Initialization Quantities

• Post-Init Configurations

  • Standard Requests Timeout

This section describes the configurations related to Micrium OS USB Host CDC Class driver.

Compile-Time Configurations#

The CDC class driver is configurable at compile time via one #define located in the usbh_cfg.h file.

We recommend that you begin the configuration process with the default configuration values, which in the next sections will be shown in bold.

Table - CDC Class Driver Compile-time Configurations in the USB Host CDC Base Class Configuration page describes the configuration.

Table - CDC Class Driver Compile-time Configurations#

Run-Time Configurations#

Class Driver Initialization#

To initialize the USB Host CDC class driver module you call the function USBH_CDC_Init(). This function takes no configuration argument.

Optional Configurations#

This section describes the configurations that are optional. If you do not set them in your application, the default configurations will apply. The default values can be retrieved via the structure USBH_CDC_InitCfgDflt.

Buffer Alignment#

This module allocates buffers used for data transfers with the devices. You may have a specific need for address alignment for these buffers depending on your USB controller. If you use more than one USB controller, you must set the alignment to the largest value.

Event URB Quantity#

Configures the number of event URBs to allocate and submit to the device. The more URBs submitted, the better will be the responsiveness to CDC events.

Memory Segments#

This module allocates control data and buffers used for data transfers with the devices. It has the ability to use a different memory segment for the control data and for the data buffers.

Optimize Speed Quantities#

This configuration is mandatory if you set USBH_CFG_OPTIMIZE_SPD_EN to DEF_ENABLED. Consequently, USBH_CDC_ConfigureOptimizeSpdCfg() must be called from your application.

When optimize speed mode is enabled, you must provide additional information to this module. The module will use indexes and arrays to retrieve its internal objects from your handles instead of browsing through a list. This configuration specifies the size of each of these tables.

Allocation at Initialization Quantities#

This configuration is mandatory if you set USBH_CFG_INIT_ALLOC_EN to DEF_ENABLED . Consequently, USBH_CDC_ConfigureInitAllocCfg() must be called from your application.

When this module allocates its objects at initialization, it must know how many objects of each type to allocate. This configuration specifies the number of objects to allocate.

Post-Init Configurations#

This section describes the configurations that can be set at any time during execution after you called the function USBH_CDC_Init().

These configurations are optional. If you do not set them in your application, the default configurations will apply.

Standard Requests Timeout#

Timeout, in milliseconds, for the standard requests executed by this module.

USB Host CDC Base Class Configuration for Speed Optimization#

If you set the configuration USBH_CFG_OPTIMIZE_SPD_EN to DEF_ENABLED, you must provide additional information to the USB host CDC class driver module.It will use indexes and arrays to retrieve its internal objects from your handles instead of browsing through a list. So it is necessary to know the size of these tables.

Table - USBH_CDC_CFG_OPTIMIZE_SPD configuration structure in the USB Host CDC Base Class Configuration for Speed Optimization page describes each configuration field available in this configuration structure.

Table - USBH_CDC_CFG_OPTIMIZE_SPD configuration structure#

USB Host CDC Base Class Configuration for Allocation at Initialization#

If you set the configuration USBH_CFG_INIT_ALLOC_EN to DEF_ENABLED, you must provide additional information to the USB host CDC class driver module. It will allocate all its objects at the initialization and will be unable to allocate more objects during execution. So you must provide the number of each object type to allocate. This greatly depends on your needs and on the USB devices you plan to use.

Table - USBH_CDC_CFG_INIT_ALLOC configuration structure in the USB Host CDC Base Class Configuration for Allocation at Initialization page describes each configuration field available in this configuration structure.

Table - USBH_CDC_CFG_INIT_ALLOC configuration structure#

USB Host CDC ACM Class Driver#

The CDC ACM class driver provided by Micrium OS USB Host is a subclass driver implementation of the CDC base class. It handles CDC ACM devices such as USB-to-serial converters or modems.

The class driver implementation complies with the "Universal Serial Bus Communications Class Subclass Specification for PSTN Devices", revision 1.2, February 9, 2007.

CDC ACM Class Modem Example#

This example will, upon connection of a CDC ACM device, issue a set of AT commands and display the results on the console. Note that in order to correctly execute this example, you will need a CDC ACM USB device that supports the AT commands.

The example accomplishes the following tasks:

• Initialize the CDC base class

• Initialize the ACM subclass

• Call the CDC base class Post Init function to inform the base class that all the subclasses have been initialized

• Allocate a buffer that is used to issue the AT commands and that holds the returned data

• Create a kernel task that will handle the AT commands issuing and that is triggered when a CDC ACM device is connected

The kernel task accomplishes the following tasks:

• Wait for the connection of a CDC ACM device

• Set a proper line coding

• Set the control line state

• Issue the following AT commands, and read and display the result:

  • ATQ0V1E0

  • ATI0

  • ATI1

  • ATI2

  • ATI3

  • ATI7

The example will also display the serial state changes on the console.

Location#

The example implementation is located in /examples/usb/host/ex_usbh_cdc_acm_modem.c.

API#

This example offers only one API named Ex_USBH_CDC_ACM_Init(). This function is normally called from a USB host core example.

USB Host CDC ACM Class Programming Guide#

• Initializing the USB Host CDC ACM Class Driver

• Using USB Host CDC ACM Class Driver Application Functions

  • Conn

  • Disconn

  • NetConn

  • RespAvail

  • SerialStateChng

• Setting the Line Coding of a CDC ACM Function

• Communicating Using the CDC ACM Class Driver

Initializing the USB Host CDC ACM Class Driver#

To support CDC ACM devices, you must first initialize the class driver. To begin, make sure you first have initialized the CDC base class. For more information, see USB Host CDC Base Class Programming Guide .

To initialize the CDC ACM class driver, you call the function USBH_ACM_Init().

Listing - Example of call to USBH_ACM_Init() in the USB Host CDC ACM Class Programming Guide page shows an example of a call to USBH_ACM_Init() using default arguments. For more information on the configuration arguments to pass to USBH_ACM_Init(), see USB Host CDC ACM Class Configuration .

Listing - Example of call to USBH_ACM_Init()#

USBH_ACM_APP_FNCTS  App_USBH_ACM_Fncts = {
    .Conn            = App_USBH_ACM_Conn,
    .Disconn         = App_USBH_ACM_Disconn,
    .NetConn         = App_USBH_ACM_NetConn,
    .RespAvail       = App_USBH_ACM_RespAvail,
    .SerialStateChng = App_USBH_ACM_SerialStateChng
}

void  App_USBH_ACM_Init (void)
{
    RTOS_ERR  err;

    USBH_ACM_Init(&App_USBH_ACM_Fncts,
                  &err);
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occured. Error handling should be added here. */
    }
}

Using USB Host CDC ACM Class Driver Application Functions#

The CDC ACM class driver provides five callback functions that will be called when an event occurs on a CDC ACM function (such as connection and disconnection).

These callbacks can have multiple purposes. Some of these include:

• Provide handles on the CDC ACM function to your application

• Execute some event driven simple task

• Trigger another task in your application

• Etc.

The following is a description of each of the available callback functions.

Conn#

This function is called when a CDC ACM function is connected. It will provide all the necessary handles on the CDC ACM function to your application. Your application can also use it to return a pointer to an application object that is linked to this particular CDC ACM function. This pointer will be passed to any other callback function that is related to the CDC ACM function.

Listing - Example of implementation of Conn function in the USB Host CDC ACM Class Programming Guide page shows an example of implementation of the Conn callback function.

Listing - Example of implementation of Conn function#

void  *App_USBH_ACM_Conn(USBH_DEV_HANDLE       dev_handle,
                         USBH_FNCT_HANDLE      fnct_handle,
                         USBH_CDC_FNCT_HANDLE  cdc_fnct_handle,
                         USBH_ACM_FNCT_HANDLE  acm_fnct_handle)
{
    /* A CDC ACM function was connected. acm_fnct_handle should be saved in your application for later use. */

    /* You can allocate an object that will be linked to this CDC ACM function. */

    /* You can trigger one of your application task from here. */

    return (<pointer to application object>);   /* DEF_NULL can be returned as well. */
}

Disconn#

This function is called when a CDC ACM function is disconnected.

Listing - Example of implementation of Disconn function in the USB Host CDC ACM Class Programming Guide page shows an example of implementation of the Disconn callback function.

Listing - Example of implementation of Disconn function#

void  *App_USBH_ACM_Disconn(USBH_AOAP_FNCT_HANDLE   acm_fnct_handle,
                            void                   *p_arg)
{
    /* A CDC ACM function was disconnected. */

    /* p_arg is the pointer you returned in the Conn function associated to this function.    */
    /* You can free the object if necessary.                                                  */

    /* You can trigger one of your application task form here. */
}

NetConn#

This function is called when a network connection/disconnection occurred on the CDC ACM function.

Listing - Example of implementation of NetConn function in the USB Host CDC ACM Class Programming Guide page shows an example of implementation of the NetConn callback function.

Listing - Example of implementation of NetConn function#

void  App_USBH_ACM_NetConn(USBH_ACM_FNCT_HANDLE   acm_fnct_handle,
                           void                  *p_arg,
                           CPU_BOOLEAN            is_conn)
{
    /* A CDC ACM function has been connected (is_conn == DEF_YES) or                        */
    /* disconnected (is_conn == DEF_NO) from a network.                                     */

    /* p_arg is the pointer you returned in the Conn function associated to this function.  */

    /* You can trigger one of your application task form here.                              */
}

RespAvail#

This function is called when a response is available from a CDC ACM function. The response can be retrieved by using the function USBH_ACM_EncapsulatedCmdRx().

Listing - Example of implementation of RespAvail function in the USB Host CDC ACM Class Programming Guide page shows an example of implementation of the RespAvail callback function.

Listing - Example of implementation of RespAvail function#

void  App_USBH_ACM_RespAvail(USBH_ACM_FNCT_HANDLE   acm_fnct_handle,
                             void                  *p_arg)
{
    /* A CDC ACM function has received a response. */

    /* p_arg is the pointer you returned in the Conn function associated to this function. */

    /* You can trigger one of your application task form here. */
}

SerialStateChng#

This function is called when the serial state changes on a CDC ACM function.

Listing - Example of implementation of SerialStateChng function in the USB Host CDC ACM Class Programming Guide page shows an example of implementation of the SerialStateChng callback function.

Listing - Example of implementation of SerialStateChng function#

void  App_USBH_ACM_SerialStateChng(USBH_ACM_FNCT_HANDLE   acm_fnct_handle,
                                   void                  *p_arg,
                                   CPU_INT08U             serial_state)
{
    CPU_BOOLEAN  state_rx_carrier;
    CPU_BOOLEAN  state_tx_carrier;
    CPU_BOOLEAN  state_brk;
    CPU_BOOLEAN  state_ring_signal;
    CPU_BOOLEAN  state_framing;
    CPU_BOOLEAN  state_parity;
    CPU_BOOLEAN  state_overrun;

    /* A CDC ACM function serial state has changed. */

    /* p_arg is the pointer you returned in the Conn function associated to this function. */

    /* You can trigger one of your application task form here. */

    /* You can retrieve the new serial state like this: */

    state_rx_carrier  = DEF_BIT_IS_SET(serial_state, USBH_CDC_SERIAL_STATE_RXCARRIER);
    state_tx_carrier  = DEF_BIT_IS_SET(serial_state, USBH_CDC_SERIAL_STATE_TXCARRIER);
    state_brk         = DEF_BIT_IS_SET(serial_state, USBH_CDC_SERIAL_STATE_BRK);
    state_ring_signal = DEF_BIT_IS_SET(serial_state, USBH_CDC_SERIAL_STATE_RINGSIGNAL);
    state_rx_framing  = DEF_BIT_IS_SET(serial_state, USBH_CDC_SERIAL_STATE_FRAMING);
    state_rx_parity   = DEF_BIT_IS_SET(serial_state, USBH_CDC_SERIAL_STATE_PARITY);
    state_rx_overrun  = DEF_BIT_IS_SET(serial_state, USBH_CDC_SERIAL_STATE_OVERRUN);
}

Setting the Line Coding of a CDC ACM Function#

The line coding of a CDC ACM function ca be set via the function USBH_ACM_LineCodingSet().

Listing - Example of CDC ACM function line coding set in the USB Host CDC ACM Class Programming Guide page shows an example of how to setting the line coding to standard values (9600 bps, 8 data bits, no parity, 1 stop bit).

Listing - Example of CDC ACM function line coding set#

void  App_USBH_ACM_LineCodingSet(USBH_ACM_FNCT_HANDLE  acm_fnct_handle)
{
    USBH_CDC_LINECODING  line_coding;
    RTOS_ERR             err;

    line_coding.Rate       = USBH_CDC_LINECODING_RATE_9600;
    line_coding.CharFmt    = USBH_CDC_LINECODING_STOP_BIT_1;
    line_coding.ParityType = USBH_CDC_LINECODING_PARITY_NONE;
    line_coding.DataBit    = USBH_CDC_LINECODING_DATA_BIT_8;

    USBH_ACM_LineCodingSet(acm_fnct_handle,
                          &line_coding,
                           5000u,
                          &err);
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occured. Error handling should be added here. */
    }
}

Communicating Using the CDC ACM Class Driver#

The CDC ACM class driver offers two functions to communicate with a CDC ACM function: USBH_ACM_RxAsync() and USBH_ACM_TxAsync().

Listing - Example of CDC ACM loopback communication in the USB Host CDC ACM Class Programming Guide page shows an example a simple loopback communication with a CDC ACM function.

Listing - Example of CDC ACM loopback communication#

void  App_USBH_ACM_RxCmpl(USBH_ACM_FNCT_HANDLE   acm_fnct_handle,
                          CPU_INT08U            *p_buf,
                          CPU_INT32U             buf_len,
                          CPU_INT32U             xfer_len,
                          void                  *p_arg,
                          RTOS_ERR               err)
{
    RTOS_ERR  err_tx;

    if (err.Code != RTOS_ERR_NONE) {
        /* An error occured while receiving the data. Error handling should be added here. */

        return;
    }

    USBH_ACM_TxAsync(acm_fnct_handle,
                     p_buf,
                     buf_len,
                     App_USBH_ACM_TxCmpl,
                     DEF_NULL,
                    &err_tx);
    if (err_tx.Code != RTOS_ERR_NONE) {
        /* An error occured. Error handling should be added here. */
    }
}

void  App_USBH_ACM_TxCmpl(USBH_ACM_FNCT_HANDLE   acm_fnct_handle,
                          CPU_INT08U            *p_buf,
                          CPU_INT32U             buf_len,
                          CPU_INT32U             xfer_len,
                          void                  *p_arg,
                          RTOS_ERR               err)
{
    RTOS_ERR  err_rx;

    if (err.Code != RTOS_ERR_NONE) {
        /* An error occured while sending the data. Error handling should be added here. */

        return;
    }

    USBH_ACM_RxAsync(acm_fnct_handle,
                     p_buf,
                     buf_len,
                     App_USBH_ACM_RxCmpl,
                     DEF_NULL,
                    &err_rx);
    if (err_rx.Code != RTOS_ERR_NONE) {
        /* An error occured. Error handling should be added here. */
    }
}

USB Host CDC ACM Class Configuration#

This section defines the configurations related to Micrium OS USB Host CDC ACM Class driver.

• Class Driver Initialization

  • p_acm_app_fncts

• Optional Configurations

  • Memory Segment

  • Optimize Speed Quantities

  • Allocation at Initialization Quantities

• Post-Init Configurations

  • Standard Requests Timeout

Class Driver Initialization#

To initialize the USB Host CDC ACM class driver module, you call the function USBH_ACM_Init() . This function takes one configuration argument that is described here.

p_acm_app_fncts#

p_acm_app_fncts is a pointer to a structure of type USBH_ACM_APP_FNCTS. Its purpose is to provide a set of application callbacks to be called when an event occurs on a CDC ACM function (such as connection and disconnection).

For more information on these callbacks, see the USB Host CDC ACM Class Programming Guide .

The sections below describe each configuration field available in this configuration structure.

.Conn#

A CDC ACM function was connected. This function provides the associated handles to your application.

Listing - .Conn function signature#

void *App_USBH_ACM_Conn          (USBH_DEV_HANDLE       dev_handle,
                                  USBH_FNCT_HANDLE      fnct_handle,
                                  USBH_CDC_FNCT_HANDLE  cdc_fnct_handle,
                                  USBH_ACM_FNCT_HANDLE  acm_fnct_handle)

.Disconn#

A CDC ACM function was disconnected. Once you return from this function, the handles passed at the Conn function for this CDC ACM function won't be valid anymore.

Listing - .Disconn function signature#

void App_USBH_ACM_Disconn        (USBH_ACM_FNCT_HANDLE  acm_fnct_handle,
                                  void                 *p_arg)

.NetConn#

Indicates a network connection or disconnection occurred on a CDC ACM function.

Listing - .NetConn function signature#

void App_USBH_ACM_NetConn        (USBH_ACM_FNCT_HANDLE  acm_fnct_handle,
                                  void                 *p_arg,
                                  CPU_BOOLEAN           is_conn)

.RespAvail#

Indicates a response is available on a CDC ACM function.

Listing - .RespAvail function signature#

void App_USBH_ACM_RespAvail      (USBH_ACM_FNCT_HANDLE   acm_fnct_handle,
                                  void                  *p_arg)

.SerialStateChng#

Indicates the serial state has changed on a CDC ACM function. Also provides the new serial state.

Listing - .SerialStateChng function signature#

void App_USBH_ACM_SerialStateChng(USBH_ACM_FNCT_HANDLE  acm_fnct_handle,
                                  void                 *p_arg,
                                  CPU_INT08U            serial_state)

Optional Configurations#

This section describes the configurations that are optional. If you do not set them in your application, the default configurations will apply.

The default values can be retrieved via the structure USBH_ACM_InitCfgDflt.

Memory Segment#

This module allocates control data from a memory segment.

Optimize Speed Quantities#

This configuration is mandatory if you set USBH_CFG_OPTIMIZE_SPD_EN to DEF_ENABLED. Consequently, USBH_ACM_ConfigureOptimizeSpdCfg() must be called from your application.

When the optimize speed mode is enabled, you must provide additional information to this module. In this case, this module will use indexes and arrays to retrieve its internal objects from your handles instead of browsing through a list. This configuration specifies the size of each of these tables.

Allocation at Initialization Quantities#

This configuration is mandatory if you set USBH_CFG_INIT_ALLOC_EN to DEF_ENABLED. Consequently, USBH_ACM_ConfigureInitAllocCfg() must be called from your application.

When this module allocates all its objects at initialization, it must know how many objects of each type it must allocate. This configuration specifies the number of objects to allocate.

Post-Init Configurations#

This section describes the configurations that can be set at any time during execution after you called the function USBH_ACM_Init() .

These configurations are optional. If you do not set them in your application, the default configurations will apply.

Standard Requests Timeout#

Timeout, in milliseconds, for the standard requests executed by this module.

USB Host CDC ACM Class Configuration for Speed Optimization#

If you set the configuration USBH_CFG_OPTIMIZE_SPD_EN to DEF_ENABLED, you must provide additional information to the USB host CDC ACM class driver module. It will use indexes and arrays to retrieve its internal objects from your handles instead of browsing through a list. Hence, it is necessary to know the size of these tables.

Table - USBH_ACM_CFG_OPTIMIZE_SPD configuration structure in the USB Host CDC ACM Class Configuration for Speed Optimization page describes each configuration field available in this configuration structure.

Table - USBH_ACM_CFG_OPTIMIZE_SPD configuration structure#

USB Host CDC ACM Class Configuration for Allocation at Initialization#

If you set the configuration USBH_CFG_INIT_ALLOC_EN to DEF_ENABLED, you must provide additional information to the USB host ACM class driver module. It will allocate all its objects at the initialization and will be unable to allocate more objects during execution. Hence, you must provide the number of each object type to allocate. This greatly depends on your needs and on the USB devices you plan to use.

Table - USBH_ACM_CFG_INIT_ALLOC configuration structure in the USB Host CDC ACM Class Configuration for Allocation at Initialization page describes each configuration field available in this configuration structure.

Table - USBH_ACM_CFG_INIT_ALLOC configuration structure#

USB Host HID Class Driver#

The HID Class driver provided with Micrium OS USB Host is a class driver that will handle HID devices such as mice and keyboards.

The class driver implementation complies with the "Device Class Definition for Human Interface Devices (HID)", Version 1.11, 6/27/01.

USB Host HID Class Example Applications#

This example presents a template that you can use to start the development of your HID class project. This application will accept the connection of mice and keyboards, parse their reports, and display either the position and button state (mouse) or key press (keyboard).

The following are the tasks accomplished by the example application when a HID device is connected:

• Allocate a memory block to represent the device

• Set the idle time to infinite

• Parse the report and determine:

  • The type of HID device (mouse, keyboard, or other)

  • The number of report IDs

Each time a key is pressed on a keyboard, the key will be displayed on the terminal. If the connected device is a mouse, each time the position changes or a button is pressed or release, the new position or button status will be displayed on the terminal.

Location#

The example implementation is located in /examples/usb/host/ex_usbh_hid.c.

API#

This example offers only one API named Ex_USBH_HID_Init(). This function is normally called from a USB host core example.

USB Host HID Class Programming Guide#

• Prerequisites

• Initializing the USB Host HID Class driver

• Using USB Host HID Class Application Functions

  • Conn

  • DataRxd

  • Disconn

Prerequisites#

The following compile-time configurations from the USB Host core are required for this class driver to work properly.

Reference: USB Host Compile-Time Configurations .

• USBH_CFG_PERIODIC_XFER_EN: Must be set to DEF_ENABLED.

Initializing the USB Host HID Class driver#

In order to support the Human Interface Device (HID) function connections, you must first initialize the class driver. This is done by calling the function USBH_HID_Init().

Listing - Example of call to USBH_HID_Init() in the USB Host HID Class Programming Guide page gives an example of call to USBH_HID_Init() using default arguments. For more information on the configuration arguments to pass to USBH_HID_Init(), see USB Host HID Class Configuration .

Listing - Example of call to USBH_HID_Init()#

USBH_HID_APP_FNCTS  App_USBH_HID_Fncts = {
    .Conn    = App_USBH_HID_Conn,
    .DataRxd = App_USBH_HID_DataRxd,
    .Disconn = App_USBH_HID_Disconn
}

void  App_USBH_HID_Init()
{
    RTOS_ERR  err;

    USBH_HID_Init(&App_USBH_HID_Fncts,
                  &err);
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occured. Error handling should be added here. */
    }
}

Using USB Host HID Class Application Functions#

The HID class driver provides three callback functions that will be called when an event occurs on a HID function (such as connection and disconnection).

These callbacks can have multiple purposes. Some of these include:

• Provide handles on the HID function to your application

• Execute some event driven simple task

• Trigger another task in your application

• Etc.

Below is a description of each of the available callback functions.

Conn#

This function is called when a HID function is connected. It will provide all the necessary handles on the HID function to your application. Your application can also use it to return a pointer to an application object that is linked to this particular HID function. This pointer will be passed to any other callback function that is related to the HID function.

Listing - Example of implementation of Conn function in the USB Host HID Class Programming Guide page gives an example of implementation of the Conn callback function.

Listing - Example of implementation of Conn function#

void  *App_USBH_HID_Conn(USBH_DEV_HANDLE        dev_handle,
                         USBH_FNCT_HANDLE       fnct_handle,
                         USBH_HID_FNCT_HANDLE   hid_fnct_handle,
                         USBH_HID_APP_COLL     *p_app_coll_head,
                         RTOS_ERR               err)
{
    /* A HID function was connected. hid_fnct_handle should be saved in your application for later use. */

    /* You can allocate an object that will be linked to this HID function. */

    /* You can trigger one of your application task from here. */

    return (<pointer to application object>);   /* DEF_NULL can be returned as well. */
}

DataRxd#

This function is called when the class driver received a report from a HID function.

Listing - Example of implementation of DataRxd function in the USB Host HID Class Programming Guide page gives an example of implementation of the DataRxd callback function. The report is provided

Listing - Example of implementation of DataRxd function#

void  App_USBH_HID_DataRxd(USBH_HID_FNCT_HANDLE   hid_fnct_handle,
                           void                  *p_arg,
                           CPU_INT08U             report_id,
                           CPU_INT08U            *p_buf,
                           CPU_INT32U             buf_len,
                           RTOS_ERR               err)
{
    /* A HID function has received a new report.                                              */

    /* p_arg is the pointer you returned in the Conn function associated to this function.    */
    /* You can free the object if necessary.                                                  */

    /* You can trigger one of your application task form here.                                */
}

Disconn#

This function is called when a HID function is disconnected.

Listing - Example of implementation of Disconn function in the USB Host HID Class Programming Guide page gives an example of implementation of the Disconn callback function.

Listing - Example of implementation of Disconn function#

void  App_USBH_HID_Disconn(USBH_HID_FNCT_HANDLE   hid_fnct_handle,
                           void                  *p_arg)
{
    /* A HID function was disconnected.                                                     */

    /* p_arg is the pointer you returned in the Conn function associated to this function.  */
    /* You can free the object if necessary.                                                */

    /* You can trigger one of your application task form here.                              */
}

USB Host HID Class Configuration#

• Class Driver Initialization

  • p_hid_app_fncts

• Optional Configurations

  • Buffer Alignment

  • Receive Buffers

  • Report Descriptor Maximum Length

  • Maximum Number of Usages Per Items

  • Memory Segments

  • Optimize Speed Quantities

  • Allocation at Initialization Quantities

• Post-Init Configurations

  • Standard Requests Timeout

Class Driver Initialization#

To initialize the USB Host Human Interface Device (HID) class driver module, you call the function USBH_HID_Init() . This function takes one configuration argument that is described below.

p_hid_app_fncts#

p_hid_app_fncts is a pointer to a structure of type USBH_HID_APP_FNCTS. Its purpose is to provide a set of application callbacks to be called when an event occurs on a HID function (such as connection or disconnection). For more information on these callbacks, see USB Host HID Class Programming Guide .

The sections below describe each configuration field available in this configuration structure.

.Conn#

A HID function was connected. This function provides the handles that were associated with it to your application.

Listing - .Conn function signature#

void  *App_USBH_HID_Conn(USBH_DEV_HANDLE        dev_handle,
                         USBH_FNCT_HANDLE       fnct_handle,
                         USBH_HID_FNCT_HANDLE   hid_fnct_handle,
                         USBH_HID_APP_COLL     *p_app_coll_head,
                         RTOS_ERR               err)

.DataRxd#

A HID function has received data (a new report).

Listing - .DataRxd function signature#

void   App_USBH_HID_DataRxd(USBH_HID_FNCT_HANDLE   hid_fnct_handle,
                            void                  *p_arg,
                            CPU_INT08U             report_id,
                            CPU_INT08U            *p_buf,
                            CPU_INT32U             buf_len,
                            RTOS_ERR               err)

.Disconn#

A HID function was disconnected. Once you return from this function, the handles passed at the Conn function for this HID function won't be valid anymore.

Listing - .Disconn function signature#

void   App_USBH_HID_Disconn(USBH_HID_FNCT_HANDLE   hid_fnct_handle,
                            void                  *p_arg)

Optional Configurations#

This section describes the configurations that are optional. If you do not set them in your application, the default configurations will apply.

The default values can be retrieved via the structure USBH_HID_InitCfgDflt.

Buffer Alignment#

This module allocates buffers used for data transfers with the devices. You may have a specific need for address alignment for these buffers depending on your USB controller. If you use more than one USB controller, you must set the alignment to the largest value.

Receive Buffers#

Configures the quantity and the length of the receive buffers. The more receive buffers you allocate, the more responsive the HID device will be.

Report Descriptor Maximum Length#

Configures the maximum length of a report descriptor in octets.

Maximum Number of Usages Per Items#

Configures the maximum number of usages per items.

Memory Segments#

This module allocates control data and buffers used for data transfers with the devices. It has the ability to use a different memory segment for the control data and for the data buffers.

Optimize Speed Quantities#

This configuration is mandatory if you set USBH_CFG_OPTIMIZE_SPD_EN to DEF_ENABLED and therefore USBH_HID_ConfigureOptimizeSpdCfg() must be called from your application.

When the Optimize Speed Mode is enabled, you must provide further information to this module. In this case, this module will use indexes and arrays to retrieve its internal objects from your handles instead of browsing through a list. This configuration specifies the size of each of these tables.

Allocation at Initialization Quantities#

This configuration is mandatory if you set USBH_CFG_INIT_ALLOC_EN to DEF_ENABLED and therefore USBH_HID_ConfigureInitAllocCfg() must be called from your application.

When this module allocates all its objects at initialization, it must know how many objects of each type it must allocate. This configuration specifies the number of objects to allocate.

Post-Init Configurations#

This section describes the configurations that can be set at any time during execution after you called the function USBH_HID_Init() .

These configurations are optional. If you do not set them in your application, the default configurations will apply.

Standard Requests Timeout#

Timeout, in milliseconds, for the standard requests executed by this module.

USB Host HID Class Configuration for Speed Optimization#

If you set the configuration USBH_CFG_OPTIMIZE_SPD_EN to DEF_ENABLED, you must provide additional information to the USB host HID class driver module. It will use indexes and arrays to retrieve its internal objects from your handles instead of browsing through a list. So, it is necessary to know the size of these tables.

Table - USBH_HID_CFG_OPTIMIZE_SPD configuration structure in the USB Host HID Class Configuration for Speed Optimization page describes each configuration field available in this configuration structure.

Table - USBH_HID_CFG_OPTIMIZE_SPD configuration structure#

USB Host HID Class Configuration for Allocation at Initialization#

If you set the configuration USBH_CFG_INIT_ALLOC_EN to DEF_ENABLED, you must provide additional information to the USB host HID class driver module. It will allocate all its objects at initialization and will be unable to allocate more objects during execution. So, you must provide the number of each object type to allocate. This greatly depends on your needs and on the USB devices you plan to use.

Table - USBH_HID_CFG_INIT_ALLOC configuration structure in the USB Host HID Class Configuration for Allocation at Initialization page describes each configuration field available in this configuration structure.

Table - USBH_HID_CFG_INIT_ALLOC configuration structure#

USB Host MSC Class Driver#

The MSC Class driver provided by Micrium OS USB Host is a class driver that will handle mass storage devices such as flash memory drives, hard drives, and card readers).

The class driver implementation is in compliance with the following specifications:

• Universal Serial Bus Mass Storage Class Specification Overview, Revision 1.3 Sept. 5, 2008.

• Universal Serial Bus Mass Storage Class Bulk-Only Transport, Revision 1.0 Sept. 31, 1999.

MSC is a protocol that enables the transfer of information between a USB device and a host. The information is anything that can be stored electronically: executable programs, source code, documents, images, configuration data, or other text or numeric data.

A file system defines how the files are organized in the storage media. The USB mass storage class specification does not require any particular file system to be used on conforming devices. Instead, it provides a simple interface to read and write sectors of data using the Small Computer System Interface (SCSI) transparent command set.

The USB mass storage device class specification defines two transport protocols:

• Bulk-Only Transport (BOT)

• Control/Bulk/Interrupt (CBI) Transport.

The MSC class driver supports the BOT protocol only, which is by far the most widely used.

USB Host MSC Class Example Applications#

This example performs only an initialization of the MSC host class. File accesses on the MSC device are handled by the Micrium OS File System module.

This application requires the SCSI driver from the Micrium OS File System Storage layer to work properly. The connection of MSC device will report as the connection of a removable media.

For concrete file access and removable media handling examples, refer to the Media Polling example in File System Example Applications .

Location#

The example implementation is located in /examples/usb/host/ex_usbh_msc.c.

API#

This example offers only one API named Ex_USBH_MSC_Init(). This function is normally called from a USB host core example.

USB Host MSC Class Programming Guide#

• Prerequisites

• Initializing the USB Host MSC Class driver

• Communicating with an MSC device

Prerequisites#

No prerequisites from core.

Initializing the USB Host MSC Class driver#

In order to support the Mass Storage Class (MSC) function connections, you must first initialize the class driver. This is done by calling the function USBH_MSC_Init().

Listing - Example of call to USBH_MSC_Init() in the USB Host MSC Class Programming Guide page gives an example of call to USBH_MSC_Init() using default arguments. For more information on the configuration arguments to pass to USBH_MSC_Init(), see USB Host MSC Class Configuration .

Listing - Example of call to USBH_MSC_Init()#

#include  <rtos/fs/include/fs_scsi.h>                   (1)

USBH_MSC_CMD_BLK_FNCTS  App_USBH_MSC_CmdBlkFncts = {    (2)
    .Conn             = FS_SCSI_LU_Conn,
    .Disconn          = FS_SCSI_LU_Disconn,
    .MaxRespBufLenGet = FS_SCSI_MaxRespBufLenGet
}

void  App_USBH_MSC_Init()
{
    RTOS_ERR  err;

    USBH_MSC_Init(&App_USBH_MSC_CmdBlkFncts,
                  &err);
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occured. Error handling should be added here. */
    }
}

(1) In this example, we use the Micrium OS File System SCSI device driver, which is the recommended method to communicate with the Mass Storage Device. Hence, inclusion is needed.

(2) The MSC event callbacks are handled by the File System SCSI device driver. The driver will handle the communication and add the MSC device as a regular File System Device. The application will be notified of a SCSI device connection or disconnection via the File System Media Poll task callbacks.

Communicating with an MSC device#

The MSC class driver does not provide any public function to communicate with the device. You must use the Micrium OS File System API to communicate with the device. For more information, see File System Module User Manual .

USB Host MSC Class Configuration#

• Run-Time Configurations

  • Class Driver Initialization

  • Optional Configurations

  • Buffer Alignment

  • Memory Segments

  • Optimize Speed Quantities

  • Allocation at Initialization Quantities

• Post-Init Configurations

  • Standard Requests Timeout

Run-Time Configurations#

Class Driver Initialization#

To initialize the USB Host Mass Storage Class (MSC) driver module, you call the function USBH_MSC_Init(). This function takes one configuration argument which is described below.

p_cmd_blk_fncts#

p_cmd_blk_fncts is a pointer to a structure of type USBH_MSC_CMD_BLK_FNCTS. Its purpose is to provide a set of application callbacks to be called when an event occurs on an MSC function (such as connection or disconnection).

We highly recommended that you map these callbacks to the Micrium OS FS SCSI driver functions. You can, however, implement your own functions that call the SCSI driver functions if you have some specific instructions to execute.

.Conn

An MSC function was connected.

Recommended handler function from SCSI device driver: FS_SCSI_LU_Conn()

Listing - .Conn function signature#

void  *App_USBH_MSC_Conn(CPU_INT08U   lun,
                         CPU_INT16U   dev_id,
                         void        *p_transport_api,
                         void        *p_transport_arg)

.Disconn

An MSC function was disconnected.

Recommended handler function from SCSI device driver: FS_SCSI_LU_Disconn()

Listing - .Disconn function signature#

void   App_USBH_MSC_Disconn(CPU_INT08U   lun,
                            CPU_INT16U   dev_id,
                            void        *p_transport_arg)

.MaxRespBufLenGet

Retrieve the maximum response buffer length, in octets. The response buffer is used by certain SCSI commands with a Data IN phase.

Recommended handler function from SCSI device driver: FS_SCSI_MaxRespBufLenGet()

Listing - .MaxRespBufLenGet function signature#

void   App_USBH_MSC_MaxRespBufLenGet(void)

Optional Configurations#

This section describes the configurations that are optional. If you do not set them in your application, the default configurations will apply.

The default values can be retrieved via the structure USBH_MSC_InitCfgDflt.Note that these configurations must be set before you call the function USBH_MSC_Init().

Buffer Alignment#

This module allocates buffers used for data transfers with the devices. You may have a specific need of address alignment for these buffers depending on your USB controller. If you use more than one USB controller, you must set the alignment to the largest value.

Memory Segments#

This module allocates control data and buffers used for data transfers with the devices. It has the ability to use a different memory segment for the control data and for the data buffers.

Optimize Speed Quantities#

This configuration is mandatory if you set USBH_CFG_OPTIMIZE_SPD_EN to DEF_ENABLED and therefore USBH_MSC_ConfigureOptimizeSpdCfg() must be called from your application.

When the optimize speed mode is enabled, you have to provide further information to this module. In this case, this module will use indexes and arrays to retrieve its internal objects from your handles instead of browsing through a list. This configuration specifies the size of each of these tables.

Allocation at Initialization Quantities#

This configuration is mandatory if you set USBH_CFG_INIT_ALLOC_EN to DEF_ENABLED and therefore USBH_MSC_ConfigureInitAllocCfg() must be called from your application.

When this module allocates all its objects at initialization, it must know how many objects of each type it must allocate. This configuration specifies the number of objects to allocate.

Post-Init Configurations#

This section describes the configurations that can be set at any time during execution after you called the function USBH_MSC_Init().

These configurations are optional. If you do not set them in your application, the default configurations will apply.

Standard Requests Timeout#

Timeout, in milliseconds, for the standard requests executed by this module.

USB Host MSC Class Configuration for Speed Optimization#

If you set the configuration USBH_CFG_OPTIMIZE_SPD_EN to DEF_ENABLED, you must provide additional information to the USB host MSC class driver module. It will use indexes and arrays to retrieve its internal objects from your handles instead of browsing through a list. So, it is necessary to know the size of these tables.

Table - USBH_MSC_CFG_OPTIMIZE_SPD configuration structure in the USB Host MSC Class Configuration for Speed Optimization page describes each configuration field available in this configuration structure.

Table - USBH_MSC_CFG_OPTIMIZE_SPD configuration structure#

USB Host MSC Class Configuration for Allocation at Initialization#

If you set the configuration USBH_CFG_INIT_ALLOC_EN to DEF_ENABLED, you must provide additional information to the USB host MSC class driver module. In this case, it will allocate all its objects at initialization and will be unable to allocate more objects during execution. So, you must provide the number of each object type to allocate. This greatly depends on your needs and on the USB devices you plan to use.

Table - USBH_MSC_CFG_INIT_ALLOC configuration structure in the USB Host MSC Class Configuration for Allocation at Initialization page describes each configuration field available in this configuration structure.

Table - USBH_MSC_CFG_INIT_ALLOC configuration structure#

USB Host USB-to-Serial Class Driver#

The USB-to-Serial Class driver provided with Micrium OS USB Host is a class driver that handles USB-to-serial adapters from different manufacturers (FTDI, Silicon Labs and Prolific).

USB Host USB-to-Serial Class Example Applications#

This example detects the connection of a USB-to-serial adapter. After configuring the adapter, the example application sends back everything that was received from it, hence creating a loopback.

The following are the tasks accomplished by the example when a USB-To-Serial adapter device is connected:

• Set baud rate to 115200

• Set data characteristics to 8 data bits, no parity, and 1 stop bit

• Disable hardware flow control

• Disable software flow control

The example then waits for data to be received from the device. Once data is received, a task is triggered to send it back to the device.

You can use you favorite terminal tool and connect to the USB-to-serial adapter from your PC using a serial port. All the data you type in should be sent back.

The example will also display on the terminal any changes in the serial status.

Location#

The example implementation is located in /examples/usb/host/ex_usbh_usb2ser_loopback.c.

API#

This example offers only one API named Ex_USBH_USB2SER_Init(). This function is normally called from a USB host core example.

USB Host USB-to-Serial Class Programming Guide#

• Prerequisites

  • Initializing the Class Driver

• Using the Class Application Callback Functions

  • Conn

  • Disconn

  • DataRxd

  • SerialStatusChng

• Setting Line Parameters

  • Sending/Receiving Data

    • Receiving

    • Sending

Prerequisites#

The following compile-time configurations in the USB Host core are required for this class driver to work properly.

Reference: USB Host Compile-Time Configurations .

• USBH_CFG_FIELD_EN_MASK: Following fields must be stored: USBH_CFG_FIELD_EN_DEV_VENDOR_ID and USBH_CFG_FIELD_EN_DEV_PRODUCT_ID. Storing USBH_CFG_FIELD_EN_DEV_REL_NBR is also recommended.

• USBH_CFG_PERIODIC_XFER_EN: Must be set to DEF_ENABLED if USBH_USB2SER_CFG_NOTIFICATIONS_RX_EN is set to DEF_ENABLED.

Initializing the Class Driver#

In order to support the USB-to-serial adapter function connections, you must first initialize the class driver. To do this, you call the function USBH_USB2SER_Init().

Listing - Example of call to USBH_USB2SER_Init() in the USB Host USB-to-Serial Class Programming Guide page shows an example of a call to USBH_USB2SER_Init() using default arguments. For more information on the configuration arguments to pass to USBH_USB2SER_Init(), see USB Host USB-to-Serial Class Configuration .

Listing - Example of call to USBH_USB2SER_Init()#

USBH_USB2SER_APP_FNCTS  App_USBH_USB2SER_Fncts = {
    .Conn             = App_USBH_USB2SER_Conn,
    .Disconn          = App_USBH_USB2SER_Disconn,
    .DataRxd          = App_USBH_USB2SER_DataRxd,
    .SerialStatusChng = App_USBH_USB2SER_SerStatusChng
};

void  App_USBH_USB2SER_Init()
{
    RTOS_ERR  err;

    USBH_USB2SER_Init(&App_USBH_USB2SER_Fncts,
                      &err);
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occured. Error handling should be added here. */
    }
}

Using the Class Application Callback Functions#

The USB-to-serial class driver provides four callback functions that will be called on connection and disconnection and when an event occurs on a USB-to-serial function.

These callbacks can have multiple purposes. Some of these include:

• Provide handles on the USB-to-serial function to your application

• Execute some event driven simple task

• Trigger another task in your application

• Etc.

Below is a description of each of the available callback functions.

Conn#

This function is called when a USB-to-serial function is connected. It will provide all the necessary handles on the USB-to-serial function to your application. Your application can also use it to return a pointer to an application object that is linked to this particular USB-to-serial function. This pointer will be passed to any other callback function that is related to the USB-to-serial function.

Listing - Example of implementation of Conn function in the USB Host USB-to-Serial Class Programming Guide page shows an example of implementation of the Conn callback function.

Listing - Example of implementation of Conn function#

void  *App_USBH_USB2SER_Conn(USBH_DEV_HANDLE           dev_handle,
                             USBH_FNCT_HANDLE          fnct_handle,
                             USBH_USB2SER_FNCT_HANDLE  usb2ser_fnct_handle)
{
    /* A USB-to-serial function was connected. usb2ser_fnct_handle should be saved in your application for later use. */

    /* You can allocate an object that will be linked to this usb-to-serial function. */

    /* You can trigger one of your application task from here. */

    return (<pointer to application object>);   /* DEF_NULL can be returned as well. */
}

Disconn#

This function is called when a USB-to-serial function is disconnected.

Listing - Example of implementation of Disconn function in the USB Host USB-to-Serial Class Programming Guide page shows an example of implementation of the Disconn callback function.

Listing - Example of implementation of Disconn function#

void  App_USBH_USB2SER_Disconn(USBH_AOAP_FNCT_HANDLE   usb2ser_fnct_handle,
                               void                   *p_arg)
{
    /* A USB-to-serial function was disconnected. */

    /* p_arg is the pointer you returned in the Conn function associated to this function. You can free the object if necessary. */

    /* You can trigger one of your application task from here. */
}

DataRxd#

This function is called when a USB-to-serial function received data.

Listing - Example of implementation of DataRxd function in the USB Host USB-to-Serial Class Programming Guide page shows an example of implementation of the DataRxd callback function.

Listing - Example of implementation of DataRxd function#

void  App_USBH_USB2SER_DataRxd(USBH_AOAP_FNCT_HANDLE   usb2ser_fnct_handle,
                               void                   *p_arg,
                               CPU_INT08U             *p_buf,
                               CPU_INT32U              buf_len)
{
    /* A USB-to-serial function received data. */

    /* p_arg is the pointer you returned in the Conn function associated to this function. */

    /* You can trigger one of your application task from here. */
}

SerialStatusChng#

This function is called when the serial status of a USB-to-serial function has changed.

Listing - Example of implementation of SerialStatusChng function in the USB Host USB-to-Serial Class Programming Guide page gives an example of implementation of the SerialStatusChng callback function.

Listing - Example of implementation of SerialStatusChng function#

void  App_USBH_USB2SER_SerStatusChng(USBH_AOAP_FNCT_HANDLE               usb2ser_fnct_handle,
                                     void                               *p_arg,
                                     const  USBH_USB2SER_SERIAL_STATUS   serial_status)
{
    /* The serial status of a USB-to-serial function has changed. */

    /* p_arg is the pointer you returned in the Conn function associated to this function. */

                                             /* Modem status.               */
    CPU_BOOLEAN  cts_state;
    CPU_BOOLEAN  dsr_state;
    CPU_BOOLEAN  ri_state;
    CPU_BOOLEAN  rlsd_state;
                                             /* Line status.                */
    CPU_BOOLEAN  oe_err_state;
    CPU_BOOLEAN  parity_err_state;
    CPU_BOOLEAN  framing_err_state;
    CPU_BOOLEAN  break_err_state;

                                             /* Retrieve serial status.     */
    cts_state         = DEF_BIT_IS_SET(serial_status.Modem, USBH_USB2SER_MODEM_STATUS_CTS);
    dsr_state         = DEF_BIT_IS_SET(serial_status.Modem, USBH_USB2SER_MODEM_STATUS_DSR);
    ri_state          = DEF_BIT_IS_SET(serial_status.Modem, USBH_USB2SER_MODEM_STATUS_RING);
    rlsd_state        = DEF_BIT_IS_SET(serial_status.Modem, USBH_USB2SER_MODEM_STATUS_CARRIER);

    oe_err_state      = DEF_BIT_IS_SET(serial_status.Line,  USBH_USB2SER_LINE_STATUS_RX_OVERFLOW_ERR);
    parity_err_state  = DEF_BIT_IS_SET(serial_status.Line,  USBH_USB2SER_LINE_STATUS_PARITY_ERR);
    framing_err_state = DEF_BIT_IS_SET(serial_status.Line,  USBH_USB2SER_LINE_STATUS_FRAMING_ERR);
    break_err_state   = DEF_BIT_IS_SET(serial_status.Line,  USBH_USB2SER_LINE_STATUS_BRK_INT);

    /* You can trigger one of your application task from here. */
}

Setting Line Parameters#

You can configure the line parameters (baud rate, parity, data bits, etc) using the functions USBH_USB2SER_BaudRateSet() and USBH_USB2SER_DataSet().

Listing - Example of line configuration in the USB Host USB-to-Serial Class Programming Guide page shows an example of how to use the line parameters configuration functions to get 9600 bps, 8 data bits, no parity and 1 stop bit.

Listing - Example of line configuration#

void  App_USBH_USB2SER_LineCfg(USBH_USB2SER_FNCT_HANDLE  usb2ser_fnct_handle)
{
    RTOS_ERR  err;

    USBH_USB2SER_BaudRateSet(usb2ser_fnct_handle,
                             9600u,
                            &err);
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occured. Error handling should be added here. */
    }

    USBH_USB2SER_DataSet(usb2ser_fnct_handle,
                         8u,
                         USBH_USB2SER_PARITY_NONE,
                         USBH_USB2SER_STOP_BITS_1,
                        &err);
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occured. Error handling should be added here. */
    }
}

Sending/Receiving Data#

Receiving#

Receiving data is handled automatically by the class driver. Once a USB-to-serial adapter receives data, the DataRxd callback function will be called to notify your application.

Sending#

The USB-to-serial class driver offers you a function to send data: USBH_USB2SER_TxAsync(). It is an asynchronous function which means that it won't block.

Listing - Example of data transmission in the USB Host USB-to-Serial Class Programming Guide page shows an example of how to send data to a USB-to-serial adapter.

Listing - Example of data transmission#

void  App_USBH_USB2SER_TxCmpl(USBH_USB2SER_FNCT_HANDLE   usb2ser_fnct_handle,
                              void                      *p_arg,
                              CPU_INT08U                *p_buf,
                              CPU_INT32U                 buf_len,
                              CPU_INT32U                 xfer_len,
                              RTOS_ERR                   err)
{
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occured. Error handling should be added here. */
    } else {
        /* Transfer completed successfully.  */
    }
}

CPU_INT08U  App_USBH_USB2SER_DataBuf[] = "Test buffer";

void  App_USBH_USB2SER_DataTx (USBH_USB2SER_FNCT_HANDLE  usb2ser_fnct_handle)
{
    RTOS_ERR  err;

    USBH_USB2SER_TxAsync(usb2ser_fnct_handle,
                         App_USBH_USB2SER_DataBuf,
                         sizeof(App_USBH_USB2SER_DataBuf),
                         App_USBH_USB2SER_TxCmpl,
                         DEF_NULL,
                        &err);
    if (err.Code != RTOS_ERR_NONE) {
        /* An error occured. Error handling should be added here. */
    }
}

USB Host USB-to-Serial Class Configuration#

• Compile-Time Configurations

• Run-Time Configurations

  • Class Driver Initialization

  • Optional Configurations

  • Buffer Alignment

  • High-Speed Adapter Support Enable

  • Receive Buffer Quantity

  • Driver Entry Table

  • Memory Segments

  • Optimize Speed Quantities

  • Allocation at Initialization Quantities

  • Post-Init Configurations

  • Standard Requests Timeout

This section describes the configurations related to Micrium OS USB Host USB-to-serial Class driver.

Compile-Time Configurations#

The USB-to-serial class driver is configurable at compile time via two #defines located in usbh_cfg.h file.

We recommend that you begin the configuration process with the default configuration values, which in the next sections will be shown in bold.

Table - USB-to-serial Class Driver Compile-time Configurations in the USB Host USB-to-Serial Class Configuration page describes the configurations.

Table - USB-to-serial Class Driver Compile-time Configurations#

Run-Time Configurations#

Class Driver Initialization#

To initialize the USB Host USB-to-serial class driver module, you call the function USBH_USB2SER_Init(). This function takes one configuration argument that is described here.

p_app_fncts#

p_app_fncts is a pointer to a structure of type USBH_USB2SER_APP_FNCTS. Its purpose is to provide a set of application callbacks to be called when a USB-to-serial function is connected, when data is received, and when it is disconnected. For more information on these callbacks, see USB Host USB-to-Serial Class Programming Guide .

The sections below describe each configuration field available in this configuration structure.

.Conn

A USB-to-serial function was connected. This function provides the associated handles to your application.

Listing - .Conn function signature#

void  *App_USBH_USB2SER_Conn(USBH_DEV_HANDLE           dev_handle,
                             USBH_FNCT_HANDLE          fnct_handle,
                             USBH_USB2SER_FNCT_HANDLE  usb2ser_fnct_handle)

.Disconn

A USB-to-serial function was disconnected. Once you return from this function, the handles passed at the Conn function for this USB-to-serial function won't be valid anymore.

Listing - .Disconn function signature#

void   App_USBH_USB2SER_Disconn(USBH_USB2SER_FNCT_HANDLE   usb2ser_fnct_handle,
                                void                      *p_arg)

.DataRxd

A USB-to-serial function has received data.

Listing - .DataRxd function signature#

void   App_USBH_USB2SER_DataRxd(USBH_USB2SER_FNCT_HANDLE   usb2ser_fnct_handle,
                                void                      *p_arg,
                                CPU_INT08U                *p_buf,
                                CPU_INT32U                 buf_len)

.SerialStatusChng

A USB-to-serial function serial status has changed.

Listing - .SerialStatusChng function signature#

void   App_USBH_USB2SER_SerStatusChng(USBH_USB2SER_FNCT_HANDLE            usb2ser_fnct_handle,
                                      void                               *p_arg,
                                      const  USBH_USB2SER_SERIAL_STATUS   serial_status)

Optional Configurations#

This section describes the configurations that are optional. If you do not set them in your application, the default configurations will apply.

The default values can be retrieved via the structure USBH_USB2SER_InitCfgDflt.Note that these configurations must be set before you call the function USBH_USB2SER_Init().

Buffer Alignment#

This module allocates buffers used for data transfers with the devices. You may have a specific need for address alignment for these buffers depending on your USB controller. If you use more than one USB controller, you must set the alignment to the largest value.

High-Speed Adapter Support Enable#

Configures support for High-Speed adapters. Enabling support for high-speed adapters will require you to allocate larger receive buffers for all the adapters (even the Full-Speed ones).

Note that most common adapters are Full-Speed.

Receive Buffer Quantity#

Configures the number of receive buffers allocated/submitted.

Driver Entry Table#

The USB-to-serial class driver uses drivers to support the different adapter protocols that are used on the market. Your application can use only the drivers for the adapter types you plan to use. A null-terminated table of type USBH_USB2SER_ADAPTER_DRV_ENTRY can be configured to provide a list of supported adapter types. The currently available adapter drivers are listed here: USB Host USB-to-Serial Class Adapter Drivers .

Memory Segments#

This module allocates some control data and buffers used for data transfers with the devices. It has the ability to use a different memory segment for the control data and for the data buffers.

Optimize Speed Quantities#

This configuration is mandatory if you set USBH_CFG_OPTIMIZE_SPD_EN to DEF_ENABLED.

Also, USBH_USB2SER_ConfigureOptimizeSpdCfg() must be called from your application when USBH_CFG_OPTIMIZE_SPD_EN is set to DEF_ENABLED.

When optimize speed mode is enabled, you must provide additional information to this module. This module will use indexes and arrays to retrieve its internal objects from your handles instead of browsing through a list. This configuration tells the size of each of these tables.This configuration is available only when USBH_CFG_OPTIMIZE_SPD_EN is set to DEF_ENABLED.

Allocation at Initialization Quantities#

This configuration is mandatory if you set USBH_CFG_INIT_ALLOC_EN to DEF_ENABLED.

Also, USBH_USB2SER_ConfigureInitAllocCfg() must be called from your application when USBH_CFG_OPTIMIZE_SPD_EN is set to DEF_ENABLED.

When this module allocates its objects at initialization, it must know how many objects of each type to allocate. This configuration specifies the number of objects to allocate.This configuration is available only when USBH_CFG_INIT_ALLOC_EN is set to DEF_ENABLED.

Post-Init Configurations#

This section describes the configurations that can be set at any time during execution after you called the function USBH_USB2SER_Init().

These configurations are optional. If you do not set them in your application, the default configurations will apply.

Standard Requests Timeout#

Timeout, in milliseconds, for the standard requests executed by this module.

USB Host USB-to-Serial Class Configuration - Adapter Driver Entry#

Table - USBH_USB2SER_ADAPTER_DRV_ENTRY configuration structure in the USB Host USB-to-Serial Class Configuration - Adapter Driver Entry page describes each configuration field available in the driver entry structure.

Table - USBH_USB2SER_ADAPTER_DRV_ENTRY configuration structure#

USB Host USB-to-Serial Class Configuration for Speed Optimization#

If you set the configuration USBH_CFG_OPTIMIZE_SPD_EN to DEF_ENABLED, you must provide additional information to the USB-to-serial class driver module. It will use indexes and arrays to retrieve its internal objects from your handles instead of browsing through a list. So, it is necessary to know the size of these tables.

Table - USBH_USB2SER_CFG_OPTIMIZE_SPD configuration structure in the USB Host USB-to-Serial Class Configuration for Speed Optimization page describes each configuration field available in this configuration structure.

Table - USBH_USB2SER_CFG_OPTIMIZE_SPD configuration structure#

USB Host USB-to-Serial Class Configuration for Allocation at Initialization#

If you set the configuration USBH_CFG_INIT_ALLOC_EN to DEF_ENABLED, you must provide additional information to the USB-to-serial class driver module. It will allocate all its objects at the initialization and will be unable to allocate more objects during execution. So, you must provide the number of each object type to allocate. This greatly depends on your needs and on the USB devices you plan to use.

Table - USBH_USB2SER_CFG_INIT_ALLOC configuration structure in the USB Host USB-to-Serial Class Configuration for Allocation at Initialization page describes each configuration field available in this configuration structure.

Table - USBH_USB2SER_CFG_INIT_ALLOC configuration structure#

USB Host USB-to-Serial Class Adapter Drivers#

The USB-to-serial class supports adapters from different vendors. Each vendor uses different protocols with their adapters, and so the USB-to-serial class uses different "adapter drivers" to support the different adapter available on the market. Following is a list of the different adapter drivers currently available and supported.

• FTDI

• SiLabs

• Prolific

FTDI#

SiLabs#

Prolific#