Micronucleus USB Bootloader for ATtinies / Digisparks

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

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

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.
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.

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.
For proper timing, the command line tool should to be started on the host computer before the bootloader is invoked / the board attached.
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.
Please invoke the command line tool with "micronucleus --help" for a list of available options.

Driver installation

If the Digispark board is not recognized by Microsoft Windows you must install the appropriate driver.
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.

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.

Update the bootloader to a new version

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

Use the new Digistump board manager URL (see above), choose a bootloader with Tools > Micronucleus variant and then burn it with Tools > Burn Bootloader.
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.

Fuse setting

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

The default fuses for a Digispark board are:

ATtiny85 Lfuse: 0xE1 - (digispark default) 64 MHZ high speed PLL Clock + Startup 64 ms. CPU clock = 64 MHz / 4 = 16 MHz. CPU clock speed can later be reduced by core or user by using the System Clock Prescaler register.
ATtiny85 Hfuse: 0xDD - External Reset pin enabled (Pin5 not usable as I/O) + BOD 2.7 V + Enable Serial Program and Data Downloading.
ATtiny85 Efuse: 0xFE - self programming enabled.

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:

ATtiny167 Lfuse: 0xFF - External crystal osc. Frequency 8-16 MHz + Startup 65 ms. The Pro has a 16 MHz crystal.
ATtiny167 Hfuse: 0xDC - External Reset pin enabled + BOD 4.3Volt + Enable Serial Program and Data Downloading.
ATtiny167 Efuse: 0xFE - self programming enabled.

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.
In this order.

Configuration overview

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

Configuration	Free FLASH	Boot- loader size	Non default config flags set
t85_agressive It works for my Digispark boards without any problems :-)	6778	1362	Do not provide calibrated OSCCAL, if no USB attached, ENABLE_UNSAFE_OPTIMIZATIONS 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_default	6650	1514	-
t85_entry_on_powerOn	6586	1550	ENTRY_POWER_ON, LED_MODE=ACTIVE_HIGH
t85_entry_on_powerOn_ fastExit	6586	1572	ENTRY_POWER_ON, FAST_EXIT_NO_USB_MS=300, LED_MODE=ACTIVE_HIGH
t85_entry_on_powerOn_ activePullup_fastExit recommended configuration	6586	1576	ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_POWER_ON, FAST_EXIT_NO_USB_MS=300, LED_MODE=ACTIVE_HIGH
t85_entry_on_powerOn_ activePullup_fastExit_noLED	6586	1558	ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_POWER_ON, FAST_EXIT_NO_USB_MS=300
t85_entry_on_powerOn_ pullupAt0	6650	1538	ENTRY_POWER_ON, USB_CFG_PULLUP_IOPORTNAME + USB_CFG_PULLUP_BIT
t85_entry_on_reset_ activePullup_fastExit	6586	1576	ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_EXT_RESET, FAST_EXIT_NO_USB_MS=300, AUTO_EXIT_MS=15000 Bootloader timeout increased to 15 seconds (if connected to USB), LED_MODE=ACTIVE_HIGH.
t85_fastExit	6586	1554	FAST_EXIT_NO_USB_MS=300, LED_MODE=ACTIVE_HIGH

t88_default	6778	1350	LED_MODE=ACTIVE_HIGH For 16 MHz quartz
t88_entry_on_powerOn_ activePullup_fastExit recommended configuration	6778	1394	ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_POWER_ON, FAST_EXIT_NO_USB_MS=300, LED_MODE=ACTIVE_HIGH For 16 MHz quartz

t167_default	14970	1342	-
t167_entry_on_powerOn_ activePullup_fastExit recommended configuration	14970	1406	ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_POWER_ON, FAST_EXIT_NO_USB_MS=300, LED_MODE=ACTIVE_HIGH For 16 MHz quartz
t167_entry_on_reset_ activePullup_fastExit	14970	1406	ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_EXT_RESET, FAST_EXIT_NO_USB_MS=300, AUTO_EXIT_MS=15000 Bootloader timeout increased to 15 seconds (if connected to USB), LED_MODE=ACTIVE_HIGH. For 16 MHz quartz

t45_default	2554	1514
t4313_default	6714	1460
Nanite841	6586	1548
t841_default	6650	1514
t84_default	6650	1480

m168p_extclock		1498
m328p_extclock		1498

Legend

ENTRY_POWER_ON - Only enter bootloader on power on, not on reset or brownout.
ENTRY_EXT_RESET - Only enter bootloader on reset, not on power up.
ENTRY_D_MINUS_PULLUP_ACTIVATED - Only enter if pull-up connected and powered.
FAST_EXIT_NO_USB_MS=300 - If not connected to USB (e.g. powered via VIN) the user program starts after 300 ms (+ initial 300 ms) -> 600 ms. If connected to USB but no upload happens the user program starts after around 1.5 seconds.
LED_MODE=ACTIVE_HIGH - The built in LED flashes during the 5 seconds of the bootloader waiting for commands.

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.
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.
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.
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.
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.
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.
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.
For ATtiny167 it is even worse, it sets the External Reset Flag and the Brown-out Reset Flag also on power up.
The content of the MCUSR is copied to the GPIOR0 register before clearing it. This enables the user program to evaluate its original content.
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).
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).
The ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_POWER_ON configuration adds 54 bytes to the ATtiny85 default configuration.
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.
In this configuration a power up with USB disconnected or a reset will immediately start your user program without any delay.

