The Pyboard's Real-Time Clock

Contents

What is an RTC?

A Real-Time Clock (RTC) is an electronic component, usually an integrated circuit, that keeps track of accurate time (hours, minutes, seconds) and date (year, month, day) for a device. While the main power is off the RTC can failover to a tiny backup battery if installed. In this case the time and date will continue to be accurately updated.

The Pyboard's STM32F405RGT6 microcontroller has an internal RTC that is available to the board's users. The Pyboard V1 board has an external 32.768 kHz quartz crystal oscillator that is used by the STM32F405RGT6 to generate one second timing pulses that updates time on the RTC.

The RTC on the Pyboard can be power backed up with a 3V coin cell battery connected across the VBACK pin and a GND pin. This keeps the RTC operating when the main power to the board is disconnected.

The Thonny MicroPython IDE on connection to the Pyboard sets the current date/time on the board's RTC . The date/time is sourced from the computer's system clock. This is a very handy Thonny feature.

MicroPython pyb.RTC Class

The pyb.RTC class provides the user access to the RTC. The date/time can be set and read. Alarm events can be set such that when they trigger they will wake up the microcontroller from sleep states and optionally run callback functions.

An alternate is the machine.RTC class. This is a generic class available to most microcontrollers with a MicroPython port. It won't be discussed further here but has similar functionality to the pyb.RTC class. Details can be found in the official MicroPython documentation.

The following constructor and methods will now be examined:

  • pyb.RTC() : Class constructor.
  • RTC.datetime() : Set/get the date and time.
  • RTC.wakeup()

Syntax:
<rtc_variable> = pyb.RTC(),

Creates an RTC object.

Example:
from pyb import RTC
rtc = RTC()
          

Syntax:
RTC.datetime([datetimetuple])

Where:
  datetimetiple : This is an 8-element tuple that's
                  used to pass a date and time between
                  the microcontroller and the RTC.
                  Uses 24hr clock.

                  The 8-tuple has the following format:
                  (year, month, day, weekday, hours,
                   minutes, seconds, subseconds)

                  With no argument passed, this method
                  returns the 8-element tuple with the
                  current date and time. If a tuple is
                  passed as an argument it is used to
                  update the current date and time.

  year    : 4-digit year
  month   : 1 - 12
  day     : 1 - 31
  weekday : 0 - 6 for Monday to Sunday.
  hours   : 0 - 23
  minutes : 0 - 59
  seconds : 0 - 59
  subseconds : counts down from 255 to 0

Example:
from pyb import RTC
rtc = RTC()

# Set RTC date/time to: 2025/Dec/24 12:42
DateTimeTuple = (2025, 12, 24, 0, 12, 42, 0, 0)
rtc.datetime(DateTimeTuple)

# Get date and time from the RTC.
dt = rtc.datetime()
# Date:
y, m, d = dt[0], dt[1], dt[2]
print('DATE - Year:', y, '  Month:', m, '  Day:', d)
# Time:
h, m, s = dt[4], dt[5], dt[6]
print('TIME - Hour:', h, '  Minutes:', m, '  Seconds:', s)

Output:
DATE - Year: 2025   Month: 12   Day: 24
TIME - Hour: 12   Minutes: 42   Seconds: 0

NOTE: When a date and time tuple is passed to the datetime() method, the RTC does not check that the values are within the correct range. For example the following call will not raise an exception:

  • dtt = (2025, 15, 40, 0, 27, 65, 0, 0)
    rtc.datetime(dtt)
    print(rtc.datetime())

Bizarrely the Pyboard REPL will return:

  • (2025, 15, 0, 0, 27, 65, 0, 255)

Syntax:
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: pyb.stop() and pyb.standby().

If callback is given then it is executed at
every trigger of the wakeup timer.

A practical example of the RTC.wakeup() method can be found in the article MicroPython 'pyb' Library: Delays & Timing.

Extending the pyb.RTC Class

It's very easy to make the pyb.RTC class more 'user friendly' by extending it. The simple example below provides all the methods from the base class but adds date and time stamps which could be used with almost any data logging application.


Example:
# Extends the pyb.RTC class to include
# methods for formatted time, date and date|time stamps.

from pyb import RTC

MONTH = ('Jan', 'Feb', 'Mar', 'Apr',
         'May', 'Jun', 'Jul', 'Aug',
         'Sep', 'Oct', 'Nov', 'Dec')

# Class extends the pyb.RTC() class
class myRTC(RTC):
    
    # Return nicely formatted time.
    def Time(self):
        dt = self.datetime()
        minute = str(dt[5])
        if len(minute) == 1: minute = '0' + minute
        return str(dt[4]) + ':' + minute
  
    # Return nicely formatted date
    def Date(self):
        dt = self.datetime()
        day = str(dt[2])
        month =MONTH[dt[1] - 1]
        year = str(dt[0])
        return (day + '/' + month + '/' + year)

    # Return nicely formatted date & time   
    def DateTime(self):
        date = self.Date()
        time = self.Time()
        return date + ' ' + time
 
# Test the extended class.
rtc = myRTC()
print('DateTime tuple:', rtc.datetime())
print('Date:', rtc.Date())
print('Time:', rtc.Time())
print('Date|Time:', rtc.DateTime())   
          

Typical Output:
DateTime tuple: (2025, 12, 22, 0, 11, 50, 45, 36)
Date: 22/Dec/2025
Time: 11:50
Date|Time: 22/Dec/2025 11:50