PiicoDev Real Time Clock (RTC) RV-3028 - Getting Started Guide

This guide will help you get started with a PiicoDev Real Time Clock. We'll set and read the time/date, observe the power-backup capability, and configure the RTC with an alarm.

A Real-Time Clock (RTC) is a timekeeping device that accurately tracks the passage of time. Most RTCs feature a calendar and alarm so they may be used to schedule actions. The PiicoDev Real-Time Clock is based on a low-power and very accurate RV-3028, factory calibrated to within 30 seconds per year. Power to the RTC is backed-up by a supercapacitor, capable of running the clock for up to a week without external power. When power is connected, the supercap is recharged. From dead-flat, it takes about three minutes to charge the supercap enough to sustain shorter power outages. A full charge takes about an hour.

The following example shows how to set and read the time. The script initialises the RTC which enables charging the supercap. The date and time are set numerically, and the weekday is set with an integer between 0 and 6.

The setDateTime() method pushes the values we have set onto the RTC. Conversely, the getDateTime() method pulls the current date-time from the RTC and stores that data into the attributes (day, month, year, etc.). That means any time we want to get the current time, we must first call getDateTime().

We can query the name of the weekday by reading from the weekdayName property which contains a string ("Monday", "Tuesday" ... "Sunday"). weekdayName assumes that Monday is day zero. If you prefer, you can also set the weekday using weekdayName eg. rtc.weekdayName = "Monday"

timestamp() is a special method that first updates the current date-time, and then returns a string in the format YYYY-MM-DD HH:MM:SS. This is useful for printing timestamps to the shell or a log file.

# PiicoDev Real Time Clock RV-3028
# An example of how to set and read the date, time, and weekday

from PiicoDev_RV3028 import PiicoDev_RV3028
from PiicoDev_Unified import sleep_ms

rtc = PiicoDev_RV3028() # Initialise the RTC module, enable charging

# Set the time by assigning values to rtc's attributes
# Replace the following values with the current date/time
rtc.day = 6
rtc.month = 5
rtc.year = 2022
rtc.hour = 11
rtc.minute = 57
rtc.second = 00
rtc.ampm = '24' # 'AM','PM' or '24'. Defaults to 24-hr time
rtc.weekday = 4 # Rolls over at midnight, works independently of the calendar date
rtc.setDateTime() # Sets the time with the above values

# Get the current time
rtc.getDateTime()

# Print the current time, and today's name
# You can read from individual time attributes eg hour, minute, weekday.
print("The time is " + str(rtc.hour) + ":" + str(rtc.minute))
print("Today is " + str(rtc.weekdayName) + "\n") # weekdayName assumes counting from 0=Monday. 

while True:
    print(rtc.timestamp()) # timestamp() automatically updates time, and returns a pre-formatted string. Useful for printing and datalogging!
    sleep_ms(1000)

In the previous example, the PiicoDev RTC was automatically configured to charge the supercapacitor during initialisation. If your RTC has remained powered for a few minutes since running the example then the capacitor will have enough charge to withstand a power outage. Let's test it out!

• Stop the example script if you haven't already
• Disconnect the RTC for some time
• Reconnect the RTC

Now we'll check if the clock has kept accurate time during the power outage. Run the following code - which is a stripped-down version of the previous example that just reads the timestamp. All going well, you should see accurate timestamps printing in the shell!

Be careful not to accidentally set the time again during this process! There should be no need to call setDateTime(), since we already set the correct time in the previous example.

# A simple example to read the date, timestamp and weekday from the PiicoDev RTC
from PiicoDev_RV3028 import PiicoDev_RV3028
from PiicoDev_Unified import sleep_ms

rtc = PiicoDev_RV3028()

while True:
    print(rtc.timestamp()) 
    sleep_ms(1000)

• PiicoDev RV-3028 MicroPython Module Documentation
• RV-3028 Datasheet
• RV-3028 Application Manual

Pinout and Pin Descriptions

(Note 1) The RV-3028 RTC will operate down to Vcc of 1.2V however at this voltage the included supercapacitor will not hold sufficient charge to guarantee that time is kept through a power failure. Time is lost when the capacitor voltage drops below about 900 mV and it will typically only charge to Vcc-0.3V due to an internal Schottky diode. The RV-3028 works up to 5V, but this is only recommended for freestyle prototyping ie. not connected to any other PiicoDev hardware. PiicoDev is a 3.3V system.