/**
 * \mainpage Binary DCF-77 Clock
 *
 * \section sec_intro Introduction
 *
 * In Germany, the official time is transmitted in a signal called DCF-77. You
 * can find many descriptions of the signal format on the internet.
 *
 * The Binary DCF-77 Clock is a simple device to receive and decode the signal
 * and display the current date and time in binary form. The signal is received
 * in a stock DCF-77 receiver module, decoded with an ATmega8 microcontroller
 * and displayed in binary form on an array of LEDs. This array consists of for
 * lines with eight LEDs each. The ATmega8 is not able to control 32 LEDs at
 * once, so an SAA1064 module is used which is connected via I2C-bus.
 *
 * The time should be displayed in several different binary formats, the format
 * can be selected with a simple button. The formats will be described later.
 *
 * The distribution contains the firmware for the controller, the schematics,
 * the documentation and a copy of the GPL license.
 *
 * \section sec_install Building and installing
 *
 * The firmware for this project requires avr-gcc and avr-libc (a C-library for
 * the AVR controller). Please read the instructions at
 * http://www.nongnu.org/avr-libc/user-manual/install_tools.html for how to
 * install the GNU toolchain (avr-gcc, assembler, linker etc.) and avr-libc.
 *
 * Once you have the GNU toolchain for AVR microcontrollers installed, you can
 * run "make" in the subdirectory "firmware". You may need to customize the
 * makefile. Also, you might have to edit the array byte[] in main.c, which
 * describes the order of the output LEDs. The current order works for me
 * because I soldered the LEDs as compact as possible, it's slightly different
 * from the layout shown in the circuit.
 *
 * Also, you may have to edit the Makefile to use your preferred downloader
 * with "make program". The current version is built for avrdude with a
 * USB connection to an avr109-compatible programmer.
 *
 * No external crystal is needed, so you don't have to struggle with setting
 * any fuse-bits.
 *
 * After making your changes, you can compile and flash to the device:
 *
 * \code
 * make program
 * \endcode
 *
 * \section sec_usage Usage
 *
 * Connect the device to a DC power source with 9V. As long as no time has been
 * decoded, a running light is shown on the output LED array. The single DCF
 * indicator LED should start flashing to indicate that a signal is received.
 * It is set to on when the input signal is high, and switched off if the
 * signal is low. So you should see it flashing with one flash per second, each
 * flash being 100ms or 200ms long.
 *
 * If the signal is received correctly, after about two minutes the clock
 * should be able to tell the correct time.
 *
 * \subsection sec_reading Reading the time
 *
 * The time and date are displayed in seven different styles. You can select
 * the style by pressing the button for a while. A pattern of lights indicate
 * which mode is selected, you can read it as a binary value.
 *
 * \subsubsection sec_mode1 Mode 1: Time as binary
 *
 * This simply displays the hours, minutes and seconds as bytes, one after
 * each other. The fourth line of the display stays blank.
 *
 * \subsubsection sec_mode2 Mode 2: Date as binary
 *
 * This is like the previous, with the difference that it displays the day of
 * the month, the month and the year in the first three lines. The last line
 * shows the day of the week, monday being a 1, tuesday a 2 and so on.
 *
 * \subsubsection sec_mode3 Mode 3: Time as BCD
 *
 * This shows the time as binary coded digits (BCD). The first line displays
 * the hours. The left four LEDs indicate the 10-hours, the right four LEDs
 * indicate the 1-hours.
 *
 * In the same way, the second and third line display the minutes and the
 * seconds.
 *
 * \subsubsection sec_mode4 Mode 4: Date as BCD
 *
 * This is like the previous mode, but the date is displayed.
 *
 * \subsubsection sec_mode5 Mode 5: Time as BCD (vertically)
 *
 * This shows the time in a BCD-form as described in mode 3, but the BCD-values
 * are put vertically next to each other. So in the first two colums you can
 * read the hours, the third column is empty, the fourth and fifth columns show
 * the minutes, the sixth is empty and the seventh and eighths indicate the
 * seconds.
 *
* \subsubsection sec_mode6 Mode 6: Date as BCD (vertically)
 *
 * This is like mode 5, but it displays the date.
 *
 * \subsubsection sec_mode7 Mode 7: Unix timestamp
 *
 * This is probably the least human readable format. It shows a 32-bit value of
 * the seconds since january 1st, 1970. :-)
 *
 * \subsection sec_demo Demo mode
 *
 * If you connect the clock in a place with a poor DCF-reception, but want to
 * demonstrate the functions, you can use the demo mode. To toggle this, you
 * can touch and hold the button for about five seconds. Afterwards, you can
 * switch through the different display modes. The time displayed will stand
 * still, so this can be used to explain the display modes without a hurry.
 *
 * Switching to demo mode is indicated by all LEDs flashing for a short moment.
 * Leaving demo mode shows an empty rectangle for a short moment.
 *
 * \section sec_drawbacks Drawbacks
 *
 * I didn't expect the DCF-signal to be so easily disturbed. In my case
 * sometimes there is no usable signal left when I put my notebook with WLAN
 * next to the clock. Fortunately, the time will be counted further until the
 * next 'correct minute' is received.
 *
 * \section sec_files Files in the distribution
 *
 * - \e Readme.txt: Documentation, created from the htmldoc-directory.
 * - \e firmware: Source code of the controller firmware.
 * - \e circuit: Circuit diagrams in PDF and EAGLE 4 format. A free version of
 *   EAGLE is available for Linux, Mac OS X and Windows from
 *   http://www.cadsoft.de/.
 * - \e License.txt: Public license for all contents of this project.
 * - \e Changelog.txt: Logfile documenting changes in firm- and hardware.
 * - \e refman.pdf: Full documentation of the software.
 *
 * \section sec_thanks Thanks!
 *
 * I'd like to thank <b>Michael Meier</b>, who developed and published a much
 * more sophisticated clock on his site. The SAA1064-stuff and the routine to
 * calculate the Unix timestamp are based on his project. You can find it under
 * http://www.mulder.franken.de/ntpdcfledclock/.
 *
 * And once again I'd like to give special credits to <b>Thomas Stegemann</b>
 * for help with the C language.
 *
 * \section sec_license About the license
 *
 * Our work - all contents except for the USB driver - are licensed under the
 * GNU General Public License (GPL). A copy of the GPL is included in
 * License.txt. The driver itself is licensed under a special license by
 * Objective Development. See firmware/usbdrv/License.txt for further info.
 *
 * <b>(c) 2006 by Ronald Schaten - http://www.schatenseite.de</b>
 */