circuitpython/docs/library/pyb.RTC.rst

.. _pyb.RTC:

class RTC -- real time clock
============================

The RTC is and independent clock that keeps track of the date
and time.

Example usage::

    rtc = pyb.RTC()
    rtc.datetime((2014, 5, 1, 4, 13, 0, 0, 0))
    print(rtc.datetime())


Constructors
------------

.. class:: pyb.RTC()

   Create an RTC object.


Methods
-------

.. method:: rtc.datetime([datetimetuple])

   Get or set the date and time of the RTC.
   
   With no arguments, this method returns an 8-tuple with the current
   date and time.  With 1 argument (being an 8-tuple) it sets the date
   and time.
   
   .. only:: port_pyboard
   
       The 8-tuple has the following format:
       
           (year, month, day, weekday, hours, minutes, seconds, subseconds)
       
       ``weekday`` is 1-7 for Monday through Sunday.
       
       ``subseconds`` counts down from 255 to 0
       
   .. only:: port_wipy
   
       The 8-tuple has the following format:
       
           ``(year, month, day, weekday, hours, minutes, seconds, milliseconds)``
       
       ``weekday`` is 0-6 for Monday through Sunday.

.. only:: port_pyboard

    .. method:: rtc.wakeup(timeout, callback=None)
    
       Set the RTC wakeup timer to trigger repeatedly at every ``timeout``
       milliseconds.  This trigger can wake the pyboard from both the sleep
       states: :meth:`pyb.stop` and :meth:`pyb.standby`.
    
       If ``timeout`` is ``None`` then the wakeup timer is disabled.
    
       If ``callback`` is given then it is executed at every trigger of the
       wakeup timer.  ``callback`` must take exactly one argument.
    
    .. method:: rtc.info()
    
       Get information about the startup time and reset source.
       
        - The lower 0xffff are the number of milliseconds the RTC took to
          start up.
        - Bit 0x10000 is set if a power-on reset occurred.
        - Bit 0x20000 is set if an external reset occurred
    
    .. method:: rtc.calibration(cal)
    
       Get or set RTC calibration.
    
       With no arguments, ``calibration()`` returns the current calibration
       value, which is an integer in the range [-511 : 512].  With one
       argument it sets the RTC calibration.
    
       The RTC Smooth Calibration mechanism addjusts the RTC clock rate by
       adding or subtracting the given number of ticks from the 32768 Hz
       clock over a 32 second period (corresponding to 2^20 clock ticks.)
       Each tick added will speed up the clock by 1 part in 2^20, or 0.954
       ppm; likewise the RTC clock it slowed by negative values. The
       usable calibration range is:
       (-511 * 0.954) ~= -487.5 ppm up to (512 * 0.954) ~= 488.5 ppm

.. only:: port_wipy

    .. method:: rtc.callback(\*, value, handler=None, wake_from=pyb.Sleep.ACTIVE)
    
       Create a callback object triggered by a real time clock alarm.
    
          - ``value`` is the alarm timeout in milliseconds. This parameter is required.
          - ``handler`` is the function to be called when the callback is triggered.
          - ``wake_from`` specifies the power mode from where this interrupt can wake
            up the system.