Getting Started with Micronucleus

Contents

• Building Micronucleus Commandline
• Aside: libusb-devel on Fedora 35
• Udev Rules
• Building the Micronucleus Bootloader
• Flashing the Firmware
• Checking the Bootloader
  • One Neat Trick
• Flashing a Program

The Micronucleus project provides a bootloader for ATTINY microcontrollers. I became aware of the project while learning how to program a Digispark ATTINY85 which I ordered on a whim in one of my component batches. For a few dollars, you get what is essentially a tiny Arduino (albeit with 8 pins total), powered by and programmable via USB. With a few library installs, you can even use the Arduino IDE with the Digispark, although I'm using avr-gcc directly.

This goals of this document are to record the process I used to build Micronucleus, update the firmware on my Digispark, and flash a program to the board. These notes are written with Linux (Fedora 35, specifically) in mind -- YMMV on other operating systems.

Building Micronucleus Commandline

It's likely that there is an official Micronucleus package or build for your platform, but I like to get my hands dirty and build it myself. Let's start by building the command line micronucleus program. First, get the latest code from Github:

https://github.com/micronucleus/micronucleus.git

You'll need to install libusb-dev or libusb-devel depending on your platform. You'll also need the build tools, which are probably already installed for your distribution.

From the base of the micronucleus repo:

cd ./commandline
make

Static Build: At least for me, this command complained about not being able to find -lusb (libusb, as noted above). This seems to be an issue only with the static build. I was able to run make STATIC= to create a dynamically linked build, and that worked fine. If you encounter the same issue, don't build static:

make STATIC=

Assuming that succeeds, you will have a micronucleus binary in the commandline/ directory.

Aside: libusb-devel on Fedora 35

libusb-devel seems to be in some flux on Fedora 35 at the time of this writing. There's a comment in the Micronucleus README mentioning this issue, and a warning in the Makefile. I did a little research and found that the Fedora 35 package for libusb-devel does indeed only provide a dynamic .so and not a static lib .a, so mystery solved.

Udev Rules

You'll need to use sudo by default, but you can avoid this by adding udev rules. The file is in the commandline/ directory. Copy 49-micronucleus.rules to /etc/udev/rules.d/. This will allow non-root users to communicate with USB devices, which is less secure. Make sure that it makes sense for your situation. You may need to reload the udev rules: udevadm control --reload-rules.

Download udev rules

Building the Micronucleus Bootloader

Install the dependencies:

avr-gcc avr-libc binutils-avr avrdude

You will need to build for the AVR device for which you want to upload the bootloader.

make CONFIG=<config_name>

The list of config names are listed in the top-level Readme.md in the repo, but I'll reproduce them here. At the time of this writing, these are the options:

| t84_default     |   ATtiny84A default configuration
| t841_default    |   ATtiny841 default configuration
| t45_default     |   ATtiny45  default configuration
| t85_default     |   ATtiny85  default configuration
| t85_aggressive  |   ATtiny85  smaller size - critical
| t88_default     |   ATtiny88  default configuration 
| t167_default    |   ATtiny167 default (uses xtal) 
| Nanite841       |   Nanite841 firmware 
| m328p_extclock  |   ATMega328p external clock 
| t4313_default   |   Attiny 4313 default configuration 

For example, for my Digispark ATTINY85, I used:

make CONFIG=t85_default

I get a few gcc warnings, but the firmware compiles successfully.

make CONFIG=<config> flash  # will upload the firmware to the board.
make CONFIG=<config> fuse   # will configure the fuses.

Flashing the Firmware

In order to apply the firmware to the ATTINY85, you'll need a programmer. I use an inexpensive UsbAsp clone that works like a champ, and only set me back a couple of dollars.

1. Connect SCK, MISO, MOSI, RESET, VCC and GND from your programmer.
2. make CONFIG=t85_default -- or the appropriate config for your build.
3. make CONFIG=t85_default flash

Note: I've got several different variants/clones of the USBASP programmer and the pinout is different for each of them. Be sure to check the details for your programmer.

Checking the Bootloader

You can confirm the details of the bootloader using the micronucleus command line. Disconnect your programmer if you haven't already.

micronucleus --info

(Make sure that micronucleus is in your PATH.)

Note: don't plug in the Digispark before running the command. It will prompt you when you run it.

> Please plug in the device ...

You should see something like this after plugging in:

$ micronucleus --info
> Please plug in the device ... 
> Device is found!
connecting: 40% complete
> Device has firmware version 2.6
> Device signature: 0x1e930b 
> Bootloader entry condition: The bootloader is always activated after reset.
> Bootloader exit condition: The bootloader exits after 6 seconds (default) if no uploading detected.
> Available space for user applications: 6650 bytes
> Suggested sleep time between sending pages: 7ms
> Whole page count: 104  page size: 64
> Erase function sleep duration: 728ms
>> Micronucleus done. Thank you!

One Neat Trick

I've noticed that if you connect a jumper to Digispark pin 5 it will sometimes act to trigger programming just like plugging/unplugging the device. I found that connecting a jumper into pin 5 to GND on my protoboard, then disconnecting it will trigger programming. This avoids having to plug/unplug the board all the time!

Flashing a Program

Now that the bootloader is installed, you can try out the classic "blink" program. I will cover that step in a separate chapter.