1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
|
/** \file
*
* This file contains special DoxyGen information for the generation of the main page and other special
* documentation pages. It is not a project source file.
*/
/** \page Page_GettingStarted Getting Started
*
* Out of the box, LUFA contains a large number of pre-made class demos for you to test, experiment with and
* ultimately build upon for your own projects. All the demos come pre-configured to build and run correctly
* on the AT90USB1287 AVR microcontroller, mounted on the Atmel USBKEY board and running at an 8MHz master clock.
* This is due to two reasons; one, it is the hardware the author posesses, and two, it is the most popular Atmel
* USB demonstration board to date.
*
*
* \section Sec_Prerequisites Prerequisites
* Before you can compile any of the LUFA library code or demos, you will need a recent distribution of avr-libc (1.6.2+)
* and the AVR-GCC (4.2+) compiler. For Windows users, the best way to obtain these is the WinAVR project
* (http://winavr.sourceforge.net) as this provides a single-file setup for everything required to compile your
* own AVR projects.
*
*
* \section Sec_Configuring Configuring the Demos, Bootloaders and Projects
* If the target AVR model, clock speed, board or other settings are different to the current settings, they must be changed
* and the project recompiled from the source code before being programmed into the AVR microcontroller. Most project
* configuration options are located in the "makefile" build script inside each LUFA application's folder, however some
* demo or application-specific configuration settings (such as the output format in the AudioOut demo) are located in the
* main .c source file of the project.
*
* Each project "makefile" contains all the script and configuration data required to compile each project. When opened with
* any regular basic text editor such as Notepad or Wordpad (ensure that the save format is a pure ASCII text format) the
* build configuration settings may be altered.
*
* Inside each makefile, a number of configuration variables are located, with the format "<VARIABLE NAME> = <VALUE>". For
* each application, the important variables which should be altered are:
*
* - <b>MCU</b>, the target AVR processor.
* - <b>BOARD</b>, the target board hardware
* - <b>F_CLOCK</b>, the target raw master clock frequency, before any prescaling is performed
* - <b>F_CPU</b>, the target AVR CPU master clock frequency, after any prescaling
* - <b>CDEFS</b>, the C preprocessor defines which configure the source code
*
* These values should be changed to reflect the build hardware.
*
* \subsection SSec_MCU The MCU Parameter
* This parameter indicates the target AVR model for the compiled application. This should be set to the model of the target AVR
* (such as the AT90USB1287, or the ATMEGA32U4), in all lower-case (e.g. "at90usb1287"). Note that not all demos support all the
* USB AVR models, as they may make use of peripherals or modes only present in some devices.
*
* For supported library AVR models, see main documentation page.
*
* \subsection SSec_BOARD The BOARD Parameter
* This parameter indicates the target AVR board hardware for the compiled application. Some LUFA library drivers are board-specific,
* such as the LED driver, and the library needs to know the layout of the target board. If you are using one of the board models listed
* on the main library page, change this parameter to the board name in all UPPER-case.
*
* If you are not using any board-specific drivers in the LUFA library, or you are using a custom board layout, change this to read
* "USER" (no quotes) instead of a standard board name. If the USER board type is selected and the application makes use of one or more
* board-specific hardware drivers inside the LUFA library, then the appropriate stub drives files should be copied from the /BoardStubs/
* directory into a /Board/ folder inside the application directory, and the stub driver completed with the appropriate code to drive the
* custom board's hardware.
*
* \subsection SSec_F_CLOCK The F_CLOCK Parameter
* This parameter indicates the target AVR's input clock frequency, in Hz. This is the actual clock input, before any prescaling is performed. In the
* USB AVR architecture, the input clock before any prescaling is fed directly to the PLL subsystem, and thus the PLL is derived directly from the
* clock input. The PLL then feeds the USB and other sections of the AVR with the correct upscaled frequencies required for those sections to function.
*
* <b>Note that this value does not actually *alter* the AVR's input clock frequency</b>, it is just a way to indicate to the library the clock frequency
* of the AVR as set by the AVR's fuses. If this value does not reflect the actual running frequency of the AVR, incorrect operation of one of more
* library components will ocurr.
*
* \subsection SSec_F_CPU The F_CPU Parameter
* This parameter indicates the target AVR's master CPU clock frequency, in Hz.
*
* <b>Note that this value does not actually *alter* the AVR's CPU clock frequency</b>, it is just a way to indicate to the library the clock frequency
* of the AVR core as set by the AVR's fuses. If this value does not reflect the actual running frequency of the AVR, incorrect operation of one of more
* library components will ocurr.
*
* \subsection SSec_CDEFS The CDEFS Parameter
* Most applications will actually have multiple CDEF lines, which are concatenated together with the "+=" operator. This ensures that large
* numbers of configuration options remain readable by splitting up groups of options into seperate lines.
*
* Normally, these options do not need to be altered to allow an application to compile and run correctly on a different board or AVR to the
* current configuration - if the options are incorrect, then the demo is most likely incompatible with the chosen USB AVR model and cannot be
* made to function through the altering of the makefile settings alone (or at all). Settings such as the USB mode (device, host or both), the USB
* interface speed (Low or Full speed) and other LUFA configuration options can be set here - refer to the library documentation for details on the
* configuration parameters.
*
*
* \section Sec_Compiling Compiling a LUFA Application
* Compiling the LUFA demos, applications and/or bootloaders is very simple. LUFA comes with makefile scripts for
* each individual demo, bootloader and project folder, as well as scripts in the /Demos/, /Bootloaders/, /Projects/
* and the LUFA root directory. This means that compilation can be started from any of the above directories, with
* a build started from an upper directory in the directory structure executing build of all child directories under it.
* This means that while a build inside a particular demo directory will build only that particular demo, a build stated
* from the /Demos/ directory will build all LUFA demo projects sequentially.
*
* \subsection SSec_CommandLine Via the Command Line
* To build a project from the source via the command line, the command <b>"make all"</b> should be executed from the command line in the directory
* of interest. To remove compiled files (including the binary output, all intermediatary files and all diagnostic output
* files), execute <b>"make clean"</b>. Once a "make all" has been run and no errors were encountered, the resulting binary will
* be located in the generated ".HEX" file. If your project makes use of pre-initialized EEPROM variables, the generated ".EEP"
* file will contain the project's EEPROM data.
*
* \subsection SSec_AVRStudio Via AVRStudio
* Each demo, project and bootloader contains an AVRStudio project (.aps) which can be used to build each project. Once opened
* in AVRStudio, the project can be built and cleaned using the GUI buttons or menus. Note that the AVRStudio project files make
* use of the external project makefile, thus the procedure for configuring a demo remains the same regardless of the build environment.
*
*
* \section Sec_Programming Programming a USB AVR
* Once you have built an application, you will need a way to program in the resulting ".HEX" file (and, if your
* application uses EEPROM variables with initial values, also a ".EEP" file) into your USB AVR. Normally, the
* reprogramming an AVR device must be performed using a special piece of programming hardware, through one of the
* supported AVR programming protocols - ISP, HVSP, HVPP, JTAG or dW. This can be done through a custom programmer,
* a third party programmer, or an official Atmel AVR tool - for more information, see the Atmel.com website.
*
* Alternatively, you can use the bootloader. From the Atmel factory, each USB AVR comes preloaded with the Atmel
* DFU (Device Firmware Update) class bootloader, a small piece of AVR firmware which allows the remainder of the
* AVR to be programmed through a non-standard interface such as the serial USART port, SPI, or (in this case) USB.
* Bootloaders have the advantage of not requiring any special hardware for programming, and cannot usually be erased
* or broken without an external programming device. They have disadvantages however; they cannot change the fuses of
* the AVR (special configuration settings that control the operation of the chip itself) and a small portion of the
* AVR's FLASH program memory must be reserved to contain the bootloader firmware, and thus cannot be used by the
* loaded application. Atmel's DFU bootloader is either 4KB (for the smaller USB AVRs) or 8KB (for the larger USB AVRs).
*
* If you wish to use the DFU bootloader to program in your application, refer to your DFU programmer's documentation.
* Atmel provides a free utility called FLIP which is USB AVR compatible, and an open source (Linux compatible)
* alternative exists called "dfu-programmer".
*/
|
