Home

Awesome

<div align = center>

Micronucleus USB Bootloader for ATtinies / Digisparks

Fork for the firmware / digispark part of the micronucleus repository.

Badge License: GPLv3     Badge Version     Badge Commits since latest     Badge Hit Counter <br/> <br/> Stand With Ukraine

</div>

If you find this library useful, please give it a star.

🌎 Google Translate

<br/>

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.<br/> The V2.0 release is a complete rewrite of the firmware and offers significant improvements over V1.x.<br/> 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.

Digisparks

Usage

The bootloader allows uploading of new firmware via USB. In its usual configuration it is invoked at device power or on reset and will identify to the host computer. If no communication is initiated by the host machine within a given time (default are 6 seconds), the bootloader will time out and enter the user program, if one is present.<br/> For proper timing, the command line tool should to be started on the host computer before the bootloader is invoked / the board attached.<br/> 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.<br/> Please invoke the command line tool with "micronucleus -help" for a list of available options.

<br/>

Driver installation

If the Digispark board is not recognized by Microsoft Windows you must install the appropriate driver.<br/> For Windows you must install the libusb driver before you can program the board. Download it here, open it and run InstallDrivers.exe. Clean Micronucleus devices without uploaded user program will not time out and allow sufficient time for proper driver installation. Linux and OS X do not require custom drivers.

<br/>

Updated configuration for Digispark boards

The new ATTinyCore by Spence Konde shrinks generated code size by 5 to 15 percent. Just replace the old Digispark board manager URL http://digistump.com/package_digistump_index.json (e.g.in Arduino File > Preferences) by the new http://drazzy.com/package_drazzy.com_index.json and install the latest version. <br/>

Update the bootloader to a new version

To update your old, flash consuming bootloader, you have 2 choices.

  1. Use the new Digistump board manager URL (see above), choose a bootloader with Tools > Micronucleus variant and then burn it with Tools > Burn Bootloader.<br/>
  2. Run one of the Windows scripts like e.g. the 1_Upgrade-t85_default.cmd. The internal mechanism is described here.

If you want to burn the bootloader to an ATtiny87 or ATtiny167 with avrdude, you must use the avrdude.config file in the windows_exe directory where ATtiny87 and ATtiny167 specifications are added.

<br/>

Fuse setting

The meaning of fuses can be seen with the Engbedded Atmel AVR Fuse Calculator.<br/> Windows helper scripts for setting fuses can be found here.

The default fuses for a Digispark board are:<br/>

BOD enabled requires additional 20 µA in sleep state and therefore may be not desirable for low power battery applications. To disable BOD, use 0xDF as Hfuse.

The default fuses for a Digispark Pro board are:<br/>

Flash the bootloader to a bricked device

This can only be done by means of a High Voltage programmer.

If nothing works...

Try another Cable, try another USB-Port, try another Board, try another Bootloader-variant, try another Computer, try another OS.<br/> In this order.

<br/>

Configuration overview

If not otherwise noted, the OSCCAL value is calibrated (+/- 1%) after boot for all ATtiny85 configurations

