Qwiic Real Time Clock Module (RV-1805) Hookup Guide

Contributors: Englandsaurus

Library Overview

Before we get into programming our RTC, let's download and check out the available functions in our library. SparkFun has written a library to control the Qwiic RTC. You can obtain these libraries through the Arduino Library Manager. Search for SparkFun Qwiic RTC RV1805 Arduino Library to install the latest version. If you prefer downloading the libraries from the GitHub repository and manually installing it, you can grab them here:

Let's get started by looking at the functions that set up the RTC.

Setup and Settings

• boolean begin( TwoWire &wirePort = Wire ); --- The begin function initalizes the RTC, enabling the trickle charging circuit along with low power mode. Also sets the RTC to a 12-hour time format.
• void reset(void); --- Performs a full software reset on the RTC.
• bool setToCompilerTime(); --- Set's the RTC to the time on the compiler.
• bool setTime(uint8_t hund, uint8_t sec, uint8_t min, uint8_t hour, uint8_t date, uint8_t month, uint8_t year, uint8_t day); --- Set's the time registers of the RTC to a chosen time using individual variables.
• bool setTime(uint8_t * time, uint8_t len) --- Set's the time registers of the RTC to a chosen time using an array of times in the following order {Hundredths, Seconds, Minutes, Hours, Date, Month, Year, Day}. Please note uint8_t len must be 7, the length of the time array, for this function to set the time properly.
• bool setHundredths(uint8_t value); --- Sets the hundredths register to value.
• bool setSeconds(uint8_t value); --- Sets the seconds register to value.
• bool setMinutes(uint8_t value); --- Sets the minutes register to value.
• bool setHours(uint8_t value); --- Sets the hours register to value.
• bool setWeekday(uint8_t value); --- Sets the weekday register to value.
• bool setDate(uint8_t value); --- Sets the date register to value.
• bool setMonth(uint8_t value); --- Sets the month register to value.
• bool setYear(uint8_t value); --- Sets the year register to value.
• void set12Hour(); --- Sets the RTC to 12 hour mode.
• void set24Hour(); --- Sets the RTC to 24 hour mode.
• void enableTrickleCharge(uint8_t diode = DIODE_0_3V, uint8_t rOut = ROUT_3K); --- Connects an internal diode and resistor to enable the trickle charging circuit to charge the supercapacitor. The default values are the fastest for charging the capacitor, although other globally scoped variables (listed below) can be passed to change the value of the diode and resistor using in the charging circuit.
  • DIODE_0_3V --- 0.3V Diode
  • DIODE_0_6V --- 0.6V Diode
  • DIODE_DISABLE --- Disconnects diode, disables trickle charging circuit
  • ROUT_3K --- 3 kΩ Resistor
  • ROUT_6K --- 6 kΩ Resistor
  • ROUT_11K --- 11 kΩ Resistor
  • ROUT_DISABLE --- Disconnects resistor, disables the trickle charging circuit.
• void disableTrickleCharge(); --- Disables the trickle charging circuit.
• void enableLowPower(); --- Enables switching to the low power RC oscillator when the RTC is powered by the supercapacitor or battery.

Interrupt Functionality

• void enableInterrupt(uint8_t source); --- Enables a given interrupt based on the value of source, which can be any of the following.
  • INTERRUPT_EIE --- External Interrupt
  • INTERRUPT_AIE --- Alarm Interrupt
  • INTERRUPT_TIE --- Timer Interrupt
  • INTERRUPT_BLIE --- Battery Interrupt
• void disableInterrupt(uint8_t source); --- Disables a given interrupt based on the value of source, see above for possible values of source.
• void clearInterrupts(); --- Clears all interrupt sources.
• void setCountdownTimer(uint8_t duration, uint8_t unit, bool repeat = true, bool pulse = true); --- Sets the countdown timer to trigger the interrupt if INTERRUPT_TIE is enabled.
  • uint8_t duration --- Sets the duration (be aware that this is just a BCD, and the time it takes to increment one LSB is decided by unit).
  • uint8_t unit --- Sets the time resolution of each LSB.
    • 0b00: 1/4096 s
    • 0b01: 1/64 s
    • 0b10: 1 s
    • 0b11: 60 s
  • bool repeat --- If repeat is true, the countdown timer will reset when it reaches 0, otherwise, it will stop.
  • bool pulse --- The interrupt will normally be a pulse unless both pulse and repeat are false, in which case the interrupt will be a level until the interrupt flag is cleared manually.
