Windows Installation Tutorial
This tutorial is adapted from an older post on the Adafruit Clocks forum and has been updated for the current version of the xmas-icetube firmware.
Okay... the first step is to download and install all the necessary tools.
If you don't already have a good text editor, you'll need one for editing the various plain-text files. I recommend Notepad++ for newbies. It's free, intuitive, and fairly powerful.
Since Windows does not come with a standard set of Unix/Linux tools, you'll need to install those as well. I recommend Cygwin. When the installer prompts you with a list of packages to install, change the Perl group from "Default" to "Install." Why? Both Adafruit's firmware and xmas-icetube use Perl scripts during compilation, and other alternative firmwares probably do the same.
The last set of tools you'll need to install is the GNU GCC AVR software development tools; I recommend WinAVR.
Okay... so you've got all the tools installed. Time to check out the xmas-icetube package.
Download xmas-icetube from GitHub using the "Download ZIP" link, and extract the files to a suitable location. I usually use **C:\Users\jarchie\Downloads*, and will use that directory here. Examine the list of files now in **C:\Users\jarchie\Downloads\xmas-icetube-master\firmware*.
The first file you should notice is the plain-text README which contains installation instructions and other important information. The CREDITS, LICENSE, and USAGE files are all plain-text documentation files.
The source code files end in .c and .h. Open the main file, icetube.c, in Notepad++. At the top of icetube.c, you'll see comment lines starting with "//" which provide human readable descriptions of each .c file. But the compiler needs a more precise description of each .c file, and that is what the .h files do. The contents of the .c and .h files will be mostly unintelligible unless/until you've learned C. That's completely okay.
The last important file is the Makefile. The Makefile automates the compilation process so you can compile the code with one simple command. Open the Makefile and look through it. Human readable comments start with "#"--not with "//" like in the .c and .h files. The first part of the Makefile contains a lot of variable definitions. The second part of the file contains rules for how the computer should compile the firmware. The contents of the Makefile will be mostly unintelligible unless/until you've learned Makefile syntax. That's completely okay.
The remaining .gitignore file is not used when compiling or installing the firmware. It is only used when modifying the firmware and committing those changes to a git repository.
Okay... so you know what comes in the xmas-icetube package. Time to modify the configuration to suit your needs.
Open the firmware README file and view the installation section. The first step is to edit the Makefile and config.h as necessary, so open these in files in Notepad++.
In the Makefile, look for where the AVRISP and AVRDUDEOPT variables are defined. Recall that everything after a "#" on each line is a comment. These variables happen to be already set appropriately for programming with the USBtinyISP, so most users won't need to edit the Makefile unless they are using a different programmer.
Skim through the config.h file. It's mostly composed of human readable comments describing the different options. Recall that anything after "//" on each line is a comment. You may enable or disable different features by commenting and uncommenting the macro definitions. The defaults are suitable for most users with the Adafruit Ice Tube Clock v1.1, so like the Makefile, config.h can typically be left as is.
Open the Cygwin Terminal to start BASH (the Bourne-Again Shell): "Start" > "All Programs" > "Cygwin" > "Cygwin Terminal." Next, change to your xmas-icetube source code directory with the cd (change directory) command:
$ cd /cygdrive/c/Users/jarchie/Downloads/xmas-icetube-master/firmware/
Note that the initial "$" and space above is part of the command prompt. You don't type that part. It is displayed on the screen to signify that the shell is ready for you to type a command and press return. Some shells use a "%" as the command prompt which is why the xmas-icetube installation instructions uses that symbol instead of a "$".
Now that you have changed to the source code directory, you may print a directory listing with the ls (list) command.
$ ls
alarm.c config.h gps.c Makefile piezo.h temp.c USAGE
alarm.h CREDITS gps.h mode.c README temp.h usart.c
buttons.c display.c icetube.c mode.h system.c time.c usart.h
buttons.h display.h LICENSE piezo.c system.h time.h util.pl
To compile the code, use the make command as described in the installation instructions (step two):
$ make
avr-gcc -c -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 -o icetube.o icetube.c
avr-gcc -MM -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 icetube.c > icetube.d
avr-gcc -c -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 -o system.o system.c
avr-gcc -MM -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 system.c > system.d
./util.pl time | xargs avr-gcc -c -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 -o time.o time.c
./util.pl time | xargs avr-gcc -MM -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 time.c > time.d
avr-gcc -c -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 -o alarm.o alarm.c
avr-gcc -MM -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 alarm.c > alarm.d
avr-gcc -c -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 -o piezo.o piezo.c
avr-gcc -MM -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 piezo.c > piezo.d
avr-gcc -c -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 -o display.o display.c
avr-gcc -MM -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 display.c > display.d
avr-gcc -c -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 -o buttons.o buttons.c
avr-gcc -MM -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 buttons.c > buttons.d
avr-gcc -c -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 -o mode.o mode.c
avr-gcc -MM -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 mode.c > mode.d
avr-gcc -c -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 -o usart.o usart.c
avr-gcc -MM -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 usart.c > usart.d
./util.pl time | xargs avr-gcc -c -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 -o gps.o gps.c
./util.pl time | xargs avr-gcc -MM -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 gps.c > gps.d
avr-gcc -c -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 -o temp.o temp.c
avr-gcc -MM -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 temp.c > temp.d
avr-gcc -I. -mmcu=atmega328p -std=gnu99 -Os -Wall -DF_CPU=8000000 -o icetube.elf icetube.o system.o time.o alarm.o piezo.o display.o buttons.o mode.o usart.o gps.o temp.o
avr-objcopy -R.eeprom -R.fuse -R.lock -O ihex icetube.elf icetube_flash.hex
avr-objcopy --change-section-lma .eeprom=0 -j .eeprom -O ihex icetube.elf icetube_eeprom.hex
avr-objcopy -j.fuse -O ihex icetube.elf icetube_fuse.hex
avr-objcopy -j.lock -O ihex icetube.elf icetube_lock.hex
ATMEGA328P MEMORY USAGE SUMMARY
Program memory (FLASH): 91% (30104/32768)
Preallocated SRAM: 8% ( 166/ 2048)
Allocated EEPROM: 6% ( 65/ 1024)
If you run the ls command again, you'll notice that there are now a lot more files:
$ ls
alarm.c display.c icetube.elf mode.h system.o usart.c
alarm.d display.d icetube.o mode.o temp.c usart.d
alarm.h display.h icetube_eeprom.hex piezo.c temp.d usart.h
alarm.o display.o icetube_flash.hex piezo.d temp.h usart.o
buttons.c gps.c icetube_fuse.hex piezo.h temp.o util.pl
buttons.d gps.d icetube_lock.hex piezo.o time.c
buttons.h gps.h LICENSE README time.d
buttons.o gps.o Makefile system.c time.h
config.h icetube.c mode.c system.d time.o
CREDITS icetube.d mode.d system.h USAGE
The .d files are used by the Makefile to improve compilation efficiency; they are not important. The .o files are the compiled versions of the .c files. These .o files are linked together to create icetube.elf, a single binary containing the entire firmware. But the AVR programming utility, avrdude, cannot read the icetube.elf format, so that file has been converted into four .hex files. As the name implies, icetube_flash.hex contains the executable portion of the firmware to be uploaded to flash (program memory). The icetube_eeprom.hex file contains the initial EEPROM contents to be uploaded to the EEPROM. The EEPROM contains data the clock stores even when power is lost, such as the last known time or the menu-configured clock settings. The icetube_fuse.hex file contains the fuse bits. The fuse bits store configuration information for the chip itself, such as the oscillator configuration or the brownout detection settings. Finally, the icetube_lock.hex file contains the lock bits. The lock bits are used to configure which--if any--memory access restrictions should be enforced.
Well, congratulations! If you've gotten this far, you've successfully compiled your first firmware.
After you build the USBtinyISP and install the Windows driver according to the Adafruit tutorial, you will be able to program chips with xmas-icetube through BASH within the Cygwin Terminal. Attach the programer exactly as described in the README (step three). Open the Cygwin Terminal, change to the xmas-icetube directory, and run the make install-all command (step four):
$ cd /cygdrive/c/Users/jarchie/Downloads/xmas-icetube-master/firmware/
$ make install-all
avrdude -B 4 -P usb -c usbtiny -p atmega328p -u -U lfuse:w:0x62:m -u -U hfuse:w:0xD1:m -u -U efuse:w:0x06:m -U flash:w:icetube_flash.hex:i -U eeprom:w:icetube_eeprom.hex:i -U lock:w:0x2B:m
avrdude.exe: AVR device initialized and ready to accept instructions
Reading | ################################################## | 100% 0.00s
avrdude.exe: Device signature = 0x1e950f
avrdude.exe: NOTE: FLASH memory has been specified, an erase cycle will be performed
To disable this feature, specify the -D option.
avrdude.exe: erasing chip
avrdude.exe: reading input file "0x62"
avrdude.exe: writing lfuse (1 bytes):
Writing | ################################################## | 100% 0.00s
avrdude.exe: 1 bytes of lfuse written
avrdude.exe: verifying lfuse memory against 0x62:
avrdude.exe: load data lfuse data from input file 0x62:
avrdude.exe: input file 0x62 contains 1 bytes
avrdude.exe: reading on-chip lfuse data:
Reading | ################################################## | 100% 0.00s
avrdude.exe: verifying ...
avrdude.exe: 1 bytes of lfuse verified
avrdude.exe: reading input file "0xD1"
avrdude.exe: writing hfuse (1 bytes):
Writing | ################################################## | 100% 0.00s
avrdude.exe: 1 bytes of hfuse written
avrdude.exe: verifying hfuse memory against 0xD1:
avrdude.exe: load data hfuse data from input file 0xD1:
avrdude.exe: input file 0xD1 contains 1 bytes
avrdude.exe: reading on-chip hfuse data:
Reading | ################################################## | 100% 0.00s
avrdude.exe: verifying ...
avrdude.exe: 1 bytes of hfuse verified
avrdude.exe: reading input file "0x06"
avrdude.exe: writing efuse (1 bytes):
Writing | ################################################## | 100% 0.00s
avrdude.exe: 1 bytes of efuse written
avrdude.exe: verifying efuse memory against 0x06:
avrdude.exe: load data efuse data from input file 0x06:
avrdude.exe: input file 0x06 contains 1 bytes
avrdude.exe: reading on-chip efuse data:
Reading | ################################################## | 100% 0.02s
avrdude.exe: verifying ...
avrdude.exe: 1 bytes of efuse verified
avrdude.exe: reading input file "icetube_flash.hex"
avrdude.exe: writing flash (30104 bytes):
Writing | ################################################## | 100% 24.02s
avrdude.exe: 30104 bytes of flash written
avrdude.exe: verifying flash memory against icetube_flash.hex:
avrdude.exe: load data flash data from input file icetube_flash.hex:
avrdude.exe: input file icetube_flash.hex contains 30104 bytes
avrdude.exe: reading on-chip flash data:
Reading | ################################################## | 100% 13.56s
avrdude.exe: verifying ...
avrdude.exe: 30104 bytes of flash verified
avrdude.exe: reading input file "icetube_eeprom.hex"
avrdude.exe: writing eeprom (65 bytes):
Writing | ################################################## | 100% 0.33s
avrdude.exe: 65 bytes of eeprom written
avrdude.exe: verifying eeprom memory against icetube_eeprom.hex:
avrdude.exe: load data eeprom data from input file icetube_eeprom.hex:
avrdude.exe: input file icetube_eeprom.hex contains 65 bytes
avrdude.exe: reading on-chip eeprom data:
Reading | ################################################## | 100% 0.03s
avrdude.exe: verifying ...
avrdude.exe: 65 bytes of eeprom verified
avrdude.exe: reading input file "0x2B"
avrdude.exe: writing lock (1 bytes):
Writing | ################################################## | 100% 0.02s
avrdude.exe: 1 bytes of lock written
avrdude.exe: verifying lock memory against 0x2B:
avrdude.exe: load data lock data from input file 0x2B:
avrdude.exe: input file 0x2B contains 1 bytes
avrdude.exe: reading on-chip lock data:
Reading | ################################################## | 100% 0.00s
avrdude.exe: verifying ...
avrdude.exe: 1 bytes of lock verified
avrdude.exe done. Thank you.
The clock should beep after successful programming. If everything seems normal, disconnect the clock board from the programmer and power cables, reassemble the clock, and power the clock with the AC adapter. If all is well, the clock will flash the time and one of the reset messages ("pin rset", "pwr rset", or "bod rset"). The meaning of these messages is described in the README file, and these messages can be dismissed by setting the time. See the usage documentation (the USAGE file) for details on how to set the time and configure various options through the clock menus.
Good luck and happy hacking!