{"id":16148888,"url":"https://github.com/erriez/erriezds3231","last_synced_at":"2025-10-28T01:36:01.875Z","repository":{"id":85067600,"uuid":"142871504","full_name":"Erriez/ErriezDS3231","owner":"Erriez","description":"DS3213 high precision RTC (Real Time Clock) library for Arduino","archived":false,"fork":false,"pushed_at":"2022-12-05T14:20:03.000Z","size":3006,"stargazers_count":25,"open_issues_count":3,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-02T18:49:54.653Z","etag":null,"topics":["advanced","alarm","arduino","atmega328","avr","date","documentation","ds3231","epoch","esp32","esp8266","examples","i2c","library","rtc","terminal","time","unix","uno"],"latest_commit_sha":null,"homepage":"https://github.com/Erriez/ErriezArduinoLibrariesAndSketches","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Erriez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-30T12:20:59.000Z","updated_at":"2025-03-13T10:24:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"beec19e0-dcb3-4b04-b7d8-49a0717664bd","html_url":"https://github.com/Erriez/ErriezDS3231","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/Erriez/ErriezDS3231","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Erriez%2FErriezDS3231","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Erriez%2FErriezDS3231/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Erriez%2FErriezDS3231/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Erriez%2FErriezDS3231/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Erriez","download_url":"https://codeload.github.com/Erriez/ErriezDS3231/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Erriez%2FErriezDS3231/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261449740,"owners_count":23159802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["advanced","alarm","arduino","atmega328","avr","date","documentation","ds3231","epoch","esp32","esp8266","examples","i2c","library","rtc","terminal","time","unix","uno"],"created_at":"2024-10-10T00:35:11.711Z","updated_at":"2025-10-28T01:36:01.798Z","avatar_url":"https://github.com/Erriez.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DS3231 high precision I2C RTC library for Arduino\n\n[![Build Status](https://travis-ci.org/Erriez/ErriezDS3231.svg?branch=master)](https://travis-ci.org/Erriez/ErriezDS3231)\n\nThis is a DS3231 high precision I2C RTC library for Arduino.\n\n![DS3231](https://raw.githubusercontent.com/Erriez/ErriezDS3231/master/extras/DS3231.png)\n\n## Library features\n\n* libc `\u003ctime.h\u003e` compatible\n* Read/write date/time `struct tm`\n* Set/get Unix epoch UTC `time_t`\n* Set/get time (hour, min, sec)\n* Set/get date and time (hour, min, sec, mday, mon, year, wday)\n* Read temperature (0.25 degree resolution)\n* Alarm 1 (second/minute/hour/day/date match) \n* Alarm 2 (minute/hour/day/date match)\n* Polling and Alarm `INT/SQW` interrupt pin\n* Control `32kHz` out signal (enable/disable)\n* Control `SQW` signal (disable / 1 / 1024 / 4096 / 8192Hz)\n* Configure aging offset\n* Serial terminal interface\n* Full RTC register access\n* Set date/time over serial with Python script\n\n## Hardware\n\nAny Arduino hardware with a TWI interface and `Wire.h` support.\n\n![DS3231 - Arduino UNO](https://raw.githubusercontent.com/Erriez/ErriezDS3231/master/extras/DS3231_Arduino_UNO.png)\n\n### ESP32 notes\n\n**ESP32 problem:** The Arduino IDE | Board manager installs an old version ```1.0.0``` from `https://dl.espressif.com/dl/package_esp32_index.json` which contains a broken I2C repeated start. Generating a repeated start with ```Wire.endTransmission(false);``` results in reading zero's from any I2C device and is not a problem of this library.\n\n**Solution:** Use the Git master branch (or a newer release when available) to solve this problem as described on:\nhttps://github.com/espressif/arduino-esp32/blob/master/docs/arduino-ide/windows.md.\n\n## Pins\n\n| Pins board - DS3231            | VCC  | GND  |    SDA     |    SCL     |    SQW     |\n| ------------------------------ | :--: | :--: | :--------: | :--------: | :--------: |\n| Arduino UNO (ATMega328 boards) |  5V  | GND  |     A4     |     A5     | D2 (INT0)  |\n| Arduino Mega2560               |  5V  | GND  |    D20     |    D21     | D2 (INT4)  |\n| Arduino Leonardo               |  5V  | GND  |     D2     |     D3     | D7 (INT6)  |\n| Arduino DUE (ATSAM3X8E)        | 3V3  | GND  |     20     |     21     |     2      |\n| ESP8266                        | 3V3  | GND  | GPIO4 (D2) | GPIO5 (D1) | GPIO0 (D3) |\n| ESP32                          | 3V3  | GND  |   GPIO21   |   GPIO22   |   GPIO0    |\n\nNote: Tested ESP8266 / ESP32 boards:\n\n* **ESP8266 boards**: ESP12F / WeMos D1 \u0026 R2 / Node MCU v2 / v3\n* **ESP32 boards:** WeMos LOLIN32 / LOLIN D32\n\nOther unlisted MCU's may work, but are not tested.\n\n## Examples\n\nArduino IDE | Examples | Erriez DS3231 RTC:\n\n* [AgingOffset](https://github.com/Erriez/ErriezDS3231/blob/master/examples/ErriezDS3231AgingOffset/ErriezDS3231AgingOffset.ino) Aging offset programming\n* [AlarmInterrupt](https://github.com/Erriez/ErriezDS3231/blob/master/examples/ErriezDS3231AlarmInterrupt/ErriezDS3231AlarmInterrupt.ino) Alarm with interrupts\n* [AlarmPolling](https://github.com/Erriez/ErriezDS3231/blob/master/examples/ErriezDS3231AlarmPolling/ErriezDS3231AlarmPolling.ino) Alarm polled\n* [DumpRegisters](https://github.com/Erriez/ErriezDS3231/blob/master/examples/ErriezDS3231DumpRegisters/ErriezDS3231DumpRegisters.ino) Dump registers polled\n* [SetBuildDateTime](https://github.com/Erriez/ErriezDS3231/blob/master/examples/ErriezDS3231SetBuildDateTime/ErriezDS3231SetBuildDateTime.ino) Set build date/time\n* [SetGetDateTime](https://github.com/Erriez/ErriezDS3231/blob/master/examples/ErriezDS3231SetGetDateTime/ErriezDS3231SetGetDateTime.ino) Simple RTC read date/time example\n* [SetGetTime](https://github.com/Erriez/ErriezDS3231/blob/master/examples/ErriezDS3231SetGetTime/ErriezDS3231SetGetTime.ino)  Set/Get time\n* [SQWInterrupt](https://github.com/Erriez/ErriezDS3231/blob/master/examples/ErriezDS3231SQWInterrupt/ErriezDS3231SQWInterrupt.ino)  Blink LED on SQW interrupt pin\n* [Temperature](https://github.com/Erriez/ErriezDS3231/blob/master/examples/ErriezDS3231Temperature/ErriezDS3231Temperature.ino) Temperature\n* [Terminal](https://github.com/Erriez/ErriezDS3231/blob/master/examples/ErriezDS3231Terminal/ErriezDS3231Terminal.ino) Advanced terminal interface with [set date/time Python](https://github.com/Erriez/ErriezDS3231/blob/master/examples/ErriezDS3231Terminal/ErriezDS3231Terminal.py) script\n* [Test](https://github.com/Erriez/ErriezDS3231/blob/master/examples/ErriezDS3231Test/ErriezDS3231Test.ino) Regression test\n* [WriteRead](https://github.com/Erriez/ErriezDS3231/blob/master/examples/ErriezDS3231WriteRead/ErriezDS3231WriteRead.ino) Write/read `struct tm`\n\n## Documentation\n\n- [Doxygen online HTML](https://erriez.github.io/ErriezDS3231) \n- [Doxygen PDF](https://github.com/Erriez/ErriezDS3231/blob/master/ErriezDS3231.pdf)\n- [DS3231 datasheet](https://github.com/Erriez/ErriezDS3231/blob/master/extras/DS3231.pdf)\n\n\n## Usage\n\n**Initialization**\n\n```c++\n#include \u003cWire.h\u003e\n#include \u003cErriezDS3231.h\u003e\n\n// Create RTC object\nErriezDS3231 rtc;\n\nvoid setup()\n{\n    // Initialize TWI with a 100kHz (default) or 400kHz clock\n    Wire.begin();\n    Wire.setClock(400000);\n    \n    // Initialize RTC\n    while (!rtc.begin()) {\n        // Error: Could not detect DS3231 RTC, retry after some time\n        delay(3000);\n    }\n}\n```\n\n**Check oscillator status at startup**\n\n```c++\n// Check oscillator status\nif (rtc.isOscillatorStopped()) {\n    // Error: RTC oscillator stopped. Date/time cannot be trusted. \n    // Set new date/time before reading date/time.\n\n    // Enable oscillator\n    rtc.clockEnable(true);\n}\n```\n\n**Set time**\n\n```c++\n// Write time to RTC\nif (!rtc.setTime(12, 0, 0)) {\n    // Error: Set time failed\n}\n```\n\n**Get time**\n\n```c++\nuint8_t hour;\nuint8_t minute;\nuint8_t second;\n\n// Read time from RTC\nif (!rtc.getTime(\u0026hour, \u0026minute, \u0026second)) {\n    // Error: RTC read failed\n}\n```\n\n**Set date and time**\n\n```c++\n// Write RTC date/time: 13:45:09  31 December 2019  0=Sunday, 2=Tuesday\nif (!rtc.setDateTime(13, 45, 9,  31, 12, 2019,  2) {\n    // Error: RTC write failed\n}\n```\n\n**Get date and time**\n\n```c++\nuint8_t hour;\nuint8_t min;\nuint8_t sec;\nuint8_t mday;\nuint8_t mon;\nuint16_t year;\nuint8_t wday;\n\n// Read RTC date/time\nif (!rtc.getDateTime(\u0026hour, \u0026min, \u0026sec, \u0026mday, \u0026mon, \u0026year, \u0026wday) {\n    // Error: RTC read failed\n}\n\n// hour: 0..23\n// min: 0..59\n// sec: 0..59\n// mday: 1..31\n// mon: 1..12\n// year: 2000..2099\n// wday: 0..6 (0=Sunday .. 6=Saturday)\n```\n\n**Write date/time struct tm**\n\n```c++\nstruct tm dt;\n\ndt.tm_hour = 12;\ndt.tm_min = 34;\ndt.tm_sec = 56;\ndt.tm_mday = 29;\ndt.tm_mon = 1; // 0=January\ndt.tm_year = 2020-1900;\ndt.tm_wday = 6; // 0=Sunday\n\nif (!rtc.write(\u0026dt)) {\n    // Error: RTC Read failed\n}\n```\n\n**Read date/time struct tm**\n\n```c++\nstruct tm dt;\n\n// Read RTC date/time\nif (!rtc.read(\u0026dt)) {\n    // Error: RTC read failed\n}\n```\n\n**Read Unix Epoch UTC**\n\n```c++\ntime_t t;\n\n// Read Unix epoch UTC from RTC\nif (!rtc.getEpoch(\u0026t)) {\n    // Error: RTC read failed\n}\n```\n\n**Write Unix Epoch UTC**\n\n```c++\n// Write Unix epoch UTC to RTC\nif (!rtc.setEpoch(1599416430UL)) {\n    // Error: Set epoch failed\n}\n```\n\n**Get temperature**\n\n```c++\nint8_t temperature = 0;\nuint8_t fraction = 0;\n\n// Force temperature conversion\n// Without this call, it takes 64 seconds before the temperature is updated.\nif (!rtc.startTemperatureConversion()) {\n    // Error: Start temperature conversion failed \n}\n\n// Read temperature\nif (!rtc.getTemperature(\u0026temperature, \u0026fraction)) {\n    // Error: Get temperature failed\n}\n\n// Print temperature. The output below is for example: 28.25C\nSerial.print(temperature);\nSerial.print(F(\".\"));\nSerial.print(fraction);\nSerial.println(F(\"C\"));\n```\n\n**Program Alarm 1**\n\nNote: Alarm 1 and Alarm 2 have different behavior. Please refer to the documentation which ```Alarm1Type``` and ```Alarm2Type``` are supported. Some examples:\n\n```c++\n// Generate alarm 1 every second\nrtc.setAlarm1(Alarm1EverySecond, 0, 0, 0, 0);\n\n// Generate alarm 1 every minute and second match\nrtc.setAlarm1(Alarm1EverySecond, 0, 0, 45, 30);\n\n// Generate alarm 1 every day, hour, minute and second match\nrtc.setAlarm1(Alarm1MatchDay, \n              1,  // Alarm day match (1 = Monday)\n              12, // Alarm hour match\n              45, // Alarm minute match\n              30  // Alarm second match\n);\n```\n\n**Program Alarm 2**\n\n```c++\n// Generate alarm 2 every minute\nrtc.setAlarm2(Alarm2EveryMinute, 0, 0, 0);\n\n// Generate alarm 2 every hour, minute match\nrtc.setAlarm2(Alarm2MatchHours, 0, 23, 59);\n\n// Generate alarm 2 every date, hour, minute match\nrtc.setAlarm2(Alarm2MatchDate, 28, 7, 0);\n```\n\n**Alarm polling**\n\nNote: The ```INT``` pin changes to low when an Alarm 1 or Alarm 2 match occurs and and the interrupt is enabled. The pin remains low until both alarm flags are cleared by the application.\n\n```c++\n// Poll alarm 1 flag\nif (rtc.getAlarmFlag(Alarm1)) {\n    // Handle Alarm 1\n    \n    // Clear alarm 1 flag\n\trtc.clearAlarmFlag(Alarm1);\n}\n\n// Poll alarm 2 flag\nif (rtc.getAlarmFlag(Alarm2)) {\n    // Handle Alarm 2\n    \n    // Clear alarm 2 flag\n\trtc.clearAlarmFlag(Alarm2);\n}\n```\n\n**Alarm interrupt**\n\nNote: Enabling interrupt will disable the ```SQW``` output signal.\n\n```c++\n// Uno, Nano, Mini, other 328-based: pin D2 (INT0) or D3 (INT1)\n#define INT_PIN     2\n\n// Alarm interrupt flag must be volatile\nvolatile bool alarmInterrupt = false;\n\n\n#if defined(ARDUINO_ARCH_ESP8266) || defined(ARDUINO_ARCH_ESP32)\nICACHE_RAM_ATTR\n#endif\nvoid alarmHandler()\n{\n    // Set global interrupt flag\n    alarmInterrupt = true;\n}\n\nvoid setup()\n{\n    ...\n\n    // Attach to INT0 interrupt falling edge\n    pinMode(INT_PIN, INPUT_PULLUP);\n    attachInterrupt(digitalPinToInterrupt(INT_PIN), alarmHandler, FALLING);\n    \n    // Enable Alarm 1 and 2 interrupts\n    rtc.alarmInterruptEnable(Alarm1, true);\n    rtc.alarmInterruptEnable(Alarm2, true);\n}\n\nvoid loop()\n{\n    // Check global alarm interrupt flag\n    if (alarmInterrupt) {\n        if (rtc.getAlarmFlag(Alarm1)) {\n            // Handle alarm 1\n            \n            // Clear alarm 1 interrupt\n            rtc.clearAlarmFlag(Alarm1);\n        }\n        \n        if (rtc.getAlarmFlag(Alarm2)) {\n            // Handle alarm 2\n            \n            // Clear alarm 2 interrupt\n            rtc.clearAlarmFlag(Alarm2);\n        }\n    }\n}\n```\n\n**32kHz clock out**\n\nEnable or disable ```32kHz``` output pin.\n\n```c++\nrtc.outputClockPinEnable(true);  // Enable \nrtc.outputClockPinEnable(false);\t// Disable\n```\n\n**Square Wave Out (SQW)**\n\nNote: Enabling ```SQW``` pin will disable the alarm ```INT``` signal.\n\n```c++\nrtc.setSquareWave(SquareWaveDisable);\t// Disable\nrtc.setSquareWave(SquareWave1Hz);\t\t// 1Hz\nrtc.setSquareWave(SquareWave1024Hz);\t// 1024Hz\nrtc.setSquareWave(SquareWave4096Hz);\t// 4096Hz\nrtc.setSquareWave(SquareWave8192Hz);\t// 8192Hz\n```\n\n\n## API changes v1.0.1 to v2.0.0\n\nThe API has been changed to make RTC libraries compatible with libc `time.h`. This makes it easier\nto calculate with date/time and port the application to different platforms. See changes below:\n\n| v1.0.1                           | v2.0.0                                                       |\n| -------------------------------- | ------------------------------------------------------------ |\n| `DS3231_DateTime`                | `struct tm`                                                  |\n| Function returns `true`: failure | Function returns `false`: failure                            |\n|                                  | `clearOscillatorStopFlag()` merged into `oscillatorEnable()` |\n| `setDateTime()`                  | `bool write(struct tm *dt)`                                  |\n| `getDateTime()`                  | `bool read(struct tm *dt)`                                   |\n| `getEpochTime()`                 | `time_t getEpoch()`                                          |\n|                                  | `bool setEpoch(time_t t)`                                    |\n|                                  | `void setDateTime(uint8_t hour, uint8_t min, uint8_t sec, uint8_t mday, uint8_t mon, uint16_t year, uint8_t wday)` |\n|                                  | `void getDateTime(uint8_t *hour, uint8_t *min, uint8_t *sec, uint8_t *mday, uint8_t *mon, uint16_t *year, uint8_t *wday)` |\n| `ErriezDS3231Debug`              | class removed to reduce flash size       |\n\n\n## Library dependencies\n\n* `Wire.h`\n* `Terminal.ino` requires `ErriezSerialTerminal` library.\n\n\n## Library installation\n\nPlease refer to the [Wiki](https://github.com/Erriez/ErriezArduinoLibraries/wiki) page.\n\n\n## More Arduino Libraries from Erriez\n\n* [Erriez Libraries](https://github.com/Erriez/ErriezArduinoLibraries)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferriez%2Ferriezds3231","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferriez%2Ferriezds3231","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferriez%2Ferriezds3231/lists"}