This is the Readme file for the directory "examples" of V-USB, a firmware-
only USB driver for AVR microcontrollers.
WHAT IS IN THIS DIRECTORY?
==========================
This directory contains examples which are mostly for educational purposes.
Examples can be device firmware only, host software only or both. Here is
a summary:
custom-class
A custom class device with host software based on libusb. It demonstrates
the straight forward way of sending small amounts of data to a device and
receiving data from the device. It does NOT demonstrate how to send large
amounts of data to the device or how to receive data generated on the fly
by the device (how to use usbFunctionWrite() and usbFunctionRead()). See
the hid-data example for how usbFunctionWrite() and usbFunctionRead() are
used.
hid-custom-rq
This example implements the same functionality as the custom-class example
above, but declares the device as HID. This prevents the "give me a driver
CD" dialog on Windows. The device can still be controlled with libusb as in
the previous example (on Windows, the filter version of libusb-win32 must
be installed). In addition to the features presented in custom-class, this
example demonstrates how a HID class device is defined.
hid-mouse
This example implements a mouse device. No host driver is required since
today's operating systems have drivers for USB mice built-in. It
demonstrates how a real-world HID class device is implemented and how
interrupt-in endpoints are used.
hid-data
This example demonstrates how the HID class can be misused to transfer
arbitrary data over HID feature reports. This technique is of great value
on Windows because no driver DLLs are needed (the hid-custom-rq example
still requires the libusb-win32 DLL, although it may be in the program's
directory). The host side application requires no installation, it can
even be started directly from a CD. This example also demonstrates how
to transfer data using usbFunctionWrite() and usbFunctionRead().
usbtool
This is a general purpose development and debugging tool for USB devices.
You can use it during development of your device to test various requests
without special test programs. But it is also an example how all the
libusb API functions are used.
More information about each example can be found in the Readme file in the
respective directory.
Hardware dependencies of AVR code has been kept at a minimum. All examples
should work on any AVR chip which has enough resources to run the driver.
Makefile and usbconfig.h have been configured for the metaboard hardware (see
http://www.obdev.at/goto.php?t=metaboard for details). Edit the target
device, fuse values, clock rate and programmer in Makefile and the I/O pins
dedicated to USB in usbconfig.h.
WHAT IS NOT DEMONSTRATED IN THESE EXAMPLES?
===========================================
These examples show only the most basic functionality. More elaborate
examples and real world applications showing more features of the driver are
available at http://www.obdev.at/vusb/projects.html. Most of these
features are described in our documentation wiki at
http://www.obdev.at/goto.php?t=vusb-wiki.
To mention just a few:
Using RC oscillator for system clock
The 12.8 MHz and 16.5 MHz modules of V-USB have been designed to cope
with clock rate deviations up to 1%. This allows an RC oscillator to be
used. Since the AVR's RC oscillator has a factory precision of only 10%,
it must be calibrated to an external reference. The EasyLogger example
shows how this can be done.
Dynamically generated descriptors
Sometimes you want to implement different typtes of USB device depending
on a jumper or other condition. V-USB has a very flexible interface for
providing USB descriptors. See AVR-Doper for how to provide descriptors
at runtime.
Virtual COM port
Some people prefer a virtual serial interface to communicate with their
device. We strongly discourage this method because it does things
forbidden by the USB specification. If you still want to go this route,
see AVR-CDC.
Implementing suspend mode
V-USB does not implement suspend mode. This means that the device does
not reduce power consumption when the host goes into sleep mode. Device
firmware is free to implement suspend mode, though. See USB2LPT for an
example.
The projects mentioned above can best be found on
http://www.obdev.at/vusb/prjall.html
where all projects are listed.
----------------------------------------------------------------------------
(c) 2009 by OBJECTIVE DEVELOPMENT Software GmbH.
http://www.obdev.at/
