##########################
## XMAS-ICETUBE PROJECT ##
##########################

Several years ago, my father gave me an Adafruit Ice Tube Clock kit as
a Christmas gift.  As an excuse to learn AVR programming, I started
playing with the firmware.  Eventually, none of the original Adafruit
code remained, and the result was a feature-rich reimplementation of
the Adafruit firmware.

Once the firmware was mature, I decided to revise the hardware design
to support many of the hacks and mods described on the Adafruit
forums.  With the help of other clock hackers, especially Phil DeGruy
and Russell Walker, the xmas-icetube hardware revision became a reality.

Today, the xmas-icetube firmware still runs on the Adafruit Ice Tube
Clock v1.1 as well as the xmas-icetube hardware revision.  For more
information on the firmware and hardware portions of this project,
please check out the firmware/README and hardware/README files.

Finally, although the xmas-icetube project is named after Christmas,
it is designed for use year-round.  The name is also a reference to
Christmas as a cultural holiday--not a religious one.  I sincerely
hope this project is compatible with all religions.

  John Archie <www.jarchie.com/email>
  April 2, 2014


###################
## USER FEEDBACK ##
###################

Below is a selection of comments posted on the Adafruit Clocks
forum.  They are listed in reverse chronological order.  And to
everyone quoted below:  Thank you all for the kind words!

  "[The xmas firmware] just worked from the beginning...
   Great documentation!"
     --MikeHg
       http://forums.adafruit.com/viewtopic.php?p=324261#p324261

  "Every mod works beautifully...  The code truly is clever...
   [John's] code is so clean that it's easy to add things."
     --rcb
       http://forums.adafruit.com/viewtopic.php?p=244224#p244224

  "This firmware is really cool. I highly recommend anyone with an
   ATmega328p lying around to program it with this firmware and use
   it instead of the one that comes with the kit."
     --motocoder
       http://forums.adafruit.com/viewtopic.php?p=243916#p243916

  "[John] has done a lot of nice work and added a lot of features.
   I can recommend his firmware as an upgrade..."
     --adafruit_support_bill,
       http://forums.adafruit.com/viewtopic.php?p=211476#p211476

  "...I LOVE your firmware, and for about 2 weeks I was still
   finding new options and features in the menu."
     --wildtang3nt
       http://forums.adafruit.com/viewtopic.php?p=204665#p204665

  "+10 for John's firmware!  Please do not let the 'xmas' name sway
   you from giving it a try. It's the most feature complete Ice-Tube
   Clock firmware to date."
     --revnull
       http://forums.adafruit.com/viewtopic.php?p=180609#p180609


##############
## FEATURES ##
##############

The xmas-icetube firmware offers the following improvements over
the official Adafruit firmware:

  - GPS synchronized timekeeping*
  - fully automatic compensation for clock drift
  - animated display transitions
  - multiple time and date formats
  - DST support (USA, EU, or manual)
  - pulsing display brightness during alarm and snooze
  - three alarm times for selectable days of the week
  - functional alarm during power outage**
  - finely adjustable alarm volume (from 0 to 10)
  - progressive alarm option (gradually increasing volume)
  - adjustable snooze duration
  - selectable alarm sound (high frequency beeps, low frequency beeps,
    high frequency three beep pulse, low frequency three beep pulse,
    Merry Christmas, Big Ben, Reveille, or For He's a Jolly Good Fellow)
  - 4-fold improvement in battery life
  - no beeping or time loss after external power failure
  - low battery warning before battery failure
  - per-digit brightness adjustment for uneven displays
  - larger range for user-configured display brightness
  - optionally disable display during specified time periods

*  An external GPS module, such as the Adafruit Ultimate GPS, is
   necessary to support GPS synchronized timekeeping.

** Without external power, the alarm sounds with loud high frequency
   beeps.  The only way to turn the alarm on or off is with the alarm
   switch.  Snooze is not supported.

The following additional features are supported on the xmas-icetube
hardware revision, but the Adafruit Ice Tube Clock v1.1 can be
modified to support any or all of the following as well:

  - automatic brightness control by ambient light
  - optionally disable display at night (when dark)
  - 25-fold improvement in battery life
  - highly accurate temperature compensated timekeeping
  - IV-18 tube driven to specifications (providing more even
    display illumination and preventing cathode poisoning)