Category: computers suck

I love the ingenuity that goes into making very tiny projects do very big things. I also love chiptunes. So when I read the metafilter post about PROTODOME’s compositions for the ATtiny85, I was very much there for it.

The circuit to play this is no more than a $2 microcontroller, a lithium coin cell and a speaker or piezo buzzer. The microcontroller has 8 KB of program space and 512 bytes of RAM. The output is a single pin, but with very clever pulse width modulation tricks, sounds like three channels plus percussion.

The album is cool enough on its own, but Blake “PROTODOME” Troise has not only published the source code, but also written an academic article on 1-bit music: “The 1-Bit Instrument: The Fundamentals of 1-Bit Synthesis, Their Implementational Implications, and Instrumental Possibilities.” Journal of Sound and Music in Games 1.1 (2020): 44-74.

I remembered I had bought a tube of ATtiny microcontrollers a while back. I knew I had a coin cell and tiny speaker. “I can do this!”, I thought.

So what follows is tutorial on compiling embedded code for an ATtiny85 microcontroller on Linux. There are larger tutorials out there, there are better tutorials: but there are also many out-of-date and misleading tutorials. This isn’t a general ATtiny development tutorial, but one specialized on getting PROTODOME’s tunes playing on your microcontroller.

Hardware

The very minimum you will need to play the music is:

• a prototyping breadboard. Half size with power rails
• a Microchip/Atmel ATtiny85 microcontroller (from now on, µc). You want the 8-pin PDIP version, as other ones are for production soldering, not breadboards. Its fancy name on Digikey is AVR® ATtiny Microcontroller IC 8-Bit 20MHz 8KB (4K x 16) FLASH 8-PDIP, but other suppliers have it too: SparkFun AVR 8 Pin 20MHz 8K 4A/D – ATtiny85
• a tiny speaker or piezo buzzer. Either will do, and will be pretty quiet — you’re not getting room-filling fidelity out of this project. I used a 28 mm headphone driver I got surplus years ago. The snazzy speaker horn in the picture above is designed to fit this and not much else, alas.
• a battery and battery holder. Pretty much anything from 3–5 V will do. I used a CR2032 coin cell in a simple holder to feed 3.2 V to the circuit: SparkFun Coin Cell Battery Holder – 20mm (PTH). Note you’ll need a battery and something to connect it to the breadboard.
• a 10 kΩ or higher resistor is highly recommended. All this does is prevent the chip resetting accidentally. Value is not important: I’ve been using a 4.7 kΩ one without problem. These are so generic I’m not going to list suppliers (along with the rest of the parts on this list)
• a 10 nF ceramic capacitor, while optional, likely makes the power into the µc a tiny bit smoother
• jumper wires to connect everything up.

But that’s not all: you’ll need much more kit to program these tiny chips:

• a computer running Linux. Yes, you can do this under Windows and Mac OS, but I don’t know how and there are search engines that care about that more than I do. I tested all of this on a Raspberry Pi 4. Tablets and phones are out, sorry
• an AVR programmer. You can use an Arduino for this (either an official one or a cheaper clone) but you’ll need some additional fiddling and a 10 µF capacitor to get that going. I used a dedicated USBtinyISP programmer just because I had one, but it’s not really necessary. Whatever you use, you’ll need a USB cable for it
• probably more jumper wires.

Software

There are two separate toolchains involved — one to build the mmml-compiler to convert PROTODOME’s compositions to µc embedded C code, and another to compile that to ATtiny85 instructions. We can install it all in one go:

sudo apt install avrdude gcc-avr binutils-avr avr-libc build-essential git

Building mmml-compiler is easy enough:

git clone https://github.com/protodomemusic/mmml.git
cd mmml/mmml-compiler
gcc -o mmml-compiler mmml-compiler.c

You can then run the compiler on each of the songs; the album title track, for example:

cd ../demo-songs/4000ad/
../../mmml-compiler/mmml-compiler 4000ad.mmml

