Atmel AVR4901 Installation and operating instructions

Atmel AVR4901: ASF - USB Vendor Class
Application
Features
• USB 2.0 compliance
- Chapter 9 compliance
- Full Speed (12Mbit/s), High Speed (480Mbit/s) data rates
• Control, Bulk, Isochronous and Interrupt transfer types
• Small stack size frees space for main application
• Remote wakeup support
• USB bus powered support
• Real time (O.S. compliance, interrupt driven)
• Support 8-bit and 32-bit AVR®
1 Introduction
The aim of this document is to provide an easy way to integrate a USB vendor
class application on a new or existing project.
8-/32-bit Atmel
Microcontrollers
Application Note
Rev. 8481A-AVR-01/12

2 Atmel AVR49011
8481A-AVR-01/12
2 Abbreviations
ASF: AVR Software Framework
CD: Composite Device: a USB device with more than one interface
CDC: Communication Device Class
FS: USB Full Speed
HID: Human Interface Device
HS: USB High Speed
LS: USB Low Speed
MSC: Mass Storage Class
UDC: USB device Controller
UDD: USB device Descriptor
UDI: USB device Interface
USB: Universal Serial Bus
SOF: Start of Frame

Atmel AVR49011
3
8481A-AVR-01/12
3 Overview
This document includes six sections for all types of requirements when building a
USB device vendor application:
•Vendor class Specification
Provides information to help users with the vendor class specification and when
they need such solution
•Quick start
Describes how to start a ready to use vendor class device example
•Example description
Describes a vendor class device example
•Building a USB device vendor
Describes how to add a USB device vendor interface in a project
•Building a USB vendor class application
Describes how to add a USB vendor class application
•Vendor class in a USB composite device
Describes how to integrate a vendor class interface in a composite device project
For all these sections, it is recommended to know the main modules organization of a
vendor class application:
•User Application
•USB device Interface VENDOR (UDI-VENDOR)
•USB device Controller (UDC)
•USB device Driver (UDD)
For more advanced information concerning the USB stack implementation, please
refer to the Atmel®AVR4900 ASF USB Device stack application note.
Figure 3-1. USB vendor class solution architecture.
NOTE The USB device stack is available in the ASF in the common/services/usb directory.
UDD
UDC UDI – VENDOR
Application
USB Device stack from the ASF

