From c2135f2776e01842a775502c24b59d9169ffa851 Mon Sep 17 00:00:00 2001 From: Dean Camera <dean@fourwalledcubicle.com> Date: Thu, 2 Jun 2011 13:40:53 +0000 Subject: [PATCH] Expand the documentation for each Bootloader to give sample usage instructions for the command line programmer utilities. Fix typo in the HID class bootloader CLI programmer application usage instructions. --- Bootloaders/CDC/BootloaderCDC.txt | 30 ++++++++++- Bootloaders/DFU/BootloaderDFU.txt | 54 +++++++++++++------ Bootloaders/HID/BootloaderHID.txt | 22 +++++++- .../HID/HostLoaderApp/hid_bootloader_cli.c | 2 +- 4 files changed, 87 insertions(+), 21 deletions(-) diff --git a/Bootloaders/CDC/BootloaderCDC.txt b/Bootloaders/CDC/BootloaderCDC.txt index 81e454d0e0..4225a4019e 100644 --- a/Bootloaders/CDC/BootloaderCDC.txt +++ b/Bootloaders/CDC/BootloaderCDC.txt @@ -51,13 +51,41 @@ * you wish to enlarge this space and/or change the AVR model, you will need to edit the BOOT_START and MCU * values in the accompanying makefile. * - * This bootloader is compatible with the open source application AVRDUDE, or Atmel's AVRPROG. + * When the bootloader is running, the board's LED(s) will flash at regular intervals to distinguish the + * bootloader from the normal user application. + * + * \section Sec_Installation Driver Installation * * After running this bootloader for the first time on a new computer, you will need to supply the .INF * file located in this bootloader project's directory as the device's driver when running under Windows. * This will enable Windows to use its inbuilt CDC drivers, negating the need for custom drivers for the * device. Other Operating Systems should automatically use their own inbuilt CDC-ACM drivers. * + * \section Sec_HostApp Host Controller Application + * + * This bootloader is compatible with the open source application AVRDUDE, Atmel's AVRPROG, or other + * applications implementing the AVR109 protocol, which is documented on the Atmel website as an application + * note. + * + * \subsection SSec_AVRDude AVRDUDE (Windows, Mac, Linux) + * + * AVRDude is a free, cross-platform and open source command line programmer for Atmel and third party AVR + * programmers. It is available on the the Windows platform as part of the "WinAVR" package, or on other systems + * either from a build from the official source code, or in many distributions as a precompiled binary package. + * + * To load a new HEX file with AVRDude, specify "AVR109" as the programmer, with the allocated COM port. On Windows + * platforms this will be a COMx port name: + * \code + * avrdude -c AVR109 -p at90usb1287 -P COM0 -U flash:w:Mouse.hex + * \endcode + * + * On Linux systems, this will typically be a /dev/ttyACMx port name: + * \code + * avrdude -c AVR109 -p at90usb1287 -P /dev/ttyACM0 -U flash:w:Mouse.hex + * \endcode + * + * Refer to the AVRDude project documentation for additional usage instructions. + * * \section Sec_Options Project Options * * The following defines can be found in this demo, which can control the demo behaviour when defined, or changed in value. diff --git a/Bootloaders/DFU/BootloaderDFU.txt b/Bootloaders/DFU/BootloaderDFU.txt index 189b3c0dbd..858549f008 100644 --- a/Bootloaders/DFU/BootloaderDFU.txt +++ b/Bootloaders/DFU/BootloaderDFU.txt @@ -47,27 +47,47 @@ * This bootloader enumerates to the host as a DFU Class device, allowing for DFU-compatible programming * software to load firmware onto the AVR. * - * This bootloader is compatible with Atmel's FLIP application. However, it requires the use of Atmel's - * DFU drivers. You will need to install Atmel's DFU drivers prior to using this bootloader. If you are - * using a 64 bit Windows OS, you will need to either disable the driver signing requirement (see online - * tutorials for details) or use a digitally signed version of the official Atmel driver provided by a - * third party AVR user at - * <a>http://www.avrfreaks.net/index.php?module=Freaks%20Academy&func=viewItem&item_id=2196&item_type=project</a>. - * - * As an open-source option, this bootloader is also compatible with the Linux Atmel USB DFU Programmer - * software, available for download at <a>http://sourceforge.net/projects/dfu-programmer/</a>. - * - * If SECURE_MODE is defined as true, upon start-up the bootloader will be locked, with only the chip erase - * function available (similar to Atmel's DFU bootloader). If SECURE_MODE is defined as false, all functions - * are usable on start-up without the prerequisite firmware erase. - * * Out of the box this bootloader builds for the USB1287, and should fit into 4KB of bootloader space. If * you wish to enlarge this space and/or change the AVR model, you will need to edit the BOOT_START and MCU * values in the accompanying makefile. * - * <b>NOTE:</b> This device spoofs Atmel's DFU Bootloader USB VID and PID so that the Atmel DFU bootloader - * drivers included with FLIP will work. If you do not wish to use Atmel's ID codes, please - * manually change them in Descriptors.c and alter your driver's INF file accordingly. + * When the bootloader is running, the board's LED(s) will flash at regular intervals to distinguish the + * bootloader from the normal user application. + * + * \section Sec_Installation Driver Installation + * + * This bootloader is designed to be compatible with Atmel's provided Windows DFU class drivers. You will need to + * install Atmel's DFU drivers prior to using this bootloader on Windows platforms. If you are using a 64 bit Windows + * OS, you will need to either disable the driver signing requirement (see online tutorials for details) or use a + * digitally signed version of the official Atmel driver provided by a third party AVR user at + * <a>http://www.avrfreaks.net/index.php?module=Freaks%20Academy&func=viewItem&item_id=2196&item_type=project</a>. + * + * \note This device spoofs Atmel's DFU Bootloader USB VID and PID so that the Atmel DFU bootloader + * drivers included with FLIP will work. If you do not wish to use Atmel's ID codes, please + * manually change them in Descriptors.c and alter your driver's INF file accordingly. + * + * \section Sec_HostApp Host Controller Application + * + * This bootloader is compatible with Atmel's FLIP utility on Windows machines, and dfu-programmer on Linux machines. + * + * \subsection SSec_FLIP FLIP (Windows) + * + * FLIP (Flexible In-System Programmer) is a utility written by Atmel, and distributed for free on the Atmel website. + * The FLIP utility is designed to assist in the bootloader programming of a range of Atmel devices, through several + * popular physical interfaces including USB. It is written in Java, however makes use of native extensions for USB + * support and thus is only offered on Windows. + * + * To program a device using FLIP, refer to the Atmel FLIP documentation. + * + * \subsection SSec_DFUProgrammer dfu-programmer (Linux) + * + * dfu-programmer is an open-source command line solution for the bootloader programming of Atmel devices through a + * USB connection, using the DFU protocol, available for download at <a>http://sourceforge.net/projects/dfu-programmer/</a>. + * + * The following example loads a HEX file into the AVR's FLASH memory using dfu-programmer: + * \code + * dfu-programmer at90usb1287 erase flash Mouse.hex + * \endcode * * \section Sec_Options Project Options * diff --git a/Bootloaders/HID/BootloaderHID.txt b/Bootloaders/HID/BootloaderHID.txt index 51dceb8319..d695822127 100644 --- a/Bootloaders/HID/BootloaderHID.txt +++ b/Bootloaders/HID/BootloaderHID.txt @@ -48,14 +48,32 @@ * * This bootloader enumerates to the host as a HID Class device, allowing for device FLASH programming through * the supplied command line software, which is a modified version of Paul's TeensyHID Command Line loader code - * from PJRC, used with permission. This bootloader is delibertely non-compatible with the properietary HalfKay - * bootloader GUI; only the command line interface software accompanying this bootloader will work with it. + * from PJRC (used with permission). This bootloader is deliberatley non-compatible with the properietary PJRC + * HalfKay bootloader GUI; only the command line interface software accompanying this bootloader will work with it. * * Out of the box this bootloader builds for the USB1287, and will fit into 2KB of bootloader space for the * Series 2 USB AVRs (ATMEGAxxU2, AT90USBxx2) or 4KB of bootloader space for all other models. If you wish to * enlarge this space and/or change the AVR model, you will need to edit the BOOT_START and MCU values in the * accompanying makefile. * + * \section Sec_Installation Driver Installation + * + * This bootloader uses the HID class driver inbuilt into all modern operating systems, thus no additional drivers + * need to be supplied for correct operation. + * + * \section Sec_HostApp Host Controller Application + * + * Due to licensing issues, the supplied bootloader is compatible with the HalfKay bootloader protocol designed + * by PJRC, but is non-compatible with the cross-platform loader GUI. A modified version of the open source + * cross-platform TeensyLoader application is supplied, which can be compiled under most operating systems. The + * command-line loader application should remain compatible with genuine Teensy boards in addition to boards using + * this custom bootloader. + * + * Once compiled, programs can be loaded into the AVR's FLASH memory through the following example command: + * \code + * hid_bootloader_cli -mmcu=at90usb1287 Mouse.hex + * \endcode + * * \section SSec_Options Project Options * * The following defines can be found in this demo, which can control the demo behaviour when defined, or changed in value. diff --git a/Bootloaders/HID/HostLoaderApp/hid_bootloader_cli.c b/Bootloaders/HID/HostLoaderApp/hid_bootloader_cli.c index 0562690a68..e22d394041 100644 --- a/Bootloaders/HID/HostLoaderApp/hid_bootloader_cli.c +++ b/Bootloaders/HID/HostLoaderApp/hid_bootloader_cli.c @@ -49,7 +49,7 @@ void usage(void) fprintf(stderr, "\n<MCU> = atmegaXXuY or at90usbXXXY"); fprintf(stderr, "\nFor support and more information, please visit:\n"); - fprintf(stderr, "http://www.lufa-lub.org\n"); + fprintf(stderr, "http://www.lufa-lib.org\n"); fprintf(stderr, "\nBased on the TeensyHID command line programmer software:\n"); fprintf(stderr, "http://www.pjrc.com/teensy/loader_cli.html\n");