pimoroni-pico/micropython/modules/breakout_rtc

RV3028 Breakout (MicroPython)

An ultra-low-power ( ~100 nA), highly accurate real-time clock breakout. The RV3028 RTC breakout is perfect for adding timekeeping to your project and, thanks to the tiny on-board battery, it'll keep time when your device is powered off. Like all the best timepieces, it's Swiss-made!

Available here: https://shop.pimoroni.com/products/rv3028-real-time-clock-rtc-breakout

Example Program

Example program shows how to setup the RV3028, set the date and time and output it once a second.

from pimoroni_i2c import PimoroniI2C
from breakout_rtc import BreakoutRTC

PINS_BREAKOUT_GARDEN = {"sda": 4, "scl": 5}  # i2c pins 4, 5 for Breakout Garden

i2c = PimoroniI2C(**PINS_BREAKOUT_GARDEN)
rtc = BreakoutRTC(i2c)

rtc.setup()
rtc.enable_periodic_update_interrupt(True)

rtc.set_time(10, 10, 10, 5, 1, 1, 2001)

while True:
    
    if (rtc.read_periodic_update_interrupt_flag()):
        rtc.clear_periodic_update_interrupt_flag()
        
        rtc.update_time()
        rtc_time = rtc.string_time()
        print(rtc_time)

Functions

.setup()

Sets the RTC to 24 Hour Mode, disables the Trickle Charge and sets Level Switching Mode to 3.

.set_time(second, minute, hour, weekday, day, month, year)

Set the time and date on the RTC. Returns True if successful and False if something went wrong.

Example:

>>> rtc.set_time(0, 52, 8, 4, 5, 6, 2024)
True
>>> rtc.update_time()
True
>>> print(rtc.string_time(), rtc.string_date())
08:52:13 05/06/2024

You can also set a time or date element individually with:

.set_seconds(), .set_minutes(), .set_hours(), .set_weekday(), .set_date(), .set_month() and .set_year()

.set_24_hour()

Set the RTC to output 0-23 Hours. This function will convert any current hour to 2 Hour Mode.

.set_12_hour()

Set the RTC to output 1-12 Hours. This function will convert any current hour to 12 Hour Mode.

.is_12_hour()

Returns True if the RV3028 has been configured for 12 Hour mode.

>>> rtc.is_12_hour()
False
>>> rtc.set_12_hour()
>>> rtc.is_12_hour()
True
>>> 

.is_pm()

Returns True if the RTC has the PM bit set and the 12 Hour bit set

Example:

>>> rtc.is_pm()
False

.update_time()

This function moves the data from the RV3028 registers to an array. You need to call this function before printing the time and date. The function returns True if successful and False if something went wrong.

Example:

while True:
    
    rtc.update_time()
    rtc_time = rtc.string_time()
    print(rtc_time)

    time.sleep(1)

Output:

10:10:25
10:10:26
10:10:27

.string_time()

Returns the time as a formatted String. You will need to call .update_time() to get the current time from the RTC before using this function.

Example:

>>> rtc.string_time()
'05:05:05'

.string_date()

Returns the date as a formatted String. You will need to call .update_time() to get the current date from the RTC before using this function.

Example:

>>> rtc.string_date()
'05/05/2005'

.enable_periodic_update_interrupt(True)

Enables the periodic update interrupt. Triggers onces every second.

.disable_periodic_update_interrupt()

Disables the periodic update interrupt.

.read_periodic_update_interrupt_flag()

Read the periodic update interrupt flag. Returns a boolean value.

Example:

>>> rtc.read_periodic_update_interrupt_flag()
True

.clear_periodic_update_interrupt_flag()

Clear the periodic update interrupt flag.

Example:

>>> rtc.clear_periodic_update_interrupt_flag()
>>> rtc.read_periodic_update_interrupt_flag()
False

.get_unix()

Get the UNIX Time from the RTC

IMPORTANT: The Real Time and the UNIX time are independent of each other. Retrieving the UNIX Time will not give you the Real Time stored by the RTC.

Example:

>>> rtc.get_unix()
3084

.set_unix()

Set the UNIX Time on the RTC. Returns True if successful and False if something went wrong.

IMPORTANT: The Real Time and the UNIX time are independent of each other. Setting the UNIX time will not update the Real Time (Hours, minutes, seconds etc)

Example:

>>> rtc.set_unix(1717508760)
True
>>> rtc.get_unix()
1717508765

.set_backup_switchover_mode(int value)

Set the backup switchover mode of the RTC. Accepts values 0-3.

0 = Switchover disabled 1 = Direct Switching Mode 2 = Standby Mode 3 = Level Switching Mode

Function returns True if successful and False if something went wrong.