RV3028: C/C++ Library docs

Author: thirdr

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.
+
+
+