ConfigurationFree FLASHBoot-<br/>loader sizeNon default config flags set
t85_agressive<br/><br/>It works for my Digispark boards without any problems :-)67781362Do not provide calibrated OSCCAL, if no USB attached, ENABLE_UNSAFE_OPTIMIZATIONS<br/>Relying on calibrated 16MHz internal clock stability, not using the 16.5 MHz USB driver version with integrated PLL. This causes the main memory saving.
t85_default66501514-
t85_entry_on_powerOn65861550ENTRY_POWER_ON, LED_MODE=ACTIVE_HIGH
t85_entry_on_powerOn_<br/>fastExit65861572ENTRY_POWER_ON, FAST_EXIT_NO_USB_MS=300, LED_MODE=ACTIVE_HIGH
<a id="t85recommended"/> t85_entry_on_powerOn_<br/>activePullup_fastExit<br/>recommended configuration65861576ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_POWER_ON, FAST_EXIT_NO_USB_MS=300, LED_MODE=ACTIVE_HIGH
t85_entry_on_powerOn_<br/>activePullup_fastExit_noLED65861558ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_POWER_ON, FAST_EXIT_NO_USB_MS=300
t85_entry_on_powerOn_<br/>pullupAt066501538ENTRY_POWER_ON, USB_CFG_PULLUP_IOPORTNAME + USB_CFG_PULLUP_BIT
t85_entry_on_reset_<br/>activePullup_fastExit65861576ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_EXT_RESET, FAST_EXIT_NO_USB_MS=300,<br/>AUTO_EXIT_MS=15000 Bootloader timeout increased to 15 seconds (if connected to USB),<br/>LED_MODE=ACTIVE_HIGH.
t85_fastExit65861554FAST_EXIT_NO_USB_MS=300, LED_MODE=ACTIVE_HIGH
t88_default67781350LED_MODE=ACTIVE_HIGH<br/>For 16 MHz quartz
<a id="t88recommended"/>t88_entry_on_powerOn_<br/>activePullup_fastExit<br/>recommended configuration67781394ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_POWER_ON, FAST_EXIT_NO_USB_MS=300, LED_MODE=ACTIVE_HIGH<br/>For 16 MHz quartz
t167_default149701342-
<a id="t167recommended"/>t167_entry_on_powerOn_<br/>activePullup_fastExit<br/>recommended configuration149701406ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_POWER_ON, FAST_EXIT_NO_USB_MS=300, LED_MODE=ACTIVE_HIGH<br/>For 16 MHz quartz
t167_entry_on_reset_<br/>activePullup_fastExit149701406ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_EXT_RESET, FAST_EXIT_NO_USB_MS=300, <br/>AUTO_EXIT_MS=15000 Bootloader timeout increased to 15 seconds (if connected to USB),<br/>LED_MODE=ACTIVE_HIGH.<br/>For 16 MHz quartz
t45_default25541514
t4313_default67141460
Nanite84165861548
t841_default66501514
t84_default66501480
m168p_extclock1498
m328p_extclock1498

Legend

<br/>

Descripion of the configuration options

FAST_EXIT_NO_USB_MS for fast bootloader exit

If the bootloader is entered, it requires minimum 300 ms to initialize USB connection (disconnect and reconnect). 100 ms after this 300 ms initialization, the bootloader receives a reset.<br/> The 100 ms time to reset may depend on the type of host CPU etc., so I took 200 ms to be safe to detect a reset.<br/> This configuration waits for 200 ms after initialization for a reset and if no reset detected it exits the bootloader and starts the user program.<br/> With this configuration the user program is started with a 500 ms delay after power up or reset if no USB is attached, even if we do not specify a special entry condition.<br/> IF USB is attached, we wait another 1200 ms (to cover slow hosts, otherwise 500 would be OK) after the reset for the host upload program (micronucleus.exe) to request the configuration information. If no upload program is detected, we start the user program.

ENTRY_POWER_ON entry condition

The ENTRY_POWER_ON configuration adds 18 bytes to the ATtiny85 default configuration.<br/> The content of the MCUSR is copied to the GPIOR0 register to enable the user program to evaluate it and then cleared to prepare for next boot.<br/> In this configuration a reset will immediately start your user program without any delay.

ENTRY_EXT_RESET entry condition

The ATtiny85 has the bug, that it sets the External Reset Flag also on power up. To guarantee a correct behavior for ENTRY_EXT_RESET condition, it is checked if only this flag is set and MCUSR is cleared before start of user program. The latter is done to avoid bricking the device by fogetting to reset the PORF flag in the user program.<br/> For ATtiny167 it is even worse, it sets the External Reset Flag and the Brown-out Reset Flag also on power up.<br/> The content of the MCUSR is copied to the GPIOR0 register before clearing it. This enables the user program to evaluate its original content.<br/> ATTENTION! If the external reset pin is disabled, this entry mode will brick the board!

ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_POWER_ON entry condition

Activate the bootloader only if the D- pin is high, i.e. a pull-up resistor is attached and powered and we have an ENTRY_POWER_ON condition (ref. described above).<br/> Useful if the pull-up is powered by USB V+ and NOT ATtiny VCC to save power. In this case often a schottky diode is connected between USB V+ and VCC (5V).<br/> The ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_POWER_ON configuration adds 54 bytes to the ATtiny85 default configuration.<br/> The content of the MCUSR is copied to the GPIOR0 register to enable the user program to evaluate it and then cleared to prepare for next boot.<br/> In this configuration a power up with USB disconnected or a reset will immediately start your user program without any delay.<br/>

ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_EXT_RESET entry condition

