Skip to content

Commit a8cc54e

Browse files
GadgetoidGadgetoid
authored
Merge pull request #955 from pimoroni/docs/rv3028
Documentation: RV3028
2 parents 9c79fbf + 5ab626e commit a8cc54e

File tree

2 files changed

+349
-0
lines changed

2 files changed

+349
-0
lines changed

‎libraries/breakout_rtc/README.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# RV3028 Breakout (C/C++)
2+
3+
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!
4+
5+
Available here: https://shop.pimoroni.com/products/rv3028-real-time-clock-rtc-breakout
6+
7+
# **Example Program**
8+
9+
Example program shows how to setup the RV3028, set the date and time and output it once a second.
10+
11+
```
12+
#include "pico/stdlib.h"
13+
#include "breakout_rtc.hpp"
14+
15+
using namespace pimoroni;
16+
17+
I2C i2c(BOARD::BREAKOUT_GARDEN);
18+
BreakoutRTC rtc(&i2c);
19+
20+
int main() {
21+
22+
stdio_init_all();
23+
24+
if(!rtc.init()) {
25+
printf("Init failed! Check your connections and i2c pin choices.\n");
26+
}
27+
28+
rtc.enable_periodic_update_interrupt(true);
29+
30+
rtc.set_time(10, 10, 10, 7, 12, 9, 2024);
31+
32+
while(true) {
33+
if(rtc.read_periodic_update_interrupt_flag()) {
34+
rtc.clear_periodic_update_interrupt_flag();
35+
36+
if(rtc.update_time()) {
37+
printf("Date: %s, Time: %s\n", rtc.string_date(), rtc.string_time());
38+
39+
}
40+
}
41+
42+
sleep_ms(100);
43+
44+
}
45+
46+
return 0;
47+
48+
}
49+
```
50+
51+
# **Functions**
52+
53+
## `bool init()`
54+
55+
Initializes the RV3028. Returns `true` if successful or `false` if something went wrong.
56+
57+
**Example**
58+
59+
```
60+
I2C i2c(BOARD::BREAKOUT_GARDEN);
61+
BreakoutRTC rtc(&i2c);
62+
63+
rtc.init();
64+
```
65+
66+
## `bool setup()`
67+
68+
Sets the RTC to 24 Hour Mode, disables the Trickle Charge and sets Level Switching Mode to 3.
69+
70+
## `bool set_time(uint8_t sec, uint8_t min, uint8_t hour, uint8_t weekday, uint8_t date, uint8_t month, uint16_t year)`
71+
72+
Set the time and date on the RTC. Returns `true` if successful and `false` if something went wrong.
73+
74+
You can also set a time or date element individually with:
75+
76+
`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)`
77+
78+
79+
## `void set_24_hour()`
80+
81+
Set the RTC to output 0-23 Hours. This function will convert any current hour to 2 Hour Mode.
82+
83+
## `void set_12_hour()`
84+
85+
Set the RTC to output 1-12 Hours. This function will convert any current hour to 12 Hour Mode.
86+
87+
## `bool is_12_hour()`
88+
89+
Returns `true` if the RV3028 has been configured for 12 Hour mode.
90+
91+
## `bool is_pm()`
92+
93+
Returns `true` if the RTC has the PM bit set and the 12 Hour bit set
94+
95+
## `bool update_time()`
96+
97+
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.
98+
99+
## `char* string_time()`
100+
101+
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.
102+
103+
## `char* string_date()`
104+
105+
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.
106+
107+
## `void enable_periodic_update_interrupt(bool every_second, bool enable_clock_output)`
108+
109+
Enables the periodic update interrupt.
110+
111+
## `void disable_periodic_update_interrupt()`
112+
113+
Disables the periodic update interrupt.
114+
115+
## `bool read_periodic_update_interrupt_flag()`
116+
117+
Read the periodic update interrupt flag. Returns a boolean value.
118+
119+
## `void clear_periodic_update_interrupt_flag()`
120+
121+
Clear the periodic update interrupt flag.
122+
123+
## `uint32_t get_unix()`
124+
125+
Get the UNIX Time from the RTC
126+
127+
## `bool set_unix(uint32_t value)`
128+
129+
Set the UNIX Time on the RTC. Returns `true` if successful and `false` if something went wrong.
130+
131+
**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)
132+
133+
## `bool set_backup_switchover_mode(uint8_t val)`
134+
135+
Set the backup switchover mode of the RTC. Accepts values 0-3.
136+
137+
0 = Switchover disabled
138+
1 = Direct Switching Mode
139+
2 = Standby Mode
140+
3 = Level Switching Mode
141+
142+
Function returns `true` if successful and `false` if something went wrong.
143+
144+
145+