⚠️ If you get [ERROR 14] Too few channels stated! instead of Successfully compiled! it seems that the compiler isn’t too happy running on some 64-bit systems. I did all my compilation on a Raspberry Pi 4 running Raspbian and all was well. If you can’t get them to compile, I’ve pre-compiled them for you and they’re at the end of this article. (Update: this has been fixed. If you still have the problem, are you running old code?)

You should now have a musicdata.h file that contains all the tune data. Copy it to the same folder as the mmml-player C code:

cp musicdata.h ../../mmml-player/
cd ../../mmml-player/

That folder now contains the player and one tune data file. Now you need to compile it into AVR instruction to write to your chip:

avr-gcc -g -Os -mmcu=attiny85 -DF_CPU=8000000 -o mmml.bin mmml.c
avr-objcopy -j .text -j .data -O ihex mmml.bin mmml.hex
rm mmml.bin

The end result of what that just did is create a single small file mmml.hex containing the ATtiny85 program instructions for the 8+ minute track 4000AD. If you’re compiling for a different µc, you’ll need a different avr-gcc line:

• -mmcu=attiny85 will need to be changed for your µc. avr-gcc –target-help lists the supported targets in the “Known MCU names” section way up at the top of its too-copious output. If you’re using the ATmega32P chip made popular by Arduinos, that option should be -mmcu=atmega328p
• -DF_CPU=8000000 tells the compiler that the CPU frequency should be 8 MHz. The AVR µcs can run at a huge range of speeds, but PROTODOME’s music is timed to work at 8 MHz only.

→→→ aside

If you find yourself compiling a few simple AVR projects but want to stop short of a fine-but-overly-complex Makefile project for AVR development, this script to create a hex file from a single embedded C source file might be useful:

#!/bin/bash
# avrbuild.sh - build a simple AVR project - scruss, 2020-04
# usage: avrbuild.sh file.c mcutype freq
# eg: avrbuild.sh mmml.c attiny85 8000000

b="${1%.c}"
rm -f "$b.bin" "$b.hex"
avr-gcc -g -Os -mmcu="$2" -DF_CPU="$3" -o "$b.bin" "$b.c"
avr-objcopy -j .text -j .data -O ihex "$b.bin" "$b.hex"
avr-size --format=avr --mcu="$2" "$b.bin"
rm -f "$b.bin"

In addition to creating a hex file, it also runs the avr-size tool to show you much memory your program uses. The 4000AD tune uses 98% of the ATtiny85’s 8192 byte program space — not quite enough to include that 14 minute extra bass solo, sorry …

←←← end aside

Flashing the chip

So now we do some wiring. If you’re using a dedicated programmer, use jumpers to connect its ICSP port to the ATtiny 85 like this:

                        ________              
                       |o   A   |             
               Reset  -+ 1  T  8+-  VCC       
                       |    t   |             
                      -+ 2  i  7+-  SCK       
                       |    n   |             
                      -+ 3  y  6+-  MISO      
                       |    8   |             
               GND    -+ 4  5  5+-  MOSI      
                       |________|             
                                              

                 MISO    o1 2o   VCC   
                 SCK     o3 4o   MOSI     
                 Reset   o5 6o   GND 

                          ICSP
                        Connector

Wire VCC to VCC, MISO to MISO, MOSI to MOSI, SCK to SCK, Reset to Reset and GND to GND. If you’re using an Arduino, you want to do this:

The wiring for that is:

• Arduino D10 → ATtiny Pin 1 (Reset)
• Arduino GND → ATtiny Pin 4 (GND)
• Arduino D11 → ATtiny Pin 5 (MOSI)
• Arduino D12 → ATtiny Pin 6 (MISO)
• Arduino D13 → ATtiny Pin 7 (SCK)
• Arduino 5V → ATtiny Pin 8 (VCC)
• You’ll also need to put a 1-10 µF electrolytic capacitor between the Arduino’s Reset and GND pins, but only after you’ve programmed it with the ArduinoISP sketch.