Activate the bootloader only if the D- pin is high, i.e. a pull-up resistor is attached and powered and we have an ENTRY_EXT_RESET condition.<br/> Useful if the pull-up is powered by USB V+ and NOT ATtiny VCC to save power. In this case often a schottky diode is connected between V* and VCC.<br/> The ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_EXT_RESET configuration adds 54 bytes to the ATtiny85 default configuration.<br/> The content of the MCUSR is copied to the GPIOR0 register to enable the user program to evaluate it and then cleared to prepare for next boot.<br/> In this configuration a power up with USB disconnected or a reset will immediately start your user program without any delay.<br/>

ENABLE_UNSAFE_OPTIMIZATIONS

The bootloader reset vector is written by the host and not by the bootloader itself. In case of an disturbed communication the reset vector may be wrong -but I have never experienced it.

You have a slightly bigger chance to brick the bootloader, which reqires it to be reprogrammed by avrdude and an ISP or an Arduino as ISP. Command files for this can be found here.

Recommendedconfiguration

For ATtiny85, ATtiny88 and ATtiny167 the recommended configuration is t85_entry_on_powerOn_activePullup_fastExit.hex, t88_entry_on_powerOn_activePullup_fastExit.hex and t167_entry_on_powerOn_activePullup_fastExit.hex respectively.

This configuration has the following features:

  1. The board is connected to an USB. In this case, the bootloader waits for the host program (micronucleus.exe) to upload a program and starts the user program after around 1.5 seconds timeout or after upload completion. The built-in LED flashes while the bootloader is waiting for user program upload and during the upload phase (LED_MODE=ACTIVE_HIGH).
  2. The board is not connected to an USB. In this case, the bootloader starts the already installed user program after 600 milliseconds (FAST_EXIT_NO_USB_MS=300 means Fast exit of bootloader after 300+300 ms). The 600 ms are required to decide if there is an USB host attached or not.
  3. The board pull-up resistor supply is modified to be USB-VCC and not CPU-VCC and not connected to an USB or the pull-up resistor is removed. In this case, the pull-up is inactive and the bootloader immediately starts the installed user program (without startup delay, without hang-up and without affecting the internal LED at boot). This is referred to the ENTRY_D_MINUS_PULLUP_ACTIVATED part of the configuration flags. The builtin LED remains off in this case (LED_MODE=ACTIVE_HIGH has no effect here).

Hex files for these configuration are available in the releases and upgrades folders.

Create your own configuration

You can easily create your own configuration by adding a new firmware/configuration directory and adjusting bootloaderconfig.h and Makefile.inc. Before you run the firmware/make_all.cmd script, check the arduino directory path in the firmware/SetPath.cmd file.<br/> If changes to the configuration lead to an increase in bootloader size, i.e. you see errors like address 0x2026 of main.bin section '.text' is not within region 'text', it may be necessary to change/decrease the bootloader start address as described in the next section and in the Makefile.inc.<br/> Feel free to supply a pull request, if you added and tested a previously unsupported device.

<br/>

Compile instructions for the bootloader

Computing the bootloader start address

The actual memory footprint for each configuration can be found in the file firmware/build.log.<br/> Bytes used by the mironucleus bootloader can be computed by taking the data size value in build.log, rounding it up to the next multiple of the page size which is e.g. 64 bytes for ATtiny85 and 128 bytes for ATtiny176.<br/> Subtracting this (+ 6 byte for postscript) from the total amount of memory will result in the free bytes numbers.

E.g. for t85_default.hex with the new compiler we get 1548 as data size. The next multiple of 64 is 1600 (25 * 64) => (8192 - (1600 + 6)) = 6586 bytes are free.<br/> In this case we have 52 bytes left for configuration extensions before using another 64 byte page.<br/> For data size from 1470 up to 1536 the address is 1A00 (6650 free), for 1538 to 1600 it is 19C0 (6586 free), for 1602 to 1664 it is 1980 (6522 free).

For t167_default.hex (as well as for the other t167 configurations) with the new compiler we get 1436 as data size. The next multiple of 128 is 1536 (12 * 128) => (16384 - (1536 + 6)) = 14842 bytes are free.<br/> For data from 1281 to 1408 the address is 3A80, for size from 1409 to 1536 the address is 3A00

<br/>

Bootloader memory comparison of different releases for t85_default.hex

<br/>

USB device manager entry / disconnect from USB