‎micropython/modules/breakout_rtc/README.md‎

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
# RV3028 Breakout (MicroPython)
2+
3+
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!
4+
5+
Available here: https://shop.pimoroni.com/products/rv3028-real-time-clock-rtc-breakout
6+
7+
# **Example Program**
8+
9+
Example program shows how to setup the RV3028, set the date and time and output it once a second.
10+
11+
```
12+
from pimoroni_i2c import PimoroniI2C
13+
from breakout_rtc import BreakoutRTC
14+
15+
PINS_BREAKOUT_GARDEN = {"sda": 4, "scl": 5} # i2c pins 4, 5 for Breakout Garden
16+
17+
i2c = PimoroniI2C(**PINS_BREAKOUT_GARDEN)
18+
rtc = BreakoutRTC(i2c)
19+
20+
rtc.setup()
21+
rtc.enable_periodic_update_interrupt(True)
22+
23+
rtc.set_time(10, 10, 10, 5, 1, 1, 2001)
24+
25+
while True:
26+
27+
if (rtc.read_periodic_update_interrupt_flag()):
28+
rtc.clear_periodic_update_interrupt_flag()
29+
30+
rtc.update_time()
31+
rtc_time = rtc.string_time()
32+
print(rtc_time)
33+
34+
```
35+
36+
# **Functions**
37+
38+
## `.setup()`
39+
40+
Sets the RTC to 24 Hour Mode, disables the Trickle Charge and sets Level Switching Mode to 3.
41+
42+
## `.set_time(second, minute, hour, weekday, day, month, year)`
43+
44+
Set the time and date on the RTC. Returns **True** if successful and **False** if something went wrong.
45+
46+
**Example:**
47+
48+
```
49+
>>> rtc.set_time(0, 52, 8, 4, 5, 6, 2024)
50+
True
51+
>>> rtc.update_time()
52+
True
53+
>>> print(rtc.string_time(), rtc.string_date())
54+
08:52:13 05/06/2024
55+
```
56+
57+
You can also set a time or date element individually with:
58+
59+
`.set_seconds()`, `.set_minutes()`, `.set_hours()`, `.set_weekday()`, `.set_date()`, `.set_month()` and `.set_year()`
60+
61+
62+
## `.set_24_hour()`
63+
64+
Set the RTC to output 0-23 Hours. This function will convert any current hour to 2 Hour Mode.
65+
66+
## `.set_12_hour()`
67+
68+
Set the RTC to output 1-12 Hours. This function will convert any current hour to 12 Hour Mode.
69+
70+
## `.is_12_hour()`
71+
72+
Returns **True** if the RV3028 has been configured for 12 Hour mode.
73+
74+
```
75+
>>> rtc.is_12_hour()
76+
False
77+
>>> rtc.set_12_hour()
78+
>>> rtc.is_12_hour()
79+
True
80+
>>>
81+
```
82+
83+
### `.is_pm()`
84+
85+
Returns **True** if the RTC has the PM bit set and the 12 Hour bit set
86+
87+
**Example:**
88+
```
89+
>>> rtc.is_pm()
90+
False
91+
```
92+
93+
## `.update_time()`
94+
95+
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.
96+
97+
**Example**:
98+
99+
```
100+
while True:
101+
102+
rtc.update_time()
103+
rtc_time = rtc.string_time()
104+
print(rtc_time)
105+
106+
time.sleep(1)
107+
```
108+
**Output**:
109+
110+
```
111+
10:10:25
112+
10:10:26
113+
10:10:27
114+
```
115+
116+
## `.string_time()`
117+
118+
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.
119+
120+
**Example:**
121+
```
122+
>>> rtc.string_time()
123+
'05:05:05'
124+
```
125+
126+
## `.string_date()`
127+
128+
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.
129+
130+
**Example:**
131+
```
132+
>>> rtc.string_date()
133+
'05/05/2005'
134+
```
135+
136+
## `.enable_periodic_update_interrupt(True)`
137+
138+
Enables the periodic update interrupt. Triggers onces every second.
139+
140+
## `.disable_periodic_update_interrupt()`
141+
142+
Disables the periodic update interrupt.
143+
144+
## `.read_periodic_update_interrupt_flag()`
145+
146+
Read the periodic update interrupt flag. Returns a boolean value.
147+
148+
**Example:**
149+
150+
```
151+
>>> rtc.read_periodic_update_interrupt_flag()
152+
True
153+
```
154+
155+
## `.clear_periodic_update_interrupt_flag()`
156+
157+
Clear the periodic update interrupt flag.
158+
159+
**Example:**
160+
```
161+
>>> rtc.clear_periodic_update_interrupt_flag()
162+
>>> rtc.read_periodic_update_interrupt_flag()
163+
False
164+
```
165+
166+
## `.get_unix()`
167+
168+
Get the UNIX Time from the RTC
169+
170+
**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.
171+
172+
**Example:**
173+
```
174+
>>> rtc.get_unix()
175+
3084
176+
```
177+
178+
## `.set_unix()`
179+
180+
Set the UNIX Time on the RTC. Returns **True** if successful and **False** if something went wrong.
181+
182+
**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)
183+
184+
**Example:**
185+
```
186+
>>> rtc.set_unix(1717508760)
187+
True
188+
>>> rtc.get_unix()
189+
1717508765
190+
```
191+
192+
## `.set_backup_switchover_mode(int value)`
193+
194+
Set the backup switchover mode of the RTC. Accepts values 0-3.
195+
196+
0 = Switchover disabled
197+
1 = Direct Switching Mode
198+
2 = Standby Mode
199+
3 = Level Switching Mode
200+
201+
Function returns **True** if successful and **False** if something went wrong.
202+
203+
204+

0 commit comments

Comments
 (0)