{"id":13581111,"url":"https://github.com/hasenradball/DS3231-RTC","last_synced_at":"2025-04-06T06:32:34.864Z","repository":{"id":203809020,"uuid":"709195808","full_name":"hasenradball/DS3231-RTC","owner":"hasenradball","description":"C++ Library for the DS3231 RTC module","archived":false,"fork":false,"pushed_at":"2024-09-05T22:01:28.000Z","size":214,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-25T23:22:56.100Z","etag":null,"topics":["arduino","datetime","ds3231","esp32","esp8266","nano","nano33iot","pio","rtc","time"],"latest_commit_sha":null,"homepage":"","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/hasenradball.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2023-10-24T08:12:14.000Z","updated_at":"2024-11-25T23:36:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"364e0c5a-5e3c-4e7c-9da3-864157f5b5b8","html_url":"https://github.com/hasenradball/DS3231-RTC","commit_stats":{"total_commits":31,"total_committers":2,"mean_commits":15.5,"dds":"0.12903225806451613","last_synced_commit":"33ecab138a966a7cb385635ed5a4ff7015870357"},"previous_names":["hasenradball/ds3231-rtc"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasenradball%2FDS3231-RTC","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasenradball%2FDS3231-RTC/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasenradball%2FDS3231-RTC/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasenradball%2FDS3231-RTC/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hasenradball","download_url":"https://codeload.github.com/hasenradball/DS3231-RTC/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247445652,"owners_count":20939952,"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":["arduino","datetime","ds3231","esp32","esp8266","nano","nano33iot","pio","rtc","time"],"created_at":"2024-08-01T15:01:58.211Z","updated_at":"2025-04-06T06:32:34.597Z","avatar_url":"https://github.com/hasenradball.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"# DS3231-RTC Library\n[![Spell Check](https://github.com/hasenradball/DS3231-RTC/actions/workflows/spell_checker.yml/badge.svg)](https://github.com/hasenradball/DS3231-RTC/actions/workflows/spell_checker.yml)\n[![Compile Examples](https://github.com/hasenradball/DS3231-RTC/actions/workflows/compile_examples.yml/badge.svg)](https://github.com/hasenradball/DS3231-RTC/actions/workflows/compile_examples.yml)\n\nThe **great** C++ Library for the DS3231 real-time clock (RTC) module.  \n\n## Description\nThe library provides easy-to-use methods to:\n\n* set and read the current date and time;\n* set, clear, and detect two, independent, Time-of-Day alarms;\n* perform certain conversions and calculations with time data;\n* manage certain hardware inside the DS3231 RTC module.\n\nThis document explains the installation and usage of the Library with the Arduino IDE. \n\nYou do have to install the Library in your Arduino IDE environment before you can use it. Installation instructions are provided, below.\n\n**REMARK**:\u003cbr\u003e\nThis library was based on the master branch of [NorthernWidget/DS3231](https://github.com/NorthernWidget/DS3231) Library in Oct/2023. It was reworked and refractured with respect of the following main topics:\n* using standardized functions of the `time.h` library.\n* introduce a `struct tm` which holds all relevant date and time values.\n* restructure comments, so that syntax highlighting works fine.\n* add a `strf_DateTime()` function with can be used to print a user specific(self defined) DateTime string easily.\n\n## Contents\n\n* [Summary](#summary)\n* [About the DS3231](#about-the-ds3231-module)\n    * [The DS3231 Battery Problem](#the-ds3231-battery-problem)\n* [How to Install the Library](#installation)\n* [Functions Provided in the Library](#functions)\n* [Examples of Using the Library](#examples-of-use)\n* [Helpful Resources](#additional-resources-and-references)\n* [Contributing, Credits and License](#contributing)\n* [To-Do List](#to-do)\n\n\n\u003chr\u003e\n\n## Summary\n\nAfter installing the Library in your Arduino IDE, using it in a program starts with three, simple steps:\n\n\u003col start=\"1\"\u003e \n  \u003cli\u003eImport the Library into the program code:\u003c/li\u003e\n\u003c/ol\u003e\n\n\n```\n#include \u003cDS3231-RTC.h\u003e\n```\n\n\u003col start=\"2\"\u003e\n  \u003cli\u003eDeclare a DS3231 object, for example:\u003c/li\u003e\n\u003c/ol\u003e\n\n\n```\nDS3231 myRTC;\n```\n\n\u003col start=\"3\"\u003e\n  \u003cli\u003eStart the Wire library to enable I2C communications with the DS3231 hardware, typically in the setup() code block:\u003c/li\u003e\n\u003c/ol\u003e\n\n\n```\nWire.begin();\n```\nor for the **ESP8266** like:\n```\nWire.begin(SDA, SCL);\n```\n\nThen, Library functions are typically accessed through the DS3231 object.\n\nFor example, to read the current date of the month (1...31), depending on the month and the year:\n\n```\nbyte theDate = myRTC.getDate();\n```\n\nThe Library incorporates two other classes to assist with managing `date` and `time` data:\n\n* `DateTime` class enables a object for managing date and time data.\n* `RTClib` class institutes a convenient `RTClib::now()` function for receiving a date/time snapshot, as a DateTime object, from the DS3231 device.\n\nThe `DateTime` class can be instantiated by a specific date and time in three different ways:\n\n* 1.) by distinct values for:\u003cbr\u003e\nyear, month, day, hour, minute and second\n\n    or\n    \n* 2.) by a single, `time_t` unix timestamp.\u003cbr\u003e\n\n* 3.) by giving a separate `const char *` string for Date and Time like:\u003cbr\u003e\n`\"Feb 16 2022\"` and `\"14:05:00\"`\u003cbr\u003e\nThis can be also achieved by usage on the precompiler Tags `__DATE__` and `__TIME__`.\n\n\n\n## About the DS3231 Module\nThe DS3231 module is a low-cost integrated circuit (IC) providing a highly accurate, real time clock for use with Arduino, ESP8266, ESP32, Raspberry Pi and other popular small computing devices. \n\nThe IC is typically mounted on a circuit board, along with other hardware, such as header pins, supportive electrical components, and even EEPROM memory chips, for convenient attachment to a breadboard or an Arduino. \n\nSeveral different modules are available from a number of competing vendors. This Library aspires to work with any DS3231 module that supports I2C communications with the IC.\n\nDS3231 runs independently and can be kept running for a considerable length of time by a small, backup battery, even if power to the Arduino is turned off.\n\nAccording to the [DS3231-datasheet](https://datasheets.maximintegrated.com/en/ds/DS3231-DS3231S.pdf), the DS3231 hardware \"completely manages all timekeeping functions (including):\n\n* Seconds, \n* Minutes, \n* Hours\n    * 12-hour format with AM/PM indication, or\n    * 24-hour format,\n* Day of the Week,\n* Date of the Month, \n* Month,  and\n* Year, with Leap-Year Compensation Valid Up to 2100\"\n\nData for the time and date are stored in registers on the DS3231. Each, distinct value is stored separately. This means the seconds are in one register, the minutes in another, and so on. The DS3231 updates the values in the date and time registers every second.\n\nThe device keeps track of time by operating its own 32.768 kHz crystal oscillator, similar to the timekeeper in an electronic watch. Temperature can affect oscillator speed. Accordingly, the DS3231 takes further steps to maintain accuracy. It senses the temperature around the crystal and adjusts the speed of the oscillator.\u003cbr\u003e\nThe oscillator can be accessed directly, independent of the date and time registers, for use as an external timer or source of interrupts.\n\nThe temperature can be read from the DS3231 using a class member function. The data sheet declares it to be accurate to within 3 degrees, Celsius. \n\n\n### Power Supply and Battery Backup\nThe DS3231 can run in a range between 2.3 V and 5.5 V. The device actually has two power supply pins:\u003cbr\u003e\n* the primary source V\u003csub\u003eCC\u003c/sub\u003e\n* a secondary, backup source V\u003csub\u003eBAT\u003c/sub\u003e\n\nSome popular DS3231 modules mounting, provide a receptacle for a coin battery (CR2032), attaching it to the V\u003csub\u003eBAT\u003c/sub\u003e pin. If a sufficiently-charged battery is present, the DS3231 will switch automatically to the battery after detecting a drop in V\u003csub\u003eCC\u003c/sub\u003e voltage below a certain \"power-fail\" level.\n\nIt will switch back to V\u003csub\u003eCC\u003c/sub\u003e automatically, if and when that voltage rises back up above both the power-fail and the battery voltage level. \n\n**REMARK**:\u003cbr\u003e\nOne point regarding the choice of battery may deserve consideration:\u003cbr\u003e\nThe question of whether to install a **rechargeable** coin battery, or to disable the charging circuit if a **nonrechargeable** battery provided on the module being used.\u003cbr\u003e\n\n\n#### The DS3231 Battery Problem:\u003cbr\u003e\nIt is highly recommended to check which battery/accumulator is placed on the DS3231 module!\u003cbr\u003e\nIf the module is connected to 5V it normally charges the accumulator, and when a normal battery is used this can cause issues.\u003cbr\u003e\nLike:\n* battery look inflated\n* battery can swell\n\nFor the use with a battery e.g.: `CR2032`, please desolder the **200 Ohm resistor** to deactivate the charging mechanism.\u003cbr\u003e\nSee the corresponding link for the problem description in detail:\u003cbr\u003e\n[DS3231-battery-problem](https://320volt.com/en/ds3231-cr2032-battery-problem-and-solution/)\n\n[back to top](#ds3231-rtc-library)\n\u003chr\u003e\n\n\n## Installation\n\n### First Method\n\n1. In the Arduino IDE, navigate to Sketch \u003e Include Library \u003e Manage Libraries\n1. Then the Library Manager will open and you will find a list of libraries that are already installed or ready for installation.\n1. Then search for DS3231 using the search bar.\n1. Click on the text area and then select the specific version and install it.\n\n### Second Method\n\n1. Navigate to the [Releases page](https://github.com/hasenradball/DS3231-RTC/releases).\n1. Download the latest release.\n1. Extract the zip file\n1. In the Arduino IDE, navigate to Sketch \u003e Include Library \u003e Add .ZIP Library\n\n### Dependencies\n\nThe user must also ensure that two, other, required libraries are available to the Arduino IDE. This DS3231 library takes care to `#include`  the following in a program, but it does not install them in your Arduino IDE:\n\n* `Wire.h` : a widely-used Arduino library for I2C twowire communications\n* `time.h` : a modified C language header file to the corresponding microcontroller based time lib functions\n\n**Remark**:\u003cbr\u003e\nthe AVR lib `time.h` is based on year 2000 against the c-standard libs are based on year 1970.\u003cbr\u003e\nSee [AVR-libc Time](https://www.nongnu.org/avr-libc/user-manual/group__avr__time.html)\n\nNote:\u003cbr\u003e\nAt the time of writing, both of these libraries were included by default with a standard installation of the 1.8.x version of Arduino IDE for AVR-based devices.\n\nA simple way to check for the availability of the two libraries is to compile the following, blank Arduino sketch. If the IDE does not complain that anything is missing, then the required libraries are available for use with this DS3231 library.\n\n```\n#include \u003cWire.h\u003e\n#include \u003ctime.h\u003e\nvoid setup() {}\nvoid loop() {}\n```\n\n[back to top](#ds3231-rtc-library)\n\u003chr\u003e\n\n## Functions\nReaders are encouraged to visit the [Documentation folder](https://github.com/hasenradball/DS3231-RTC/tree/master/Documentation) for detailed information about the functions in this Library. Additional information is available in the [Examples of Use](#examples-of-use) described below, and in the code source files of this repository:\n\n* [DS3231-RTC.h](https://github.com/hasenradball/DS3231-RTC/blob/master/src/DS3231-RTC.h)\n* [DS3231-RTC.cpp](https://github.com/hasenradball/DS3231-RTC/blob/master/src/DS3231-RTC.cpp)\n\n### [Read the Date or Time](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Retrieval.md)\n- [RTClib::now() \u003csup\u003e\\*\u003c/sup\u003e](https://github.com/hasenradball/DS3231-RTC#the-special-rtclibnow-function-)\n- [getSecond()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Retrieval.md#getsecond)\n- [getMinute()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Retrieval.md#getminute)\n- [getHour(bool, bool)](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Retrieval.md#gethour)\n- [getDoW()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Retrieval.md#getdow)\n- [getDate()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Retrieval.md#getdate)\n- [getMonth(bool)](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Retrieval.md#getmonth)\n- [getYear()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Retrieval.md#getyear)\n\n\\* The *RTClib::now()* function is not accessed through the DS3231 object. Rather, it has a very specific syntax as described below in \u003ca href=\"#RTClib_now_function\"\u003eThe Special RTClib::now() Function\u003c/a\u003e.\n\n\n### [Set the Date or Time](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Set.md)\nWe emphasize here and elsewhere that the code writer bears responsibility to ensure that the values passed into the following functions fall within the valid range, as specified in the documentation for each function.\n\nUnexpected values in the DS3231 hardware registers may follow from the insertion of an invalid parameter into any one of these functions.\n\n- [setEpoch()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Set.md#void-setepochtime_t-epoch--0-bool-flag_localtime--false)\n- [setSecond()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Set.md#void-setsecondbyte-second)\n- [setMinute()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Set.md#void-setminutebyte-minute)\n- [setHour()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Set.md#void-sethourbyte-hour)\n- [setDoW()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Set.md#void-setdowbyte-dow)\n- [setDate()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Set.md#void-setdatebyte-date)\n- [setMonth()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Set.md#void-setmonthbyte-month)\n- [setYear()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Set.md#void-setyearbyte-year)\n- [setClockMode()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Time-Set.md#void-setclockmodebool-h12)\n\n### [Set, Clear and Check Alarms](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Alarms.md)\nThe following functions set and retrieve time and date values in the DS3231 hardware alarm registers. \n\nParameters include a special 8-bit value named \"AlarmBits\". Readers may find additional information about it at the following links: [Alarm Bits Quick Reference](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Alarms.md#alarm-bits-quick-reference), and [Alarm Bits in Detail](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Alarms.md#alarm-bits-in-detail).\n\n- [getA1Time()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Alarms.md#geta1time)\n- [getA1Time() with Option](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Alarms.md#geta1time-with-option)\n- [getA2Time()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Alarms.md#geta2time)\n- [getA2Time() with Option](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Alarms.md#geta2time-with-option)\n- [setA1Time()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Alarms.md#seta1time)\n- [setA2Time()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Alarms.md#seta2time)\n\nThe remaining functions in this group set and retrieve certain flags in the DS3231 hardware that govern or report the operation of the alarms.\n\n- [turnOnAlarm()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Alarms.md#turnonalarm)\n- [turnOffAlarm()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Alarms.md#turnoffalarm)\n- [checkAlarmEnabled()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Alarms.md#checkalarmenabled)\n- [checkIfAlarm()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Alarms.md#checkifalarm)\n- [checkIfAlarm() with Option](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Alarms.md#checkifalarm-with-option)\n\n### [Manage DS3231 Hardware](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Utilities.md)\nThe functions in this group support uses for a DS3231 other than as an alarm clock.\n\n- [getTemperature()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Utilities.md#gettemperature)\n- [enableOscillator()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Utilities.md#enableoscillator)\n- [enable32kHz()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Utilities.md#enable32khz)\n- [oscillatorCheck()](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/Utilities.md#oscillatorcheck)\n\n### [DateTime Object](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/DateTime.md)\nA DateTime class is defined in this DS3231-RTC.h library. The link, above, provides more information about the class. \n\n[Retrieving Date and Time Data](https://github.com/hasenradball/DS3231-RTC/blob/master/Documentation/DateTime.md#retrieving-date-and-time-data)\u003cbr\u003e\nfurther lists the DateTime class methods (for Documentation look into the src file): \n\n- getYear()\n- getMonth()\n- getDay()\n- getHour()\n- getMinute()\n- getSecond()\n- getWeekDay()\n- getYearDay()\n- getDST()\n- strf_DateTime()\n- getUnixTime()\n- getY2KTime()\n\n\u003ch3 id=\"RTClib_now_function\"\u003eThe \u003ccode\u003eRTClib::now()\u003c/code\u003e Function \u003c/h3\u003e\n\n`RTClib::now()` is the precise, complete name for a special function that returns a `DateTime` object from the DS3231. Always write it just so: `RTClib::now()`.\n\nThe function returns a DateTime object. To use it in your program, declare a DateTime type of variable to receive the value. For example: \n\n`DateTime currentMoment = RTClib::now();`\n\nThe value of `currentMoment` can then be accessed as either:\n* getting an unsigned integer containing the number of seconds since a certain reference date (Unix-Time or Y2K-Time)\n* distinct values out of the `struct tm` for Year, Month, Day, Date, Hour, Minute, Second etc...\u003cbr\u003e\nsee [Definition of struct tm](https://en.cppreference.com/w/c/chrono/tm).\n\n[back to the list of functions](#functions)\u003cbr\u003e\n[back to top](#ds3231-rtc-library)\n\u003chr\u003e\n\n## Examples of Use\n\nThere are many examples provided in the [examples](https://github.com/hasenradball/DS3231-RTC/tree/master/examples) folder of this repository.\u003cbr\u003e\nAt the time of writing the examples include:\n\n* `set`: demonstrates selected time-setting functions\n* `test`: demonstrates selected time-reading functions\n* `echo`: demonstrates setting the time and date then reading it back\n* `echo_time`: similar to *echo*, demonstrates setting and reading time/date data\n* `oscillator_test`: demonstrates advanced techniques for managing and using the DS3231 device as a pulse generator\n\nFuture development plans include updating these examples and adding more of them.\n\nSee also [Working with the DS3231 libraries and interrupts](https://github.com/IowaDave/RTC-DS3231-Arduino-Interrupt), a tutorial provided by [IowaDave](https://github.com/IowaDave).\n\n[back to top](#ds3231-rtc-library)\n\u003chr\u003e\n\n## Additional Resources and References\n\n* [Maxim DS3231 Data Sheet](https://datasheets.maximintegrated.com/en/ds/DS3231-DS3231S.pdf)\n\n[back to top](#ds3231-rtc-library)\n\u003chr\u003e\n\n## Contributing\n\nIf you want to contribute to this project:\n\n- Report bugs and errors\n- Ask for enhancements\n- Create issues and pull requests\n- Tell others about this library\n- Contribute new protocols\n\nPlease read [CONTRIBUTING.md](https://github.com/hasenradball/DS3231-RTC/blob/master/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.\n\n[back to top](#ds3231-rtc-library)\n\u003chr\u003e\n\n## Credits\nThis library is in the first shot based on [A. Wickerts'](https://github.com/NorthernWidget/DS3231) library and then refractured.\n\nThe author of this library is F. Häfele \u003cmail@frankhaefele.de\u003e\n\nBased on previous work by:\n\n- A. Wickert\n\n[back to top](#ds3231-rtc-library)\n\u003chr\u003e\n\n## License\n\nDS3231-RTC is licensed under [MIT License](https://github.com/hasenradball/DS3231-RTC/blob/master/LICENSE).\n\n[back to top](#ds3231-rtc-library)\n\u003chr\u003e\n\n## To Do\nA project is underway to update the library's documentation.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhasenradball%2FDS3231-RTC","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhasenradball%2FDS3231-RTC","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhasenradball%2FDS3231-RTC/lists"}