To avoid periodically disconnect->connect if no sketch is loaded and to avoid an unknown USB Device (Device Descriptor Request Failed) entry in device manager when entering user program, the bootloader finishes without an active disconnect from USB.<br/> This means that you still can see a libusb-win32 decive / Digispark Bootloader in the Device manager, even when it is not alive, since your program has taken over the control of the CPU.<br/> This behavior is compatible to the old v1 micronucleus versions, which also do not disconnect from the host. You can avoid this by actively disconnecting from the host by pulling the D- line to low for up to 300 milliseconds.<br/> E.g a short beep at startup with tone(3, 2000, 200) will pull the D- line low and keep the module disconnected.

<br/>

Reducing current of digispark bords for low power applications

Measured Digispark (ATtiny85 fast 64 MHz PLL clock) supply current

CurrentVoltageClockConfiguration
20 mA5 V16.5 MHzStandard Hardware
13 mA3.8 V16.5 MHz"
16 mA5 V8 MHz"
11 mA5 V1 MHz"
6 mA3.8 V1 MHz"
4.5 mA3 V1 MHz"
7.7 mA5 V1 MHzSLEEP_MODE_PWR_DOWN + ADC disabled
17 mA5 V16.5 MHzVoltage regulator removed
14 mA5 V16.5 MHzPower LED and voltage regulator removed
9.3 mA5 V8 MHz"
4.3 mA5 V1 MHz"
14.3 mA5 V16.5 MHzPower LED, voltage regulator removed + USB D- pull-up reconnected and powered directly at VCC (loop with delay)
9.5 mA3.8 V16.5 MHz"
8.3 mA5 V8 MHz"
7.5 mA5 V8 MHzAll Hardware changes + empty loop + Timer and ADC disabled
3.0 mA5 V1 MHzAll Hardware changes (loop with delay)
2.6 mA3.8 V1 MHz"
2.9 mA5 V1 MHzAll Hardware changes + empty loop
2.4 mA5 V1 MHzAll Hardware changes + empty loop + Timer and ADC disabled
230 µA5 V1 MHzAll Hardware changes + SLEEP_MODE_PWR_DOWN
27 µA5 V1 MHzAll Hardware changes + SLEEP_MODE_PWR_DOWN + ADC disabled + Watchdog enabled
25 µA3 V1 MHz"
7 µA5 V1 MHzAll Hardware changes + SLEEP_MODE_PWR_DOWN + ADC disabled + BOD disabled + Watchdog enabled
5.5 µA3.8 V1 MHz" The Watchdog draws around 5 µA

