Arduino library · Data and time

uRTCLib: an example that runs

Yes. You can use the uRTCLib library online in Mokxi with nothing to install, and the sketch runs in your browser against the simulated part (Real-time clock, DS3231). The example below, "A DS3231 through uRTCLib, with alarm 1", runs on the Arduino Uno R3.

Built in on Mokxi: #include <uRTCLib.h> and it builds, with nothing to install. Free, and no account needed.

What uRTCLib does

The DS3231, DS3232 and DS1307 clocks: refresh() and the getters, set(), the 12-hour form, lostPower(), the alarms with alarmTriggered(), temp() in hundredths, the square wave, the aging offset and ramRead() and ramWrite(). That is what uRTCLib, by Naguissa, covers. The sketch below uses it on the Arduino Uno: “A DS3231 through uRTCLib, with alarm 1”.

The uRTCLib library's interface (Naguissa, 6.9.9), for the DS1307, DS3231 and DS3232 clocks.

As upstream, the model is URTCLIB_MODEL_DS3232 unless the constructor or set_model() says otherwise.

The calls follow release 6.9.9 of the library, so a sketch written here builds on a real board too. The example is the one Mokxi's own tests build and run, so what is printed here is what runs.

Library Manager nameuRTCLib
AuthorNaguissa
Include#include <uRTCLib.h>
Boardsevery board Mokxi compiles for but ATtiny85
In the simulatorSimulated: it runs against the part the way it does on the bench.
Parts it drivesReal-time clock, DS3231, Real-time clock, DS1307

Install it

It builds on every board Mokxi compiles for but ATtiny85.

In Mokxi it is built in: #include <uRTCLib.h> and the sketch compiles, with no download, no zip and no Library Manager.

On a real board, install "uRTCLib" by Naguissa from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add uRTCLib to lib_deps in PlatformIO. Mokxi follows the calls of release 6.9.9, so a sketch written here builds there too.

What to know in the simulator: The default model is the DS3232, as upstream. The ds3231 part has no SRAM, so ramRead() there reads 0; the ds1307’s RAM is modeled. The 32 kHz output is stored and not driven.

The calls you will use

In the order a sketch meets them.

uRTCLib rtc(0x68)

Makes rtc, the uRTCLib object the calls below are made on.

rtc.set_model(URTCLIB_MODEL_DS3231)

Sets the model to the value you pass in. Arguments: model.

rtc.year()

Returns the year as a whole number.

rtc.month()

Returns the month as a whole number.

rtc.day()

Returns the day as a whole number.

Example: A DS3231 through uRTCLib, with alarm 1

On the Arduino Uno R3. It runs in the browser exactly as printed.

sketch.ino · Arduino Uno R3
#include "Arduino.h"
#include "uRTCLib.h"

uRTCLib rtc(0x68);

char daysOfTheWeek[7][12] = {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"};

void setup() {
  Serial.begin(9600);
  URTCLIB_WIRE.begin();
  rtc.set_model(URTCLIB_MODEL_DS3231);

  rtc.refresh();
  Serial.print("Lost power: ");
  Serial.println(rtc.lostPower());
  rtc.lostPowerClear();

  // second, minute, hour, dayOfWeek (Sunday 1), dayOfMonth, month, year
  rtc.set(0, 45, 13, 5, 17, 9, 26);
  // Alarm 1 when the seconds read 02.
  rtc.alarmSet(URTCLIB_ALARM_TYPE_1_FIXED_S, 2, 0, 0, 1);
}

void loop() {
  rtc.refresh();

  Serial.print("RTC DateTime: ");
  Serial.print(rtc.year());
  Serial.print('/');
  Serial.print(rtc.month());
  Serial.print('/');
  Serial.print(rtc.day());
  Serial.print(' ');
  Serial.print(rtc.hour());
  Serial.print(':');
  Serial.print(rtc.minute());
  Serial.print(':');
  Serial.print(rtc.second());
  Serial.print(" DOW: ");
  Serial.print(daysOfTheWeek[rtc.dayOfWeek() - 1]);
  Serial.print(" - Temp: ");
  Serial.print(rtc.temp() / 100);
  Serial.print('.');
  Serial.print(rtc.temp() % 100);
  Serial.print(" - Lost power: ");
  Serial.println(rtc.lostPower());

  if (rtc.alarmTriggered(URTCLIB_ALARM_1)) {
    Serial.println("Alarm 1 triggered");
    rtc.alarmClearFlag(URTCLIB_ALARM_1);
  }
  delay(1000);
}

Wiring

  • Arduino Uno R3 A4 to Real-time clock, DS3231 SDA
  • Arduino Uno R3 A5 to Real-time clock, DS3231 SCL
  • Arduino Uno R3 5V to Real-time clock, DS3231 VCC
  • Arduino Uno R3 GND to Real-time clock, DS3231 GND

Open it in the editor, wired and ready to run

Try uRTCLib without installing anything

Open the example, change the sketch, and keep your version in a free account.