RV3028: MicroPython docs

Author: thirdr

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