Rev 3332 Rev 3333
1 This is the Readme file to Objective Development's firmware-only USB driver 1 This is the Readme file to Objective Development's firmware-only USB driver
2 for Atmel AVR microcontrollers. For more information please visit 2 for Atmel AVR microcontrollers. For more information please visit
3 http://www.obdev.at/avrusb/ 3 http://www.obdev.at/vusb/
4   4  
5 This directory contains the USB firmware only. Copy it as-is to your own 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 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
7 "usbconfig.h" can be found in "usbconfig-prototype.h" in this directory. 8 usbconfig.h to your project and edit it according to your configuration.
8   9  
9   10  
10 TECHNICAL DOCUMENTATION 11 TECHNICAL DOCUMENTATION
11 ======================= 12 =======================
12 The technical documentation for the firmware driver is contained in the file 13 The technical documentation (API) for the firmware driver is contained in the
13 "usbdrv.h". Please read all of it carefully! 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 USB-ID-FAQ.txt ......... General infos about USB Product- and Vendor-IDs.
-   43 USB-IDs-for-free.txt ... List and terms of use for free shared PIDs.
-   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 18 MHz and 20 MHz. Other clock rates are not supported. The
-   52 actual clock rate must be configured in usbconfig.h.
-   53  
-   54 12 MHz Clock
-   55 This is the traditional clock rate of V-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/vusb/easylogger.html for
-   81 code which calibrates the RC oscillator based on the USB frame clock.
-   82  
-   83 18 MHz Clock
-   84 This module is closer to the USB specification because it performs an on the
-   85 fly CRC check for incoming packets. Packets with invalid checksum are
-   86 discarded as required by the spec. If you also implement checks for data
-   87 PID toggling on application level (see option USB_CFG_CHECK_DATA_TOGGLING
-   88 in usbconfig.h for more info), this ensures data integrity. Due to the CRC
-   89 tables and alignment requirements, this code is bigger than modules for other
-   90 clock rates. To activate this module, you must define USB_CFG_CHECK_CRC to 1
-   91 and USB_CFG_CLOCK_KHZ to 18000 in usbconfig.h.
-   92  
-   93 20 MHz Clock
-   94 This module is for people who won't do it with less than the maximum. Since
-   95 20 MHz is not divisible by the USB low speed bit clock of 1.5 MHz, the code
-   96 uses similar tricks as the 16 MHz module to insert leap cycles.
14   97  
15   98  
16 USB IDENTIFIERS 99 USB IDENTIFIERS
17 =============== 100 ===============
18 Every USB device needs a vendor- and a product-identifier (VID and PID). VIDs 101 Every USB device needs a vendor- and a product-identifier (VID and PID). VIDs
19 are obtained from usb.org for a price of 1,500 USD. Once you have a VID, you 102 are obtained from usb.org for a price of 1,500 USD. Once you have a VID, you
20 can assign PIDs at will. 103 can assign PIDs at will.
21   104  
22 Since an entry level cost of 1,500 USD is too high for most small companies 105 Since an entry level cost of 1,500 USD is too high for most small companies
23 and hobbyists, we provide a single VID/PID pair for free. If you want to use 106 and hobbyists, we provide some VID/PID pairs for free. See the file
24 your own VID and PID instead of our's, define the macros "USB_CFG_VENDOR_ID" -  
25 and "USB_CFG_DEVICE_ID" accordingly in "usbconfig.h". -  
26   -  
27 To use our predefined VID/PID pair, you MUST conform to a couple of -  
28 requirements. See the file "USBID-License.txt" for details. 107 USB-IDs-for-free.txt for details.
29   108  
30 Objective Development also has some offerings which include product IDs. See 109 Objective Development also has some license offerings which include product
31 http://www.obdev.at/avrusb/ for details. 110 IDs. See http://www.obdev.at/vusb/ for details.
32   -  
33   -  
34 HOST DRIVER -  
35 =========== -  
36 You have received this driver together with an example device implementation -  
37 and an example host driver. The host driver is based on libusb and compiles -  
38 on various Unix flavors (Linux, BSD, Mac OS X). It also compiles natively on -  
39 Windows using MinGW (see www.mingw.org) and libusb-win32 (see -  
40 libusb-win32.sourceforge.net). The "Automator" project contains a native -  
41 Windows host driver (not based on libusb) for Human Interface Devices. -  
42   111  
43   112  
44 DEVELOPMENT SYSTEM 113 DEVELOPMENT SYSTEM
45 ================== 114 ==================
46 This driver has been developed and optimized for the GNU compiler version 3 115 This driver has been developed and optimized for the GNU compiler version 3
47 (gcc 3). It does work well with gcc 4 and future versions will probably be -  
48 optimized for gcc 4. We recommend that you use the GNU compiler suite because 116 and 4. We recommend that you use the GNU compiler suite because it is freely
49 it is freely available. AVR-USB has also been ported to the IAR compiler and 117 available. V-USB has also been ported to the IAR compiler and assembler. It
50 assembler. It has been tested with IAR 4.10B/W32 and 4.12A/W32 on an ATmega8 118 has been tested with IAR 4.10B/W32 and 4.12A/W32 on an ATmega8 with the
51 with the "small" and "tiny" memory model. Please note that gcc is more 119 "small" and "tiny" memory model. Not every release is tested with IAR CC and
-   120 the driver may therefore fail to compile with IAR. Please note that gcc is
52 efficient for usbdrv.c because this module has been deliberately optimized 121 more efficient for usbdrv.c because this module has been deliberately
53 for gcc. 122 optimized for gcc.
-   123  
-   124 Gcc version 3 produces smaller code than version 4 due to new optimizing
-   125 capabilities which don't always improve things on 8 bit CPUs. The code size
-   126 generated by gcc 4 can be reduced with the compiler options
-   127 -fno-move-loop-invariants, -fno-tree-scev-cprop and
-   128 -fno-inline-small-functions in addition to -Os. On devices with more than
-   129 8k of flash memory, we also recommend the linker option --relax (written as
-   130 -Wl,--relax for gcc) to convert absolute calls into relative where possible.
-   131  
-   132 For more information about optimizing options see:
-   133  
-   134 http://www.tty1.net/blog/2008-04-29-avr-gcc-optimisations_en.html
-   135  
-   136 These optimizations are good for gcc 4.x. Version 3.x of gcc does not support
-   137 most of these options and produces good code anyway.
54   138  
55   139  
56 USING AVR-USB FOR FREE 140 USING V-USB FOR FREE
57 ====================== 141 ====================
58 The AVR firmware driver is published under the GNU General Public License 142 The AVR firmware driver is published under the GNU General Public License
59 Version 2 (GPL2). See the file "License.txt" for details. 143 Version 2 (GPL2) and the GNU General Public License Version 3 (GPL3). It is
-   144 your choice whether you apply the terms of version 2 or version 3.
60   145  
61 If you decide for the free GPL2, we STRONGLY ENCOURAGE you to do the following 146 If you decide for the free GPL2 or GPL3, we STRONGLY ENCOURAGE you to do the
62 things IN ADDITION to the obligations from the GPL2: 147 following things IN ADDITION to the obligations from the GPL:
63   148  
64 (1) Publish your entire project on a web site and drop us a note with the URL. 149 (1) Publish your entire project on a web site and drop us a note with the URL.
65 Use the form at http://www.obdev.at/avrusb/feedback.html for your submission. 150 Use the form at http://www.obdev.at/vusb/feedback.html for your submission.
-   151 If you don't have a web site, you can publish the project in obdev's
-   152 documentation wiki at
-   153 http://www.obdev.at/goto.php?t=vusb-wiki&p=hosted-projects.
66   154  
67 (2) Adhere to minimum publication standards. Please include AT LEAST: 155 (2) Adhere to minimum publication standards. Please include AT LEAST:
68 - a circuit diagram in PDF, PNG or GIF format 156 - a circuit diagram in PDF, PNG or GIF format
69 - full source code for the host software 157 - full source code for the host software
70 - a Readme.txt file in ASCII format which describes the purpose of the 158 - a Readme.txt file in ASCII format which describes the purpose of the
71 project and what can be found in which directories and which files 159 project and what can be found in which directories and which files
72 - a reference to http://www.obdev.at/avrusb/ 160 - a reference to http://www.obdev.at/vusb/
73   161  
74 (3) If you improve the driver firmware itself, please give us a free license 162 (3) If you improve the driver firmware itself, please give us a free license
75 to your modifications for our commercial license offerings. 163 to your modifications for our commercial license offerings.
76   164  
77   165  
78 COMMERCIAL LICENSES FOR AVR-USB 166 COMMERCIAL LICENSES FOR V-USB
79 =============================== 167 =============================
80 If you don't want to publish your source code under the terms of the GPL2, 168 If you don't want to publish your source code under the terms of the GPL,
81 you can simply pay money for AVR-USB. As an additional benefit you get 169 you can simply pay money for V-USB. As an additional benefit you get
82 USB PIDs for free, licensed exclusively to you. See the file 170 USB PIDs for free, reserved exclusively to you. See the file
83 "CommercialLicense.txt" for details. 171 "CommercialLicense.txt" for details.
84   172