Home

Public API

The BBRTC class exposes the methods detailed below.

This is the entire class definition for BBRTC:

class BBRTC {
    BBRTC() {}
    ~BBRTC() {};
    int getType();
    int getStatus();
    int getTemp();
    int init(int iSDA=-1, int iSCL=-1, bool bWire = true);
    void setFreq(int iFreq);
    void setAlarm(uint8_t type, struct tm *thetime);
    void setTime(struct tm *pTime);
    void getTime(struct tm *pTime);
    void setCountdownAlarm(int iSeconds);
    void clearAlarms();
    uint32_t getEpoch();
    void setEpoch(uint32_t tt);

private:
    int _iRTCType;
    int _iRTCAddr;
    BBI2C _bb;
};

init()
There are three optional parameters for the init method - the first two define the GPIO pins used for the I2C signals SDA & SCL and the third specifies whether to use hardware I2C (true) or bit bang I2C (false). For Arduino targets with default I2C pins, the init method can be called with no parameters. For MCUs with flexible I/O pins such as the ESP32 family, you can specify almost any GPIO pins to use. The init method will probe the I2C bus to see if the address of the supported devices responds and then initialize it. If a supported device is found and initialized successfully, init() will return RTC_SUCCESS otherwise RTC_FAILURE. The RTC type can then by queried with the getType() method.

getType()
Returns the enumerated RTC chip type detected (or RTC_UNKNOWN if it fails).

getStatus()
Returns the current power and IRQ status as a bit field with bits set for each option. The following bits are defined:
#define STATUS_RUNNING 1
#define STATUS_IRQ1_TRIGGERED 2
#define STATUS_IRQ2_TRIGGERED 4

getTemp()
Returns the current temperature value (if this capability exists) as an integer fraction (Celcius * 4). For example, the value 25.5C would be returned as 102.

setFreq(uint32_t iFreq)
For RTCs with a clock output pin, this method allows you to enable/disable the output and set its frequency. Only specific frequencies are available for each RTC. Here are the available frequencies for the 2 RTCs which support this feather:
DS3231 - 8192Hz, 4096Hz, 1024Hz, 1Hz
RV3032 - (low speed) 32768Hz, 1024Hz, 64Hz, 1Hz, (high speed) 8192Khz to 67.1Mhz in 8192Khz increments
PCF8563 - 32768Hz, 1024Hz, 32Hz, 1Hz
Passing a frequency of -1 disables the clock output.

setAlarm(uint8_t u8AlarmType, struct tm *time)
Sets an alarm (output on the INT pin as a low signal) for the given time. The alarm type can be one of:
ALARM_SECOND = Once every second
ALARM_MINUTE = Once every minute
ALARM_HOUR = for a specific hour
ALARM_TIME = When a specific hour:second match
ALARM_DAY = When a specific day of the week and time match
ALARM_DATE = When a specific day of the month and time match
Not all alarm types are supported on all devices. For example, the DS3231 allows setting an alarm for a specific date+hh:mm:ss, but the RV3032 does not allow setting an alarm time down to the second.

setTime(struct tm *)
Sets the current time and date to the values passed in the tm structure pointer.

getTime(struct tm *)
Retrieves the current time and date and writes them into the passed tm structure pointer.

setCountdownAlarm(int iSeconds)
Sets an alarm based on an integer number of seconds from the current time. This feature is native to the RV3032, but doesn't exist on the DS3231 nor on the PCF8563, so on those devices, a fixed date/time offset alarm is set instead.

clearAlarms()
Clear all pending alarms and disable the interrupt (if set). This may be needed after an alarm is triggered in order to allow a new interrupt to occur

getEpoch()
Return the current time and date as a 32-bit value of seconds from Epoch (Jan 1, 1970). This feature is native to the RV3032, but simulated on the other supported RTC chips.

setEpoch(uint32_t tt)
Set the current time and date from a 32-bit epoch time (seconds since Jan 1, 1970). This feature is native to the RV3032, but simulated on the other supported RTC chips.