3 * This file contains special DoxyGen information for the generation of the main page and other special
4 * documentation pages. It is not a project source file.
7 /** \mainpage AVRISP MKII Programmer Project
9 * \section Sec_Compat Project Compatibility
11 * The following list indicates what microcontrollers are compatible with this project.
13 * \li Series 7 USB AVRs (AT90USBxxx7)
14 * \li Series 6 USB AVRs (AT90USBxxx6)
15 * \li Series 4 USB AVRs (ATMEGAxxU4)
16 * \li Series 2 USB AVRs (AT90USBxx2, ATMEGAxxU2) - <i>8KB versions with reduced features only</i>
18 * \section Sec_Info USB Information
20 * The following table gives a rundown of the USB utilization of this project.
24 * <td><b>USB Mode:</b></td>
28 * <td><b>USB Class:</b></td>
29 * <td>Vendor Specific Class</td>
32 * <td><b>USB Subclass:</b></td>
36 * <td><b>Relevant Standards:</b></td>
37 * <td>Atmel AVRISP MKII Protocol Specification</td>
40 * <td><b>Supported USB Speeds:</b></td>
41 * <td>Full Speed Mode</td>
45 * \section Sec_Description Project Description
47 * Firmware for an Atmel Studio/AVR Studio compatible AVRISP-MKII clone programmer. This project will enable the USB
48 * AVR series of microcontrollers to act as a clone of the official Atmel AVRISP-MKII programmer, usable within
49 * Atmel Studio/AVR Studio or with any software capable of driving a real Atmel AVRISP-MKII programmer. In its most
50 * basic form, it allows for the programming of AVR TINY, MEGA and XMEGA devices aat the programmer's VCC voltage from
51 * within Atmel Studio/AVR Studio with no special hardware other than the USB AVR and the parts needed for the USB
52 * interface. If the user desires, more advanced circuits incorporating level conversion can be made to allow for the
53 * programming of target AVRs running at a different voltage to the programmer.
55 * This device spoofs Atmel's official AVRISP-MKII device PID so that it remains compatible with Atmel's AVRISP-MKII
56 * drivers. When prompted, direct your OS to install Atmel's AVRISP-MKII drivers provided with Atmel Studio/AVR Studio.
58 * Note that this design currently has the following limitations:
59 * - No reversed/shorted target connector detection and notification
60 * - A separate header is required for each of the ISP, PDI and TPI programming protocols that the user wishes to use
62 * On AVR models with an ADC converter, the USB AVR's AVCC pin should be tied to 5V (e.g. VBUS) and the
63 * \c VTARGET_ADC_CHANNEL token should be set to an appropriate ADC channel number in the project makefile for VTARGET
64 * detection to operate correctly. On models without an ADC converter, VTARGET will report a fixed 3.3V level at all times
65 * which should allow the programmer to remain compatible at the protocol level with all AVR devices.
67 * While this application can be compiled for USB AVRs with as little as 8KB of FLASH, for full functionality 16KB or more
68 * of FLASH is required. On 8KB devices, ISP or PDI/TPI protocol programming support can be disabled to reduce program size.
70 * \section Sec_KnownIssues Known Issues:
72 * \par Incompatible with newer AVRDUDE releases.
73 * Due to <a href="http://savannah.nongnu.org/bugs/index.php?40831">a change in 6.0.1 and never AVRDUDE releases</a>,
74 * these builds are incompatible with the AVRISP-MKII clone project. Use an older 5.x release until AVRDUDE is patched.
76 * \par XMEGA EEPROM programming fails in some cases.
77 * Several users have reported that XMEGA EEPROM programming fails unless the chip is erased first. If a non-blank EEPROM
78 * is present, writing further EEPROM data causes corruption.
79 * <a href="https://github.com/abcminiuser/lufa/issues/25">LUFA issue tracker entry</a>.
81 * \section Sec_Installation Installation
82 * The programmer supports multiple platforms, both Windows and Linux.
84 * \subsection SSec_LinuxInstallation Linux Installation
85 * On Linux systems, the programmer should be usable out of the box with no special setup other than (on some systems)
86 * editing of the system permissions to allow the programmer to be used from a non-elevated (root) context. The programmer
87 * is compatible with the free open source AVRDude programming software project.
89 * \subsection SSec_WindowsInstallation Windows Installation
90 * On Windows systems, due to an unfortunate limitation of the USB AVR devices and the driver used in the official AVR
91 * Studio/Atmel Studio platform, the programmer cannot be made compatible with AVRDude and AVR Studio/Atmel Studio at the
92 * same time. Instead, the programmer will be compatible with the official Atmel software by default, with a recompilation
93 * with the \c LIBUSB_DRIVER_COMPAT token (see \ref Sec_Options) being required to use the alternative libUSB driver
94 * compatibility mode that will allow the programmer to work under AVRDude on Windows.
96 * If compiled for Atmel Studio/AVR Studio compatibility, install the Jungo device drivers that ship with the Atmel software.
97 * If compiled in the alternative libUSB compatibility mode for AVRDude use, install the libUSB drivers that are included
98 * with your compiled copy of AVRDude, or create them using the libUSB-Win32 (http://sourceforge.net/projects/libusb-win32)
101 * For convenience, the programmer will report two different serial numbers depending on the firmware compatibility mode, so
102 * that the correct driver can be installed for the matching firmware. If the \c RESET_TOGGLES_LIBUSB_COMPAT compile option
103 * is used (see \ref Sec_Options) this allows for an easy way to automatically switch device drivers along with the firmware
104 * compatibility mode. The serials are:
108 * <th><b>Serial Number:</b></th>
109 * <th><b>Compatibility Mode:</b></th>
112 * <td>000200012345</td>
113 * <td>Jungo (Atmel Studio) Compatibility</td>
116 * <td>000200112345</td>
117 * <td>libUSB Compatibility</td>
121 * \section Sec_ISP ISP Connections
122 * Connections to the device for SPI programming (when enabled):
126 * <th><b>Programmer Pin:</b></th>
127 * <th><b>Target Device Pin:</b></th>
128 * <th><b>ISP 6 Pin Layout:</b></th>
136 * <td>ADCx <b><sup>1</sup></b></td>
151 * <td>PORTx.y <b><sup>2</sup></b></td>
162 * In addition, the AVR's OCR1A pin will generate a 4MHz clock, to act as an external rescue device clock if the
163 * fuses have been mis-set. To use the recovery clock, connect the OCR1A pin of the USB AVR to the target AVR's
164 * XTAL1 pin, and set the ISP programming speed to 125KHz (note: other ISP speeds will not work correctly).
166 * <b><sup>1</sup></b> <i>Optional, see \ref Sec_Options section - for USB AVRs with ADC modules only</i> \n
167 * <b><sup>2</sup></b> <i>See AUX line related tokens in the \ref Sec_Options section</i>
169 * \section Sec_PDI PDI Connections
170 * Connections to the device for PDI programming (when enabled):
174 * <th><b>Programmer Pin:</b></th>
175 * <th><b>Target Device Pin:</b></th>
176 * <th><b>PDI 6 Pin Layout:</b></th>
179 * <td>Tx/Rx <b><sup>2</sup></b></td>
184 * <td>ADCx <b><sup>1</sup></b></td>
210 * <b><sup>1</sup></b> <i>Optional, see \ref Sec_Options section - for USB AVRs with ADC modules only</i> \n
211 * <b><sup>2</sup></b> <i>The AVR's Tx and Rx become the DATA line when connected together via a pair of 220 ohm resistors</i> \n
213 * \section Sec_TPI TPI Connections
214 * Connections to the device for TPI programming (when enabled):
218 * <th><b>Programmer Pin:</b></th>
219 * <th><b>Target Device Pin:</b></th>
220 * <th><b>TPI 6 Pin Layout:</b></th>
223 * <td>Tx/Rx <b><sup>2</sup></b></td>
228 * <td>ADCx <b><sup>1</sup></b></td>
233 * <td>XCK <b><sup>2</sup></b></td>
243 * <td>PORTx.y <b><sup>3</sup></b></td>
254 * <b><sup>1</sup></b> <i>Optional, see \ref Sec_Options section - for USB AVRs with ADC modules only</i> \n
255 * <b><sup>2</sup></b> <i>The AVR's Tx and Rx become the DATA line when connected together via a pair of 220 ohm resistors</i> \n
256 * <b><sup>3</sup></b> <i>See AUX line related tokens in the \ref Sec_Options section</i>
258 * \section Sec_Options Project Options
260 * The following defines can be found in this project, which can control the project behaviour when defined, or changed in value.
264 * <th><b>Define Name:</b></th>
265 * <th><b>Location:</b></th>
266 * <th><b>Description:</b></th>
269 * <td>AUX_LINE_PORT</td>
270 * <td>AppConfig.h</td>
271 * <td>PORT register for the programmer's AUX target line. The use of this line varies between the programming protocols,
272 * but is generally used for the target's /RESET line.
273 * \n \n <i>Ignored when compiled for the XPLAIN board.</i></td>
276 * <td>AUX_LINE_PIN</td>
277 * <td>AppConfig.h</td>
278 * <td>PIN register for the programmer's AUX target line. The use of this line varies between the programming protocols,
279 * but is generally used for the target's /RESET line.
280 * \n \n <i>Ignored when compiled for the XPLAIN board.</i></td>
283 * <td>AUX_LINE_DDR</td>
284 * <td>AppConfig.h</td>
285 * <td>DDR register for the programmer's AUX target line. The use of this line varies between the programming protocols,
286 * but is generally used for the target's /RESET line.
287 * \n \n <i>Ignored when compiled for the XPLAIN board.</i></td>
290 * <td>AUX_LINE_MASK</td>
291 * <td>AppConfig.h</td>
292 * <td>Mask for the programmer's AUX target line. The use of this line varies between the programming protocols,
293 * but is generally used for the target's /RESET line. <b>Must not be the AVR's /SS pin</b>.
294 * \n \n <i>Ignored when compiled for the XPLAIN board.</i></td>
297 * <td>VTARGET_ADC_CHANNEL</td>
298 * <td>AppConfig.h</td>
299 * <td>ADC channel number (on supported AVRs) to use for VTARGET level detection, if NO_VTARGET_DETECT is not defined.
300 * \n \n <i>Ignored when compiled for targets lacking an ADC.</i></td>
303 * <td>ENABLE_ISP_PROTOCOL</td>
304 * <td>AppConfig.h</td>
305 * <td>Define to enable SPI programming protocol support.
306 * \n \n <i>Ignored when compiled for the XPLAIN board.</i></td>
309 * <td>ENABLE_XPROG_PROTOCOL</td>
310 * <td>AppConfig.h</td>
311 * <td>Define to enable PDI and TPI programming protocol support.
312 * \n \n <i>Ignored when compiled for the XPLAIN board.</i></td>
315 * <td>NO_VTARGET_DETECT</td>
316 * <td>AppConfig.h</td>
317 * <td>Define to disable VTARGET sampling and reporting on AVR models with an ADC converter. This will cause the programmer
318 * to report a fixed 3.3V target voltage to the host regardless of the real target voltage.
319 * \n \n <i>Ignored when compiled for targets lacking an ADC.</i></td>
322 * <td>VTARGET_REF_VOLTS</td>
323 * <td>AppConfig.h</td>
324 * <td>Indicates the programmer AVR's AVCC reference voltage when measuring the target's supply voltage. Note that the supply
325 * voltage should never exceed the reference voltage on the programmer AVR without some form of protection to prevent damage
327 * \n \n <i>Ignored when compiled for targets lacking an ADC, or when NO_VTARGET_DETECT is defined.</i></td>
330 * <td>VTARGET_USE_INTERNAL_REF</td>
331 * <td>AppConfig.h</td>
332 * <td>Selects the internal 2.56V ADC reference voltage, instead of using the AVR's VREF pin. When enabled, this option will
333 * override the VTARGET_REF_VOLTS configuration option.
334 * \n \n <i>Ignored when compiled for targets lacking an ADC, or when NO_VTARGET_DETECT is defined.</i></td>
337 * <td>VTARGET_SCALE_FACTOR</td>
338 * <td>AppConfig.h</td>
339 * <td>Indicates the target's supply voltage scale factor when applied to the ADC. A simple resistive divider can be used on the
340 * ADC pin for measuring the target's supply voltage, so that voltages above the programmer AVR's AVCC reference voltage can be
341 * measured. This should be the reciprocal of the division performed - e.g. if the VTARGET voltage is halved, this should be set
343 * \n \n <i>Ignored when compiled for targets lacking an ADC, or when NO_VTARGET_DETECT is defined.</i></td>
346 * <td>LIBUSB_DRIVER_COMPAT</td>
347 * <td>AppConfig.h</td>
348 * <td>Define to switch to a non-standard endpoint scheme, breaking compatibility with Atmel Studio/AVR Studio under Windows but
349 * making the code compatible with software such as avrdude (all platforms) that use the libUSB driver.
351 * \note This option is incompatible with \c RESET_TOGGLES_LIBUSB_COMPAT.</td>
354 * <td>RESET_TOGGLES_LIBUSB_COMPAT</td>
355 * <td>AppConfig.h</td>
356 * <td>Define to make the /RESET line of the AVR toggle between Jungo and libUSB driver compatibility modes. Each time the AVR is
357 * reset externally via the reset pin, the compatibility mode will be toggled. The compatibility mode is preserved between
358 * power cycles and is not toggled via other forms of reset such as Watchdog or Brown Out.
360 * When this option is enabled, all board LEDs will flash twice on startup for Jungo compatibility mode, and five times for
361 * libUSB compatibility mode.
363 * \note This option is incompatible with \c LIBUSB_DRIVER_COMPAT.</td>
366 * <td>XCK_RESCUE_CLOCK_ENABLE</td>
367 * <td>AppConfig.h</td>
368 * <td>Define to move the ISP rescue clock to the AVR's XCK pin instead of the OCR1A output pin. This is useful for existing programming
369 * hardware that does not expose the OCR1A pin of the AVR, but <i>may</i> cause some issues with PDI programming mode.</td>
372 * <td>INVERTED_ISP_MISO</td>
373 * <td>AppConfig.h</td>
374 * <td>Define to invert the received data on the ISP MISO line. This is sometimes needed depending on the level translation hardware used,
375 * if the translator hardware inverts the received logic level.</td>
378 * <td>FIRMWARE_VERSION_MINOR</td>
379 * <td>AppConfig.h</td>
380 * <td>Define to set the minor firmware revision nunber reported to the host on request. By default this will use a firmware version compatible
381 * with the latest Atmel IDE version, however if desired the reported minor value can be adjusted here.</td>