`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.
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.
The ENTRY_D_MINUS_PULLUP_ACTIVATED_AND_ENTRY_EXT_RESET configuration adds 54 bytes to the ATtiny85 default configuration.
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.
In this configuration a power up with USB disconnected or a reset will immediately start your user program without any delay.

`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:

A hardware reset (e.g., Digispark P5 shorted to ground or brownout happened) will always immediately run the user program.
If no user program is loaded, the LED quickly flashes indefinitely.
At power-on, we distinguish 3 cases.

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).
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.
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.
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.
Feel free to supply a pull request, if you added and tested a previously unsupported device.

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.
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.
Subtracting this (+ 6 byte for postscript) from the total amount of memory will result in the free bytes numbers.

Postscript are the few bytes at the end of programmable memory which store tinyVectors.

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.
In this case we have 52 bytes left for configuration extensions before using another 64 byte page.
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.
For data from 1281 to 1408 the address is 3A80, for size from 1409 to 1536 the address is 3A00

Bootloader memory comparison of different releases for t85_default.hex

V1.6 6012 bytes free
V1.11 6330 bytes free
V2.3 6522 bytes free
V2.04 6522 bytes free
V2.5 6650 bytes free

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.
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.
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.
E.g a short beep at startup with tone(3, 2000, 200) will pull the D- line low and keep the module disconnected.

Reducing current of digispark bords for low power applications

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

Current	Voltage	Clock	Configuration
20 mA	5 V	16.5 MHz	Standard Hardware
13 mA	3.8 V	16.5 MHz	"
16 mA	5 V	8 MHz	"
11 mA	5 V	1 MHz	"
6 mA	3.8 V	1 MHz	"
4.5 mA	3 V	1 MHz	"
7.7 mA	5 V	1 MHz	SLEEP_MODE_PWR_DOWN + ADC disabled
17 mA	5 V	16.5 MHz	Voltage regulator removed
14 mA	5 V	16.5 MHz	Power LED and voltage regulator removed
9.3 mA	5 V	8 MHz	"
4.3 mA	5 V	1 MHz	"
14.3 mA	5 V	16.5 MHz	Power LED, voltage regulator removed + USB D- pull-up reconnected and powered directly at VCC (loop with delay)
9.5 mA	3.8 V	16.5 MHz	"
8.3 mA	5 V	8 MHz	"
7.5 mA	5 V	8 MHz	All Hardware changes + empty loop + Timer and ADC disabled
3.0 mA	5 V	1 MHz	All Hardware changes (loop with delay)
2.6 mA	3.8 V	1 MHz	"
2.9 mA	5 V	1 MHz	All Hardware changes + empty loop
2.4 mA	5 V	1 MHz	All Hardware changes + empty loop + Timer and ADC disabled
230 µA	5 V	1 MHz	All Hardware changes + SLEEP_MODE_PWR_DOWN
27 µA	5 V	1 MHz	All Hardware changes + SLEEP_MODE_PWR_DOWN + ADC disabled + Watchdog enabled
25 µA	3 V	1 MHz	"
7 µA	5 V	1 MHz	All Hardware changes + SLEEP_MODE_PWR_DOWN + ADC disabled + BOD disabled + Watchdog enabled
5.5 µA	3.8 V	1 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.

Current per device @ 5 volt

Current	Device
3 mA	Voltage regulator (1.5 mA at 3.8 V)
2 mA	Power LED
1 mA	USB D- pull-up
14.3 mA	CPU + timer @16.5 MHz
14 mA	CPU + timer @16 MHz
8 mA	CPU + timer @8 MHz
3 mA	CPU + timer @1 MHz
20 µA	BOD
212 µA	ADC
5 µA	Watchdog

With fast PLL Clock and standard fuses, the start-up time from sleep is around 64ms and requires 2/3 of regular CPU power!
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).
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).
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.
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.
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+.
Now the USB pull-up resistor is only activated if the Digispark board is connected to USB e.g. during programming.

Another example for current reduction

Moddings:

Connect A to C (A is the right terminal of the 1kohm resistor; C is USB V+)
Cut B with a cutter (power supply rail interconnecting the 1kohm resistor with 5V)
Connect C with D (C is USB V+, D is the left terminal of the green LED resistor)
Remove the 78M05 linear regulator G
Connect E with F (short the two input/output terminals of the removed linear regulator)
Cut H with a cutter (power supply rail connecting 5V with the output of the linear regulator)

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.

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