Shopping Cart 0 items
log in register
Today's Deals Forum Desktop Site
All Categories
Featured
Brands
Development
Sensors
Tools
Miscellaneous
Components
E-Textiles
Robotics
Wireless & IoT
Audio
  • Home
  • Tutorials
  • Real Time Clock Module - RV-8803 (Qwiic) Hookup Guide

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

≡ Pages
Contributors: El Duderino, Englandsaurus
Favorited Favorite 2

RV-8803 Arduino Library

Note: This tutorial assumes you are familiar with Arduino products and you are using the latest stable version of the Arduino IDE on your desktop. If this is your first time using the Arduino IDE, please review our tutorial on installing the Arduino IDE. If you have not previously installed an Arduino library, please check out our installation guide.

The easiest way to install the library is to search for SparkFun RV-8803 in the Arduino Library Manager tool. You can also manually install the RV-8803 Library from the GitHub Repository or you can download it by clicking the button below.

Download the SparkFun RV-8803 Library (ZIP)

Library Functions

The list below outlines all of the functions of the library with some quick descriptions of what they do. The examples cover most of the functions so we recommend going through those first.

Device Setup & Settings

  • bool begin(TwoWire &wireport); - Initializes the RV-8803 on the I2C bus.
  • void set12Hour(); - Configures the microcontroller to convert to 12 hour mode.
  • void set24Hour(); - Configures the microcontroller to not convert from the default 24 hour mode.
  • bool is12Hour(); - Returns true if the microcontroller is configured to 12 hour mode.
  • bool isPM(); - Returns true if the microcontroller is in 12 hour mode and the RTC has an hours value greater than or equal to 12 (Noon).
  • char* stringDateUSA(); - Returns the date in MM/DD/YYYY format.
  • char* stringDate(); - Returns the date in the DD/MM/YYYY format.
  • char* stringTime(); - Returns the time in hh:mm:ss (Adds AM/PM if in 12 hour mode).
  • char* stringTimeStamp(); - Returns the most recent timestamp captured on the EVI pin (if the EVI pin has been configured to capture events). The format is hh:mm:ss:HHXM with \0 terminator where 'X' is 'A' or 'P' depending on the time of day.
  • char* stringTime8601(); - Returns timestamp in ISO 8601 format (yyyy-mm-ddThh:mm:ss).
  • bool setTime(uint8_t sec, uint8_t min, uint8_t hour, uint8_t date, uint8_t month, uint8_t year, uint8_t day); - Sets the RTC's time registers using a set of individual variables.
  • bool setTime(uint8_t * time, uint8_t len); - Sets the RTC's time registers using an array with the following structure; {HUNDREDTHS, SECONDS, MINUTES, HOURS, WEEKDAY, DATE, MONTH, YEAR}
  • bool setHundredthsToZero(); - The hundredths register is read only so instead of writing to it, this function uses the Reset Bit Function on the RV8803 to set this register to zero. Check out section 4.13 of the RV-8803 Application Manual for more information about this function.
  • 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 setDate(uint8_t value); - Sets the date register to value.
  • bool setMonth(uint8_t value); - Sets the month register to value.
  • bool setYear(uint16_t value); - Sets the year register to value.
  • bool setWeekday(uint8_t value); - Sets the weekday register to value.
  • bool setToCompilerTime(); - Sets the RTC to the time from the last build and uses it as current time.
  • bool setCalibrationOffset(float ppm); - Loads the calibrated PPM offset to the RV8803_OFFSET register.
  • float getCalibrationOffset(); - Returns the calibration offset value stored in the RV8803_OFFSET register.

Reading from the RTC

  • bool updateTime(); - Move the time registers (hours, mins, secs, etc.) from the RV-8803 into the _time array that lives on the microcontroller. Needs to be called before printing time or date.
  • uint8_t getHundredths(); - Returns _time value from the hundredths register.
  • uint8_t getSeconds(); - Returns _time value from the seconds register.
  • uint8_t getMinutes(); - Returns _time value from the minutes register.
  • uint8_t getHours(); - Returns the _time value from the hours register.
  • uint8_t getDate(); - Returns the _time value from the date register.
  • uint8_t getWeekday(); - Returns the _time value from the weekday register.
  • uint8_t getMonth(); - Returns the _time value from the month register.
  • uint16_t getYear(); - Returns the _time value from the year register.
  • uint8_t getHundredthsCapture(); - Returns the captured value from the hundredths register (Time Stamp).
  • uint8_t getSecondsCapture(); - Returns the captured value from the seconds register (Time Stamp).

Alarm & Interrupt Functionality

Since the RV-8803 has three types of alarms/interrupts, this list is quite extensive so we've split it up into the individual alarm and interrupt functionalities.

