USAGE

####################
## BUTTONS SCHEME ##
####################

Unless the ADAFRUIT_BUTTONS macro is defined in config.h, the buttons
function as described below.

.----------------------------------------------.
| Button | Function                            |
|--------+-------------------------------------|
| "menu" | enter menu / exit menu              |
|  "set" | open menu item / save setting value |
|    "+" | next menu item / next setting value |
'----------------------------------------------'

When time is displayed, pressing the "set" or "plus" button will display
the date.

When time is displayed, the "menu" button will enter the configuration
menu.  While in the configuration menu, pressing "menu" will return to the
time display, canceling any changes that may have been made.

While in the configuration menu and a menu label is displayed, the "set"
button will open the displayed category or setting.  While in the
configuration menu and a setting is displayed, the "set" button saves the
selected setting and either proceeds to the next related setting or returns
to the time display.

While in the configuration menu and a menu label is displayed, the "+"
button moves to the next menu label.  While in the configuration menu and a
setting is displayed, the "+" button moves to the next possible value for
that setting.

The "alarm" switch turns enabled alarms on or off.  When the alarm sounds,
pressing any button will enable snooze.  Only the alarm switch will turn a
sounding alarm off.


###################################
## RESET AND DIAGNOSTIC MESSAGES ##
###################################

After a reset, the microcontroller will examine MCUSR (microcontroller
unit status register) to determine the reason for the reset, and the
display will alternate between the restored time and a message showing
the cause of the reset.  Reset messages can be dismissed by setting
the time, as the time is usually wrong after a reset.

  "bod rset" (brown out detection reset):  The clock was reset due to
      insufficient voltage.  This usually happens when power is lost
      and the backup battery is nearly dead.

  "pin rset" (external reset):  The clock was reset by an external
      signal to the microcontroller reset pin (pin 1).  Programming
      the clock through the ISP header will trigger an external reset.
      Accidently shorting the reset pin to ground will do the same.
      This message used to read "ext rset", but the "x" looked more
      like an "H".

  "pwr rset" (power reset):  The clock started up after a complete
      power loss.  This usually happens if the clock loses external
      with without a backup battery or with a completely dead backup
      battery.

  "wdt rset" (watchdog timer reset):  During normal operation the
      clock will periodically reset the watchdog timer.  If this
      timer expires, the clock is behaving abnormally and will reset
      itself in an attempt to fix the problem.  Usually watchdog timer
      resets are caused by problems with the crystal oscillator; see
      the troubleshooting entry on crystal oscillator problems.

  "oth rset" (other reset):  If no flags were set in MCUSR to indicate
      the cause of the reset, the display will flash "oth rest".  In
      theory, this should never happen.

The clock might also flash one of the following status messages:

  "bad batt" (low battery warning):  The microcontroller checks
      the system voltage whenever the clock sleeps for more than ten
      minutes.  When the battery is low, the display will flash
      "bad batt" after the clock wakes, and the message can be
      dismissed by pressing any button.

  "gps lost" (GPS signal lost; only applies if GPS_TIMEKEEPING was
      defined in config.h):  The clock is receiving data from the GPS,
      but the GPS has been unable to acquire a signal for at least
      three minutes.

  "temp err" (temperature sensor error; only applies if
      TEMPERATURE_SENSOR was defined in config.h):  If the
      microcontroller is unable to communicate with the temperature
      sensor, the display will flash "temp err".


###################
## MENU SETTINGS ##
###################

Because of the many configuration options, the menus options are arranged
in a nested structure.

"set alar"
  "alarm 1 " / "alarm 2 " / "alarm 3 "
    Enable alarm ("alar  on") or disable alarm ("alar off").  If the alarm
    is enabled, next set the hour and minute of the alarm time.  Finally,
    choose the days in which the alarm should sound ("all days" /
    "weekdays" / "weekends" / " custom ").  If " custom " is selected,
    specify a subset of days by showing only the letters ("smtwtfs ")
    corresponding to the days on which the alarm should sound.

"set time"
  Set the current hour, minute, and second.

"set date"
  Set the current year, month, and day.

"cfg alar"  --  Configure Alarm
  "a. sound"
    Change the alarm sound.  Choices are high frequency beeps ("beeps hi"),
    low frequency beeps ("beeps lo"), high frequency three beep pulse
    ("pulse hi"), low frequency three beep pulse ("pulse lo"),
    Merry Christmas ("mery chr"), Big Ben ("big ben "), Reveille ("reveille"),
    or For He's a Jolly Good Fellow ("jly good").

  "a. volume"  
    Set the alarm volume or enable the progressive alarm ("vol prog").  With
    the progressive alarm option, also set the minimum volume ("v. min XX"),
    maximum volume ("v. max XX"), and ramp time in minutes ("time XX").  The
    alarm will start at the minimum volume and gradually reach the maximum
    volume over the specified ramp time.

  "a. snooze"
    Change the snooze time (minutes).

  "a. pulse"
    Enable display brightness pulsing during alarm and snooze ("puls  on"),
    alarm only ("puls alr"), snooze only ("puls snz"), or neither
    ("puls off").


