From 620a1658a2d0f4aaf6fa13f450df89886e81f5c4 Mon Sep 17 00:00:00 2001 From: cpldcpu Date: Sat, 6 Jun 2015 20:36:44 +0200 Subject: update readme --- Readme.txt | 121 +++++++++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 93 insertions(+), 28 deletions(-) (limited to 'Readme.txt') diff --git a/Readme.txt b/Readme.txt index ac2d7db..a614e55 100644 --- a/Readme.txt +++ b/Readme.txt @@ -1,6 +1,78 @@ -Micronucleus +Micronucleus V2.0b ============= -Micronucleus is a bootloader designed for AVR tiny 85 chips with a minimal usb interface, cross platform libusb-based program upload tool, and a strong emphasis on bootloader compactness. The project aims to release a 2.0kb usb bootloader, and has reached this goal with the latest release. By using the tinyvector mechanism designed by Embedded Creations in their USBaspLoader-tiny85 project, combined with the simplicity of Objective Development's bootloadHID and a unique bare bones usb protocol, Micronucleus is the smallest usb bootloader available for tiny85 at the time of writing. +Micronucleus is a bootloader designed for AVR ATtiny microcontrollers with a minimal usb interface, cross platform libusb-based program upload tool, and a strong emphasis on bootloader compactness. To the authors knowledge this is, by far, the smallest USB bootloader for AVR ATtiny + +The V2.0 release is a complete rewrite of the firmware and offers significant improvements over V1.x: + + • Support for the entire ATtiny family instead of only ATtiny85 + • Much smaller size. All configurations are below 2kb. + • Interrupt free V-USB does not require patching of the user program INT-vector anymore. + • Faster uploads due to new protocol. + • Far jmp also allows using ATtinies with more than 8kb flash. + • Many robustness improvements, such as compatibility to USB hubs and less erratic time out behavior. + +Due to the many changes, also the uploadtool had to be updated. The V2.0 upload tool is backwards compatible to the V1.X tool, though. + +The last release of the V1.x can be found here: https://github.com/micronucleus/micronucleus/tree/v1.11 + +Usage +===== + +The bootloader allows uploading of new firmware via USB. In its usual configuration it is invoked at device reset and will identify to the host computer. If no comminucation is initiated by the host machine within a given time, the bootloader will time out and enter the user program, if one is present. + +For proper timing, the commmand line tool should to be started on the host computer _before_ the bootloader is invoked. + +Windows machines will need to install the libusb drivers found in the /windows_drivers folder. Clean Micronucleus devices without uploaded userprogram will not time out and allow suffucient time for proper driver installation. Linux and OS X do not require custom drivers. + +Please invoke the command line tool with "microcleus -help" for a list of available options. + +The bootloader resides in the same memory as the user program, since the ATtiny series does not support a protected bootloader section. Therefore, special care has to be taken not to overwrite the bootloader if the user programm uses the self programming features. The bootloader will patch itself into the reset vector of the user program. No other interrupt vectors are changed. + +Compiling +========= + +Micronucleus can be configured to support all devices of the ATtiny series, with the expection of the reduced core ATtiny 4/5/9/10/20/40. + +To allow maximum flexibility, micronucleus supports a configuration system. To compile micronucleus with a specific configuratiion, please invoke the AVR-GCC toolchain with: + + make CONFIG= + +Currently the following configurations are included and tested. Please check /firmware/configurations/ for details. Hex files can be found in /releases. + +t84_default - ATtiny84A default configuration - 1532 bytes +t841_default - ATtiny841 default configuration - 1584 bytes +t85_default - ATtiny85 default configuration - 1606 bytes +t85_aggressive - ATtiny85 smaller size - critical - 1414 bytes +t167_default - ATtiny167 default (uses xtal) - 1390 bytes +Nanite841 - Nanite841 firmware - 1608 bytes + +You can add your own configuration by adding a new folder to /firmware/configurations/. The folder has to contain a customized "Makefile.inc" and "boorloaderconfig.h". The bootloader options are explaines in these files. Feel free to supply a pull request if you added and tested a previously unsupported device. + +If changes to the configuration lead to an increase in bootloader size, it may be necessary to change the bootloader start address. Please consult "Makefile.inc" for details. + +Other make options: + + make CONFIG= fuse # to set the clock generator, boot section size etc. + make CONFIG= flash # to load the boot loader into flash using avrdude + +There is also an option to disable the reset line and use it as an I/O. While it may seem tempting to use this feature to make available an additional I/O pin available on the ATtiny85, we strongly discourage from doing so, as it led to many issues in the past. + +Please "make clean" when switching from one configuration to another. + +Devices using Micronucleus +========================== + +Micronucleus is widely installed on thousands of open source hardware devices. Please find an incomplete list here https://github.com/micronucleus/micronucleus/Devices_with_Microncleus.md + +License +======= + +This project is released under the GPLv2 license. Code uploaded via the bootloader is not subject to any license issues. + + + + + Micronucleus adds a small amount of delay to the Pin Change interrupt in user applications, but this latency is low enough to not interfere with V-USB applications. Once bootloaded, an ISP or HVSP programmer can disable the reset pin, offering an extra pin for GPIO and ADC use! After disabling the reset pin functionality, of course you will no longer be able to use ISP programmers with the chip, but that's okay because we made a neat 'upgrade' program. The Upgrade program takes a compiled bootloader hex file and packs it in to an AVR program. You upload the 'upgrade' program via an existing micronucleus installation, any other bootloader, or via ISP or HVSP programmer, and once uploaded the upgrade program runs and writes over the bootloader and then installs a trampoline over it's own interrupt vector table, then reboots, launching the new bootloader. In this way users can change their bootloader to have bugfixes or different configurations like the 'jumper' versions without needing any programming tools. @@ -11,37 +83,30 @@ Micronucleus is now widely installed on over 40,000 Digispark devices from Digis Changes ======= -This is release 1.11. Please use this at your own risk. The last official release for the DigiSpark is v1.06, which can be found here: https://github.com/micronucleus/micronucleus/tree/v1.06 - -Changes compared to v1.10: - • The size was reduced further to 1816 bytes, allowing 6380 bytes user space. - (320 bytes more than in v1.06) - • The bootloader will always start and never quit if no user program was loaded. - This allows for much easier driver installation. Use the new "--erase-only" - function of the command line tool to create a clean device. - • New entrymodes have been added. See firmware release notes and source code - comments for details. - • All incoming data is now CRC checked to improve robustness. - -Changes compared to v1.06: - • Major size optimization and code reorganization. - • The size was reduced to 1878 bytes, allowing 6314 bytes user space - (256 bytes more than in v1.06). - • The bootloader will disconnect from USB on exit. +This pull request documents changes leading to V2.0: https://github.com/micronucleus/micronucleus/pull/43 -See release notes (/firmware/releases/release notes.txt) for details. - -@cpldcpu - Jan 14th, 2013 ----------------------------------------------------------------------------------- +Credits +======= + +Firmware: + • Micronucleus V2.0 (c) 2015 Tim Bo"scke - cpldcpu@gmail.com + (c) 2014 Shay Green + • Original Micronucleus (c) 2012 Jenna Fox + + • Based on USBaspLoader-tiny85 (c) 2012 Louis Beaudoin + • Based on USBaspLoader (c) 2007 by OBJECTIVE DEVELOPMENT Software GmbH + +Commandline tool: + + • Original commandline tool (c) 2012 by ihsan Kehribar + • Updates for V2.x (c) 2014 T. Bo"scke + Special Thanks: - • Shay Green/@gblargg for numerous optimization ideas. + • Aaron Stone/@sodabrew for building the OS X command line tool and various fixes. • Objective Development's great V-USB bitbanging usb driver • Embedded Creations' pioneering and inspiring USBaspLoader-tiny85 • Digistump for motivation and contributing the VID/PID pair - • Ihsan Kehribar for the command line C-based upload tool - -This project is released under the GPLv2 license. Code uploaded via the bootloader is not subject to any license issues. - + \ No newline at end of file -- cgit v1.2.3 From b0689a013f0b9544c4b448755ed8bc888bf6deb3 Mon Sep 17 00:00:00 2001 From: cpldcpu Date: Sat, 6 Jun 2015 20:54:54 +0200 Subject: update of readme. --- Readme.txt | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) (limited to 'Readme.txt') diff --git a/Readme.txt b/Readme.txt index a614e55..938fe91 100644 --- a/Readme.txt +++ b/Readme.txt @@ -6,10 +6,11 @@ The V2.0 release is a complete rewrite of the firmware and offers significant im • Support for the entire ATtiny family instead of only ATtiny85 • Much smaller size. All configurations are below 2kb. - • Interrupt free V-USB does not require patching of the user program INT-vector anymore. + • Interrupt free V-USB: no patching of the user program INT-vector anymore. • Faster uploads due to new protocol. • Far jmp also allows using ATtinies with more than 8kb flash. - • Many robustness improvements, such as compatibility to USB hubs and less erratic time out behavior. + • Many robustness improvements, such as compatibility to USB hubs and + less erratic time out behavior. Due to the many changes, also the uploadtool had to be updated. The V2.0 upload tool is backwards compatible to the V1.X tool, though. @@ -52,8 +53,8 @@ If changes to the configuration lead to an increase in bootloader size, it may b Other make options: - make CONFIG= fuse # to set the clock generator, boot section size etc. - make CONFIG= flash # to load the boot loader into flash using avrdude + make CONFIG= fuse # Configure fuses + make CONFIG= flash # Uploade the bootloader using AVRDUDE There is also an option to disable the reset line and use it as an I/O. While it may seem tempting to use this feature to make available an additional I/O pin available on the ATtiny85, we strongly discourage from doing so, as it led to many issues in the past. @@ -62,23 +63,27 @@ Please "make clean" when switching from one configuration to another. Devices using Micronucleus ========================== -Micronucleus is widely installed on thousands of open source hardware devices. Please find an incomplete list here https://github.com/micronucleus/micronucleus/Devices_with_Microncleus.md +Micronucleus is widely installed on thousands of open source hardware devices. Please find an incomplete list here: + https://github.com/micronucleus/micronucleus/Devices_with_Microncleus.md License ======= This project is released under the GPLv2 license. Code uploaded via the bootloader is not subject to any license issues. +In addition, we'd like you to consider these points as well if you intend to sell devices using micronucleus: - - - - -Micronucleus adds a small amount of delay to the Pin Change interrupt in user applications, but this latency is low enough to not interfere with V-USB applications. Once bootloaded, an ISP or HVSP programmer can disable the reset pin, offering an extra pin for GPIO and ADC use! After disabling the reset pin functionality, of course you will no longer be able to use ISP programmers with the chip, but that's okay because we made a neat 'upgrade' program. The Upgrade program takes a compiled bootloader hex file and packs it in to an AVR program. You upload the 'upgrade' program via an existing micronucleus installation, any other bootloader, or via ISP or HVSP programmer, and once uploaded the upgrade program runs and writes over the bootloader and then installs a trampoline over it's own interrupt vector table, then reboots, launching the new bootloader. In this way users can change their bootloader to have bugfixes or different configurations like the 'jumper' versions without needing any programming tools. - -tiny85 does not offer any hardware bootloading support, and does not protect the bootloader from being accidentally overwritten by a misbehaving app. We recommend great caution if using flash self programming inside an uploaded program due to the potential of bricking. - -Micronucleus is now widely installed on over 40,000 Digispark devices from Digistump - a tiny unofficial arduino device, so you can be confident that micronucleus will be well supported in the future. Micronucleus is now also the recommended bootloader for Ihsan Kehribar's wonderful LittleWire devices, and can be successfully installed on to existing LittleWire's by uploading the 'upgrade' program via the old serial bootloader, then uploading the littlewire firmware via the micronucleus command line upload tool. + • Please make your hardware open source. At least the schematic needs to be + published according to the license inherited from V-USB. + + • Your documentation should mention Micronucleus and include a link to the + main repository (https://github.com/micronucleus/) + + • Please do not "rebrand" micronucleus. + + • Feel welcome to submit a pull request to include your product in the + "Devices using Micronucleus"-list. + Changes ======= -- cgit v1.2.3 From b082bd33a01707c67b41c511656557076da787fe Mon Sep 17 00:00:00 2001 From: cpldcpu Date: Sat, 6 Jun 2015 21:04:33 +0200 Subject: readme --- Readme.txt | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) (limited to 'Readme.txt') diff --git a/Readme.txt b/Readme.txt index 938fe91..1904e53 100644 --- a/Readme.txt +++ b/Readme.txt @@ -16,6 +16,7 @@ Due to the many changes, also the uploadtool had to be updated. The V2.0 upload The last release of the V1.x can be found here: https://github.com/micronucleus/micronucleus/tree/v1.11 + Usage ===== @@ -29,6 +30,7 @@ Please invoke the command line tool with "microcleus -help" for a list of availa The bootloader resides in the same memory as the user program, since the ATtiny series does not support a protected bootloader section. Therefore, special care has to be taken not to overwrite the bootloader if the user programm uses the self programming features. The bootloader will patch itself into the reset vector of the user program. No other interrupt vectors are changed. + Compiling ========= @@ -60,18 +62,20 @@ There is also an option to disable the reset line and use it as an I/O. While it Please "make clean" when switching from one configuration to another. + Devices using Micronucleus ========================== Micronucleus is widely installed on thousands of open source hardware devices. Please find an incomplete list here: - https://github.com/micronucleus/micronucleus/Devices_with_Microncleus.md +https://github.com/micronucleus/micronucleus/Devices_with_Microncleus.md + License ======= This project is released under the GPLv2 license. Code uploaded via the bootloader is not subject to any license issues. -In addition, we'd like you to consider these points as well if you intend to sell devices using micronucleus: +In addition, we'd like you to consider these points if you intend to sell products using micronucleus: • Please make your hardware open source. At least the schematic needs to be published according to the license inherited from V-USB. @@ -82,9 +86,9 @@ In addition, we'd like you to consider these points as well if you intend to sel • Please do not "rebrand" micronucleus. • Feel welcome to submit a pull request to include your product in the - "Devices using Micronucleus"-list. - + "Devices using Micronucleus"-list. + Changes ======= @@ -96,12 +100,12 @@ Credits Firmware: - • Micronucleus V2.0 (c) 2015 Tim Bo"scke - cpldcpu@gmail.com - (c) 2014 Shay Green - • Original Micronucleus (c) 2012 Jenna Fox + • Micronucleus V2.0 (c) 2015 Tim Bo"scke - cpldcpu@gmail.com + (c) 2014 Shay Green + • Original Micronucleus (c) 2012 Jenna Fox - • Based on USBaspLoader-tiny85 (c) 2012 Louis Beaudoin - • Based on USBaspLoader (c) 2007 by OBJECTIVE DEVELOPMENT Software GmbH + • Based on USBaspLoader-tiny85 (c) 2012 Louis Beaudoin + • Based on USBaspLoader (c) 2007 by OBJECTIVE DEVELOPMENT Software GmbH Commandline tool: -- cgit v1.2.3 From cb935e1c297e880ff4506b43e4a41b2cac363fcc Mon Sep 17 00:00:00 2001 From: cpldcpu Date: Sat, 6 Jun 2015 21:12:52 +0200 Subject: readme: Found the spellchecker! --- Readme.txt | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) (limited to 'Readme.txt') diff --git a/Readme.txt b/Readme.txt index 1904e53..f3c2de1 100644 --- a/Readme.txt +++ b/Readme.txt @@ -12,7 +12,7 @@ The V2.0 release is a complete rewrite of the firmware and offers significant im • Many robustness improvements, such as compatibility to USB hubs and less erratic time out behavior. -Due to the many changes, also the uploadtool had to be updated. The V2.0 upload tool is backwards compatible to the V1.X tool, though. +Due to the many changes, also the upload tool had to be updated. The V2.0 upload tool is backwards compatible to the V1.X tool, though. The last release of the V1.x can be found here: https://github.com/micronucleus/micronucleus/tree/v1.11 @@ -20,23 +20,23 @@ The last release of the V1.x can be found here: https://github.com/micronucleus/ Usage ===== -The bootloader allows uploading of new firmware via USB. In its usual configuration it is invoked at device reset and will identify to the host computer. If no comminucation is initiated by the host machine within a given time, the bootloader will time out and enter the user program, if one is present. +The bootloader allows uploading of new firmware via USB. In its usual configuration it is invoked at device reset and will identify to the host computer. If no communication is initiated by the host machine within a given time, the bootloader will time out and enter the user program, if one is present. -For proper timing, the commmand line tool should to be started on the host computer _before_ the bootloader is invoked. +For proper timing, the command line tool should to be started on the host computer _before_ the bootloader is invoked. -Windows machines will need to install the libusb drivers found in the /windows_drivers folder. Clean Micronucleus devices without uploaded userprogram will not time out and allow suffucient time for proper driver installation. Linux and OS X do not require custom drivers. +Windows machines will need to install the libusb drivers found in the /windows_drivers folder. Clean Micronucleus devices without uploaded userprogram will not time out and allow sufficient time for proper driver installation. Linux and OS X do not require custom drivers. -Please invoke the command line tool with "microcleus -help" for a list of available options. +Please invoke the command line tool with "micronucleus -help" for a list of available options. -The bootloader resides in the same memory as the user program, since the ATtiny series does not support a protected bootloader section. Therefore, special care has to be taken not to overwrite the bootloader if the user programm uses the self programming features. The bootloader will patch itself into the reset vector of the user program. No other interrupt vectors are changed. +The bootloader resides in the same memory as the user program, since the ATtiny series does not support a protected bootloader section. Therefore, special care has to be taken not to overwrite the bootloader if the user program uses the self programming features. The bootloader will patch itself into the reset vector of the user program. No other interrupt vectors are changed. Compiling ========= -Micronucleus can be configured to support all devices of the ATtiny series, with the expection of the reduced core ATtiny 4/5/9/10/20/40. +Micronucleus can be configured to support all devices of the ATtiny series, with the exception of the reduced core ATtiny 4/5/9/10/20/40. -To allow maximum flexibility, micronucleus supports a configuration system. To compile micronucleus with a specific configuratiion, please invoke the AVR-GCC toolchain with: +To allow maximum flexibility, micronucleus supports a configuration system. To compile micronucleus with a specific configuration, please invoke the AVR-GCC tool-chain with: make CONFIG= @@ -49,7 +49,7 @@ t85_aggressive - ATtiny85 smaller size - critical - 1414 bytes t167_default - ATtiny167 default (uses xtal) - 1390 bytes Nanite841 - Nanite841 firmware - 1608 bytes -You can add your own configuration by adding a new folder to /firmware/configurations/. The folder has to contain a customized "Makefile.inc" and "boorloaderconfig.h". The bootloader options are explaines in these files. Feel free to supply a pull request if you added and tested a previously unsupported device. +You can add your own configuration by adding a new folder to /firmware/configurations/. The folder has to contain a customized "Makefile.inc" and "boorloaderconfig.h". Feel free to supply a pull request if you added and tested a previously unsupported device. If changes to the configuration lead to an increase in bootloader size, it may be necessary to change the bootloader start address. Please consult "Makefile.inc" for details. @@ -58,7 +58,7 @@ Other make options: make CONFIG= fuse # Configure fuses make CONFIG= flash # Uploade the bootloader using AVRDUDE -There is also an option to disable the reset line and use it as an I/O. While it may seem tempting to use this feature to make available an additional I/O pin available on the ATtiny85, we strongly discourage from doing so, as it led to many issues in the past. +There is also an option to disable the reset line and use it as an I/O. While it may seem tempting to use this feature to make an additional I/O pin available on the ATtiny85, we strongly discourage from doing so, as it led to many issues in the past. Please "make clean" when switching from one configuration to another. @@ -83,7 +83,7 @@ In addition, we'd like you to consider these points if you intend to sell produc • Your documentation should mention Micronucleus and include a link to the main repository (https://github.com/micronucleus/) - • Please do not "rebrand" micronucleus. + • Please do not "rebrand" micronucleus by renaming the USB device. • Feel welcome to submit a pull request to include your product in the "Devices using Micronucleus"-list. @@ -94,6 +94,7 @@ Changes This pull request documents changes leading to V2.0: https://github.com/micronucleus/micronucleus/pull/43 + • v2.0b June 6th, 2015 Credits ======= -- cgit v1.2.3 From be7274ead1e06a1d7dfb12505d407a68a3dc8007 Mon Sep 17 00:00:00 2001 From: cpldcpu Date: Sat, 6 Jun 2015 22:13:26 +0200 Subject: Devices with Micronucleus --- Readme.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'Readme.txt') diff --git a/Readme.txt b/Readme.txt index f3c2de1..907ebfa 100644 --- a/Readme.txt +++ b/Readme.txt @@ -4,7 +4,7 @@ Micronucleus is a bootloader designed for AVR ATtiny microcontrollers with a min The V2.0 release is a complete rewrite of the firmware and offers significant improvements over V1.x: - • Support for the entire ATtiny family instead of only ATtiny85 + • Support for the entire ATtiny family instead of only ATtiny85. • Much smaller size. All configurations are below 2kb. • Interrupt free V-USB: no patching of the user program INT-vector anymore. • Faster uploads due to new protocol. @@ -40,7 +40,7 @@ To allow maximum flexibility, micronucleus supports a configuration system. To c make CONFIG= -Currently the following configurations are included and tested. Please check /firmware/configurations/ for details. Hex files can be found in /releases. +Currently, the following configurations are included and tested. Please check the subfolders /firmware/configurations/ for details. Hex files can be found in /releases. t84_default - ATtiny84A default configuration - 1532 bytes t841_default - ATtiny841 default configuration - 1584 bytes @@ -49,7 +49,7 @@ t85_aggressive - ATtiny85 smaller size - critical - 1414 bytes t167_default - ATtiny167 default (uses xtal) - 1390 bytes Nanite841 - Nanite841 firmware - 1608 bytes -You can add your own configuration by adding a new folder to /firmware/configurations/. The folder has to contain a customized "Makefile.inc" and "boorloaderconfig.h". Feel free to supply a pull request if you added and tested a previously unsupported device. +You can add your own configuration by adding a new folder to /firmware/configurations/. The folder has to contain a customized "Makefile.inc" and "bootloaderconfig.h". Feel free to supply a pull request if you added and tested a previously unsupported device. If changes to the configuration lead to an increase in bootloader size, it may be necessary to change the bootloader start address. Please consult "Makefile.inc" for details. @@ -73,7 +73,7 @@ https://github.com/micronucleus/micronucleus/Devices_with_Microncleus.md License ======= -This project is released under the GPLv2 license. Code uploaded via the bootloader is not subject to any license issues. +This project is released under the GPLv2 license. Code uploaded via the bootloader is not subject to any license. In addition, we'd like you to consider these points if you intend to sell products using micronucleus: -- cgit v1.2.3 From 8096c6397195278f69a36fd528ed05135fa2606f Mon Sep 17 00:00:00 2001 From: cpldcpu Date: Sat, 6 Jun 2015 22:15:07 +0200 Subject: readme --- Readme.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Readme.txt') diff --git a/Readme.txt b/Readme.txt index 907ebfa..f058523 100644 --- a/Readme.txt +++ b/Readme.txt @@ -1,5 +1,6 @@ Micronucleus V2.0b -============= +================== + Micronucleus is a bootloader designed for AVR ATtiny microcontrollers with a minimal usb interface, cross platform libusb-based program upload tool, and a strong emphasis on bootloader compactness. To the authors knowledge this is, by far, the smallest USB bootloader for AVR ATtiny The V2.0 release is a complete rewrite of the firmware and offers significant improvements over V1.x: -- cgit v1.2.3