This is an Arduino library for RP2040-based RTC
The RTC keeps track of time in human readable format and generates events when the time is equal to a preset value.
Think of a digital clock, not epoch time used by most computers. There are seven fields, one each for year (12 bit),
month (4 bit), day (5 bit), day of the week (3 bit), hour (5 bit) minute (6 bit) and second (6 bit), storing the data in binary
format.
The examples will demonstrate how to get the UTC time from NTP server, then update the RTC to make sure the time is perfectly correct.
Imagine you have a system with a mission-critical function, measuring water level and control the sump pump or doing something much more important. You normally use a software timer to poll, or even place the function in loop(). But what if another function is blocking the loop() or setup().
So your function might not be executed, and the result would be disastrous.
You'd prefer to have your function called, no matter what happening with other functions (busy loop, bug, etc.).
The correct choice is to use an ISR-based Alarm with Interrupt to call your function.
These ISR-based Alarm, using interrupt, still work even if other functions are blocking. Moreover, they are much more precise (certainly depending on clock frequency accuracy) than other software timers using millis() or micros(). That's necessary if you need to measure some data requiring better accuracy.
Functions using normal software timers, relying on loop() and calling millis(), won't work if the loop() or setup() is blocked by certain operation. For example, certain function is blocking while it's connecting to WiFi or some services.
The catch is your function is now part of an ISR (Interrupt Service Routine), and must be lean / mean, and follow certain rules. More to read on:
Ethernet_Generic
libraryEthernet_Generic
library, such as WIZnet Ethernet HAT and W5100S-EVB-PicoWiFiNINA
using WiFiNINA_Generic
libraryCYW43439 WiFi
with RASPBERRY_PI_PICO_W using arduino-pico coreArduino mbed_rp2040 core 3.3.0+
for Arduino RP2040-based boards, such as Arduino Nano RP2040 Connect, RASPBERRY_PI_PICO, etc..
Earle Philhower's arduino-pico core v2.5.4+
for RP2040-based boards such as RASPBERRY_PI_PICO, ADAFRUIT_FEATHER_RP2040 and GENERIC_RP2040, etc.
Timezone_Generic library v1.10.0+
to use examples using Timezone.
WiFiNINA_Generic library v1.8.14-6+
to use WiFiNINA modules/shields.
Depending on which Ethernet card/module/shield you're using:
Ethernet_Generic library v2.6.1+
for W5100, W5200 and W5500/WIZ550io/WIZ850io/USR-ES1 with Wiznet W5500 chip. EthernetENC library v2.0.3+
for ENC28J60. The best and easiest way is to use Arduino Library Manager
. Search for RP2040_RTC, then select / install the latest version.
You can also use this link for more detailed instructions.
Another way to install is to:
RP2040_RTC-main.zip
.RP2040_RTC-main
directory RP2040_RTC-main
folder to Arduino libraries' directory such as ~/Arduino/libraries/
.If your application requires 2K+ HTML page, the current Ethernet library
must be modified if you are using W5200/W5500 Ethernet shields. W5100 is not supported for 2K+ buffer. If you use boards requiring different CS/SS pin for W5x00 Ethernet shield, for example ESP32, ESP8266, nRF52, etc., you also have to modify the following libraries to be able to specify the CS/SS pin correctly.
To fix Ethernet library
, just copy these following files into the Ethernet library
directory to overwrite the old files:
To fix EthernetLarge library
, just copy these following files into the EthernetLarge library
directory to overwrite the old files:
To fix Ethernet2 library
, just copy these following files into the Ethernet2 library
directory to overwrite the old files:
To add UDP Multicast support, necessary for the UPnP_Generic library:
Ethernet3 library
, just copy these following files into the Ethernet3 library
directory to overwrite the old files:
To be able to compile and run on nRF52 boards with ENC28J60 using UIPEthernet library, you have to copy these following files into the UIPEthernet utility
directory to overwrite the old files:
From Raspberry Pi Pico C/C++ SDK
typedef void(* rtc_callback_t )(void);
typedef struct
{
int16_t year; ///< 0..4095
int8_t month; ///< 1..12, 1 is January
int8_t day; ///< 1..28,29,30,31 depending on month
int8_t dotw; ///< 0..6, 0 is Sunday
int8_t hour; ///< 0..23
int8_t min; ///< 0..59
int8_t sec; ///< 0..59
} datetime_t;
void rtc_init (void);
bool rtc_set_datetime (datetime_t *t);
bool rtc_get_datetime (datetime_t *t);
bool rtc_running (void);
void rtc_set_alarm (datetime_t *t, rtc_callback_t user_callback);
void rtc_enable_alarm (void);
void rtc_disable_alarm (void);
// Not very good to use
void datetime_to_str (char *buf, uint buf_size, const datetime_t *t);
Use one of these functions with interval in unsigned long microseconds
void rtc_disable_alarm (void)
Disable the RTC alarm (if active)
void rtc_enable_alarm (void)
Enable the RTC alarm (if inactive)
bool rtc_get_datetime (datetime_t *t)
Get the current time from the RTC.
Parameters
• t
: Pointer to a datetime_t structure to receive the current RTC time
Returns
• true
if datetime is valid, false
if the RTC is not running.
void rtc_init (void)
Initialise the RTC system.
bool rtc_running (void)
Is the RTC running?
void rtc_set_alarm (datetime_t *t, rtc_callback_t user_callback)
Set a time in the future for the RTC to call a user provided callback.
Parameters
• t
: Pointer to a datetime_t structure containing a time in the future to fire the alarm. Any values set to -1 will not be
matched on.
• user_callback
: pointer to a rtc_callback_t
to call when the alarm fires
bool rtc_set_datetime (datetime_t *t)
Set the RTC to the specified time.
Parameters
• t
: Pointer to a datetime_t structure contains time to set
Returns
• true
if set, false
if the passed in datetime was invalid.
void datetime_to_str (char *buf, uint buf_size, const datetime_t *t)
Convert a datetime_t structure to a string.
Parameters
• buf
: character buffer to accept generated string
• buf_size
: The size of the passed in buffer
• t
: The datetime to be converted
class TimeSpan;
class DateTime;
/** ISO 8601 Timestamp function */
enum timestampOpt
{
TIMESTAMP_FULL, // YYYY-MM-DDTHH:MM:SS
TIMESTAMP_TIME, // HH:MM:SS
TIMESTAMP_DATE // YYYY-MM-DD
};
class DateTime
{
DateTime (uint32_t t = SECONDS_FROM_1970_TO_2000);
DateTime (const uint16_t year, const uint8_t month, const uint8_t day, const uint8_t hour = 0, const uint8_t min = 0, const uint8_t sec = 0);
DateTime (const DateTime& copy);
DateTime (const tmElements_t& tm);
// To use with RP2040 datetime_t struct
DateTime (const datetime_t &tm);
tmElements_t get_tmElements_t();
void setFrom_tmElements_t(const tmElements_t& tm);
time_t get_time_t();
void setFrom_time_t(const time_t& timeInput);
uint16_t year() const;
uint8_t month() const;
uint8_t day() const;
uint8_t hour() const;
uint8_t minute() const;
uint8_t second() const;
uint16_t yearOffset() const;
uint8_t dayOfTheWeek() const;
/** 32-bit times as seconds since 1/1/2000 */
long secondstime() const;
/** 32-bit times as seconds since 1/1/1970 */
uint32_t unixtime() const;
/** ISO 8601 Timestamp function */
String timestamp(timestampOpt opt = TIMESTAMP_FULL)
}
The following is the sample terminal output when running example RP2040_RTC_Time_Ethernet on RASPBERRY_PI_PICO with W5100S using Ethernet_Generic Library
Start RP2040_RTC_Time_Ethernet on RASPBERRY_PI_PICO with W5x00 using Ethernet_Generic Library
RP2040_RTC v1.1.1
Timezone_Generic v1.10.0
[EWS] =========== USE_ETHERNET_GENERIC ===========
[EWS] Default SPI pinout:
[EWS] MOSI: 19
[EWS] MISO: 16
[EWS] SCK: 18
[EWS] SS: 17
[EWS] =========================
[EWS] RPIPICO setCsPin: 17
=========================
Currently Used SPI pinout:
MOSI:19
MISO:16
SCK:18
SS:17
=========================
Using mac index = 10
You're connected to the network, IP = 192.168.2.95
Packet received
Seconds since Jan 1 1900 = 3859851978
Unix time = 1650863178
The UTC time is 5:06:18
============================
05:06:19 Mon 25 Apr 2022 UTC
01:06:19 Mon 25 Apr 2022 EDT
The following is the sample terminal output when running example RP2040_RTC_Time_Ethernet on MBED RASPBERRY_PI_PICO with W5x00 using Ethernet_Generic Library
Start RP2040_RTC_Time_Ethernet on MBED RASPBERRY_PI_PICO with W5x00 using Ethernet_Generic Library
RP2040_RTC v1.1.1
Timezone_Generic v1.10.0
[EWS] =========== USE_ETHERNET_GENERIC ===========
[EWS] Default SPI pinout:
[EWS] MOSI: 19
[EWS] MISO: 16
[EWS] SCK: 18
[EWS] SS: 17
[EWS] =========================
[EWS] RPIPICO setCsPin: 17
=========================
Currently Used SPI pinout:
MOSI:19
MISO:16
SCK:18
SS:17
=========================
Using mac index = 1
You're connected to the network, IP = 192.168.2.102
Packet received
Seconds since Jan 1 1900 = 3859851547
Unix time = 1650862747
The UTC time is 4:59:07
============================
04:59:08 Mon 25 Apr 2022 UTC
00:59:08 Mon 25 Apr 2022 EDT
============================
05:00:08 Mon 25 Apr 2022 UTC
01:00:08 Mon 25 Apr 2022 EDT
============================
05:01:08 Mon 25 Apr 2022 UTC
01:01:08 Mon 25 Apr 2022 EDT
The following is the sample terminal output when running example RP2040_RTC_Time_WiFiNINA on MBED NANO_RP2040_CONNECT with WiFiNINA using WiFiNINA_Generic Library
Start RP2040_RTC_Time_WiFiNINA on MBED NANO_RP2040_CONNECT with WiFiNINA using WiFiNINA_Generic Library
RP2040_RTC v1.1.1
Timezone_Generic v1.10.0
Connecting to WPA SSID: HueNet1
You're connected to the network, IP = 192.168.2.153
Packet received
Seconds since Jan 1 1900 = 3859851547
Unix time = 1650862747
The UTC time is 4:59:07
============================
04:59:08 Mon 25 Apr 2022 UTC
00:59:08 Mon 25 Apr 2022 EDT
The following is the sample terminal output when running example RP2040_RTC_Alarm_Ethernet on RASPBERRY_PI_PICO with W5x00 using Ethernet_Generic Library
Start RP2040_RTC_Alarm_Ethernet on RASPBERRY_PI_PICO with W5x00 using Ethernet_Generic Library
RP2040_RTC v1.1.1
Timezone_Generic v1.10.0
[EWS] =========== USE_ETHERNET_GENERIC ===========
[EWS] Default SPI pinout:
[EWS] MOSI: 19
[EWS] MISO: 16
[EWS] SCK: 18
[EWS] SS: 17
[EWS] =========================
[EWS] RPIPICO setCsPin: 17
=========================
Currently Used SPI pinout:
MOSI:19
MISO:16
SCK:18
SS:17
=========================
Using mac index = 12
You're connected to the network, IP = 192.168.2.99
Packet received
Seconds since Jan 1 1900 = 3859852325
Unix time = 1650863525
The UTC time is 5:12:05
============================
05:12:06 Mon 25 Apr 2022 UTC
01:12:06 Mon 25 Apr 2022 EDT
Set Repeatitive Alarm @ alarmSeconds = 5
============================
Alarm @
05:13:05 Mon 25 Apr 2022 UTC
01:13:05 Mon 25 Apr 2022 EDT
============================
05:13:06 Mon 25 Apr 2022 UTC
01:13:06 Mon 25 Apr 2022 EDT
Start RP2040_RTC_Alarm_Ethernet on RASPBERRY_PI_PICO with W5x00 using Ethernet_Generic Library
RP2040_RTC v1.1.1
Timezone_Generic v1.10.0
[EWS] =========== USE_ETHERNET_GENERIC ===========
[EWS] Default SPI pinout:
[EWS] MOSI: 19
[EWS] MISO: 16
[EWS] SCK: 18
[EWS] SS: 17
[EWS] =========================
[EWS] Board : RASPBERRY_PI_PICO , setCsPin: 17
_pinCS = 0
W5100 init, using SS_PIN_DEFAULT = 10, new ss_pin = 10, W5100Class::ss_pin = 17
W5100::init: W5500, SSIZE =8192
=========================
Currently Used SPI pinout:
MOSI:19
MISO:16
SCK:18
SS:17
=========================
Using mac index = 17
You're connected to the network, IP = 192.168.2.101
Packet received
Seconds since Jan 1 1900 = 3859852325
Unix time = 1650863525
The UTC time is 5:12:05
============================
05:12:06 Mon 25 Apr 2022 UTC
01:12:06 Mon 25 Apr 2022 EDT
Set One-time Alarm @ alarmSeconds = 5
============================
Alarm @
05:13:05 Mon 25 Apr 2022 UTC
01:13:05 Mon 25 Apr 2022 EDT
The following is the sample terminal output when running example RP2040_RTC_Alarm_Ethernet on MBED RASPBERRY_PI_PICO with W5x00 using Ethernet_Generic Library
Start RP2040_RTC_Alarm_Ethernet on MBED RASPBERRY_PI_PICO with W5x00 using Ethernet_Generic Library
RP2040_RTC v1.1.1
Timezone_Generic v1.10.0
[EWS] =========== USE_ETHERNET_GENERIC ===========
[EWS] Default SPI pinout:
[EWS] MOSI: 19
[EWS] MISO: 16
[EWS] SCK: 18
[EWS] SS: 17
[EWS] =========================
[EWS] RPIPICO setCsPin: 17
=========================
Currently Used SPI pinout:
MOSI:19
MISO:16
SCK:18
SS:17
=========================
Using mac index = 19
You're connected to the network, IP = 192.168.2.104
Packet received
Seconds since Jan 1 1900 = 3859852627
Unix time = 1650863827
The UTC time is 5:17:07
============================
05:17:08 Mon 25 Apr 2022 UTC
01:17:08 Mon 25 Apr 2022 EDT
Set Repeatitive Alarm @ alarmSeconds = 5
============================
Alarm @
05:18:05 Mon 25 Apr 2022 UTC
01:18:05 Mon 25 Apr 2022 EDT
============================
05:18:08 Mon 25 Apr 2022 UTC
01:18:08 Mon 25 Apr 2022 EDT
Start RP2040_RTC_Alarm_Ethernet on RASPBERRY_PI_PICO with W5x00 using Ethernet_Generic Library
RP2040_RTC v1.1.1
Timezone_Generic v1.10.0
[EWS] =========== USE_ETHERNET_GENERIC ===========
[EWS] Default SPI pinout:
[EWS] MOSI: 19
[EWS] MISO: 16
[EWS] SCK: 18
[EWS] SS: 17
[EWS] =========================
[EWS] Board : RASPBERRY_PI_PICO , setCsPin: 17
_pinCS = 0
W5100 init, using SS_PIN_DEFAULT = 10, new ss_pin = 10, W5100Class::ss_pin = 17
W5100::init: W5500, SSIZE =8192
=========================
Currently Used SPI pinout:
MOSI:19
MISO:16
SCK:18
SS:17
=========================
Using mac index = 17
You're connected to the network, IP = 192.168.2.101
Packet received
Seconds since Jan 1 1900 = 3859852627
Unix time = 1650863827
The UTC time is 5:17:07
============================
05:17:08 Mon 25 Apr 2022 UTC
01:17:08 Mon 25 Apr 2022 EDT
Set One-time Alarm @ alarmSeconds = 5
============================
Alarm @
05:18:05 Mon 25 Apr 2022 UTC
01:18:05 Mon 25 Apr 2022 EDT
The following is the sample terminal output when running example RP2040_RTC_Alarm_WiFiNINA on MBED NANO_RP2040_CONNECT with WiFiNINA using WiFiNINA_Generic Library
Start RP2040_RTC_Alarm_WiFiNINA on MBED NANO_RP2040_CONNECT with WiFiNINA using WiFiNINA_Generic Library
RP2040_RTC v1.1.1
Timezone_Generic v1.10.0
Connecting to WPA SSID: HueNet1
You're connected to the network, IP = 192.168.2.125
Packet received
Seconds since Jan 1 1900 = 3859852627
Unix time = 1650863827
The UTC time is 5:17:07
============================
05:17:08 Mon 25 Apr 2022 UTC
01:17:08 Mon 25 Apr 2022 EDT
Set Repeatitive Alarm @ alarmSeconds = 5
============================
Alarm @
05:18:05 Mon 25 Apr 2022 UTC
01:18:05 Mon 25 Apr 2022 EDT
============================
05:18:08 Mon 25 Apr 2022 UTC
01:18:08 Mon 25 Apr 2022 EDT
Start RP2040_RTC_Alarm_WiFiNINA on MBED NANO_RP2040_CONNECT with WiFiNINA using WiFiNINA_Generic Library
RP2040_RTC v1.1.1
Timezone_Generic v1.10.0
Connecting to WPA SSID: HueNet1
You're connected to the network, IP = 192.168.2.125
Packet received
Seconds since Jan 1 1900 = 3859852627
Unix time = 1650863827
The UTC time is 5:17:07
============================
05:17:08 Mon 25 Apr 2022 UTC
01:17:08 Mon 25 Apr 2022 EDT
Set One-time Alarm @ alarmSeconds = 5
============================
Alarm @
05:18:05 Mon 25 Apr 2022 UTC
01:18:05 Mon 25 Apr 2022 EDT
If you get compilation errors, more often than not, you may need to install a newer version of the core for Arduino boards.
Sometimes, the library will only work if you update the board core to the latest version because I am using newly added functions.
Submit issues to: RP2040_RTC issues
SPI1
for RP2040
using Earle Philhower's arduino-pico
coreRP2040W
using CYW43439 WiFi
with Earle Philhower's arduino-pico
coreMany thanks for everyone for bug reporting, new feature suggesting, testing and contributing to the development of this library.
![]() kenb2054 |
![]() josephchrzempiec |
![]() ⭐️ Maximilian Gerhardt |
If you want to contribute to this project:
Copyright 2021- Khoi Hoang