aboutsummaryrefslogtreecommitdiffstats
path: root/examples/Readme.txt
diff options
context:
space:
mode:
Diffstat (limited to 'examples/Readme.txt')
-rw-r--r--examples/Readme.txt101
1 files changed, 101 insertions, 0 deletions
diff --git a/examples/Readme.txt b/examples/Readme.txt
new file mode 100644
index 0000000..25f8c55
--- /dev/null
+++ b/examples/Readme.txt
@@ -0,0 +1,101 @@
+This is the Readme file for the directory "examples" of AVR-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://metalab.at/wiki/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/avrusb/projects.html. Most of these
+features are described in the Documentation Wiki linked from this page.
+
+To mention just a few:
+
+Using RC oscillator for system clock
+ The 16.5 MHz module of AVR-USB has 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
+ is done.
+
+Dynamically generated descriptors
+ Sometimes you want to implement different typtes of USB device depending
+ on a jumper or other condition. AVR-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
+ AVR-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/avrusb/prjall.html
+
+where all projects are listed.
+
+----------------------------------------------------------------------------
+(c) 2008 by OBJECTIVE DEVELOPMENT Software GmbH.
+http://www.obdev.at/