Readme.txt

This is the Readme file to Objective Development's firmware-only USB driverfor Atmel AVR microcontrollers. For more information please visithttp://www.obdev.at/vusb/

This directory contains the USB firmware only. Copy it as-is to your ownproject and add all .c and .S files to your project (these files are markedwith an asterisk in the list below). Then copy usbconfig-prototype.h asusbconfig.h to your project and edit it according to your configuration.

TECHNICAL DOCUMENTATION=======================The technical documentation (API) for the firmware driver is contained in thefile "usbdrv.h". Please read all of it carefully! Configuration options aredocumented in "usbconfig-prototype.h".

The driver consists of the following files: Readme.txt ............. The file you are currently reading. Changelog.txt .......... Release notes for all versions of the driver. usbdrv.h ............... Driver interface definitions and technical docs.* usbdrv.c ............... High level language part of the driver. Link this module to your code!* usbdrvasm.S ............ Assembler part of the driver. This module is mostly a stub and includes one of the usbdrvasm*.S files depending on processor clock. Link this module to your code! usbdrvasm*.inc ......... Assembler routines for particular clock frequencies. Included by usbdrvasm.S, don't link it directly! asmcommon.inc .......... Common assembler routines. Included by usbdrvasm*.inc, don't link it directly! usbconfig-prototype.h .. Prototype for your own usbdrv.h file.* oddebug.c .............. Debug functions. Only used when DEBUG_LEVEL is defined to a value greater than 0. Link this module to your code! oddebug.h .............. Interface definitions of the debug module. usbportability.h ....... Header with compiler-dependent stuff. usbdrvasm.asm .......... Compatibility stub for IAR-C-compiler. Use this module instead of usbdrvasm.S when you assembler with IAR's tools. License.txt ............ Open Source license for this driver. CommercialLicense.txt .. Optional commercial license for this driver. USB-ID-FAQ.txt ......... General infos about USB Product- and Vendor-IDs. USB-IDs-for-free.txt ... List and terms of use for free shared PIDs.

12 MHz ClockThis is the traditional clock rate of V-USB because it's the lowest clockrate where the timing constraints of the USB spec can be met.

15 MHz ClockSimilar to 12 MHz, but some NOPs inserted. On the other hand, the higher clockrate allows for some loops which make the resulting code size somewhat smallerthan the 12 MHz version.

16 MHz ClockThis clock rate has been added for users of the Arduino board and otherready-made boards which come with a fixed 16 MHz crystal. It's also an optionif you need the slightly higher clock rate for performance reasons. Since16 MHz is not divisible by the USB low speed bit clock of 1.5 MHz, the codeis somewhat tricky and has to insert a leap cycle every third byte.

12.8 MHz and 16.5 MHz ClockThe assembler modules for these clock rates differ from the other modulesbecause they have been built for an RC oscillator with only 1% precision. Thereceiver code inserts leap cycles to compensate for clock deviations. 1% isalso the precision which can be achieved by calibrating the internal RCoscillator of the AVR. Please note that only AVRs with internal 64 MHz PLLoscillator can reach 16.5 MHz with the RC oscillator. This includes the verypopular ATTiny25, ATTiny45, ATTiny85 series as well as the ATTiny26. Almostall AVRs can reach 12.8 MHz, although this is outside the specified range.

See the EasyLogger example at http://www.obdev.at/vusb/easylogger.html forcode which calibrates the RC oscillator based on the USB frame clock.

18 MHz ClockThis module is closer to the USB specification because it performs an on thefly CRC check for incoming packets. Packets with invalid checksum arediscarded as required by the spec. If you also implement checks for dataPID toggling on application level (see option USB_CFG_CHECK_DATA_TOGGLINGin usbconfig.h for more info), this ensures data integrity. Due to the CRCtables and alignment requirements, this code is bigger than modules for otherclock rates. To activate this module, you must define USB_CFG_CHECK_CRC to 1and USB_CFG_CLOCK_KHZ to 18000 in usbconfig.h.

20 MHz ClockThis module is for people who won't do it with less than the maximum. Since20 MHz is not divisible by the USB low speed bit clock of 1.5 MHz, the codeuses similar tricks as the 16 MHz module to insert leap cycles.

USB IDENTIFIERS===============Every USB device needs a vendor- and a product-identifier (VID and PID). VIDsare obtained from usb.org for a price of 1,500 USD. Once you have a VID, youcan assign PIDs at will.

Since an entry level cost of 1,500 USD is too high for most small companiesand hobbyists, we provide some VID/PID pairs for free. See the fileUSB-IDs-for-free.txt for details.

Objective Development also has some license offerings which include productIDs. See http://www.obdev.at/vusb/ for details.

DEVELOPMENT SYSTEM==================This driver has been developed and optimized for the GNU compiler version 3(gcc 3). It does work well with gcc 4, but with bigger code size. We recommendthat you use the GNU compiler suite because it is freely available. V-USBhas also been ported to the IAR compiler and assembler. It has been testedwith IAR 4.10B/W32 and 4.12A/W32 on an ATmega8 with the "small" and "tiny"memory model. Not every release is tested with IAR CC and the driver maytherefore fail to compile with IAR. Please note that gcc is more efficient forusbdrv.c because this module has been deliberately optimized for gcc.

USING V-USB FOR FREE====================The AVR firmware driver is published under the GNU General Public LicenseVersion 2 (GPL2) and the GNU General Public License Version 3 (GPL3). It isyour choice whether you apply the terms of version 2 or version 3.

If you decide for the free GPL2 or GPL3, we STRONGLY ENCOURAGE you to do thefollowing things IN ADDITION to the obligations from the GPL:

(1) Publish your entire project on a web site and drop us a note with the URL.Use the form at http://www.obdev.at/vusb/feedback.html for your submission.If you don't have a web site, you can publish the project in obdev'sdocumentation wiki athttp://www.obdev.at/goto.php?t=vusb-wiki&p=hosted-projects.

(2) Adhere to minimum publication standards. Please include AT LEAST: - a circuit diagram in PDF, PNG or GIF format - full source code for the host software - a Readme.txt file in ASCII format which describes the purpose of the project and what can be found in which directories and which files - a reference to http://www.obdev.at/vusb/

COMMERCIAL LICENSES FOR V-USB=============================If you don't want to publish your source code under the terms of the GPL,you can simply pay money for V-USB. As an additional benefit you getUSB PIDs for free, reserved exclusively to you. See the file"CommercialLicense.txt" for details.