.. currentmodule:: machine .. _machine.RTC:

class RTC -- real time clock

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

Example usage::

rtc = machine.RTC()
rtc.datetime((2020, 1, 21, 2, 10, 32, 36, 0))
print(rtc.datetime())

Constructors

.. class:: RTC(id=0, ...)

Create an RTC object. See init for parameters of initialization.

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.

The 8-tuple has the following format:

   (year, month, day, weekday, hours, minutes, seconds, subseconds)

The meaning of the subseconds field is hardware dependent.

.. method:: RTC.init(datetime)

Initialise the RTC. Datetime is a tuple of the form:

  ``(year, month, day, hour, minute, second, microsecond, tzinfo)``

All eight arguments must be present. The microsecond and tzinfo values are currently ignored but might be used in the future.

Availability: CC3200, ESP32, MIMXRT, SAMD. The rtc.init() method on the stm32 and renesas-ra ports just (re-)starts the RTC and does not accept arguments.

.. method:: RTC.now()

Get get the current datetime tuple.

Availability: WiPy.

.. method:: RTC.deinit()

Resets the RTC to the time of January 1, 2015 and starts running it again.

.. method:: RTC.alarm(id, time, *, repeat=False)

Set the RTC alarm. Time might be either a millisecond value to program the alarm to current time + time_in_ms in the future, or a datetimetuple. If the time passed is in milliseconds, repeat can be set to True to make the alarm periodic.

.. method:: RTC.alarm_left(alarm_id=0)

Get the number of milliseconds left before the alarm expires.

.. method:: RTC.alarm_cancel(alarm_id=0)

Cancel a running alarm.

The mimxrt port also exposes this function as RTC.cancel(alarm_id=0), but this is scheduled to be removed in MicroPython 2.0.

.. method:: RTC.irq(*, trigger, handler=None, wake=machine.IDLE)

Create an irq object triggered by a real time clock alarm.

  - ``trigger`` must be ``RTC.ALARM0``
  - ``handler`` is the function to be called when the callback is triggered.
  - ``wake`` specifies the sleep mode from where this interrupt can wake
    up the system.

.. method:: RTC.memory([data])

RTC.memory(data) will write data to the RTC memory, where data is any object which supports the buffer protocol (including bytes, bytearray, memoryview and array.array). RTC.memory() reads RTC memory and returns a bytes object.

Data written to RTC user memory is persistent across restarts, including :ref:soft_reset and machine.deepsleep().

The maximum length of RTC user memory is 2048 bytes by default on esp32, and 492 bytes on esp8266.

Availability: esp32, esp8266 ports.

Constants

.. data:: RTC.ALARM0

irq trigger source