Readme.txt 6.9 KB

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