BOD can only be disabled by setting fuses via ISP programmer](https://www.google.de/search?q=arduino+as+isp) and a connecting adapter. For reprogramming the fuses, you can use this script.<br/>

Current per device @ 5 volt

CurrentDevice
3 mAVoltage regulator (1.5 mA at 3.8 V)
2 mAPower LED
1 mAUSB D- pull-up
14.3 mACPU + timer @16.5 MHz
14 mACPU + timer @16 MHz
8 mACPU + timer @8 MHz
3 mACPU + timer @1 MHz
20 µABOD
212 µAADC
5 µAWatchdog

With fast PLL Clock and standard fuses, the start-up time from sleep is around 64ms and requires 2/3 of regular CPU power!<br/> If we use the longest sleep time of 8 seconds and an empty loop, this result in an average current consumption of 23 µA (1 year with a 200 mAh button cell 2032).<br/> The start-up time from sleep can be reduced (at own risk of unstable clock) to 5 ms using this fuse settings. This results in an average current consumption of 9 µA (2.5 years with a 200 mAh button cell 2032).<br/> This startup time can even be reduced to 6 clock cycles by changing fuses to use the internal 8Mhz clock, but this disables the possibility to program the Digispark board via USB and and on the other hand removes the need for a bootloader and therefore leaves the whole memory for your program.

Modifying the board

Here is an Instructable covering the topic.

Disabling the power LED

Break the copper wire that connects the power LED to the diode with a knife or remove / disable the 102 resistor.

Removing the VIN voltage regulator

First, lift the outer pins with the help of a solder iron and a pin. Then solder the big connector and remove the regulator. For small regulators, use much solder and heat up all 3 pins together, then remove it.

Disconnecting the USB D- Pullup resistor (marked 152) from 5 volt (VCC)

Break the copper wire on the side of the resistor that points to the ATtiny.<br/> This disables the USB interface and in turn the possibility to program the Digispark board via USB. To enable it again, but still save power, connect the resistor (marked 152) directly to the USB V+ that is easily available at the outer side of the schottky diode.<br/> The diode and its correct sides can be found by using a continuity tester. One side of this diode is connected to pin 8 of the ATtiny (VCC) and Digispark 5V. The other side is connected to the USB V+.<br/> Now the USB pull-up resistor is only activated if the Digispark board is connected to USB e.g. during programming.

Final power reduction

Another example for current reduction

<img src="pictures/modding_front.png" width="300" title="Modding front"/><img src="pictures/modding_back.png" width="300" title="Modding back"/>

Moddings:

Now we have 3 power supply variants: 1 Use the USB to upload a sketch (the green LED is lighted) - Disconnect 5V and VIN. 2 Use 5V - GND to test the device with D- pull-up (the green LED is lighted) - Disconnect USB and VIN. 3 Use VIN - GND for standard operation in low current consumption. The power supply can be 3V to 5V (the green LED can be used as debug output of PB3). - Disconnect USB and 5V.

<br/>

Pin layouts

ATtiny85 on Digispark

                       +-\/-+
 RESET/ADC0 (D5) PB5  1|    |8  VCC
  USB- ADC3 (D3) PB3  2|    |7  PB2 (D2) INT0/ADC1 - default TX Debug output for ATtinySerialOut
  USB+ ADC2 (D4) PB4  3|    |6  PB1 (D1) MISO/DO/AIN1/OC0B/OC1A/PCINT1 - (Digispark) LED
                 GND  4|    |5  PB0 (D0) OC0A/AIN0
                       +----+
  USB+ and USB- are each connected to a 3.3 volt Zener to GND and with a 68 ohm series resistor to the ATtiny pin.
  On boards with a micro USB connector, the series resistor is 22 ohm instead of 68 ohm.
  USB- has a 1.5k pull-up resistor to indicate a low-speed device.  
  USB+ and USB- are each terminated on the host side with 15k to 25k pull-down resistors.

ATtiny167 on Digispark pro

Digital Pin numbers in parenthesis are for ATTinyCore library

                  +-\/-+
RX   6 (D0) PA0  1|    |20  PB0 (D8)  0 OC1AU
TX   7 (D1) PA1  2|    |19  PB1 (D9)  1 OC1BU - (Digispark) LED
     8 (D2) PA2  3|    |18  PB2 (D10) 2 OC1AV
INT1 9 (D3) PA3  4|    |17  PB3 (D11) 4 OC1BV USB-
           AVCC  5|    |16  GND
           AGND  6|    |15  VCC
    10 (D4) PA4  7|    |14  PB4 (D12)   XTAL1
    11 (D5) PA5  8|    |13  PB5 (D13)   XTAL2
    12 (D6) PA6  9|    |12  PB6 (D14) 3 INT0  USB+
     5 (D7) PA7 10|    |11  PB7 (D15)   RESET
                  +----+
  USB+ and USB- are each connected to a 3.3 volt Zener to GND and with a 51 ohm series resistor to the ATtiny pin.
  USB- has a 1k5 pull-up resistor to indicate a low-speed device.
  USB+ and USB- are each terminated on the host side with 15k to 25k pull-down resistors.

MH-ET LIVE Tiny88 (16.0MHz) board

Digital Pin numbers in parenthesis are for ATTinyCore library

                        USB
                      +-\__/-+
               PA2  15|      |14  PB7
               PA3  16|      |13  PB5 SCK
           D17 PA0  A6|      |12  PB4 MISO
           D18 PA1  A7|      |11  PB3 MOSI
     (D17) D19 PC0  A0|      |10  PB2 OC1B/PWM SS
     (D18) D20 PC1  A1|      |9   PB1 OC1A/PWM
     (D19) D21 PC2  A2|      |8   PB0
     (D20) D22 PC3  A3|      |7   PD7 RX
SDA  (D21) D23 PC4  A4|      |6   PD6 TX
SCL  (D22) D24 PC5  A5|      |5   PD5
     (D23)     PC7  25|      |4   PD4
RESET          PC6 RST|      |3   PD3 INT1
LED            PD0   0|      |5V
USB-           PD1   1|      |GND
USB+  INT0     PD2   2|      |VIN
                      +------+
  USB+ and USB- are each connected to a 3.3 volt Zener to GND and with a 68 ohm series resistor to the ATtiny pin.
  USB- has a 1k0 pullup resistor to indicate a low-speed device.
  USB+ and USB- are each terminated on the host side with 15k to 25k pull-down resistors.

  Pins not available: PB6 is CLOCK_IN, PC7 is 25

<br/>

Revision History

Version 2.6.0

Version 2.5.2

Version 2.5.1

Version 2.5