• enableSleep() --- Enables Sleep
• setPowerSwitchFunction(uint8_t function); --- Changes the behavior of the PSW pin.
  • 0b000: Inverse of the combined interrupt signal IRQ if at least one interrupt is enabled.
  • 0b001: Square wave if SQW = 1;
  • 0b010: Reserved.
  • 0b011: Inverse of alarm if alarm interrupt is set
  • 0b100: Timer if timer interrupt is set
  • 0b101: Inverse of timer if timer interrupt is set
  • 0b110: SLEEP Signal
  • 0b111: Static PSWB bit
• setPowerSwitchLock(bool lock) --- Sets the power switch lock, if the lock is enabled, the PSWB bit cannot be set to 1. This is typically used when using PSW as a power switch, as setting PSWB puts PSW in a high impedance state.
• setsStaticPowerSwitchOutput(bool psw); --- Enables the PSW bit to switch.
• bool setAlarm(uint8_t sec, uint8_t min, uint8_t hour, uint8_t date, uint8_t month); --- Sets the alarm to a chosen time using individual variables.
• bool setAlarm(uint8_t * time, uint8_t len); --- Sets the alarm to a chosen time using an array of times. uint8_t len must be 7, the length of the time array, for this function to set the alarm properly.
• enableAlarmInterrupt(); --- Attaches the interrupt pin to the alarm function.
• void setAlarmMode(uint8_t mode); --- mode must be between 0 and 7, alarm goes off with match of second, minute, hour, etc depending on the value of mode.
  • 0: Disabled
  • 1: Hundredths, seconds, minutes, hours, date and month match (once per year)
  • 2: Hundredths, seconds, minutes, hours and date match (once per month)
  • 3: Hundredths, seconds, minutes, hours and weekday match (once per week)
  • 4: Hundredths, seconds, minutes and hours match (once per day)
  • 5: Hundredths, seconds and minutes match (once per hour)
  • 6: Hundredths and seconds match (once per minute)
  • 7: Depends on the alarm value for hundredths.
    • 0-99: Hundredths match (once per second)
    • 240-249: Once per tenth (10 Hz)
    • 255: Once per hundredth (100 Hz)
• void enableBatteryInterrupt(uint8_t voltage, bool edgeTrigger); --- Enables the battery interrupt and sets the voltage at which the interrupt is triggered. The trigger voltages for different values of voltage and edgeTrigger are found in the table below.
  
  

• void setReferenceVoltage(uint8_t voltage, bool edgeTrigger); --- Can be used to set the reference voltage used for the battery interrupt. Use the values in the above table.
• bool checkBattery(uint8_t voltage, bool edgeTrigger); --- Checks if the battery level is above the threshold set by the values voltage and edgeTrigger.

Reading the RTC

• bool updateTime(); --- Updates the local time array with the RTC time registers.
• stringDateUSA(); --- Returns the date in MM-DD-YYYY format.
• stringDate(); --- Return date in DD-MM-YYYY format.
• stringTime(); --- Return time in HH:MM:SS with AM/PM if the RTC is in 12 hour mode.
• uint8_t getHundredths(); --- Returns the value of the hundredths register.
• uint8_t getSeconds(); --- Returns the value of the seconds register.
• uint8_t getMinutes(); --- Returns the value of the minutes register.
• uint8_t getHours(); --- Returns the value of the hours register.
• uint8_t getWeekday(); --- Returns the value of the weekday register.
• uint8_t getDate(); --- Returns the value of the date register.
• uint8_t getMonth(); --- Returns the value of the month register.
• uint8_t getYear(); --- Returns the value of the year register.
• bool is12Hour(); --- Returns true if 12hour bit is set.
• bool isPM(); --- Returns true if is12Hour() == true and PM bit is set.
• uint8_t status(); --- Returns the status byte.
• uint8_t BCDtoDEC(uint8_t val); --- Converts from BCD to decimal format.
• uint8_t DECtoBCD(uint8_t val); --- Converts from decimal to BCD format.
• uint8_t readRegister(uint8_t addr); --- Reads the register at addr.
• bool writeRegister(uint8_t addr, uint8_t val); --- Writes val to location addr.
• bool readMultipleRegisters(uint8_t addr, uint8_t * dest, uint8_t len); --- Reads len number of registers, incrementing up from the addr location, into the array dest.
• bool writeMultipleRegisters(uint8_t addr, uint8_t * values, uint8_t len); --- Writes len number of registers, incrementing up from the addr location, from the array values.