External Event Interrupt
  • bool setEVICalibration(bool eviCalibration); - Enables or disables the the External Event Interrupt (EVI) button and pin.
  • bool setEVIDebounceTime(uint8_t debounceTime); - Sets the debounce time for the EVI pin and button. Can be set to None, 256 Hz, 64 Hz or 8 Hz.
  • bool setEVIEdgeDetection(bool edge); - Sets the EVI to fire on either the rising or falling edge of the signal.
  • bool setEVIEventCapture(bool capture); - Enables or disables the EVI Event Capture function.
  • uint8_t getEVIDebounceTime(); - Returns the value set for the EVI Debounce time.
  • bool getEVICalibration(); - Returns whether or not the EVI functionality is enabled or disabled.
  • bool getEVIEdgeDetection(); - Returns whether the EVI function is set to rising or falling edge.
  • bool getEVIEventCapture(); - Returns whether or not the EVI Event Capture function is enabled or disabled.
Countdown Interrupt
  • bool setCountdownTimerEnable(bool timerState); - Enables or disables the Periodic Countdown Timer interrupt function.
  • bool setCountdownTimerFrequency(uint8_t countdownTimerFrequency); - Sets the time for the Periodic Countdown Timer. Built in values are 4096 Hz, 60 Hz, 1 Hz and 1/60 Hz.
  • bool setCountdownTimerClockTicks(uint16_t clockTicks); - Sets the number of clock ticks to count for the Countdown Timer. Refer to the Example 4B - Countdown Interrupt overview in the next section of this guide for more information on calculating the number of clock ticks for your timer.
  • bool getCountdownTimerEnable(); - Returns whether or not the Countdown Timer is enabled or disabled.
  • uint8_t getCountdownTimerFrequency(); - Returns the frequency set for the Countdown Timer.
  • uint16_t getCountdownTimerClockTicks(); - Returns the number of clock ticks set for the Countdown Timer.
Periodic Interrupt
  • bool setPeriodicTimeUpdateFrequency(bool timeUpdateFrequency); - Sets the frequency of the Periodic Time Update interrupt function. Can be 1 Hz (one second) or 1/60 Hz (one minute).
  • bool getPeriodicTimeUpdateFrequency(); - Returns the time set for the Periodic Time Update interrupt frequency.
Alarm Interrupt
  • void setItemsToMatchForAlarm(bool minuteAlarm, bool hourAlarm, bool dateAlarm, bool weekdayOrDate); - Function to select which time values need to match to trigger an alarm. Can be set to minutes, hours, date or weekday+date. Setting the bit to 1 means the RTC will not look to match that item for an alarm.
  • bool setAlarmMinute(uint8_t minute); - Set the minute value for the RTC to match to trigger an alarm.
  • bool setAlarmHour(uint8_t hour); - Set the hour value for the RTC to match to trigger an alarm.
  • bool setAlarmWeekday(uint8_t weekday); - Set the weekday value for the RTC to match to trigger an alarm.
  • bool setAlarmDate(uint8_t date); - Set the date value for the RTC to match to trigger an alarm.
  • uint8_t getAlarmMinute(); - Returns the minute value set for the RTC to match for an alarm.
  • uint8_t getAlarmHour(); - Returns the hour value set for the RTC to match for an alarm.
  • uint8_t getAlarmWeekday(); - Returns the weekday value set for the RTC to match for an alarm.
  • uint8_t getAlarmDate(); - Returns the date value set for the RTC to match for an alarm.

Configuring the Clock Out (CLKOUT) pin

These two functions are for enabling and configuring the Clock Out pin. Use these with the setCalibrationOffset(); and getCalibrationOffset(); functions to fine tune your RTC. Refer to Example 6 - Fine Tuning in the next section of this guide for more information.

  • bool setClockOutTimerFrequency(uint8_t clockOutTimerFrequency); - Sets the frequency of the square wave output from the Clock Out pin. Available frequencies are 1Hz, 1024Hz and 32,768 Hz.
  • uint8_t getClockOutTimerFrequency(); - Returns the frequency set for the Clock Out.

Extra Functions

  • uint8_t BCDtoDEC(uint8_t val); - Convert values in the RTC from Binary Coded Decimal to Decimal.
  • uint8_t DECtoBCD(uint8_t val); - Convert values in the RTC from Decimal to Binary Coded Decimal.
  • bool readBit(uint8_t regAddr, uint8_t bitAddr); - Read a single bit from the selected register.
  • uint8_t readTwoBits(uint8_t regAddr, uint8_t bitAddr); - Read two bits from the selected register.
  • bool writeBit(uint8_t regAddr, uint8_t bitAddr, bool bitToWrite); - Write a selected bit to a register.
  • bool writeBit(uint8_t regAddr, uint8_t bitAddr, uint8_t bitToWrite); - Write a selected bit to a register.
  • uint8_t readRegister(uint8_t addr); - Read a specific register.
  • bool writeRegister(uint8_t addr, uint8_t val); - Write a specific register.
  • bool readMultipleRegisters( uint8_t addr, uint8_t * dest, uint8_t len); - Read multiple consecutive registers.
  • bool writeMultipleRegisters(uint8_t addr, uint8_t * values, uint8_t len); - Write multiple consecutive registers.

Next up we'll go over the examples included with the RV-8803 Arduino Library.

View as a single page Next Page →
Arduino Examples
← Previous Page
Hardware Assembly