"cfg disp"  --  Configure the Display

  "disp bri"
    Set display brightness or enable automatic dimming ("bri auto").  With
    automatic dimming the user is prompted for the minimum ("b. min XX") and
    maximum ("b. max XX") brightness.

    The autodim minimum and maximum values may range from -5 to
    20---beyond the allowed brightness range of 0 to 10.  The actual
    display brightness, however, will never be brighter or dimmer than
    allowed to ensure that the display will always be visible and prevent
    display damage.

    With the autodim feature, display brightness is calculated from
    photoresistor voltage.  In the dark, voltage is highest and decreases
    as the ambient light increases.  The minimum and maximum autodim
    values set the brightness at 5 volts and ground level.  Display
    brightness is linearly interpolated from the photoresistor voltage.
    If the interpolation yields a value above or below the allowed
    brightness, display brightness is changed to the minimum or maximum
    allowed brightness, respectively.

    In normal clock use, photoresistor voltages change over only part of
    the 0 to 5 volt range.  So setting the autodim thresholds below and
    above the minimum and maximum provides more flexibility when
    configuring autodimming.

  "digt bri"
    Adjust the brightness of each individual digit to compensate for
    inconsistent digit brightness.  In addition to the standard
    single-button commands, the per-digit brightness controls also
    respond to two multi-button commands:

      (1) Pressing "set" and "+" simultaneously resets the brightness of
	  the current digit to the minimum (default) value.

      (2) Pressing "menu" and "+" simultaneously resets the brightness of
	  all digits to the minimum (default) value.

  "auto off" -- Automatic Display Off
    Some users may wish to inactivate the display when no one is around, as
    doing so should extend VFD lifetime.  Other users may wish to inactivate
    the display at night, as extra light can interfere with sleep.  When the
    display is inactive, pressing any button will enable the display for one
    minute.

    "off dark"
      Enable or disable automatic inactivation at night (when dark).
      This option is only available if the automatic dimmer is enabled,
      which requires a photoresistor and pull-up.  Unless this option is
      disabled, the user will be prompted for a darkness detection
      threshold ("thrsh XX").

    "off time"
      Enable or disable automatic inactivation during certain hours.
      For example, if the clock is at the workplace of someone with a 9-to-5
      schedule, the display may be disabled from 5:00pm to 9:00am.

    "off days"
      Enable or disable automatic inactivation during certain days.
      For example, if the clock is at the workplace of someone with a
      Monday-through-Friday schedule, the display may be disabled during
      weekends.

    "on days "
      Force the display to be active on certain days (overrides off time).
      For example, if the clock is at the home of a person with a 9-to-5
      Monday-through-Friday schedule, they might set the "off time" to 9:00am
      to 5:00 pm and set the "on days" to weekends, so the display would be
      enabled whenever the person is home.

  "animated" 
    Enable or disable animated display transitions.


"cfg regn" -- Configure Regional Preferences

  "set dst "
    Configure daylight saving time.  The user may manually enable
    ("dst   on") or disable ("dst  off") daylight saving time.
    Alternatively, the user may configure automatic enabling and disabling of
    DST by United States ("dst  usa") or European Union ("dst   eu") rules.

    When using the European Union rules, the user must also specify the time
    zone as Western European Time ("zone wet"), Central European Time
    ("zone cet"), or Eastern European Time ("zone eet").

  "set zone"
    Configure the timezone relative to UTC/GMT.  This option is only available
    with the GPS timekeeping mod and is used to convert UTC/GMT time from the
    GPS to local time.  The time offset is for standard time and does
    not include the extra hour for daylight saving time; use the "set dst "
    option above for configuring daylight saving time.

  "time fmt"
    Configure the time format.  First, specify if the time format should be
    displayed in a 12-hour or 24-hour format with "hours 12" or "hours 24".
    Second, select the format of the time display.  Third, select how colons
    in the time format should be displayed ("sep  a:b").  Fourth, specify if 
    daylight saving time should be shown with "dst show" or "dst hide".
    If compiled with GPS support, a fifth option might allow you to show if
    the GPS is receiving data with "gps show" or "gps hide".

    The two binary indicators are the leftmost indicator circle and rightmost
    final decimal point.  Depending on the specified time format, these
    indicators will show AM/PM, DST, or GPS.  Because there are only two binary
    indicators, it is not possible to enable all three indicators at once.

  "date fmt"
    Configure the date format.  First, specify if the weekday should be shown
    with "wday  on" or "wday off".  Second, select the format of the month-day
    display.  Third, specify if the year should be shown with "year  on" or
    "year off".  Fourth and finally, specify if the date should be
    automatically shown at regular intervals of 10, 30, or 60 seconds
    ("auto off", "auto  10", "auto 30", "auto 60").

  "misc fmt"
    Configure how numbers and letters are displayed.  First, select whether
    single digit numbers should have a leading zero with "zero   0" or
    "zero  00".  Second, select how the number nine should be displayed with
    "nine   9" or "nine   9".  Third and finally, select the font for
    display characters with "char  eg" or "ChAr  EG".