From Penguin Development
|This article is a verbatim copy of a plain-text documentation file.|
The original file is INSTALL, contained in the tarball timelapse-0.1.xz.
This document describes the general procedure of compiling and flashing the timelapse firmware. It should be noted that a working Intel Hex file is provided, which can be flashed immediately -- unless you really wish to compile the firmware yourself, you can skip straight to the FLASHING section. COMPILING In order to compile the firmware from source, it is necessary to have a working AVR toolchain. Setting up such a toolchain is beyond the scope of this document; it is henceforth assumed that at least a working avr-gcc and avr-objcopy are present on the host system. Compilation has been tested with avr-gcc-4.8.1, however, different versions should also work (possibly using different command-line arguments). The suggested sequence of commands for compiling the timelapse firmware using GCC 4.8.1 is as follows: cd src/ avr-gcc -std=gnu89 -g -Wall -Os -Wextra -Werror -pedantic \ -pedantic-errors -mmcu=attiny2313 -Wl,--as-needed,-Map,timelapse.map \ -flto -fwhole-program -mrelax -mstrict-X -maccumulate-args -o timelapse \ lcd.c main.c avr-objcopy -j .text -j .data -O ihex timelapse timelapse.hex Very aggressive size optimisation is necessary to allow the firmware to fit on an ATtiny2313 or ATtiny2313A. After successfully compiling the firmware, the size of the resulting binary can be determined with the following command: avr-size -A timelapse The sum of the sizes of the .text and .data sections must be 2048 or less for the firmware to fit on an ATtiny2313(A). (The hex file shipped in the source tarball has, at the time of writing, a cumulative .text and .data size of 2044 bytes.) It is important to note that `-mmcu=attiny2313' should be used, even when the target device an an ATtiny2313A or ATtiny4313. These newer devices are fully backwards-compatible with code compiled for ATtiny2313, however the headers specific to these devices as shipped with GCC are presently broken. The suggested compilation commands should complete without error and should result in the creation of the files `timelapse' (an ELF binary), `timelapse.map' (a linker map file) and `timelapse.hex' (an Intel HEX file). COMPILE-TIME CONFIGURATION Some elements of the firmware may be configured at compile-time, most prominently through editing settings.h. The most prominent options shall briefly be explained here; see settings.h for additional documentation. (1) Clock frequency It is possible to run the timelapse board from a number of different crystal frequencies. The shipped HEX file assumes 4.096 MHz, however any crystal frequency which is divisible by 256 kHz may be used. It is critically important that the F_CPU #define in settings.h is set to the correct value (i.e. the crystal's frequency in hertz). Please take care to burn the correct fuses for the selected crystal frequency; see the FLASHING section in this document. (2) EEPROM address of runtime configuration timelapse stores the user-configured timing settings to the AVR's EEPROM. By default, this information is simply placed at the start of the EEPROM (address 0x00). The EE_CONFIG_ADDR #define can be used to change this default address. Care should be taken that the entire configuration structure fits in the space after this address. At the time of writing, the configuration takes twelve bytes of space; EE_CONFIG_ADDR should therefore be at least twelve bytes less than the total EEPROM size (e.g. on the ATtiny2313(A), which has 128 bytes of EEPROM, the maximum value of EE_CONFIG_ADDR is 116). It is highly recommended to erase the EEPROM when changing this value! (3) Debounce time The push-buttons on the timelapse board are debounced in software using a timer, and the duration of this timer is set by the DEBOUNCE #define. The duration in milliseconds is given by 256000*(DEBOUNCE+1)/F_CPU. The default value of DEBOUNCE is 799, which gives a duration of 50 ms. If button presses are registered twice, increase DEBOUNCE. If some short button presses fail to register at all, decrease DEBOUNCE. FLASHING Flashing the firmware requires AVRDUDE or an equivalent program; AVRDUDE version 5.11.1 has been confirmed to work. timelapse is in-system programmable; this requires a programmer with a six-pin connector. The USBTinyISP by Adafruit Industries has been confirmed to work. Programming the AVR requires a firmware HEX file; such a file, suitable for the reference design, should be provided with the source distribution. See the section COMPILING in this document if you wish to compile the firmware yourself. Perhaps the most important step when flashing the firmware is to ensure the fuses are set correctly. The CKSEL and SUT fuses are of particular importance as they affect the timing characteristics; the necessary values for these fuses depends on the crystal used. Make sure the CKDIV8, CKOUT and WDTON fuses are NOT set. With a 4.096 MHz crystal, low, high and extended fuse values of 0xcd, 0xdf and 0xff, respectively, have been confirmed to work. See the table below for recommended fuses: +---------------+------+------+------+ | Crystal freq. | Low | High | Ext | +---------------+------+------+------+ | 0.4-0.9 MHz | 0xc9 | 0xdf | 0xff | | 0.9-3.0 MHz | 0xcb | 0xdf | 0xff | | 3.0-8.0 MHz | 0xcd | 0xdf | 0xff | | 9.0-20.0 MHz | 0xcf | 0xdf | 0xff | +---------------+------+------+------+ These fuses are valid for ATtiny2313, ATtiny2313A and ATtiny4313. Some additional and potentially useful options which should not affect normal operation can be set by changing the High fuse. These options are the brown-out detector and the EESAVE fuse. The brown-out detector (BOD) resets the AVR if the voltage drops below a certain threshold, and the EESAVE fuse enables you to preserve the user configuration when re-flashing the AVR. The brown-out threshold can be set to 4.3 V, 2.7 V or 1.8 V; only 4.3 V is recommended. The table below lists the High fuse value for these options: +-----+--------+-----------+ | BOD | EESAVE | High fuse | +-----+--------+-----------+ | No | No | 0xdf | | Yes | No | 0xd9 | | No | Yes | 0x9f | | Yes | Yes | 0x99 | +-----+--------+-----------+ Once you have determined the fuses you wish to use, connect the programmer to the ISP header (J1). (In the current PCB design, the pin closest to the crystal is pin 1.) Some programmers allow the board to either be self-powered or powered by the programmer. If the programmer allows 5 V signals, it is recommended to use the self-powered configuration (i.e. powering the timelapse board using a 9 V battery, as in normal operation). Powering the timelapse board through the programmer is also possible; however, as this reverse-biases the on-board regulator, this is not recommended. Using AVRDUDE, the following commands should program the AVR correctly: cd src/ avrdude -c usbtiny -p t2313 -U lfuse:w:0xcd:m -U hfuse:w:0xdf:m \ -U efuse:w:0xff avrdude -c usbtiny -p t2313 -U flash:w:timelapse.hex In the above commands, `usbtiny' should be replaced with your programmer of choice, and `t2313' should be replaced by t4313 if an ATtiny4313 is used. The lfuse, hfuse and efuse settings should of course be set to match the desired settings from the tables above. If the timelapse firmware and fuses have been programmed correctly, the LCD should display text immediately after the firmware is flashed (provided it was connected during programming). If this does not happen, disconnect the programmer and power the timelapse board from an external battery. LINKS  http://www.nongnu.org/avrdude/  http://learn.adafruit.com/usbtinyisp