Makerverse Real Time Clock with Supercapacitor Backup - Raspberry Pi Pico Guide

Introduction

This guide covers the basic use of the Makerverse Supercap Real Time clock on the Raspberry Pi Pico using our RV3028 MicroPython module. The MicroPython module implements some commonly used features of the RV3028 RTC but is not exhaustive. Full details of every RV3028 feature can be found in the RV3028 Application Manual.

Likewise, this guide only covers the commonly used features of the MicroPython module. A description of every function can be found in the GitHub repository.

To follow along it's best to have:

• The Makerverse Supercap Real Time Clock module
• A Raspberry Pi Pico
• Some pin headers
• Some jumper wires
• A small breadboard

We'll be programming a Raspberry Pi Pico using Thonny - if you've never used Thonny before, see our Getting Started Guide.

Contents

• Pinout
• Download MicroPython Modules
• Basic Example
• Time Formats, Setting Time, and Getting Time
• Example Project: A Simple Data Logger
• Event Interrupts and Timestamps
• Conclusion

Pinout

The pinout and pin description of the Makerverse Supercap RTC is as follows:

Pin	Description
Vcc	Power input, 3.3V-5V (Note 1)
SDA	I2C data
SCL	I2C Clock
INT	Interrupt output, low when an interrupt occurs
CLK	1Hz to 32768Hz clock output, user selectable
EVI	Event input - short to ground to trigger event interrupt
GND	Power input, ground

(Note 1) The RV3028 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.

Download MicroPython Module

For this guide you will only need a single driver file to start using the Makerverse Supercap RTC.

• Download the Makerverse RV3028 MicroPython Module: Makerverse_RV3028.py (right click, "Save Link As...")

Once downloaded, copy Makerverse_RV3028.py onto your Raspberry Pi Pico with Thonny.

Basic Example

The following example illustrates the basic use of the RV3028 module. The Makerverse_RV3028() constructor (class initialisation function) takes an I2C device as its only argument and returns an Makerverse_RV3028 class.

The Makerverse_RV3028.timestamp() function prints a date and time in the format  YYYY-MM-DD HH:MM:SS and is designed for data logging applications where a log containing human-readable times is desirable.

from machine import I2C, Pin
from Makerverse_RV3028 import Makerverse_RV3028

i2c = I2C(0, sda = Pin(0), scl = Pin(1))
rtc = Makerverse_RV3028(i2c = i2c)

print(rtc.timestamp())

During initialisation the following configuration is also performed:

• The battery switchover is set to use the backup ultracapacitor in the event of power failure
• The trickle charger is enabled and configured for the fastest charge rate (a 3k Ohm resistor, absolute peak of 1.7mA, typically less)

If needed, setTrickleCharger(False) will disable the trickle charger or configTrickleCharger(R='15k') can increase the series resistance to 15k (5k and 9k are also valid options).

Time Formats, Setting Time, and Getting Time

At time of writing the Python datetime module is not yet implemented in MicroPython. As such, two date & time data formats have been developed for this module:

1. Using lists:

   date = [day, month, year]
   
   time = [hours, minutes, seconds]
   # AM/PM indicator optional
   time = [hours, minutes, seconds, 'AM']

2. Using dictionaries:

   date = {}
   date['day'] = day
   date['month'] = month
   date['year'] = year
   
   time = {}
   time['hour'] = hours
   time['min'] = minutes
   time['sec'] = seconds
   # AM/PM indicator optional
   time['ampm'] = 'AM' # or 'PM'

The functions setTime(), getTime(), setDate(), getDate(), and getDateTime() can all work with both time formats.

When using lists the time values are identified by their list index. Because of this, different variables must be used to store the date and time. Dictionaries don't have this restriction so the full date and time can be stored in a single dictionary variable. The set*() functions will detect the argument variable's type and apply it as appropriate while the get*() functions take the timeFormat = keyword argument which can be set to the strings 'dict' or 'list' to control whether they return a dictionary or list, respectively.

To optional AM/PM element controls whether the RV3028 is configured for 12hr or 24hr time. If the AM/PM string exists in the input then 12hr time is configured and the hours field assumed to be in 12hr format. If the string is not present then 24hr format is assumed and the RV3028 is configured to operate in 24hr time.

For demonstration purposes the following example shows both list and dictionary formats with list format commented out.

from machine import I2C, Pin
from Makerverse_RV3028 import Makerverse_RV3028

