| 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 all .c and .S files to your project (these files are marked |
| 7 | with an asterisk in the list below). Then copy usbconfig-prototype.h as |
| 8 | usbconfig.h to your project and edit it according to your configuration. |
| 9 | |
| 10 | |
| 11 | TECHNICAL DOCUMENTATION |
| 12 | ======================= |
| 13 | The technical documentation (API) for the firmware driver is contained in the |
| 14 | file "usbdrv.h". Please read all of it carefully! Configuration options are |
| 15 | documented in "usbconfig-prototype.h". |
| 16 | |
| 17 | The driver consists of the following files: |
| 18 | Readme.txt ............. The file you are currently reading. |
| 19 | Changelog.txt .......... Release notes for all versions of the driver. |
| 20 | usbdrv.h ............... Driver interface definitions and technical docs. |
| 21 | * usbdrv.c ............... High level language part of the driver. Link this |
| 22 | module to your code! |
| 23 | * usbdrvasm.S ............ Assembler part of the driver. This module is mostly |
| 24 | a stub and includes one of the usbdrvasm*.S files |
| 25 | depending on processor clock. Link this module to |
| 26 | your code! |
| 27 | usbdrvasm*.inc ......... Assembler routines for particular clock frequencies. |
| 28 | Included by usbdrvasm.S, don't link it directly! |
| 29 | asmcommon.inc .......... Common assembler routines. Included by |
| 30 | usbdrvasm*.inc, don't link it directly! |
| 31 | usbconfig-prototype.h .. Prototype for your own usbdrv.h file. |
| 32 | * oddebug.c .............. Debug functions. Only used when DEBUG_LEVEL is |
| 33 | defined to a value greater than 0. Link this module |
| 34 | to your code! |
| 35 | oddebug.h .............. Interface definitions of the debug module. |
| 36 | usbportability.h ....... Header with compiler-dependent stuff. |
| 37 | usbdrvasm.asm .......... Compatibility stub for IAR-C-compiler. Use this |
| 38 | module instead of usbdrvasm.S when you assembler |
| 39 | with IAR's tools. |
| 40 | License.txt ............ Open Source license for this driver. |
| 41 | CommercialLicense.txt .. Optional commercial license for this driver. |
| 42 | USBID-License.txt ...... Terms and conditions for using particular USB ID |
| 43 | values for particular purposes. |
| 44 | |
| 45 | (*) ... These files should be linked to your project. |
| 46 | |
| 47 | |
| 48 | CPU CORE CLOCK FREQUENCY |
| 49 | ======================== |
| 50 | We supply assembler modules for clock frequencies of 12 MHz, 12.8 MHz, 15 MHz, |
| 51 | 16 MHz, 16.5 MHz and 20 MHz. Other clock rates are not supported. The actual |
| 52 | clock rate must be configured in usbdrv.h unless you use the default 12 MHz. |
| 53 | |
| 54 | 12 MHz Clock |
| 55 | This is the traditional clock rate of AVR-USB because it's the lowest clock |
| 56 | rate where the timing constraints of the USB spec can be met. |
| 57 | |
| 58 | 15 MHz Clock |
| 59 | Similar to 12 MHz, but some NOPs inserted. On the other hand, the higher clock |
| 60 | rate allows for some loops which make the resulting code size somewhat smaller |
| 61 | than the 12 MHz version. |
| 62 | |
| 63 | 16 MHz Clock |
| 64 | This clock rate has been added for users of the Arduino board and other |
| 65 | ready-made boards which come with a fixed 16 MHz crystal. It's also an option |
| 66 | if you need the slightly higher clock rate for performance reasons. Since |
| 67 | 16 MHz is not divisible by the USB low speed bit clock of 1.5 MHz, the code |
| 68 | is somewhat tricky and has to insert a leap cycle every third byte. |
| 69 | |
| 70 | 12.8 MHz and 16.5 MHz Clock |
| 71 | The assembler modules for these clock rates differ from the other modules |
| 72 | because they have been built for an RC oscillator with only 1% precision. The |
| 73 | receiver code inserts leap cycles to compensate for clock deviations. 1% is |
| 74 | also the precision which can be achieved by calibrating the internal RC |
| 75 | oscillator of the AVR. Please note that only AVRs with internal 64 MHz PLL |
| 76 | oscillator can reach 16.5 MHz with the RC oscillator. This includes the very |
| 77 | popular ATTiny25, ATTiny45, ATTiny85 series as well as the ATTiny26. Almost |
| 78 | all AVRs can reach 12.8 MHz, although this is outside the specified range. |
| 79 | |
| 80 | See the EasyLogger example at http://www.obdev.at/avrusb/easylogger.html for |
| 81 | code which calibrates the RC oscillator based on the USB frame clock. |
| 82 | |
| 83 | 20 MHz Clock |
| 84 | This module is for people who won't do it with less than the maximum. Since |
| 85 | 20 MHz is not divisible by the USB low speed bit clock of 1.5 MHz, the code |
| 86 | uses similar tricks as the 16 MHz module to insert leap cycles. |
| 87 | |
| 88 | |
| 89 | USB IDENTIFIERS |
| 90 | =============== |
| 91 | Every USB device needs a vendor- and a product-identifier (VID and PID). VIDs |
| 92 | are obtained from usb.org for a price of 1,500 USD. Once you have a VID, you |
| 93 | can assign PIDs at will. |
| 94 | |
| 95 | Since an entry level cost of 1,500 USD is too high for most small companies |
| 96 | and hobbyists, we provide some VID/PID pairs for free. See the file |
| 97 | USBID-License.txt for details. |
| 98 | |
| 99 | Objective Development also has some license offerings which include product |
| 100 | IDs. See http://www.obdev.at/avrusb/ for details. |
| 101 | |
| 102 | |
| 103 | DEVELOPMENT SYSTEM |
| 104 | ================== |
| 105 | This driver has been developed and optimized for the GNU compiler version 3 |
| 106 | (gcc 3). It does work well with gcc 4, but with bigger code size. We recommend |
| 107 | that you use the GNU compiler suite because it is freely available. AVR-USB |
| 108 | has also been ported to the IAR compiler and assembler. It has been tested |
| 109 | with IAR 4.10B/W32 and 4.12A/W32 on an ATmega8 with the "small" and "tiny" |
| 110 | memory model. Not every release is tested with IAR CC and the driver may |
| 111 | therefore fail to compile with IAR. Please note that gcc is more efficient for |
| 112 | usbdrv.c because this module has been deliberately optimized for gcc. |
| 113 | |
| 114 | |
| 115 | USING AVR-USB FOR FREE |
| 116 | ====================== |
| 117 | The AVR firmware driver is published under the GNU General Public License |
| 118 | Version 2 (GPL2) and the GNU General Public License Version 3 (GPL3). It is |
| 119 | your choice whether you apply the terms of version 2 or version 3. |
| 120 | |
| 121 | If you decide for the free GPL2 or GPL3, we STRONGLY ENCOURAGE you to do the |
| 122 | following things IN ADDITION to the obligations from the GPL: |
| 123 | |
| 124 | (1) Publish your entire project on a web site and drop us a note with the URL. |
| 125 | Use the form at http://www.obdev.at/avrusb/feedback.html for your submission. |
| 126 | If you don't have a web site, you can publish the project in obdev's |
| 127 | documentation wiki at |
| 128 | http://www.obdev.at/goto.php?t=avrusb-wiki&p=hosted-projects. |
| 129 | |
| 130 | (2) Adhere to minimum publication standards. Please include AT LEAST: |
| 131 | - a circuit diagram in PDF, PNG or GIF format |
| 132 | - full source code for the host software |
| 133 | - a Readme.txt file in ASCII format which describes the purpose of the |
| 134 | project and what can be found in which directories and which files |
| 135 | - a reference to http://www.obdev.at/avrusb/ |
| 136 | |
| 137 | (3) If you improve the driver firmware itself, please give us a free license |
| 138 | to your modifications for our commercial license offerings. |
| 139 | |
| 140 | |
| 141 | COMMERCIAL LICENSES FOR AVR-USB |
| 142 | =============================== |
| 143 | If you don't want to publish your source code under the terms of the GPL, |
| 144 | you can simply pay money for AVR-USB. As an additional benefit you get |
| 145 | USB PIDs for free, licensed exclusively to you. See the file |
| 146 | "CommercialLicense.txt" for details. |
| 147 | |