Quick start guide for USB host vendor module (UHI vendor)

This is the quick start guide for the USB host vendor module (UHI vendor) with step-by-step instructions on how to configure and use the modules in a selection of use cases.

The use cases contain several code fragments. The code fragments in the steps for setup can be copied into a custom initialization function, while the steps for usage can be copied into, e.g., the main application function.

Basic use case

In this basic use case, the "USB Vendor (Single Class support)" module is used.

The "USB Vendor (Composite)" module usage is described in Advanced use cases.

Setup steps

Prerequisites

This module is based on USB host stack full interrupt driven and supporting Sleep manager sleepmgr. For AVR and SAM3/4 devices the Clock Management clock services is supported. For SAMD21 devices the asfdoc_sam0_system_clock_group clock driver is supported.

The following procedure must be executed to setup the project correctly:

• Specify the clock configuration:
  • UC3 and SAM3/4 devices without USB high speed support need 48MHz clock input.
    You must use a PLL and an external OSC.
  • UC3 and SAM3/4 devices with USB high speed support need 12MHz clock input.
    You must use an external OSC.
  • UC3 devices with USBC hardware need CPU frequency higher than 25MHz.
  • SAMD21 devices without USB high speed support need 48MHz clock input.
    You must use a DFLL and an external OSC.
• In conf_board.h, the define CONF_BOARD_USB_PORT must be added to enable USB lines. (Not mandatory for all boards)
• Enable interrupts
• Initialize the clock service

The usage of Sleep manager sleepmgr service is optional, but recommended to reduce power consumption:

• Initialize the sleep manager service
• Activate sleep mode when the application is in IDLE state

conf_clock.h examples with USB support.

For AVR and SAM3/4 devices, add to the initialization code:

sysclk_init();
irq_initialize_vectors();
cpu_irq_enable();
board_init();
sleepmgr_init(); // Optional

For SAMD21 devices, add to the initialization code:

system_init();
irq_initialize_vectors();
cpu_irq_enable();
sleepmgr_init(); // Optional

Add to the main IDLE loop:

sleepmgr_enter_sleep(); // Optional

Example code

Content of conf_usb_host.h:

#define USB_HOST_POWER_MAX  500

Add to application C-file:

void usb_init(void)
{
uhc_start();
}

Workflow

1. Ensure that conf_usb_host.h is available and contains the following configuration which is the main USB device configuration:

// Maximum current allowed on Vbus (mA) which depends of 5V generator
#define USB_HOST_POWER_MAX  500 // (500mA) 

1. Call the USB host stack start function to enable USB Host stack:

   • uhc_start(); 

Usage steps

Example code

Content of conf_usb_host.h:

#define USB_HOST_UHI        UHI_VENDOR
#define UHI_VENDOR_CHANGE(dev, b_plug) my_callback_vendor_change(dev, b_plug)
extern void my_callback_vendor_change(uhc_device_t* dev, bool b_plug);
#define UHI_VENDOR_VID_PID_LIST {USB_VID_ATMEL, USB_PID_ATMEL_ASF_VENDOR_CLASS}
#include "uhi_vendor.h" // At the end of conf_usb_host.h file

Add to application C-file:

static bool my_flag_vendor_test_start = false;
void my_callback_vendor_change(uhc_device_t* dev, bool b_plug)
{
   // USB Device Vendor connected
   my_flag_vendor_test_start = b_plug;
}

static void my_callback_bulk_in_done (usb_add_t add,
        usb_ep_t ep, uhd_trans_status_t status, iram_size_t nb_transfered)
{
  if (status != UHD_TRANS_NOERROR) {
    return; // Error during transfer
  }
  // Data received then restart test
  my_flag_vendor_test_start = true;
}

#define MESSAGE "Hello bulk"
#define HELLO_SIZE 5
#define HELLO_BULK_SIZE 10
uint8_t my_out_buffer[MESSAGE_SIZE+1] = MESSAGE;
uint8_t my_in_buffer[MESSAGE_SIZE+1];
void my_task(void)
{
   if (!my_flag_vendor_test_start) {
     return;
   }
   my_flag_vendor_test_start = false;

   // Send data through control endpoint
   uhi_vendor_control_out_run(my_out_buffer, HELLO_SIZE, NULL);

   // Check if bulk endpoints are available
   if (uhi_vendor_bulk_is_available()) {
     // Send data through bulk OUT endpoint
     uhi_vendor_bulk_out_run(my_out_buffer, HELLO_BULK_SIZE, NULL);
     // Receive data through bulk IN endpoint
     uhi_vendor_bulk_in_run(my_in_buffer, sizeof(my_in_buffer),
             my_callback_bulk_in_done);
   }
}

Workflow

1. Ensure that conf_usb_host.h is available and contains the following configuration which is the USB host vendor configuration:

   • #define USB_HOST_UHI   UHI_HID_VENDOR 

     Note

     It defines the list of UHI supported by USB host.

   • #define UHI_VENDOR_CHANGE(dev, b_plug) my_callback_vendor_change(dev, b_plug)
         extern bool my_callback_vendor_change(uhc_device_t* dev, bool b_plug); 

     Note

     This callback is called when a USB device vendor is plugged or unplugged.

   • #define UHI_VENDOR_VID_PID_LIST {USB_VID_ATMEL, USB_PID_ATMEL_ASF_VENDOR_CLASS} 

     Note

     It defines the list of devices supported by USB host (defined by VID and PID).

2. The Vendor data transfert functions are described in UHI for Vendor Class.

   • uhi_vendor_control_out_run(), uhi_vendor_bulk_out_run(),... 

Advanced use cases

• Enable USB high speed support
• Multiple classes support
• Dual roles support