Timelapse/INSTALL

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[1] 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[2] 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
[1] http://www.nongnu.org/avrdude/
[2] http://learn.adafruit.com/usbtinyisp