diff --git a/libraries/breakout_rtc/README.md b/libraries/breakout_rtc/README.md new file mode 100644 index 00000000..2c3dc039 --- /dev/null +++ b/libraries/breakout_rtc/README.md @@ -0,0 +1,145 @@ +# RV3028 Breakout (C/C++) + +An ultra-low-power ( ~100 nA), highly accurate real-time clock breakout. The RV3028 RTC breakout is perfect for adding timekeeping to your project and, thanks to the tiny on-board battery, it'll keep time when your device is powered off. Like all the best timepieces, it's Swiss-made! + +Available here: https://shop.pimoroni.com/products/rv3028-real-time-clock-rtc-breakout + +# **Example Program** + +Example program shows how to setup the RV3028, set the date and time and output it once a second. + +``` +#include "pico/stdlib.h" +#include "breakout_rtc.hpp" + +using namespace pimoroni; + +I2C i2c(BOARD::BREAKOUT_GARDEN); +BreakoutRTC rtc(&i2c); + +int main() { + + stdio_init_all(); + + if(!rtc.init()) { + printf("Init failed! Check your connections and i2c pin choices.\n"); + } + + rtc.enable_periodic_update_interrupt(true); + + rtc.set_time(10, 10, 10, 7, 12, 9, 2024); + + while(true) { + if(rtc.read_periodic_update_interrupt_flag()) { + rtc.clear_periodic_update_interrupt_flag(); + + if(rtc.update_time()) { + printf("Date: %s, Time: %s\n", rtc.string_date(), rtc.string_time()); + + } + } + + sleep_ms(100); + +} + +return 0; + +} +``` + +# **Functions** + +## `bool init()` + +Initializes the RV3028. Returns `true` if successful or `false` if something went wrong. + +**Example** + +``` +I2C i2c(BOARD::BREAKOUT_GARDEN); +BreakoutRTC rtc(&i2c); + +rtc.init(); +``` + +## `bool setup()` + +Sets the RTC to 24 Hour Mode, disables the Trickle Charge and sets Level Switching Mode to 3. + +## `bool set_time(uint8_t sec, uint8_t min, uint8_t hour, uint8_t weekday, uint8_t date, uint8_t month, uint16_t year)` + +Set the time and date on the RTC. Returns `true` if successful and `false` if something went wrong. + +You can also set a time or date element individually with: + +`set_seconds(uint8_t value)`, `set_minutes(uint8_t value)`, `set_hours(uint8_t value)`, `set_weekday(uint8_t value)`, `set_date(uint8_t value)`, `set_month(uint8_t value)` and `set_year(uint8_t value)` + + +## `void set_24_hour()` + +Set the RTC to output 0-23 Hours. This function will convert any current hour to 2 Hour Mode. + +## `void set_12_hour()` + +Set the RTC to output 1-12 Hours. This function will convert any current hour to 12 Hour Mode. + +## `bool is_12_hour()` + +Returns `true` if the RV3028 has been configured for 12 Hour mode. + +## `bool is_pm()` + +Returns `true` if the RTC has the PM bit set and the 12 Hour bit set + +## `bool update_time()` + +This function moves the data from the RV3028 registers to an array. You need to call this function before printing the time and date. The function returns `true` if successful and `false` if something went wrong. + +## `char* string_time()` + +Returns a pointer to array of chars that represents the time in hh:mm:ss format. Adds AM/PM if in 12 hour mode. You will need to call `update_time()` to get the current time from the RTC before using this function. + +## `char* string_date()` + +Returns a pointer to array of chars that are the date in dd/mm/yyyy format. You will need to call `update_time()` to get the current date from the RTC before using this function. + +## `void enable_periodic_update_interrupt(bool every_second, bool enable_clock_output)` + +Enables the periodic update interrupt. + +## `void disable_periodic_update_interrupt()` + +Disables the periodic update interrupt. + +## `bool read_periodic_update_interrupt_flag()` + +Read the periodic update interrupt flag. Returns a boolean value. + +## `void clear_periodic_update_interrupt_flag()` + +Clear the periodic update interrupt flag. + +## `uint32_t get_unix()` + +Get the UNIX Time from the RTC + +## `bool set_unix(uint32_t value)` + +Set the UNIX Time on the RTC. Returns `true` if successful and `false` if something went wrong. + +**IMPORTANT:** The Real Time and the UNIX time are independent of each other. Setting the UNIX time will not update the Real Time (Hours, minutes, seconds etc) + +## `bool set_backup_switchover_mode(uint8_t val)` + +Set the backup switchover mode of the RTC. Accepts values 0-3. + +0 = Switchover disabled +1 = Direct Switching Mode +2 = Standby Mode +3 = Level Switching Mode + +Function returns `true` if successful and `false` if something went wrong. + + + diff --git a/micropython/modules/breakout_rtc/README.md b/micropython/modules/breakout_rtc/README.md new file mode 100644 index 00000000..f095e862 --- /dev/null +++ b/micropython/modules/breakout_rtc/README.md @@ -0,0 +1,204 @@ +# RV3028 Breakout (MicroPython) + +An ultra-low-power ( ~100 nA), highly accurate real-time clock breakout. The RV3028 RTC breakout is perfect for adding timekeeping to your project and, thanks to the tiny on-board battery, it'll keep time when your device is powered off. Like all the best timepieces, it's Swiss-made! + +Available here: https://shop.pimoroni.com/products/rv3028-real-time-clock-rtc-breakout + +# **Example Program** + +Example program shows how to setup the RV3028, set the date and time and output it once a second. + +``` +from pimoroni_i2c import PimoroniI2C +from breakout_rtc import BreakoutRTC + +PINS_BREAKOUT_GARDEN = {"sda": 4, "scl": 5} # i2c pins 4, 5 for Breakout Garden + +i2c = PimoroniI2C(**PINS_BREAKOUT_GARDEN) +rtc = BreakoutRTC(i2c) + +rtc.setup() +rtc.enable_periodic_update_interrupt(True) + +rtc.set_time(10, 10, 10, 5, 1, 1, 2001) + +while True: + + if (rtc.read_periodic_update_interrupt_flag()): + rtc.clear_periodic_update_interrupt_flag() + + rtc.update_time() + rtc_time = rtc.string_time() + print(rtc_time) + +``` + +# **Functions** + +## `.setup()` + +Sets the RTC to 24 Hour Mode, disables the Trickle Charge and sets Level Switching Mode to 3. + +## `.set_time(second, minute, hour, weekday, day, month, year)` + +Set the time and date on the RTC. Returns **True** if successful and **False** if something went wrong. + +**Example:** + +``` +>>> rtc.set_time(0, 52, 8, 4, 5, 6, 2024) +True +>>> rtc.update_time() +True +>>> print(rtc.string_time(), rtc.string_date()) +08:52:13 05/06/2024 +``` + +You can also set a time or date element individually with: + +`.set_seconds()`, `.set_minutes()`, `.set_hours()`, `.set_weekday()`, `.set_date()`, `.set_month()` and `.set_year()` + + +## `.set_24_hour()` + +Set the RTC to output 0-23 Hours. This function will convert any current hour to 2 Hour Mode. + +## `.set_12_hour()` + +Set the RTC to output 1-12 Hours. This function will convert any current hour to 12 Hour Mode. + +## `.is_12_hour()` + +Returns **True** if the RV3028 has been configured for 12 Hour mode. + +``` +>>> rtc.is_12_hour() +False +>>> rtc.set_12_hour() +>>> rtc.is_12_hour() +True +>>> +``` + +### `.is_pm()` + +Returns **True** if the RTC has the PM bit set and the 12 Hour bit set + +**Example:** +``` +>>> rtc.is_pm() +False +``` + +## `.update_time()` + +This function moves the data from the RV3028 registers to an array. You need to call this function before printing the time and date. The function returns **True** if successful and **False** if something went wrong. + +**Example**: + +``` +while True: + + rtc.update_time() + rtc_time = rtc.string_time() + print(rtc_time) + + time.sleep(1) +``` +**Output**: + +``` +10:10:25 +10:10:26 +10:10:27 +``` + +## `.string_time()` + +Returns the time as a formatted String. You will need to call `.update_time()` to get the current time from the RTC before using this function. + +**Example:** +``` +>>> rtc.string_time() +'05:05:05' +``` + +## `.string_date()` + +Returns the date as a formatted String. You will need to call `.update_time()` to get the current date from the RTC before using this function. + +**Example:** +``` +>>> rtc.string_date() +'05/05/2005' +``` + +## `.enable_periodic_update_interrupt(True)` + +Enables the periodic update interrupt. Triggers onces every second. + +## `.disable_periodic_update_interrupt()` + +Disables the periodic update interrupt. + +## `.read_periodic_update_interrupt_flag()` + +Read the periodic update interrupt flag. Returns a boolean value. + +**Example:** + +``` +>>> rtc.read_periodic_update_interrupt_flag() +True +``` + +## `.clear_periodic_update_interrupt_flag()` + +Clear the periodic update interrupt flag. + +**Example:** +``` +>>> rtc.clear_periodic_update_interrupt_flag() +>>> rtc.read_periodic_update_interrupt_flag() +False +``` + +## `.get_unix()` + +Get the UNIX Time from the RTC + +**IMPORTANT:** The Real Time and the UNIX time are independent of each other. Retrieving the UNIX Time will not give you the Real Time stored by the RTC. + +**Example:** +``` +>>> rtc.get_unix() +3084 +``` + +## `.set_unix()` + +Set the UNIX Time on the RTC. Returns **True** if successful and **False** if something went wrong. + +**IMPORTANT:** The Real Time and the UNIX time are independent of each other. Setting the UNIX time will not update the Real Time (Hours, minutes, seconds etc) + +**Example:** +``` +>>> rtc.set_unix(1717508760) +True +>>> rtc.get_unix() +1717508765 +``` + +## `.set_backup_switchover_mode(int value)` + +Set the backup switchover mode of the RTC. Accepts values 0-3. + +0 = Switchover disabled +1 = Direct Switching Mode +2 = Standby Mode +3 = Level Switching Mode + +Function returns **True** if successful and **False** if something went wrong. + + +