firmware/usbdrv/Readme.txt

   1 This is the Readme file to Objective Development's firmware-only USB driver
   2 for Atmel AVR microcontrollers. For more information please visit
   3 http://www.obdev.at/avrusb/
   4
   5 This directory contains the USB firmware only. Copy it as-is to your own
   6 project and add your own version of "usbconfig.h". A template for your own
   7 "usbconfig.h" can be found in "usbconfig-prototype.h" in this directory.
   8
   9
  10 TECHNICAL DOCUMENTATION
  11 =======================
  12 The technical documentation (API) for the firmware driver is contained in the
  13 file "usbdrv.h". Please read all of it carefully! Configuration options are
  14 documented in "usbconfig-prototype.h".
  15
  16 The driver consists of the following files:
  17   Readme.txt ............. The file you are currently reading.
  18   Changelog.txt .......... Release notes for all versions of the driver.
  19   usbdrv.h ............... Driver interface definitions and technical docs.
  20 * usbdrv.c ............... High level language part of the driver. Link this
  21                            module to your code!
  22 * usbdrvasm.S ............ Assembler part of the driver. This module is mostly
  23                            a stub and includes one of the usbdrvasm*.S files
  24                            depending on processor clock. Link this module to
  25                            your code!
  26   usbdrvasm12.S .......... 12 MHz version of the assembler routines. Included
  27                            by usbdrvasm.S, don't link it directly!
  28   usbdrvasm16.S .......... 16 MHz version of the assembler routines. Included
  29                            by usbdrvasm.S, don't link it directly!
  30   usbdrvasm165.S ......... 16.5 MHz version of the assembler routines including
  31                            a PLL so that an 1% accurate RC oscillator can be
  32                            used. Included by usbdrvasm.S, don't link directly!
  33   usbconfig-prototype.h .. Prototype for your own usbdrv.h file.
  34 * oddebug.c .............. Debug functions. Only used when DEBUG_LEVEL is
  35                            defined to a value greater than 0. Link this module
  36                            to your code!
  37   oddebug.h .............. Interface definitions of the debug module.
  38   iarcompat.h ............ Compatibility definitions for IAR C-compiler.
  39   usbdrvasm.asm .......... Compatibility stub for IAR-C-compiler. Use this
  40                            module instead of usbdrvasm.S when you assembler
  41                            with IAR's tools.
  42   License.txt ............ Open Source license for this driver.
  43   CommercialLicense.txt .. Optional commercial license for this driver.
  44   USBID-License.txt ...... Terms and conditions for using particular USB ID
  45                            values for particular purposes.
  46
  47 (*) ... These files should be linked to your project.
  48
  49
  50 CPU CORE CLOCK FREQUENCY
  51 ========================
  52 We supply assembler modules for clock frequencies of 12 MHz, 16 MHz and
  53 16.5 MHz. Other clock rates are not supported. The actual clock rate must be
  54 configured in usbdrv.h unless you use the default 12 MHz.
  55
  56 12 MHz Clock
  57 This is the traditional clock rate of AVR-USB because it's the lowest clock
  58 rate where the timing constraints of the USB spec can be met.
  59
  60 16 MHz Clock
  61 This clock rate has been added for users of the Arduino board and other
  62 ready-made boards which come with a fixed 16 MHz crystal. It's also an option
  63 if you need the slightly higher clock rate for performance reasons. Since
  64 16 MHz is not divisible by the USB low speed bit clock of 1.5 MHz, the code
  65 is somewhat tricky and has to insert a leap cycle every third byte.
  66
  67 16.5 MHz Clock
  68 The assembler module for this clock rate differs from the other modules because
  69 it has been built for an RC oscillator with only 1% precision. The receiver
  70 code inserts leap cycles to compensate for clock deviations. 1% is also the
  71 precision which can be achieved by calibrating the internal RC oscillator of
  72 the AVR. Please note that only AVRs with internal 64 MHz PLL oscillator can be
  73 used since the 8 MHz RC oscillator cannot be trimmed up to 16.5 MHz. This
  74 includes the very popular ATTiny25, ATTiny45, ATTiny85 series as well as the
  75 ATTiny26.
  76
  77 We recommend that you obtain appropriate calibration values for 16.5 MHz core
  78 clock at programming time and store it in flash or EEPROM or compute the value
  79 from a reference clock at run time. However, since Atmel's 8 MHz calibration
  80 is much more precise than the guaranteed 10%, it's usually possible to add a
  81 fixed offset to this value.
  82
  83
  84 USB IDENTIFIERS
  85 ===============
  86 Every USB device needs a vendor- and a product-identifier (VID and PID). VIDs
  87 are obtained from usb.org for a price of 1,500 USD. Once you have a VID, you
  88 can assign PIDs at will.
  89
  90 Since an entry level cost of 1,500 USD is too high for most small companies
  91 and hobbyists, we provide a single VID/PID pair for free. If you want to use
  92 your own VID and PID instead of our's, define the macros "USB_CFG_VENDOR_ID"
  93 and "USB_CFG_DEVICE_ID" accordingly in "usbconfig.h".
  94
  95 To use our predefined VID/PID pair, you MUST conform to a couple of
  96 requirements. See the file "USBID-License.txt" for details.
  97
  98 Objective Development also has some offerings which include product IDs. See
  99 http://www.obdev.at/avrusb/ for details.
 100
 101
 102 HOST DRIVER
 103 ===========
 104 You have received this driver together with an example device implementation
 105 and an example host driver. The host driver is based on libusb and compiles
 106 on various Unix flavors (Linux, BSD, Mac OS X). It also compiles natively on
 107 Windows using MinGW (see www.mingw.org) and libusb-win32 (see
 108 libusb-win32.sourceforge.net). The "Automator" project contains a native
 109 Windows host driver (not based on libusb) for Human Interface Devices.
 110
 111
 112 DEVELOPMENT SYSTEM
 113 ==================
 114 This driver has been developed and optimized for the GNU compiler version 3
 115 (gcc 3). It does work well with gcc 4 and future versions will probably be
 116 optimized for gcc 4. We recommend that you use the GNU compiler suite because
 117 it is freely available. AVR-USB has also been ported to the IAR compiler and
 118 assembler. It has been tested with IAR 4.10B/W32 and 4.12A/W32 on an ATmega8
 119 with the "small" and "tiny" memory model. Please note that gcc is more
 120 efficient for usbdrv.c because this module has been deliberately optimized
 121 for gcc.
 122
 123
 124 USING AVR-USB FOR FREE
 125 ======================
 126 The AVR firmware driver is published under the GNU General Public License
 127 Version 2 (GPL2). See the file "License.txt" for details.
 128
 129 If you decide for the free GPL2, we STRONGLY ENCOURAGE you to do the following
 130 things IN ADDITION to the obligations from the GPL2:
 131
 132 (1) Publish your entire project on a web site and drop us a note with the URL.
 133 Use the form at http://www.obdev.at/avrusb/feedback.html for your submission.
 134
 135 (2) Adhere to minimum publication standards. Please include AT LEAST:
 136     - a circuit diagram in PDF, PNG or GIF format
 137     - full source code for the host software
 138     - a Readme.txt file in ASCII format which describes the purpose of the
 139       project and what can be found in which directories and which files
 140     - a reference to http://www.obdev.at/avrusb/
 141
 142 (3) If you improve the driver firmware itself, please give us a free license
 143 to your modifications for our commercial license offerings.
 144
 145
 146 COMMERCIAL LICENSES FOR AVR-USB
 147 ===============================
 148 If you don't want to publish your source code under the terms of the GPL2,
 149 you can simply pay money for AVR-USB. As an additional benefit you get
 150 USB PIDs for free, licensed exclusively to you. See the file
 151 "CommercialLicense.txt" for details.