********************
Alarm Clock Device
********************

Overview
====================

The Alarm Clock device is a low-speed general resource which can help
other devices accomplish simple timed actions. It is designed to work
at resolutions on the order of minutes or hours.  Users who need
timed behavior faster than once per minute should use their own thread
and timer logic.

It publishes time data to a set of timed channels at intervals denoted
by the channel names.

Configuration
====================

A typical alarm clock configuration block looks like this::

  - name: tick_tock
    driver: devices.alarm_clock_device:AlarmClockDevice
    settings:
        printf: minute

Settings
--------------------

tick_rate (optional, default: 60) 
    Interval update rate in seconds. Determines how often the thread
    wakes.  Setting it to 15 means the thread wakes up 4 times for
    every ``minute`` event.  Setting to 300 means 4 out of 5 ``minute``
    events are missed.

    .. warning:: This setting is no longer used.  Old configuration
                 files will continue to be accepted, but the driver
                 will always generate events for all channels on their
                 schedule without allowing the rate to be specified

printf (optional, default: None) 
    Defines how often the driver prints trace 'time is now' to the
    console, and can be set to one of
    ``['minute','hour','six_hour','day']``

Channels
====================

15_sec (Get, type: tuple)
    set/publish a sample once per 15 seconds

minute (Get, type: tuple)
    set/publish a sample once per minute

15_min (Get, type: tuple)
    set/publish a sample once per 15 minutes

hour (Get, type: tuple)
    set/publish a sample once per hour

six_hour (Get, type: tuple)
    set/publish a sample once per 6 hours

day (Get, type: tuple)
    set/publish a sample once per day

The sample value published to each channel is a tuple of the form::
 
    (1244544360.0, (2009, 6, 9, 10, 46, 0, 1, 160, -1))

* The first number is the ``time.time()`` response, so seconds since epoch.
* The second item is the ``time.localtime()`` converted to a tuple.
  
.. Note:: It is possible for publish events to be skipped or delayed
          in some cases -- for example another task might cause the
          alarm clock to be busy longer than one minute. So your
          device may want to examine the time value in the channel
          value to determine more precisely how many seconds have
          occurred since the last event.
  