4 Atmel AVR49011
8481A-AVR-01/12
4 Vendor class specification
The development of a vendor class can be required when the existing class
(http://www.usb.org/developers/defined_class) does not correspond to the user
specification.
Before starting a vendor class specification, check in Table 4-1 that the native USB
classes are not applicable for your USB application.
Table 4-1. Analysis of native classes.
Class PROS. CONS.
HID
•Native driver
•USB Low Speed mode support
•Suitable for controlling or
monitoring an application
•Interrupt endpoint:
olow and full speed
64KB/s
ohigh speed 2.93MB/s
CDC
•High transfer rate
•Simple Host application
(terminal)
•Easy migration for USART based
applications
•Need of *.inf file under Windows®
•Driver not WHQL certified
MSC •Native driver •SCSI protocol adapted only for
mass storage
AUDIO
•Native driver
•Interesting to record or send data
stream
•No handshake data transfer
(isochronous)
When building a vendor class, the main important thing to specify is the transfer
modes used by endpoints.
These can be chosen based on the description given in Table 4-2.
Table 4-2. Endpoint type description.
Endpoint
type
Description Use case
Control
•Low transfer rate
•No need of new endpoint which
can reduce application footprint
•Configuration of the device
Interrupt •Very low transfer
•Frequency guaranteed
•Real time constraints and low
bandwidth transfer
Bulk •High transfer rate
•Transfer guaranteed (ACK)
•Large amount of data transfer
Isochronous •Very High transfer rate
•Transfer not guaranteed
•Streaming application

Atmel AVR49011
5
8481A-AVR-01/12
5 Quick start
The USB device vendor examples are available in Atmel AVR Studio®5 and ASF.
Hereunder is the procedure to start a USB device vendor class example quickly:
1. Connect the board (for example the Atmel AVR XMEGA®-A3BU Xplained kit)
to the PC using the USB cable.
2. Connect the Atmel debugger (hereafter the JTAGICE3) to program the
device.
Figure 5-1 Board connection.
3. Start AVR Studio 5 and click on “New Example Project from ASF”.
In the New Example Project’s list, select “USB Device Vendor Class Example”
based on the board you are using. The filter list can be used to find the example
quickly.
1
3
2
4

6 Atmel AVR49011
8481A-AVR-01/12
4. Compile, load and execute.
The project does not require any modification and only needs to be compiled, loaded
and ran. Connect the Atmel debugger supported by the board and press F5.
When running the application for the first time a Found New Hardware Wizard pops
up as showing below, select “No, not this time” and click on “Next”:
5. Load the driver using the inf file.
NOTE Since the USB vendor class is not supported by any native driver, user needs to
provide a proprietary driver or use a third party solution.
For this example, an open source solution “libusb” is used to support this device. An
inf file was generated by the libusb tool. Point to the folder avr4901/driver/ to install
the driver.

Atmel AVR49011
7
8481A-AVR-01/12
Once the device is correctly installed, lunch the avr_vendor_class_example.exe from
the folder avr4901/tool/. This program will perform a loopback in all endpoints. A
status is displayed to show the correct execution of the application:
5.1 Hardware behavior
During the application execution the hardware (used board) should behave as below:
•A LED is on when USB device is in active mode and is off in SUSPEND mode
•A LED blinks showing that vendor class interface is enabled by the USB Host
•A LED is on when the loopback is running
Figure 5-2. Example with the Atmel XMEGA-A3BU Xplained board.
LED on when
USB is active
LED blinks showing
Vendor interface is
enabled
LED blinks showing
loopback is running

8 Atmel AVR49011
8481A-AVR-01/12
The user interface description (specific to the board) is defined at the end of ui.c
source file. This file is available within the “Solution Explorer” under
“common/services/usb/class/vendor/device/example/part_number_board/”.
Figure 5-3 ui.c file location.

Atmel AVR49011
9
8481A-AVR-01/12
6 Example description
6.1 Example content
The ASF provides a USB device vendor class example for various Atmel AVR
products. All these examples share common files and implement the same
application.
The Table 6-1 introduces a summary of the main files included in the USB device
vendor example. These files are associated to the modules described in Figure 3-1.
Table 6-1. USB device VENDOR example files.
Modules Files ASF paths Description
Application main.c
ui.c
conf_usb.h
Examples folder
Main loop.
Set up hardware switches and LEDs to show
operations.
USB device configuration.
udi_vendor.c/h common/services/usb/class/vendor/device/ Vendor class implementation
UDI VENDOR
udi_vendor_desc.c
udi_vendor_conf.h common/services/usb/class/vendor/device/
USB Descriptors for an USB device with
vendor interface (not applicable for USB
composite device)
udc.c/h
udc_desc.h
udi.h
udd.h
common/services/usb/udc/ USB device Core
UDC
usb_protocol.h
usb_atmel.h common/services/usb/ USB Protocol constants
UDD usbb_device.c/h
usbc_device.c/h
usb_device.c/h
avr32/drivers/usbb/
avr32/drivers/usbc/
xmega/drivers/usb/
USB Drivers
6.2 Example behavior
The main.c and ui.c files implement the user interface vendor application. It is
based on three steps:
1. Start USB device:
udc_start();
udc_attach(); // Must be called when the USB cable is plugged
// Cable plugged is detected via VBus events
2. Wait the enable of vendor interface via call-back and enable the loopback
process:
UDI_VENDOR_ENABLE_EXT() // Interface enabled callback
The callback calls:
- udi_vendor_bulk_out_run()// Enable transfer on interrupt OUT endpoint
- udi_vendor_interrupt_out_run()//Enable transfer on interrupt OUT endpoint
- udi_vendor_iso_out_run() //Enable transfer on isochronous OUT endpoint

10 Atmel AVR49011
8481A-AVR-01/12
3. Perform loopback in all endpoints (Control, Interrupt, Bulk and Isochronous):
// When a OUT data is received, then send this data on IN
void main_vendor_int_out_received(udd_ep_status_t status,
iram_size_t nb_transfered)
{
if (UDD_EP_TRANSFER_OK != status) {
return; // Tranfert aborted, then stop loopback
}
ui_loop_back_state(true);
// Send on IN endpoint the data received on endpoint OUT
udi_vendor_interrupt_in_run(
main_buf_loopback,
nb_transfered,
main_vendor_int_in_received);
}
// When a IN data has been sent, then the OUT transfer is enabled again
void main_vendor_int_in_received(udd_ep_status_t status,
iram_size_t nb_transfered)
{
if (UDD_EP_TRANSFER_OK != status) {
return; // Tranfert aborted, then stop loopback
}
ui_loop_back_state(false);
// Wait a full buffer
udi_vendor_interrupt_out_run(
main_buf_loopback,
sizeof(main_buf_loopback),
main_vendor_int_out_received);
}