You’re almost there!

Setting up the programmer: USBtinyISP

If you haven’t used one with your computer before, you need to do a little bit of prep so your computer recognizes it. These are modified from a gist:

• do sudo vi /etc/udev/rules.d/41-usbtiny.rules
• add the line SUBSYSTEM=="usb", ATTR{idVendor}=="1781", ATTR{idProduct}=="0c9f", GROUP="plugdev", MODE="0666"
• save and exit
• do sudo udevadm control --reload then sudo udevadm trigger

Your system should automatically recognize the device and give you permission to use it without sudo privileges.

Setting up the programmer: ArduinoISP

• Load the ArduinoISP sketch (it’s in File → Examples)
• Add (or find and uncomment) the line #define USE_OLD_STYLE_WIRING
• Upload the code to your Arduino
• Connect the 1-10 µF electrolytic capacitor between the Arduino’s Reset and GND pins

To program the mmml.hex you created earlier, you’ll need one of these avrdude commands:

For USBTinyISP:

avrdude -c usbtiny -p attiny85 -U lfuse:w:0xe2:m -U hfuse:w:0xdf:m -U efuse:w:0xff:m -U flash:w:mmml.hex:i

For ArduinoISP:

avrdude -c arduino -P /dev/ttyUSB0 -b 19200 -p attiny85 -U lfuse:w:0xe2:m -U hfuse:w:0xdf:m -U efuse:w:0xff:m -U flash:w:mmml.hex:i

What all that means:

• -c usbtiny or -c arduino: programmer type. In addition, the arduino programmer takes additional parameters -P /dev/ttyUSB0 -b 19200 which specify the port (usually /dev/ttyUSB0 or /dev/ttyACM0) and the baud rate (always 19200, unless you changed it in the source of ArduinoISP)
• -p attiny85: the chip type, as used in the avr-gcc compiler call way up the top
• -U lfuse:w:0xe2:m -U hfuse:w:0xdf:m -U efuse:w:0xff:m: fuses are AVR’s confusing name for configuration bits. You might just have to take my word that this sets an ATtiny85 to use the internal 8 MHz oscillator (as opposed to an external crystal) we told the compiler to use further back. A guide to fuse settings is available at the Engbedded AVR Fuse Calculator
• -U flash:w:mmml.hex:i: the hex file we prepared, mmml.hex.

If everything went right with your flashing process, you should see lots of “avrdude: verifying … done. Thank you”. If you don’t, likely you missed a connection somewhere.

♫ Playing the tunes! ♫

I already described all of the bits in the bill of materials in the Hardware section. If you want it in ASCII art, here’s all there is to it:

                        ________              
                       |o   A   |             
          VCC--(10kΩ)--+ 1  T  8+--VCC        
                       |    t   |             
                      -+ 2  i  7+-            
                       |    n   |             
                      -+ 3  y  6+-      (     
                       |    8   |      ((     
                  GND--+ 4  5  5+--(SPKR(--GND
                       |________|      ((     
                                        (     

          Pin 1: RST - held high through pull-up to prevent reset
          Pin 4: GND
          Pin 5: PB0 - through speaker/buzzer to GND
          Pin 8: VCC - can be a CR2032 Lithium coin cell

          Not shown: 100 nF decoupling capacitor between VCC and GND
          Short Pin 1 to GND to restart song

If you weren’t able to compile the tunes, I’ve included (with Blake’s permission) source for any AVR µc plus hex files for ATtiny85s here: protodome-mmml-examples.zip

Last but not least, there are a couple of tracks included in the source that aren’t on the 4000AD album. Blake gave me permission to include them here, too:

These weren’t recorded from a tiny speaker (that went badly), but directly to a Marantz solid state recorder. The rig’s the same as the playback one, with the speaker replaced by a potentiometer (for level control), a 100 µF capacitor (to take off some of the DC bias and also to cut some of the very high frequencies) and a headphone socket. Have fun!