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 |
|
---|