Source: https://mokxi.com/libraries/ds1307rtc Updated: 2026-11-02 Libraries / Data and time Arduino library · Data and time # DS1307RTC: a hardware clock behind the Time library DS1307RTC, from Michael Margolis and Paul Stoffregen, is the small library that ties a DS1307 clock chip to the Time library (TimeLib.h). Instead of reading the chip every time, a sketch hands RTC.get to setSyncProvider(), and TimeLib then keeps the time in software with millis() and corrects itself from the chip every five minutes. After that, hour(), minute() and now() just work. Open the example in the editor See the calls Built in on Mokxi: #include and it builds, with nothing to install. Free, and no account needed. ## What DS1307RTC does For direct access, RTC.read(tm) fills a tmElements_t with the fields as the chip has them (Second, Minute, Hour, Wday, Day, Month and Year as years since 1970), and RTC.write(tm) or RTC.set(t) puts a new time into it. read() returns false when the chip does not answer or its clock is halted, and chipPresent() tells those two cases apart. A DS3231 keeps its time registers at the same address and in the same layout, so this library reads one too. The DS1307 itself needs 5 V and a 32 kHz crystal, and a brand new chip starts halted until its time is set once. Library Manager name | DS1307RTC Author | Michael Margolis, Paul Stoffregen Include | #include Boards | every board Mokxi compiles for but ATtiny85 In the simulator | Simulated: it runs against the part the way it does on the bench. Parts it drives | Real-time clock, DS1307, Real-time clock, DS3231 ## Install it It builds on every board Mokxi compiles for but ATtiny85. In Mokxi it is built in: #include and the sketch compiles, with no download, no zip and no Library Manager. On a real board, install "DS1307RTC" by Michael Margolis, Paul Stoffregen from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add DS1307RTC to lib_deps in PlatformIO. Mokxi follows the calls of release 1.4.1, so a sketch written here builds there too. ESP32-C3 · Arduino Uno · Arduino Nano · Arduino Mega 2560 · Arduino Leonardo · SparkFun Pro Micro · Arduino Micro · ESP32-C6 · Raspberry Pi Pico · Raspberry Pi Pico W · Seeed XIAO SAMD21 · STM32 · STM32 Nucleo-F411RE · STM32 Blue Pill · micro:bit V2 · Arduino Uno R4 · ESP32 DevKit · ESP32-S3-DevKitC-1 · ESP8266 NodeMCU · Arduino Pro Mini 3.3 V · Seeed XIAO ESP32-C3 · ESP32-C3 SuperMini · Seeed XIAO ESP32-C6 · ESP32-DevKitC V4 · LOLIN32 Lite · Wemos D1 R32 · Cheap Yellow Display · TTGO T-Display · Seeed XIAO ESP32-S3 · Arduino Nano ESP32 · Arduino Nano RP2040 Connect · Seeed XIAO RP2040 · Waveshare RP2040-Zero · Arduino Uno R4 WiFi ## The calls you will use In the order a sketch meets them. ### setSyncProvider(RTC.get) Tells TimeLib to set itself from the chip now and every few minutes. Afterwards hour(), minute() and now() read the synced software clock. ### timeStatus() From TimeLib: timeSet when the sync worked, timeNotSet when it never did, timeNeedsSync when the last attempt failed. ### tmElements_t tm; A time broken into fields. tm.Year counts from 1970, so use tmYearToCalendar(tm.Year) to print 2026. ### RTC.read(tm) Reads the chip into tm. Returns true on success and false if nothing answered or the clock is halted. ### RTC.set(makeTime(tm)) Sets the chip from a time_t, here built from the fields with TimeLib’s makeTime(). It also starts a halted clock. ### RTC.chipPresent() After a failed read(), true if the chip answered (so it is only halted) and false if it is not on the bus at all. ### time_t t = RTC.get(); Reads the chip and returns seconds since 1970, or 0 when the read failed. ## Example: Read a DS1307 with TimeLib On the Arduino Uno R3. It runs in the browser exactly as printed. sketch.ino · Arduino Uno R3 ### Wiring - Arduino Uno R3 A4 to Real-time clock, DS1307 SDA - Arduino Uno R3 A5 to Real-time clock, DS1307 SCL - Arduino Uno R3 5V to Real-time clock, DS1307 VCC - Arduino Uno R3 GND to Real-time clock, DS1307 GND Open it in the editor, wired and ready to run ## Common errors and how to fix them ### Unable to sync with the RTC timeStatus() is not timeSet after setSyncProvider(), so RTC.get returned 0. Check the module answers at 0x68 on the I2C pins, and set the time once if the chip is new and halted. ### DS1307 read error! Please check the circuitry. The library examples print this when read() fails and chipPresent() is false: the chip is not on the bus. Check SDA and SCL, power, ground and the pull-ups on the module. ### The year prints as 56 instead of 2026 tm.Year counts from 1970. Print tmYearToCalendar(tm.Year), or call year() from TimeLib after syncing, which gives the full year. ### 'tmElements_t' does not name a type TimeLib.h is not included, or the Time library is not installed. Include TimeLib.h before DS1307RTC.h, as in the library’s own examples, and install the Time library by Paul Stoffregen. ## Keep going ### Learn - Arduino DS3231 Clock With a TM1637 Display ### Parts - Real-time clock, DS1307 - Real-time clock, DS3231 ### More data and time libraries - QRCode - Madgwick - PID - TimerOne - MsTimer2 - Low-Power - RTClib - DS3231 (NorthernWidget) and DS3231 (Rinky-Dink Electronics) Every built-in library · Open the editor ## Try DS1307RTC without installing anything Open the example, change the sketch, and keep your version in a free account. Start building free Open the editor