i2c = I2C(0, sda = Pin(0), scl = Pin(1))
rtc = Makerverse_RV3028(i2c = i2c)

# Setting the time with list format
# time = [10, 12, 3, 'AM'] # 10:12:03 AM, [HH:MM:SS 'AM/PM']
# date = [10, 11, 21] # 10th November, 2021, [DD MM YY]

# Setting the time with dictionary format
date = {}
date['day'] = 6
date['month'] = 12
# Year can be "20xx" or "xx"
date['year'] = 2021

time = {}
time['hour'] = 1
time['min'] = 20
time['sec'] = 0
# AM/PM indicator optional
# If omitted, time is assumed to be in 24-hr format
time['ampm'] = 'PM' # or 'PM'

rtc.setTime(time)
rtc.setDate(date)

print(rtc.timestamp())

Example Project: A Simple Data Logger

The following example uses the Makerverse Supercap RTC in a simple data logging project. For battery operated, long term, data logging project you can consider using a Makerverse Nano Power Timer to maximise battery life and a Makerverse Micro SD Module for bulk data storage and easy transfer to a PC.

The RTC is used to measure the delay between data samples so that long term timing accuracy is maximised. The compromise with this approach is that timing resolution is limited to 1 second intervals. Note that the RTC's Unix time is used for measuring time intervals. On the RV3028 unix time is simply an integer number of seconds since the last reset so it removes the need for a complicated algorithm which calculates a time difference in days / hours / minutes / seconds format.

If sub-second accuracy is required the RV3028's CLK pin can be configured as appropriate with rtc.configClockOutput() and counted by either polling the pin or utilising a GPIO interrupt callback.

from machine import I2C, Pin, ADC
import time
from Makerverse_RV3028 import Makerverse_RV3028

# Interval, in seconds, between data samples
logInterval = 1

i2c = I2C(0, sda = Pin(0), scl = Pin(1))
rtc = Makerverse_RV3028(i2c = i2c)

# ADC on Pin GP26
adc = ADC(0)

while True:
    x = adc.read_u16()
    print(rtc.timestamp(), x)
    # Opening with "a" for appending
    with open("datalog.csv", "a") as f:
        f.write(rtc.timestamp())
        f.write(',') # Comma separator
        f.write(str(x))
        f.write('\n') # New line
        f.flush() # Ensure data is written
        f.close() # Really ensure data is written
        
        # Wait for "logInterval" seconds
        timeNow = rtc.getUnixTime()
        while rtc.getUnixTime() - timeNow < logInterval:
            time.sleep_ms(100)
            continue

Event Interrupts and Timestamps

The RV3028 has the ability to record the time at which an "event" occurs. For this module an "event" is a configurable falling or rising edge on the EVI pin. Upon the configured edge appearing on the EVI pin the current time and date is copied to the "timestamp" registers and stored there so it can be read at a later time.

The general algorithm for recording and reading event timestamps is:

1. Run resetEventInterrupt() to clear the current timestamp and configure the interrupt
2. Either poll the interrupt using the getEventInterrupt() function or observing the state of the INT pin. When an event is detected the getEventInterrupt() function will return True and the INT pin will go low.
3. Read the event timestamp registers by passing the eventTimestamp = True keyword argument to getTime(), getDate(), or getDateTime()

The event timestamp will remain in the timestamp registers until reset by another call to resetEventInterrupt().

Note that the Makerverse Supercap Real Time Clock module has a pull-up resistor on the EVI pin. If the event is generated by, say, a switch then it will need to be a normally open switch which connects to ground when closed. If logic high event detection is required an external circuit will need to drive the EVI pin low until the event occurs.

The code example below demonstrates the basic use of the event interrupt by polling the interrupt flag with getEventInterrupt().

from machine import I2C, Pin
from Makerverse_RV3028 import Makerverse_RV3028
import time

i2c = I2C(0, sda = Pin(0), scl = Pin(1))
rtc = Makerverse_RV3028(i2c = i2c)

rtc.clearAllInterrupts()
rtc.resetEventInterrupt()

while rtc.getEventInterrupt() is False:
    time.sleep_ms(100)
    continue

print(rtc.getDateTime(timeFormat = 'dict', eventTimestamp = True))

Conclusion

You're now ready to add accurate time keeping to your Raspberry Pi Pico projects!

If you make something cool from this starter guide we'd love for you to share it on our forums! And if you'd like some help with this guide, start the conversation below - We're full-time makers and here to help!