Commit | Line | Data |
---|---|---|
93ac315e MPM |
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 |